This tutorial will show you how to build a Contact Manager application.  It's very similar to the FAQTutorialManual tutorial. The only difference (so far) is that the FAQ tutorial involves a very trivial object: a FAQ object contains just two things: a "question" and an "answer", while this example uses a Person object that has more properties ("name", "age", "sex", etc.) .This is a very simple application that makes use of XWiki's classes, properties, and objects. It also uses a technique that you may frequently use as the basis for several different kinds of applications.

Also, this tutorial explains things a little differently than the FAQ tutorial. If something here doesn't make sense to you, try going through the FAQ tutorial and maybe it will make more sense.

Prerequisites for following the tutorial

You should have installed XWiki and have a basic understanding of how to use it.

All through this tutorial you should refer to the XWiki Data Model for information on XWiki's data model. You might also use the XWiki Scripting Guide to get you started with scripting in XWiki and manipulating XWiki objects. In addition, this tutorial will introduce the concepts of Authoring Templates and Page Design Sheets, patterns that you will find particularly useful in creating XWiki applications. Completing this tutorial is a recommended prerequisite for anyone who wants to build custom applications on the XWiki engine. And by "custom application", we mean a huge variety of web applications.

Application Overview

The Person Manager application will allow users to create a "Person object" by entering data (name, age, sex, etc) into a simple form and then submitting the form. Let's sketch out what roughly what those two pages should look like on a "napkin", using Balsamiq:

Our page won't look exactly like that, but the point is that a website user can create a Person by filling out a "form" page like this.

Note all the various types of "widgets" shown here:

• "name" is a single-line text field
• "email" is also a single-line text field, but we'd like it to be validated (e.g. give an error if it doesn't have a "@" in it)
• "address" is a multi-line text field
• "phone" is a single-line text field (perhaps some validation here, too)
• "sex" is a drop-down list
• "married" is a checkbox: the only allowed values are "true" and "false"
• "image" is actually the name of some image file, but we actually display the image itself. Nice!
• "age" is Number field, which looks like a single-line text field, but has validation.
• "related people" is one more more links to other web pages. Very nice!

The Person then appears in a table with all other Person objects that have been previously created. Users can click on the Person in the table to see all the information about the Person. He may also edit that information or delete the Person. The table might look something like this:

When the user clicks on a row in the table, he will get a page that shows the information about the Person, which will look similar to the "Create Person" page, but without the ability to change anything.

Objects Overview And Terminology

Next, let's summarize the terminology for "Objects". For full details, see Data Model. There is nothing fancy happening here, but it's important to get our terminology straight.

A Person is an example of some "Object" or "class". We will use XWiki to define what "properties" are in a "Person" object. For example, we will say that there's a property called "name" of type "String". There's also a property called "age" of type "Number", and an "address" property that's type "TextArea" (a string that can be multiple lines).

When a user creates a new Person, we call that an "instance" of the "class". So we might say something like "I've created an instance of the Person class, with name 'Joe Smith'". And we would say that our table shows all the instances of the Person class. And instances can not only be created, but also edited or deleted.

We, the creators of the website, define the "Person" class. We define that once, and we're done. Our users use our website to create, edit, and delete instances of our Person class.

Overview Of What We Will Do

In this tutorial, we'll do the following steps:

• Define our Person class, using the XWiki "Data Types" page.
• Specify the properties of our Person class, using the XWiki "Class Editor" page.
• Define how a Person instance should be displayed, by creating a "Person Sheet" page.
• Create a Template and a Template Provider (whatever they are) for our Person class.
• Create a web page that displays a table of people.
• For each Person that you want to create, create a page and add an instance of our Person class to the page.

Note that we don't need to define a page for creating or editing a Person, just a page for *displaying* a Person. XWiki will automatically do that for us!

Once we are done with these steps, our application will be finished. A user of our website can see a page containing the table of Person objects, view the page for an existing person, add a new Person, edit an existing Person, or delete a Person.

Go to the Special "Data Types" Page

The "Data Types" page is a special XWiki page that lets us define classes like "Person". It'sactually hidden by default. To be "unhide" it, go to your profile page, select the Preferences tab, edit the page and choose to view Hidden Documents. 

To find the "Data Types" page, enter a search query for the keyword "D". This should return a document titled "Data Types".

Create the Person Class

• On the "Data Types" page, under the heading "Create a new data type", in the "Title" field, enter Person as the name of the page to create:

  

• As you can see in the Breadcrumb below the new page will be created at location XWiki > Person. In practice the "Data Types" page will automatically prefix the page name with Class (you could also enter PersonClass as the page name directly).
• Now it would be nice to have it created in a new location such as PersonSpace > Person Class. Since the PersonSpace parent doesn't exist we cannot use the Tree picker button. Thus click the Pencil button as shown in the following image and replace XWiki by PersonSpace.

  

