Wiki source code of Creating a FAQ Application

Version 72.1 by Manuel Smeria on 2015/08/27

Hide last authors
Ricardo Rodríguez 52.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Vincent Massol 1.1 4
Silvia Macovei 48.1 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.
Vincent Massol 1.1 6
Vincent Massol 54.2 7 = Pre Requisites for following the tutorial =
8
9 You should have [[installed XWiki>>AdminGuide.Installation]] and have a [[basic understanding of how to use it>>Features.WebHome]].
10
Vincent Massol 54.3 11 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.
12
Silvia Macovei 48.2 13 = Application Overview =
Vincent Massol 1.1 14
Guillaume Lerouge 42.1 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.
Vincent Massol 1.1 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.)
18
Silvia Macovei 48.1 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]]
Vincent Massol 1.1 22
Silvia Macovei 48.2 23 = Authoring Templates and Page Design Sheets =
Silvia Macovei 48.1 24
Anca Luca 14.1 25 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.
Vincent Massol 1.1 26
Silvia Macovei 48.1 27 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.
Vincent Massol 1.1 28
Anca Luca 14.1 29 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.
Vincent Massol 1.1 30
Silvia Macovei 31.6 31 The Page Design Sheet is like a style sheet that defines what each document will look like when 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.
Vincent Massol 1.1 32
Silvia Macovei 48.2 33 = Go to the Class Editor Wizard =
Silvia Macovei 31.6 34
Vincent Massol 62.2 35 Five pages, which collectively make up a [[XClass application>>extensions:Extension.XClass Application]] (a.k.a Class Wizard or Class Editor Wizard), have been developed to assist you in this process. Those page are technical pages hidden by default. To navigate to the wizard home page, go to your profile page, select the Preferences tab, edit the page and choose to view Hidden Documents. Enter a search query for the keyword "XWikiClasses". This should return a document called ##XWikiClasses## in the ##XWiki## space (i.e. ##XWiki.XWikiClasses##). This is the homepage of the class wizard creator: you are now ready to start building your FAQs application.
Vincent Massol 1.1 36
Silvia Macovei 48.2 37 = Create the FAQ Class =
Vincent Massol 1.1 38
Silvia Macovei 32.1 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:
Silvia Macovei 41.1 40 ** Space: FAQ
Ricardo Rodríguez 52.1 41 ** Class: FAQ(((
Silvia Macovei 48.1 42 image:CreateANewClass.PNG
Silvia Macovei 48.4 43 )))
Ricardo Rodríguez 52.1 44 * Click the "Create this Class" button. You should then see a code page with the following code:(((
Silvia Macovei 48.1 45 {{code language="none"}}
Silvia Macovei 41.1 46 {{velocity}}
Jean SIMARD 60.6 47 ## Replace the default space with the space where you want your documents to be created.
Silvia Macovei 41.1 48 ## Replace the default parent with the one of your choice and save the document.
49 ##
Jean SIMARD 60.6 50 #set($defaultSpace = $doc.space)
51 #set($defaultParent = $doc.fullName)
Silvia Macovei 41.1 52 {{/velocity}}
Silvia Macovei 48.1 53 {{/code}}
Silvia Macovei 48.4 54 )))
Anca Luca 14.1 55
Silvia Macovei 41.1 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:
Vincent Massol 1.1 57
Ricardo Rodríguez 52.1 58 {{code language="none"}}
59 #set($defaultSpace = 'FAQ')
60 {{/code}}
Anca Luca 14.1 61
Guillaume Lerouge 42.1 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:
Vincent Massol 1.1 63
Ricardo Rodríguez 52.1 64 {{code language="none"}}
65 #set($defaultParent = 'FAQ.WebHome')
66 {{/code}}
Vincent Massol 1.1 67
Guillaume Lerouge 42.1 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:
georgosn 28.1 69
Silvia Macovei 48.1 70 image:FAQClass1.PNG
georgosn 29.1 71
Silvia Macovei 48.2 72 = Add Properties to the Class =
Vincent Massol 1.1 73
Silvia Macovei 48.3 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!
Vincent Massol 1.1 75
Guillaume Lerouge 42.1 76 * Click on the 'class editor' link: a list of existing XClasses will be displayed
Silvia Macovei 48.1 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.
Vincent Massol 1.1 78
Silvia Macovei 48.1 79 In our document, we'll store both a //question// and an //answer//. So we need a property for each.
Vincent Massol 1.1 80
Silvia Macovei 48.1 81 * Enter the text //question// in the "NAME" field of the Class Editor panel: the "ADD PROPERTY" panel is in the right column.
Ricardo Rodríguez 52.1 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.(((
Silvia Macovei 48.1 83 image:AddQuestionProperty.PNG
Silvia Macovei 48.4 84 )))
Ricardo Rodríguez 52.1 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):(((
Silvia Macovei 48.1 86 image:QuestionProperty.PNG
Silvia Macovei 48.4 87 )))
Silvia Macovei 48.1 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
Guillaume Lerouge 42.1 90 * When you are done adding and configuring the properties, click the "Save & View" button.
Vincent Massol 1.1 91
Silvia Macovei 48.2 92 = Create the Page Design Sheet =
Vincent Massol 1.1 93
Ricardo Rodríguez 52.1 94 * After the previous step you are now on the FAQClass page which should look like this:(((
Silvia Macovei 48.1 95 image:FAQClass2.PNG
Silvia Macovei 48.4 96 )))
Guillaume Lerouge 44.1 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.
98 * Click on "View the sheet document"
99 * Edit that page in Object edition mode
Jean SIMARD 60.5 100 * Using the menu, add a XWiki.SheetClass object to the page
Silvia Macovei 48.1 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**
Guillaume Lerouge 44.1 102 * Click "Save & View"
Ricardo Rodríguez 52.1 103 * If you edit the page in wiki mode, you will see the following code:(((
Silvia Macovei 48.1 104 {{code language="none"}}
Silvia Macovei 41.1 105 {{velocity}}
106 ## You can modify this page to customize the presentation of your object.
107 ## At first you should keep the default presentation and just save the document.
Anca Luca 14.1 108
Silvia Macovei 41.1 109 #set($class = $doc.getObject('FAQ.FAQClass').xWikiClass)
Vincent Massol 12.1 110 #foreach($prop in $class.properties)
Silvia Macovei 41.1 111 ; $prop.prettyName
112 : $doc.display($prop.getName())
Vincent Massol 12.1 113 #end
Silvia Macovei 41.1 114 {{/velocity}}
Silvia Macovei 48.1 115 {{/code}}
Ricardo Rodríguez 52.1 116 )))Let's take a moment now and analyze this code:
Anca Luca 14.1 117
Guillaume Lerouge 42.1 118 * The first line retrieves the FAQ.FAQClass from the wiki
119 * Then we iterate through all its properties and display their values for the current document in a definition list.
120
Silvia Macovei 48.1 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:
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:
124
Guillaume Lerouge 42.1 125 * In view mode it will display the value of the property
126 * In edit mode it will display a form field that will allow the user to edit it
127
Silvia Macovei 48.1 128 This way we can use a single Design Sheet to both display and edit our FAQ entries. See the [[XWiki API reference>>DevGuide.API]] and [[XWiki Scripting>>DevGuide.Scripting]] pages for more details about this.
Guillaume Lerouge 42.1 129
130 * Click "Save & View"
131
Silvia Macovei 48.2 132 = Create the Authoring Template =
Vincent Massol 1.1 133
Ricardo Rodríguez 52.1 134 * Click on "FAQClass" in the breadcrumb. The document should look like this:(((
Silvia Macovei 48.1 135 image:FAQClass3.PNG
Silvia Macovei 48.4 136 )))
Guillaume Lerouge 42.1 137 * Notice that now, there is a link for the FAQSheet in place of the button that was previously there
Ricardo Rodríguez 52.1 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"}}
petskratt 59.1 140 {{include document="FAQ.FAQClassSheet"/}}
Ricardo Rodríguez 52.1 141 {{/code}}
Silvia Macovei 48.4 142 )))
Guillaume Lerouge 42.1 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
Silvia Macovei 48.1 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.
Vincent Massol 1.1 145
Guillaume Lerouge 42.1 146 Now we need to associate the prototype object with this document to turn it into a true authoring template.
147
148 * If you're on the template page, click on "FAQClass" in the breadcrumb to get back to the FAQ Class page
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 »"
Ricardo Rodríguez 52.1 151 * Congratulations: you just created an Authoring Template! You're almost done now.(((
Silvia Macovei 48.1 152 image:FAQClass4.PNG
Silvia Macovei 48.4 153 )))
Ricardo Rodríguez 52.1 154
Silvia Macovei 48.2 155 = Create a home page for the FAQ application =
Silvia Macovei 38.1 156
Guillaume Lerouge 42.1 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.
Vincent Massol 1.1 158
Vincent Massol 46.1 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
Vincent Massol 1.1 161
Silvia Macovei 48.2 162 == Displaying existing FAQ entries ==
Vincent Massol 1.1 163
Guillaume Lerouge 55.2 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.
165
166 === Using the Livetable component ===
167
168 In this section, we will show how to use the [[Livetable Macro>>extensions:Extension.Livetable Macro]] to display the existing questions and answers.
169
Guillaume Lerouge 56.1 170 The livetable component will give users the ability to easily list and filter through existing FAQ documents. The macro is made of 3 parts:
171
172 * The list of columns: for each entry, we will display the question, the date when it was created and a special column that lets users quickly modify entries
173 * The properties of each column: for each column, we will define how it should be displayed, whether it should link to the entry and whether it should be filterable
174 * The livetable options: those are options related to the display of the livetable (in this case we will to display a tag cloud and 10 rows by default)
175
176 Here is the resulting code:
177
178 {{code language="none"}}
179 {{velocity}}
Guillaume Lerouge 55.2 180 #set($columns = ["question", "doc.creationDate", "_actions"])
181 #set($columnsProperties = {
182 "question" : { "type" : "text", "link" : "view", "html" : "true", "sortable":true },
Guillaume Lerouge 56.1 183 "_actions" : {"actions": ["edit","delete"]}
Guillaume Lerouge 55.2 184 })
185 #set($options = {
186 "className":"FAQ.FAQClass",
187 "translationPrefix" : "faq.",
188 "tagCloud" : true,
189 "rowCount": 10
190 })
191 #livetable("faq" $columns $columnsProperties $options)
crowne 57.1 192 {{/velocity}}
Guillaume Lerouge 55.2 193 {{/code}}
194
Guillaume Lerouge 56.1 195 * Copy that code and paste it in your page
196 * Click "Save and View"
197 * New FAQ entries will now be displayed on the page once you create them
198
Guillaume Lerouge 55.2 199 === Using custom code ===
200
Guillaume Lerouge 42.1 201 You will need to write the following code:
Vincent Massol 1.1 202
Guillaume Lerouge 42.1 203 * A HQL query that will find all your FAQ documents
204 ** The HQL query looks for all documents that have a FAQ.FAQClass object other than the template
205 ** If no document has been created yet, a warning message is displayed
Guillaume Delhumeau 59.2 206 * A piece of velocity code to display all those documents
Guillaume Lerouge 42.1 207 ** The velocity code loops in that list
208 ** For each item, the full document is loaded in memory so that values can be retrieved from it
209 ** For each document, the question is retrieved and displayed as a link towards the FAQ entry
Vincent Massol 1.1 210
Guillaume Lerouge 42.1 211 Here's the resulting code:
Vincent Massol 1.1 212
Silvia Macovei 48.1 213 {{code language="none"}}
Guillaume Lerouge 42.1 214 = Existing FAQ entries =
Vincent Massol 1.1 215
Guillaume Lerouge 42.1 216 {{velocity}}
Thibaut Camberlin 50.1 217 #set($sql = ", BaseObject as obj where obj.name = doc.fullName and obj.className = 'FAQ.FAQClass' and obj.name <> 'FAQ.FAQTemplate'")
Guillaume Lerouge 42.1 218 #set($results = $xwiki.searchDocuments($sql))
219 #if($results.empty)
Thibaut Camberlin 49.1 220 No FAQ has been created yet!
Guillaume Lerouge 42.1 221 #else
Thibaut Camberlin 49.1 222 #foreach ($item in $results)
223 #set($faq = $xwiki.getDocument($item))
Thibaut Camberlin 51.1 224 * [[${faq.display("question").replace("<p>", "").replace("</p>", "")}>>${item}]]
Thibaut Camberlin 49.1 225 #end
Guillaume Lerouge 42.1 226 #end
227 {{/velocity}}
Silvia Macovei 48.1 228 {{/code}}
Vincent Massol 1.1 229
Guillaume Lerouge 42.1 230 * Copy that code and paste it in your page
231 * Click "Save and View"
232 * New FAQ entries will now be displayed on the page once you create them
Vincent Massol 1.1 233
Silvia Macovei 48.2 234 == Creating new FAQ entries ==
Vincent Massol 1.1 235
Guillaume Lerouge 55.1 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.
Anca Luca 14.1 237
Guillaume Lerouge 55.1 238 === Using a Template ===
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]]
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"
243
244 You can then use the following values:
245
246 * Provider name: "FAQ Template Provider"
247 * Template name "New FAQ entry"
Jean SIMARD 60.8 248 * Template to use: "FAQ.FAQTemplate"
Guillaume Lerouge 55.1 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.
251
252 === Custom creation form ===
253
254 If you choose this option, you will need to write some code to let your users create new FAQ entries. To do this, you will have to create a form in which the user can enter the name of the questions she wants to create. Once typed in, the form calls the same page to trigger the new document creation based on the parameters entered by the user:
255
Guillaume Lerouge 42.1 256 * The first part of the code checks whether the page has a parameter. If so:
257 ** The name of the document that will be created is computed
258 ** A check is done to verify the document doesn't exist yet
259 ** If everything's ok, the user is sent to the new document in inline edition mode
260 * The second part of the code is the actual FAQ creation form
261 ** It builds the name of the document to create it in the "FAQ" space
262 ** It sets the document parent as being the current document
263 ** It defines the template to use to create the new document
Vincent Massol 1.1 264
Silvia Macovei 48.1 265 {{code language="none"}}
Guillaume Lerouge 42.1 266 {{velocity}}
267 #if("$!request.docName" != '')
268 ## Request for creating a new instance
Clemens Robbenhaar 62.1 269 #set($docName = ${request.docName})
Guillaume Lerouge 47.1 270 #set($targetDocName = "${request.spaceName}.${docName}")
Clemens Robbenhaar 62.1 271 #if(!$xwiki.exists($targetDocName) && $xwiki.hasAccessLevel('edit', $xcontext.user, $targetDocName))
Clemens Robbenhaar 61.1 272 $response.sendRedirect($xwiki.getURL($targetDocName, 'inline', "template=${escapetool.url($request.template)}&parent=${escapetool.url($request.parent)}"))
Guillaume Lerouge 42.1 273 ## Stop processing, since we already sent a redirect.
274 #stop
275 #end
276 #end
Vincent Massol 1.1 277
Guillaume Lerouge 42.1 278 = Add a new question =
279
280 #if("$!targetDocName" != '' && $xwiki.exists($targetDocName))
281 {{warning}}The target document already exists. Please choose a different name, or [[view the existing document>>$targetDocName]]{{/warning}}
282 #elseif("$!targetDocName" != '')
283 {{warning}}You don't have permission to create that document{{/warning}}
284 #end
285
286 {{html}}
287 <form action="" id="newdoc" method="post">
288 <div>
289 <input type="hidden" name="parent" value="${doc.fullName}"/>
290 <input type="hidden" name="template" value="FAQ.FAQTemplate"/>
291 <input type="hidden" name="sheet" value="1"/>
292 <input type="hidden" name="spaceName" value="FAQ"/>
293 Document: <input type="text" name="docName" value="Enter your question here" class="withTip" size="50"/>
294 <span class="buttonwrapper"><input type="submit" value="Create this FAQ" class="button"/></span>
295 </div>
296 </form>
297 {{/html}}
298 {{/velocity}}
Silvia Macovei 48.1 299 {{/code}}
Vincent Massol 1.1 300
Guillaume Lerouge 42.1 301 * Copy that code and paste it in your page, below the code that's already there
302 * Click "Save and View"
303 * A form to create new FAQ entries is now available on the page
Anca Luca 14.1 304
Silvia Macovei 48.2 305 = Test the Application =
jingbo 27.1 306
Guillaume Lerouge 42.1 307 Now let's just create a new document in our application to test it out.
308
Silvia Macovei 48.1 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?//.
Ricardo Rodríguez 52.1 310 * You can then enter your question in longer form using the //Question// field on the template, like this:(((
Silvia Macovei 48.1 311 image:FAQSheetEdit.PNG
Silvia Macovei 48.4 312 )))
Ricardo Rodríguez 52.1 313 * Click //Save & View// and then you will see the newly created document, like this:(((
Silvia Macovei 48.1 314 image:FAQSheetView.PNG
Silvia Macovei 48.4 315 )))
Guillaume Lerouge 43.1 316 * Go back to the "FAQ.WebHome" page to see the list of existing questions
Guillaume Lerouge 42.1 317
Silvia Macovei 48.2 318 = Conclusion =
Vincent Massol 1.1 319
Anca Luca 14.1 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.
Vincent Massol 1.1 321
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