<
From version < 13.2 >
edited by Sergiu Dumitriu
on 2007/12/12
To version < 14.1 >
edited by Anca Luca
on 2008/03/08
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.Sergiu
1 +XWiki.lucaa
Content
... ... @@ -1,7 +1,9 @@
1 1  1 Creating a FAQ Application
2 2  
3 -This tutorial will show you how to build a Frequently Asked Questions (FAQs) Application much like the one you can find on the [FAQ page>xwiki:FAQ.WebHome]. 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. In addition to the data model, this tutorial will introduce the concept of Authoring Templates and Page Design Sheets. Completing this tutorial is a recommended prerequisite for anyone who wants to build custom applications on the XWiki engine.
3 +This tutorial will show you how to build a Frequently Asked Questions (FAQs) Application much like the one you can find on the [FAQ page>xwiki:FAQ.WebHome]. 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.
4 4  
5 +All through this tutorial you should refer to the [XWiki Data Model> DevGuide.DataModel] for information on XWiki's data model. You might also use the [XWiki Scripting Guide> DevGuide.Scripting] 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.
6 +
5 5  1.1 Application Overview
6 6  
7 7  The FAQ application allows users to post a question by entering the question into a simple form field and then submitting the form. The question then appears in a list along with all other questions that have been previously posted. Users can click on the questions to view both the question and answer in a consistently styled view. If the question has not yet been answered, any user can post an answer to the question by editing the page. In edit mode, the page will display a web form that is always consistent for every FAQ page.
... ... @@ -8,19 +8,18 @@
8 8  
9 9  Let us begin by taking a look at what we are going to build. The system has the following views. Click any view link below to preview a screenshot. (Note: Firefox users can middle click or click down on the mouse scroll-wheel to open the links in a new tab.)
10 10  
11 -* The FAQs Summary View
12 -* A Question and Answer Page in Display Mode
13 -* A Question and Answer Page in Edit Mode
14 -
13 +* {attach:The FAQs Summary View|FAQsSummary.png}
14 +* {attach:A Question and Answer Page in Display Mode|FAQSheetView.png}
15 +* {attach:A Question and Answer Page in Edit Mode|FAQSheetEdit.png}
15 15  1.1 Authoring Templates and Page Design Sheets
16 16  
17 -An Authoring Template is a template for creating documents of a specific type. Unlike a regular content page in edit mode with one field for freeform editing, an Authoring Template presents a custom set of form fields. Each form field can have different types of form elements. These form elements are defined by the properties of a class.
18 +An Authoring Template is a template for creating documents of a specific type. Unlike a regular content page in edit mode with one field for freeform editing, an Authoring Template presents a custom set of form fields for creating a document with specific type of data. These form elements are defined by the properties of a class.
18 18  
19 -In object oriented programming, remember that a ~~class~~ is a template for an object. Using the analogy of a cookie cutter, the ~~class~~ is the ~~cookie cutter~~ and the ~~objects~~ are the actual ~~cookies~~. An Authoring Template provides one way to represent a class visually so that users can fill out a form to set unique properties (values in form fields). When the user submits the form, they are creating a unique ~~object~~ of the ~~class~~ type.
20 +In object oriented programming, remember that a ~~class~~ is a template for an object. Using the analogy of a cookie cutter, the ~~class~~ is the ~~cookie cutter~~ and the ~~objects~~ are the actual ~~cookies~~. An Authoring Template provides one way to represent a class visually so that users can fill out a form to set unique properties (values in form fields). When the user submits the form, they are creating a unique ~~object~~ of the ~~class~~ type.
20 20  
21 -~~In this sample application, a new document is created and the object instance is automatically added to the new document. So, in truth, objects in XWiki are not really documents; they are added to a document. Once an object is added to a document, it's properties can easily be accessed by scripting in that document's content.~~
22 +Precisely, an Authoring Template is a prototype document used to create other specific instances of documents of the same type, along with a method of exposing the creation process to the user: the properties edit form. Remember that a XWiki Document can contain objects and this is the case of an authoring template: it is a XWiki Document with an empty object of a specific class, which is duplicated to create more and more documents based on that model, using the data inserted by the user in the editing form as specific values for the particular object instance in the current copy.
22 22  
23 -The Page Design Sheet is like a style sheet that defines each document will look when it is rendered. Even though the unique object instances will have different values for their properties, they will always have a consistent presentation display because they will be rendered through the Page Design Sheet.
24 +The Page Design Sheet is like a style sheet that defines each document will look when it is rendered. Even though the unique object instances will have different values for their properties, they will always have a consistent presentation display because they will be rendered through the Page Design Sheet. The XWiki API available in scripting languages provides a mechanism that will help us use the same sheet for both editing and view modes. We will see how we can achieve this once we get to the FAQ Design Sheet section.
24 24  
25 25  1.1 Get Set with the Class Editor Wizard
26 26  
... ... @@ -37,90 +37,102 @@
37 37  * ClassItemSheet
38 38  * ClassItemTemplate
39 39  
40 -If they're not showing up or if they are showing up but with question marks, you do not have the pages in your XWiki database. Copy the page contents from the links below and paste them into the respective pages in your XWiki instance (create them as children of the XWikiClasses page) to ensure that you have all the parts that make up the wizard. Once you have all of these pages in place, you are ready to start building your FAQs application.
41 +If they're not showing up or if they are showing up but with question marks, you do not have the pages in your XWiki database.
42 +You can either use this provided {attach:ClassWizard.xar} to import the documents in your wiki (see the [Import guide> AdminGuide.ImportExport#HImportingXWikipages] in the XWiki Administration Guide for details on this operation) or copy the page contents from the links below and paste them into the respective pages in your XWiki instance (create them as children of the XWikiClasses page) to ensure that you have all the parts that make up the wizard:
41 41  
42 -* Get the [XWikiClasses>http://www.xwiki.com/xwiki/bin/view/XWiki/XWikiClasses?xpage=code] page code.
43 -* Get the [ClassSheet>http://www.xwiki.com/xwiki/bin/view/XWiki/ClassSheet?xpage=code] page code
44 -* Get the [ClassTemplate>http://www.xwiki.com/xwiki/bin/view/XWiki/ClassTemplate?xpage=code] page code.
45 -* Get the [ClassItemSheet>http://www.xwiki.com/xwiki/bin/view/XWiki/ClassItemSheet?xpage=code] page code.
46 -* Get the [ClassItemTemplate>http://www.xwiki.com/xwiki/bin/view/XWiki/ClassItemTemplate?xpage=code] page code.
44 +* Get the [XWikiClasses>http://www.xwiki.org/xwiki/bin/view/XWiki/XWikiClasses?viewer=code&showlinenumbers=0] page code.
45 +* Get the [ClassSheet>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassSheet?viewer=code&showlinenumbers=0] page code
46 +* Get the [ClassTemplate>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassTemplate?viewer=code&showlinenumbers=0] page code.
47 +* Get the [ClassItemSheet>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassItemSheet?viewer=code&showlinenumbers=0] page code.
48 +* Get the [ClassItemTemplate>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassItemTemplate?viewer=code&showlinenumbers=0] page code.
47 47  
50 +Once you have all of these pages in place, you are ready to start building your FAQs application.
48 48  
52 +Keep in mind that you should always use the Wiki editing mode when editing scripts inside documents.
53 +
49 49  1.1 Create the FAQ Class
50 50  
51 51  * On the Class Editor wizard entry page (XWiki.XWikiClasses), under the heading "Create a new Class", enter the following web space and class name:
52 52  ** Web: FAQs
53 53  ** Class: FAQ
59 +
60 +{image:CreateANewClass.png}
61 +
54 54  * Click the "Create this Class" button. You should then see a code page with the following code:
55 55  
56 56  {code:none}
57 -<!-- replace Main with the Space where you want your documents to be created -->
58 -<!-- replace the default parent with the one of your choice -->
59 -<!-- Save this template using the &#8217;Save&#8217; button -->
60 -#set($class = $doc.name.substring(0,$doc.name.indexOf("Class")))
65 +## replace Main with the Space where you want your documents to be created
66 +## replace the default parent with the one of your choice
67 +## Save this template using the ?Save? button
68 +#set( $class = $doc.name.substring(0,$doc.name.indexOf("Class")))
61 61  #set($defaultparent = "XWiki.${class}Class")
62 62  #set($defaultweb = "Main")
63 63  #includeForm("XWiki.ClassSheet")
72 +
64 64  {code}
65 65  
66 -* In the code, change the word "Main" with the name of the space where you want you FAQ pages to be created as the commented instructions in the page code suggest. Replace the word "Main" with the word "FAQs". The line of code should now look like this:
75 +In the code, change the word "Main" with the name of the space where you want you FAQ pages to be created as the commented instructions in the page code suggest. Replace the word "Main" with the word "FAQs". The line of code should now look like this:
67 67  
68 68  {code:none}
69 69  #set($defaultweb = "FAQs")
79 +
70 70  {code}
71 71  
72 -* Click the "Save" button. The class is now created and you should the be looking at a page titled "Class: FAQClass" that looks like this:
82 +Click the "Save & View" button. The class is now created and you should the be looking at a page titled "Class: FAQClass" that looks like this:
73 73  
74 -{image:FAQClassDoc.gif}
84 +{image:FAQClass1-border.png}
75 75  
86 +
76 76  1.1 Add Properties to the Class
77 77  
78 -Under the page title, you should see the words "The first thing to do is to <u>Edit the Class</u> to add properties to it." So, let's just follow those instructions!
89 +Under the page title, you should see the words "The first thing to do is to __Edit the Class__ to add properties to it." So, let's just follow those instructions!
79 79  
80 80  * Click on the 'Edit the Class' link; a blank page will be displayed.
81 -* Note that the link trail in the header is something like "XWiki.XWikiClasses > FAQs.FAQClass". Even though the page is blank, this shows you are indeed on the class page.
92 +* Note that the link trail in the header is something like "Welcome to the Class Editor > FAQClass". Even though the page is blank, this shows you are indeed on the class page.
82 82  
83 -In our document, we'll store both a ~~question~~ and an ~~answer~~. So we need a property for each.
94 +In our document, we'll store both a ~~question~~ and an ~~answer~~. So we need a property for each.
84 84  
85 -* Enter the text ~~question~~ in the Property Name field of the Class Editor panel.
96 +* Enter the text ~~question~~ in the Property Name field of the Class Editor panel (in the column on the right).
86 86  * Choose a TextArea type for the property and then click the 'Add Property' button. The TextArea will ultimately give us a multi-line text field in our authoring template.
87 -* Configure this property with the following values:
98 +* Configure this property with the following values (actually, if you are using the current XWiki version, you don't need to change anything else but the Pretty name &ndash; all the rest are the default values):
88 88  
89 -{image:QuestionProperty.gif}
100 +{image:QuestionProperty.png}
90 90  
91 91  * Now add a property called ~~answer~~ in the same way that you did for the 'question' property (choosing TextArea for the property type).
92 -* Configure this property with the following values:
103 +* Choose it from the property list on the left and configure this property with the same values as the "question" property, except for the ~~name~~ and ~~pretty name~~ which will, obviously, match the new property we're creating.
104 +* When you are done adding and configuring the properties, click the 'Save & View' button.
93 93  
94 -{image:AnswerProperty.gif}
95 95  
96 -* When you are done adding and configuring the properties, click the 'Save Class' button.
97 -
98 98  1.1 Create the Page Design Sheet
99 99  
100 -* Search for the keywords 'FAQs.FAQClass' and click on the document to open it in XWiki.
101 -* The title of the page should be "Class: FAQClass" and it should look like this:
109 +* After the previous step you are now on the FAQClass page which should look like this:
102 102  
103 -{image:FAQClassSheet.gif}
111 +{image:FAQClass1.png}
104 104  
105 -* Click the first button to create the document sheet (the Page Design Sheet). This sheet determines how your page objects will be rendered to the user in ~~read~~ mode. You should see the following page code for the document sheet:
113 +* Click the first button to create the document sheet (the Page Design Sheet). This sheet determines how your page objects will be rendered to the user. You should see the following page code for the document sheet:
106 106  
107 107  {code:none}
108 -## you can modify this page to customize the presentation of your object
109 -## at first you should keep the default presentation
110 -## save this template using the save button at the top left
111 111  
117 +11. You can modify this page to customize the presentation of your object
118 +11. at first you should keep the default presentation.
119 +11. Save this template using the save button.
120 +
112 112  1 Document $doc.name
113 113  
114 114  ## Change class name to your class name
115 115  #set($class = $doc.getObject("XWiki.MyClass").xWikiClass)
116 -
117 -<table border="1" cellspacing="0" cellpadding="2">
125 +#set($hasProps = false)
118 118  #foreach($prop in $class.properties)
119 -<tr><td> *${prop.prettyName}* </td>
120 -<td>$doc.display($prop.getName())</td>
121 -</tr>
127 + #if($velocityCount == 1)
128 + #set($hasProps = true)
129 + <dl>
130 + #end
131 +<dt> ${prop.prettyName} </dt>
132 +<dd>$doc.display($prop.getName())</dd>
122 122  #end
123 -</table>
134 +#if($hasProps)
135 + </dl>
136 +#end
124 124  {code}
125 125  
126 126  * Change the class name ~~XWiki.MyClass~~ in the code to ~~FAQs.FAQClass~~ so that the line looks like this:
... ... @@ -130,67 +130,72 @@
130 130  #set($class = $doc.getObject("FAQs.FAQClass").xWikiClass)
131 131  {code}
132 132  
133 -* Click 'Save'.
146 +* Let's take a moment now and analyze the code: with the line we just modified we retrieve the FAQs.FAQClass from the wiki and then we iterate through all its properties and display their values for the current document in a definition list. As we mentioned, XWiki provides a mechanism that help us create sheets used for both view and edit mode: this is the display function used in the line: {code:none}<dd>$doc.display($prop.getName())</dd>{code} It detects the current mode (edit or view) and displays the property referenced by it's argument as the mode dictates: for view, it is the value of the property, for edit it is a form field that will allow the user to edit it. This way we can use a single Design Sheet for both displaying and editing our FAQs. See the [XWiki API reference > DevGuide.API] and [XWiki Scripting > DevGuide.Scripting] pages for more details.
134 134  
148 +* Click 'Save & View'.
149 +
135 135  1.1 Create the Authoring Template
136 136  
137 -* Search for the keywords 'FAQs.FAQClass' and click on the document to open it in XWiki again. The document should look like this:
152 +* Search for the keywords 'FAQs.FAQClass' and click on the document to open it in XWiki again, or click the FAQClass in the breadcrumbs. The document should look like this:
138 138  
139 -{image:PageDesignSheetCreated.gif}
154 +{image:FAQClass2.png}
140 140  
141 141  * Notice that now, there is a link for the FAQClassSheet in place of the button that was previously there.
142 -* Click on the 'Create the document template' button. The template will be created with the following page code:
157 +* Click on the 'Create the document template' button. The Authoring Template will be created with the following page code:
143 143  
144 144  {code:none}
145 -## replace MyName with the real class name
146 -## save this template using the save button at the top left
160 +## Replace MyName with the real class name.
161 +## Save this template using the save button.
147 147  #includeForm("XWiki.MyNameClassSheet")
148 148  {code}
149 149  
150 150  * As the comments instruct, change the words ~~MyName~~ with ~~FAQ~~ so that instead of having ~~XWiki.MyNameClassSheet~~, you will have ~~FAQs.FAQClassSheet~~. In this case, we changed the space preceding the page name also because we want all of our FAQ page objects to reside in a unique wiki web space.
151 -* Click 'Save' to save the page object.
152 -* Now the saved page object (the authoring template) should show the page title "Document FAQClassTemplate". Now, we need to associate the class object with this page object to turn it into a true authoring template.
153 -* Click 'More Actions > Edit Objects'.
154 -* In the Object Editor panel, select FAQs.FAQClass from the drop-down and then click 'Add Object from this Class'. The ~~Question~~ and ~~Answer~~ form fields appear on the page.
155 -* Click 'Save Objects'. Congratulations; You just created an Authoring Template!
166 +* Click 'Save & Continue' to save the document. Remember that all our documents will be copies of the Authoring Template used as a prototype so the content we just saved will be copied in all our FAQs documents and will execute the Design Sheet code in the context of the current document. See the [dedicated page > DevGuide.IncludeInVelocity] for more information regarding this technique.
167 +* Now, we need to associate the prototype object with this document to turn it into a true authoring template.
168 +* On the right side, in the Choose editor list, click ~~Objects~~.
169 +* In the Add Object panel on the right, select FAQs.FAQClass from the drop-down and then click 'Add Object from this Class'. The ~~Question~~ and ~~Answer~~ form fields appear on the page.
170 +* Click 'Save & View'. Congratulations; You just created an Authoring Template!
156 156  * Click the FAQs.FAQClass link in the header breadcrumb trail. As you can see, you are almost done!
157 157  
158 -{image:MakingProgress.gif}
173 +{image:FAQClass3.png}
159 159  
160 160  1.1 Test the Application
161 161  
162 162  Now let's just create a new document in our application to test it out.
163 163  
164 -* Enter a document title in the ~~Document~~ field and click ~~Create~~. For example, enter ~~'What is the meaning of life'~~. Don't use a question mark in the document name.
165 -* You can then enter your question in longer form using the ~~question~~ field on the template, like this:
179 +* Under the "Create a new document" header, enter a document title in the ~~Document~~ field and click ~~Create~~. For example, enter ~~What is the meaning of life?~~.
180 +* You can then enter your question in longer form using the ~~Question~~ field on the template, like this:
166 166  
167 -{image:FirstQuestion.gif}
182 +{image:FAQSheetEdit.png}
168 168  
169 -* Click ~~Save~~ and then you will see the newly created document, like this:
184 +* Click ~~Save & View~~ and then you will see the newly created document, like this:
170 170  
171 -{image:FirstQuestion2.gif}
186 +{image:FAQSheetView.png}
172 172  
173 -* Search for 'FAQ' to find the FAQClass document again and click to open it. You can now see that the FAQ documents you are creating will build in a list on the main entry page to the application, like this:
188 +* Open the FAQClass document again. You can now see that the FAQ documents you are creating will build in a list on the main entry page to the application, like this:
174 174  
175 -{image:Final.gif}
190 +{image:FAQClass4.png}
176 176  
177 177  1.1 Displaying the FAQ Questions as summary
178 178  
179 179  If you want to display the FAQ question instead of the FAQ document name in the summary area, you can proceed as follow:
180 180  * Edit the content of the FAQs.FAQClass page
181 -* Replace the #\include\Form("XWiki.ClassSheet") with the content of the XWiki.ClassSheet (go to the XWiki.ClassSheet, edit the content and past it instead of the includeForm command
182 -* After the #\foreach($\item in $\xwiki.searchDocuments($\sql)) command add the following line <br/> #\set ($\faq=$\xwiki.getDocument($\{item})) and replace the {code:none}[${item}]{code} with {code:none}[${faq.display("question")}>${item}]{code}
196 +* Replace the #\include\Form("XWiki.ClassSheet") with the content of the XWiki.ClassSheet (go to the XWiki.ClassSheet, edit the content and paste it instead of the #\includeForm command
197 +* Then, after the {code:none}#foreach ($item in $xwiki.searchDocuments($sql)){code} command add the following line {code:none}#set ($faq=$xwiki.getDocument(${item})){code} and replace the {code:none}[$item]{code} with {code:none}[${faq.display("question")}>${item}]{code} The line we added retrieves the document using the document name while the line we replaced displays the "question" property for the document instead of the document name.
198 +* Click "Save & View" and enjoy your new FAQ application.
183 183  
200 +
184 184  1.1 Finally, link to the FAQs.FAQClass page
185 185  
186 186  We don't want our users to have to search for this page using the search engine, so finally pick a spot on your Wiki and make a user-friendly link to FAQs.FAQClass. For example:
187 187  
188 188  {code:none}
189 -* [Frequently Asked Questions (FAQs) > FAQs.FAQClass]
206 +[Frequently Asked Questions (FAQs) > FAQs.FAQClass]
190 190  {code}
191 191  
209 +
192 192  1.1 Conclusion
193 193  
194 -This tutorial has shown how to use the Class Wizard app and it has introduced the concepts of classes, objects, properties, 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.
212 +This tutorial has shown how to use the Class Wizard app and it has detailed the concepts of classes, objects, 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.
195 195  
196 196  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.

Get Connected