<
From version < 79.1 >
edited by Manuel Smeria
on 2015/08/27
To version < 80.1 >
edited by Manuel Smeria
on 2015/08/27
>
Change comment: fixed + updated the tutorial for XWiki 7.x

Summary

Details

Page properties
Content
... ... @@ -2,9 +2,9 @@
2 2  {{toc/}}
3 3  {{/box}}
4 4  
5 -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.
5 +This tutorial will show you how to build a Frequently Asked Questions (FAQs) [[Application>>platform:Features.Applications]] 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>>platform:DevGuide.DataModel||anchor=HXWikiClasses2CObjects2CandProperties]]. It also uses a technique that you may frequently use as the basis for several different kinds of applications.
6 6  
7 -= Pre Requisites for following the tutorial =
7 += Prerequisites for following the tutorial =
8 8  
9 9  You should have [[installed XWiki>>AdminGuide.Installation]] and have a [[basic understanding of how to use it>>Features.WebHome]].
10 10  
... ... @@ -14,11 +14,14 @@
14 14  
15 15  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 the same for every FAQ page.
16 16  
17 -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.)
17 +Let us begin by taking a look at what we are going to build. The new application will have the following views:
18 18  
19 -* [[The FAQs Summary View>>attach:FAQsSummary.png]]
20 -* [[A Question and Answer Page in Display Mode>>attach:FAQSheetView.png]]
21 -* [[A Question and Answer Page in Edit Mode>>attach:FAQSheetEdit.png]]
19 +* The FAQs Summary View
20 +{{image reference="FAQsSummary.png"/}}
21 +* A Question and Answer Page in Display Mode
22 +{{image reference="FAQSheetView.PNG"/}}
23 +* A Question and Answer Page in Edit Mode
24 +{{image reference="FAQSheetEdit.PNG"/}}
22 22  
23 23  = Authoring Templates and Page Design Sheets =
24 24  
... ... @@ -39,9 +39,9 @@
39 39  * On the Class Editor wizard entry page (XWiki.XWikiClasses), under the heading "Create a new data type", enter the following web space and class name:
40 40  ** Space: FAQ
41 41  ** Class: FAQ(((
42 -image:CreateANewClass.PNG
45 +{{image reference="CreateANewClass.PNG"/}}
43 43  )))
44 -* Click the "Create this Class" button. You should then see a code page with the following code:(((
47 +* Click the "Create this Class" button. You should then see a page with the following content:(((
45 45  {{code language="none"}}
46 46  {{velocity}}
47 47  ## Replace the default space with the space where you want your documents to be created.
... ... @@ -53,13 +53,15 @@
53 53  {{/code}}
54 54  )))
55 55  
56 -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 "FAQ". The line of code should now look like this:
59 +In the code, change the word "$doc.space" with the name of the space where you want you FAQ pages to be created as the commented instructions in the page code suggest.
60 +The line of code should look like this:
57 57  
58 58  {{code language="none"}}
59 59  #set($defaultSpace = 'FAQ')
60 60  {{/code}}
61 61  
62 -You can also change the default parent of the new FAQ documents that are going to be created. To do so, replace the variables with the name of your document. The line of code should now look like this:
66 +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.
67 +The line of code should look like this:
63 63  
64 64  {{code language="none"}}
65 65  #set($defaultParent = 'FAQ.WebHome')
... ... @@ -67,37 +67,38 @@
67 67  
68 68  Click the "Save & View" button. The class is now created and you should be looking at a page titled "Class: FAQ" that looks like this:
69 69  
70 -image:FAQClass1.PNG
75 +{{image reference="FAQClass1.PNG"/}}
71 71  
72 72  = Add Properties to the Class =
73 73  
74 74  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!
75 75  
76 -* Click on the 'class editor' link: a list of existing XClasses will be displayed
77 -* Note that the link trail in the header is something like "FAQ: XWiki Space » Data types » FAQClass". This shows you that you are indeed on the class page.
81 +* Click on the 'class editor' link
82 +* Note that the link trail in the header is something like "Wiki Home / XWiki Space / Data types / FAQ Class". This shows you that you are indeed on the FAQ class page in Class edit mode.
78 78  
79 -In our document, we'll store both a //question// and an //answer//. So we need a property for each.
84 +In our document, we'll store both a //question// and an //answer//. So we need to create a property for eachof them.
80 80  
81 -* Enter the text //question// in the "NAME" field of the Class Editor panel: the "ADD PROPERTY" panel is in the right column.
82 -* 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.(((
83 -image:AddQuestionProperty.PNG
86 +* Enter the text //question// in the "name" field
87 +* Choose a TextArea type for the property and then click on "Add". The TextArea will ultimately give us a multi-line text field in our authoring template.(((
88 +{{image reference="AddQuestionProperty.PNG"/}}
84 84  )))
85 -* Configure this property with the following values (actually, if you are using the current XWiki version, you don't need to change anything but the Pretty name ? all the rest are the default values):(((
86 -image:QuestionProperty.PNG
90 +* Click on the "+" icon to expand the options for the newly created property
91 +* Change the value of the "Pretty Name" field to "Question"(capital Q):(((
92 +{{image reference="QuestionProperty.PNG"/}}
87 87  )))
88 -* Now add a property called //answer// in the same way that you did for the "question" property (choosing TextArea for the property type)
89 -* 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
90 -* When you are done adding and configuring the properties, click the "Save & View" button.
94 +* Now create another property called //answer// the same way that you did for the previous "question" property (choose TextArea for the property type)
95 +* Expand it from the property list and change the value of the "Pretty Name" field to "Answer"
96 +* When you are done adding and configuring the properties, click the "Save & View" button
91 91  
92 92  = Create the Page Design Sheet =
93 93  
94 94  * After the previous step you are now on the FAQClass page which should look like this:(((
95 -image:FAQClass2.PNG
101 +{{image reference="FAQClass2.PNG"/}}
96 96  )))
97 -* 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.
103 +* 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.
98 98  * Click on "View the sheet document"
99 -* Edit that page in Object edition mode
100 -* Using the menu, add a XWiki.SheetClass object to the page
105 +* Edit that page in Object mode (make sure your user is an [[Advanced user>>platform:Features.PageEditing||anchor=HAdvancedMode]])
106 +* Add a XWiki.SheetClass object to the page
101 101  ** **Adding the XWiki.SheetClass object is important. It's because of this object that users will be sent to form edition mode when editing FAQ entries**
102 102  * Click "Save & View"
103 103  * If you edit the page in wiki mode, you will see the following code:(((
... ... @@ -118,10 +118,13 @@
118 118  * The first line retrieves the FAQ.FAQClass from the wiki
119 119  * Then we iterate through all its properties and display their values for the current document in a definition list.
120 120  
121 -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:
127 +As we mentioned, XWiki provides a mechanism that helps us create sheets used for both View and Edit mode.
128 +This is the display function used in the line:
122 122  
123 -{{code language="none"}}: $doc.display($prop.getName()){{/code}}. It detects the current mode (edit or view) and displays the property referenced by its argument as the mode dictates:
130 +{{code language="none"}}: $doc.display($prop.getName()){{/code}}
124 124  
132 +It detects the current mode (Edit or View) and displays the property referenced by its argument as the mode dictates:
133 +
125 125  * In view mode it will display the value of the property
126 126  * In edit mode it will display a form field that will allow the user to edit it
127 127  
... ... @@ -129,40 +129,51 @@
129 129  
130 130  * Click "Save & View"
131 131  
141 +Next, we neet to bind our class document (FAQ.FAQClass) to this new sheet (FAQ.FAQSheet):
142 +* Edit FAQ.FAQClass in Object mode and add a new object of type XWiki.ClassSheetBinding
143 +* Type in FAQSheet inside the field
144 +* Save & View
145 +
132 132  = Create the Authoring Template =
133 133  
134 134  * Click on "FAQClass" in the breadcrumb. The document should look like this:(((
135 -image:FAQClass3.PNG
149 +{{image reference="FAQClass3.PNG"/}}
136 136  )))
137 -* Notice that now, there is a link for the FAQSheet in place of the button that was previously there
138 -* Click on the "CREATE THE DOCUMENT TEMPLATE" button. The Authoring Template will be automatically created. If you click on "View the template document" and edit that page in wiki mode, you will see the following code:(((
139 -{{code language="none"}}
140 -{{include document="FAQ.FAQClassSheet"/}}
141 -{{/code}}
142 -)))
143 -* Note that we changed the space name preceding the page name also because we want all of our FAQ pages to reside in the same XWiki space
144 -* 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 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.
151 +* Notice that now there is a link for the FAQSheet instead of the button that was previously there
152 +* Click on the "Create the document template" button. The Authoring Template will be automatically created.
145 145  
154 +Note that we changed the space name preceding the page name also because we want all of our FAQ pages to reside in the same XWiki space
155 +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 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.
146 146  Now we need to associate the prototype object with this document to turn it into a true authoring template.
147 147  
148 148  * If you're on the template page, click on "FAQClass" in the breadcrumb to get back to the FAQ Class page
149 149  * At the bottom of the page, look for the following error message: "The template does not contain an object of type FAQClass. Add a FAQ object to the template »."
150 -* Click on "Add a FAQ object to the template »"
160 +* Click on "Add a FAQ object to the template »":(((
161 +{{image reference="FAQObject.png"/}}
162 +)))
151 151  * Congratulations: you just created an Authoring Template! You're almost done now.(((
152 -image:FAQClass4.PNG
164 +{{image reference="FAQClass4.PNG"/}}
153 153  )))
154 154  
155 155  = Create a home page for the FAQ application =
156 156  
157 157  You want your users to be able to see a list of all existing questions and answers and to add new questions. The best way to do this is to put the FAQ application in its own space and to use that space's homepage to display existing questions.
170 +We need to create the FAQ.WebHome page
158 158  
159 -* Use the Create top level menu (when using the Colibri skin) or the Create Panel to create the FAQ.WebHome page (Space = FAQ, Page = WebHome). Alternatively you can navigate to the wiki dashboard page (the home page) and click on the FAQ space which should have a question mark (that's because you've created documents in the FAQ space above but there's no WebHome page created yet).
160 -* Edit the page in Wiki model and input a title such as "FAQs" in the title field
172 +* Click on "FAQClass" in the breadcrumb
173 +* Click on the "+ Add" green button
174 +* Choose FAQ as the "Space name" and type WebHome for the "Page name" field
175 +* Click "Create"
176 +* Type in the title "FAQs" in the title field
177 +* Click "Save & View"
161 161  
162 162  == Displaying existing FAQ entries ==
163 163  
164 -You have 2 options when it comes to displaying existing FAQ entries. You can either use the livetable component or write custom code in order to display them.
181 +You have 2 options when it comes to displaying existing FAQ entries:
165 165  
183 +1. Use the livetable component
184 +1. Write custom code in order to display them
185 +
166 166  === Using the Livetable component ===
167 167  
168 168  In this section, we will show how to use the [[Livetable Macro>>extensions:Extension.Livetable Macro]] to display the existing questions and answers.
... ... @@ -192,10 +192,31 @@
192 192  {{/velocity}}
193 193  {{/code}}
194 194  
195 -* Copy that code and paste it in your page
215 +* Copy this code and paste it as Wiki content inside FAQ.WebHome
196 196  * Click "Save and View"
197 197  * New FAQ entries will now be displayed on the page once you create them
198 198  
219 +The FAQ.WebHome page should look similar to this:
220 +
221 +{{image reference="FAQsLivetable.png"/}}
222 +
223 +Notice how there are some translation keys displayed inside the livetable.
224 +Let's create a translations document and change those keys to actual text:
225 +* Create a new page inside the FAQ space called Translations
226 +* Edit it in Wiki mode and paste this content inside:(((
227 +{{code language="none"}}
228 +faq.question=Question
229 +faq.doc.creationDate=Creation Date
230 +faq._actions=Actions
231 +{{/code}})))
232 +* Save & View
233 +* Edit FAQ.Translations in Object mode and add a new XWiki.TranslationDocumentClass object
234 +* Save & View again
235 +
236 +Now the FAQ.WebHome page should look like this (notice the translations instead of the keys):
237 +
238 +{{image reference="FAQsLivetableWithTranslations.png"/}}
239 +
199 199  === Using custom code ===
200 200  
201 201  You will need to write the following code:
... ... @@ -208,7 +208,7 @@
208 208  ** For each item, the full document is loaded in memory so that values can be retrieved from it
209 209  ** For each document, the question is retrieved and displayed as a link towards the FAQ entry
210 210  
211 -Here's the resulting code:
252 +Here is the resulting code:
212 212  
213 213  {{code language="none"}}
214 214  = Existing FAQ entries =
... ... @@ -227,19 +227,25 @@
227 227  {{/velocity}}
228 228  {{/code}}
229 229  
230 -* Copy that code and paste it in your page
271 +* Copy this code and paste it as Wiki content inside FAQ.WebHome
231 231  * Click "Save and View"
232 232  * New FAQ entries will now be displayed on the page once you create them
233 233  
275 +The FAQ.WebHome page should look similar to this:
276 +
277 +{{image reference="FAQsCustomCode.png"/}}
278 +
234 234  == Creating new FAQ entries ==
235 235  
236 -There are 2 ways for you to let your users create new FAQ entries. You can either declare the FAQ as a template or add a custom creation form.
281 +There are 2 ways for you to let your users create new FAQ entries:
282 +1. Declare the FAQ as a template
283 +1. Add a custom creation form
237 237  
238 238  === Using a Template ===
239 239  
240 -You will have to define a template provider [[as explained on this page>>http://extensions.xwiki.org/xwiki/bin/view/Extension/Administration+Application#HCreatethetemplateprovider]]
287 +You will have to define a template provider [[as explained on this page>>extensions:Extension.Administration Application||anchor=HCreatethetemplateprovider]]
241 241  
242 -Go to your wiki's administration interface, in the "Templates" section. Create a new template provider in the "FAQ" space and name it "FAQTemplateProvider"
289 +Go to your wiki's administration interface, in the "Templates" section (Administration -> Content -> Templates). Create a new template provider in the "FAQ" space and name it "FAQTemplateProvider"
243 243  
244 244  You can then use the following values:
245 245  
... ... @@ -247,7 +247,7 @@
247 247  * Template name "New FAQ entry"
248 248  * Template to use: "FAQ.FAQTemplate"
249 249  
250 -If you'd like, you can restrict FAQ entries so that they're created only in the "FAQ" space. Once you're done, click "Save & View". Your template is now ready to be used! Users who click on the "Add >> Create page" button will now have the option to create a new page using the FAQ template.
297 +If you'd like, you can restrict FAQ entries so that they're created only in the "FAQ" space. Once you're done, click "Save & View". Your template is now ready to be used! Users who click on the "Add >> Page" button will now have the option to create a new page using the FAQ template.
251 251  
252 252  === Custom creation form ===
253 253  
... ... @@ -298,25 +298,33 @@
298 298  {{/velocity}}
299 299  {{/code}}
300 300  
301 -* Copy that code and paste it in your page, below the code that's already there
348 +* Copy this code and paste it as Wiki content inside FAQ.WebHome, below the code that's already there
302 302  * Click "Save and View"
303 -* A form to create new FAQ entries is now available on the page
350 +* A form to create new FAQ entries is now available on the page:(((
351 +{{image reference="FAQsWithForm.png"/}}
352 +)))
304 304  
305 305  = Test the Application =
306 306  
307 -Now let's just create a new document in our application to test it out.
356 +Now let's just create a new document in our application to test it out.
357 +If you previously chose to use a "Custom creation form" for creating new FAQ entries, follow these steps:
308 308  
309 -* Under the "Add a new question" header, enter a document title in the //Document// field and click //Create this FAQ//. For example, enter //What is the meaning of life?//.
359 +* Go to FAQ.WebHome
360 +* Below the "Add a new question" header, enter a question (which will also be used as the document title) in the //Document// field
361 +* Click //Create this FAQ//
310 310  * You can then enter your question in longer form using the //Question// field on the template, like this:(((
311 -image:FAQSheetEdit.PNG
363 +{{image reference="FAQSheetEdit.PNG"/}}
312 312  )))
313 313  * Click //Save & View// and then you will see the newly created document, like this:(((
314 -image:FAQSheetView.PNG
366 +{{image reference="FAQSheetView.PNG"/}}
315 315  )))
316 -* Go back to the "FAQ.WebHome" page to see the list of existing questions
368 +* Go back to the "FAQ.WebHome" page to see the list of existing questions(((
369 +{{image reference="FAQsWithEntry.png"/}}
370 +)))
317 317  
318 318  = Conclusion =
319 319  
320 -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.
374 +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.
375 +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.
321 321  
322 322  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