• In technical terms you're creating a page named PersonClass (with a title of "Person Class") located in a space also called PersonSpace and thus the technical reference is PersonSpace.PersonClass.
• Click the "Create this Class" button. You should then see a page with the following content:
  {{velocity}}
  ## Replace the default space with the space where you want your documents to be created.
  ## Replace the default parent with the one of your choice and save the document.
  ##
  #set($defaultSpace = $doc.space)
  #set($defaultParent = $doc.fullName)
  {{/velocity}}

In the code, change the word "$doc.space" with the name of the space where you want your pages to be created: "PersonSpace".
The line of code should look like this:

You can also change the default parent of the new FAQ documents that are going to be created. To do so, replace the "$defaultParent" variable with the name of your document.
The line of code should look like this:

Click the "Save & View" button. The class is now created and you should be looking at a page titled "Class: Person" that looks like this:

Add Properties to the Class

Under the page title, you should see the words "The class does not have any properties yet. You can use the class editor to define them." Let's just follow those instructions!

• Click on the 'class editor' link
• Note that the link trail in the header is something like "Wiki Home / PersonSpace / Person Class". This shows you that you are indeed on the Person class page in Class edit mode.

Now, we need to specify all the properties of a Person. Let's have the following properties:

• Enter the text name in the "name" field
• Choose "String" for the type of the property and then click on "Add". By using a String type, when a user goes to enter the name of a new Person, he will be prompted with a single-line text field.

  

• Click on the "+" icon to expand the options for the newly created property
• Change the value of the "Pretty Name" field to "Name"(capital N). With this done, the user sees the label "Name" rather than "name" when prompted for the name of a Person. This doesn't make a huge difference for this property, but when it comes to the property with the name "relatedPeople", it's nice to show the user something a little more friendy like "Related People". Also, you could later decide to change that label to "Similar People" without actually renaming the property (and thereby probably breaking something).
• Now repeat this to add each of the properties shown in the table above.
  • Note that the "EMail" type is like a String, except that it has a "Validation Expression" (e.g. to make sure it has an "@" character).
  • If we wanted to, we could add a "Validation Expression" to the "phone" property to make sure it's in a particular format.
  • For the "sex" property, in the "Display Type" field, enter "Select". This will give the user a drop-down menu.
  • As we define the "sex" property as type "static list", we specify the values for the field like this:

    

  • Note that there is no "Image" type. That's unfortunate. Let's just define it as a String here, and deal with that later.
  • Note that the "size" of our "age" field is 30 digits. Three digits should be plenty, so feel free to change that.
  • For our "relatedPeople" property, we want to allow multiple values, not just one. So find the "Multi Select" checkbox and check it.
• When you are done, you should see all your properties like this:

  

• When you are done adding and configuring the properties, click the "Save & View" button

Create the Page Design Sheet

• After the previous step you are now on the FAQClass page which should look like this:

  

• Click the first button ("Create the document sheet") to create the document sheet (the Page Design Sheet). This sheet determines how your page's objects will be rendered to the user. The document is automatically created.
• You should see a warning message with the text "The sheet is not bound to the class so it won't be applied automatically when a page that has an object of this class is displayed". Click the "Bind the sheet to the class" link that appears after the text. Basically, this ties the Person Class to the Person Sheet.
• Now click on "View the sheet document". This takes you to the PersonSpace.PersonSheet page which you can edit in wiki mode and see its default content. This content is Velocity code which simply goes through all the properties and displays each one.  For example, it will see that our Person class has a "married" property of type "Boolean", and will show a checkbox with a label of "married" (or perhaps "Married" if we specified that as our "pretty name" for the property).  See FAQTutorialManual for more details about this code.  This code is actually very close to working as-is. The only thing that would be ugly is that our "image" property would display as just a String, whereas we probably want to display the image itself, not some URL.

• Click "Save & View"

Create the Authoring Template

• Navigate back to the PersonSpace.PersonClass document (you can use the arrows in the breadcrumb to do so). 
• Click on the "Create the document template" button. The Authoring Template will be automatically created.

Note that earlier, we changed the space name preceding the page name because we wanted all of our Person pages to reside in a space named PersonSpace. Remember that all our documents will be copies of the Authoring Template used as a prototype so the content will be copied in all our Person documents and will execute the Design Sheet code in the context of the current document. See the dedicated page for more information regarding this technique.

Now we need to associate the prototype object with this document to turn it into a true authoring template:

• If you're on the template page, navigate back to the PersonSpace.PersonClass document.
• At the bottom of the page, look for the following warning message: "The template does not contain an object of type PersonClass. Add a Person object to the template »."
• Click on "Add a Person object to the template »":

  

Next, we want to remove the title for the newly created template:

• Navigate to the PersonSpace.PersonTemplate document (you can click on the "View the template page (PersonSpace / Person Template)" link for doing that for example.
• Edit this document in Wiki mode
• Inside the Title field you have "Person Template" written -> delete this text
• Save & View

This step is needed so that all of our future entries don't have "Person Template" as their title.

Congratulations: you just created an Authoring Template! You're almost done now.

Create the Template Provider

After the template was created and the object was added, a new section appears with a button to create a template provider to use the existing template. Click that button.

Create a home page for the Person Manager application

Now we are finished defining our Person class, and it's time to create our web pages. Recall that we only have two pages to create:

• A "main" page that contains a table of Person objects.
• A "Person" page that displays a single Person
• (We don't need to create a "form" page for creating a new Person or edit an existing person - XWiki does that for us)

Our "main" page will be the PersonSpace.WebHome page.

• Click on "PersonSpace" in the breadcrumb to navigate to PersonSpace.WebHome and notice that the page doesn't exist yet.
• Edit it in wiki mode
• Type in the title "People"

Displaying existing Person entries

You have 2 options when it comes to displaying existing Person entries:

1. Use the livetable component
2. Write custom code in order to display them in a table

We will only cover the "custom code" option here, because it's actually very easy to write a little code to display the table the way we want to.  See the "Using the Livetable component" section of the FAQTutorialManual page for instructions to use a "livetable" instead.

To create our table, we need to think about Objects, not web pages.  As people use our application, they create new instances of our Person class - they create Objects. Let's say there have been three "Person" objects created so far. That means there will be three rows in our table. But how do we write code for this table? We will need to "query the XWiki database" - essentially tell XWiki "get me all the instances of the PersonClass that exist". XWiki provides several different ways to do this query:

• XWiki Query Language (XWQL)
• Hibernate Query Language (HQL)
• Solr Query Language (SOLR)

The FAQTutorialManual page tells you how to use XWQL, but I will show you how to use SOLR. Why is SOLR "better"? It's a bit of a standard, it's very well documented, very flexible and fast. It's also pretty simple.

Regardless of which of these techniques we use to query, we will be writing code in the Velocity Template Language.

Using custom code

You will need to write the following code:

• Display a header above the table that says "People"
• Do SOLR query to get all documents (i.e. pages) containing an instance of PersonClass, with a "name" property of any value.
• Let's limit the number of results to 1000 because the default for SOLR is 10 and that's too low.
• Let's use XWiki syntax to create a table with three columns: Name, Email, and Phone (note that we don't bother to show all properties of a Person as columns in our table, but we could if we wanted).
• Loop through each document, doing the following:
  • find the PersonClass instance on the page. Set a variable called $object to that.
  • get the "name" property from the instance and display that in the first column of the table. 
  • get the "email" property from the instance and display that in the second column of the table. 
  • get the "phone" property from the instance and display that in the third column of the table. 

Here is the resulting code:

Notes:

• (TODO: explain why the check for empty name is needed - is the query returning the Template or class definition?)
• The "" characters at the end of the lines showing rows in the table are required because XWiki wants all table data for a row to be on a single line.
• TODO: explain Document, DocumentReference, and link to the javadoc.

• Copy this code and paste it as Wiki content inside PersonSpace.WebHome
• Click "Save and View"
• New Person entries will now be displayed on the page once you create them.

At this point, your PersonSpace.WebHome page will just display as an empty table because no instances of PersonClass have been created yet.

Creating new Person instances

There are 2 ways for you to let your users create new instances of our PersonClass:

1. Declare the Person as a template
2. Add a custom creation form

The FAQTutorialManual page describes how to create a custom form if you want to do that. But the simpler way is for you to use a template. Remember earlier, on the Person Class page, we clicked on a button to create a template, and clicked on another button to create a "Template Provider"? That's all we needed to do!  

With that done, let's go ahead and create an instance of PersonClass. Go to your PersonSpace.WebHome page (the one with the table), and click the "Create" button to create a child page. You will be prompted for a page title and page type. In the list of Types, under "Template" you should see "Person":

Fill in the person's name as the page title, choose the "Person" type, and click "Create."
You will then be prompted for all the information about your the Person instance that you want to create:

If you previously chose to use a "Custom creation form" for creating new FAQ entries, follow these steps:

• Go to FAQ.WebHome
• Below the "Add a new question" header, enter a question (which will also be used as the document title) in the Document field
• Click Create this FAQ
• You can then enter your question in longer form using the Question field on the template, like this:

  

• Click Save & View and then you will see the newly created document, like this:

  

• Go back to the FAQ.WebHome page (you can use the breadcrumbs) to see the list of existing questions

  

Conclusion

This tutorial has taught you how to use the Class Wizard app and it has detailed the concepts of classes, objects and properties and introduced the authoring templates and page design sheets.

You may also have learned a little bit about Velocity scripting in documents. You can use these basic concepts to build custom applications at the document or presentation layer of XWiki without having to compile or deploy code.

As always, please take the time to make this document better for other users if you find ways that it can be improved as you read it for the first time.