Hide last authors
Ricardo Rodríguez 52.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Vincent Massol 1.1 4
Michael Hamann 117.3 5 {{info}}
Michael Hamann 122.1 6 This page is a draft for [[Creating a FAQ Application (Manual) >>Documentation.DevGuide.Tutorials.FAQTutorial.FAQTutorialManual]]. The rework should be completed until 2021-10-12.
Michael Hamann 117.3 7 {{/info}}
8
Ecaterina Moraru (Valica) 102.1 9 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>>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.
Vincent Massol 96.1 10
Ecaterina Moraru (Valica) 105.1 11 {{info}}
Fawad Ali 117.1 12 It's also possible to follow this tutorial as a [[video tutorial on Youtube>>https://youtu.be/tIzASeJb2Bs]].
Ecaterina Moraru (Valica) 105.1 13 {{/info}}
Vincent Massol 103.1 14
Vincent Massol 96.1 15 = Prerequisites for following the tutorial =
16
Vincent Massol 95.1 17 {{warning}}
Ecaterina Moraru (Valica) 102.1 18 If you've already followed the [[AWM FAQ Tutorial>>Documentation.DevGuide.FAQTutorial.FAQTutorialAWM]] or installed the [[FAQ Application>>extensions:Extension.FAQ Application]] you'll need to do one of 2 things before you can take this tutorial:
Fawad Ali 117.1 19
Vincent Massol 95.1 20 * Delete the ##FAQ## space (if you've followed the AWM FAQ Tutorial) or uninstall the FAQ Application (if you've installed the FAQ Application)
21 * or simply follow the tutorial below but replace the space ##FAQ## with another value everywhere it's used. For example use ##MyFAQ## as the space name instead.
22 {{/warning}}
23
Vincent Massol 101.3 24 You should have [[installed XWiki>>platform:AdminGuide.Installation]] and have a [[basic understanding of how to use it>>platform:Features.WebHome]].
Vincent Massol 54.2 25
Vincent Massol 101.3 26 All through this tutorial you should refer to the [[XWiki Data Model>>platform:DevGuide.DataModel]] for information on XWiki's data model. You might also use the [[XWiki Scripting Guide>>platform: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.
Vincent Massol 54.3 27
Vincent Massol 100.3 28 {{warning}}
Ecaterina Moraru (Valica) 101.4 29 Make sure that your user is an [[Advanced user>>platform:Features.PageEditing||anchor="HAdvancedMode"]] before following this tutorial since you'll need for example to use the wiki editor (##Wiki > Edit## menu).
Vincent Massol 100.2 30 {{/warning}}
31
Silvia Macovei 48.2 32 = Application Overview =
Vincent Massol 1.1 33
Guillaume Lerouge 42.1 34 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 35
Manuel Smeria 80.1 36 Let us begin by taking a look at what we are going to build. The new application will have the following views:
Vincent Massol 1.1 37
Vincent Massol 112.1 38 * The FAQ [[Class>>FAQ.WhatIsAClass]](((
Vincent Massol 111.1 39 {{image reference="FAQsSummary.png"/}}
Vincent Massol 112.1 40 )))
41
Marius Dumitru Florea 115.1 42 * An FAQ entry in View mode (notice that the properties can be edited in-place starting with XWiki 12.4RC1)(((
Vincent Massol 111.1 43 {{image reference="FAQSheetView.PNG"/}}
Vincent Massol 112.1 44 )))
45 * An FAQ entry in Edit mode(((
Vincent Massol 111.1 46 {{image reference="FAQSheetEdit.PNG"/}}
Vincent Massol 112.1 47 )))
Hassan Ali 110.1 48
Silvia Macovei 48.2 49 = Authoring Templates and Page Design Sheets =
Silvia Macovei 48.1 50
Anca Luca 14.1 51 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 52
Silvia Macovei 48.1 53 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 54
Anca Luca 14.1 55 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 56
Silvia Macovei 31.6 57 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 58
Silvia Macovei 48.2 59 = Go to the Class Editor Wizard =
Silvia Macovei 31.6 60
Bart Kummel 104.1 61 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##). (Note that the //title// of this document is "Data types".) This is the homepage of the class wizard creator: you are now ready to start building your FAQs application.
Vincent Massol 1.1 62
Silvia Macovei 48.2 63 = Create the FAQ Class =
Vincent Massol 1.1 64
Vincent Massol 111.1 65 * On the Class Editor wizard entry page (XWiki.XWikiClasses), under the heading "Create a new data type", in the "Title" field, enter ##FAQ## as the name of the page to create:(((
Vincent Massol 84.3 66 {{image reference="CreateANewClass1.png"/}}
Silvia Macovei 48.4 67 )))
Vincent Massol 96.2 68 * As you can see in the Breadcrumb below the new page will be created at location ##XWiki > FAQ##. In practice the Class Wizard will automatically prefix the page name with ##Class## (you could also enter ##FAQClass## as the page name directly).
Vincent Massol 111.1 69 * Now it would be nice to have it created in a new location such as ##FAQ > FAQ Class##. Since the ##FAQ## 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 ##FAQ##.(((
Vincent Massol 84.3 70 {{image reference="CreateANewClass2.png"/}}
71 )))
Vincent Massol 96.2 72 * In technical terms you're creating a page named ##FAQClass## (with a title of "FAQ Class") located in a space also called ##FAQ## and thus the technical reference is ##FAQ.FAQClass##.
Manuel Smeria 80.1 73 * Click the "Create this Class" button. You should then see a page with the following content:(((
Silvia Macovei 48.1 74 {{code language="none"}}
Silvia Macovei 41.1 75 {{velocity}}
Jean SIMARD 60.6 76 ## Replace the default space with the space where you want your documents to be created.
Silvia Macovei 41.1 77 ## Replace the default parent with the one of your choice and save the document.
78 ##
Jean SIMARD 60.6 79 #set($defaultSpace = $doc.space)
80 #set($defaultParent = $doc.fullName)
Silvia Macovei 41.1 81 {{/velocity}}
Silvia Macovei 48.1 82 {{/code}}
Silvia Macovei 48.4 83 )))
Anca Luca 14.1 84
Manuel Smeria 80.1 85 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.
86 The line of code should look like this:
Vincent Massol 1.1 87
Ricardo Rodríguez 52.1 88 {{code language="none"}}
89 #set($defaultSpace = 'FAQ')
90 {{/code}}
Anca Luca 14.1 91
Manuel Smeria 80.1 92 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.
93 The line of code should look like this:
Vincent Massol 1.1 94
Ricardo Rodríguez 52.1 95 {{code language="none"}}
96 #set($defaultParent = 'FAQ.WebHome')
97 {{/code}}
Vincent Massol 1.1 98
Guillaume Lerouge 42.1 99 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 100
Manuel Smeria 80.1 101 {{image reference="FAQClass1.PNG"/}}
georgosn 29.1 102
Silvia Macovei 48.2 103 = Add Properties to the Class =
Vincent Massol 1.1 104
Silvia Macovei 48.3 105 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 106
Manuel Smeria 80.1 107 * Click on the 'class editor' link
Vincent Massol 92.2 108 * Note that the link trail in the header is something like "Wiki Home / FAQ / FAQ Class". This shows you that you are indeed on the FAQ class page in Class edit mode.
Vincent Massol 1.1 109
Vincent Massol 92.3 110 In our document, we'll store both a //question// and an //answer//. So we need to create a property for each of them.
Vincent Massol 1.1 111
Manuel Smeria 80.1 112 * Enter the text //question// in the "name" field
Vincent Massol 111.1 113 * 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.(((
Manuel Smeria 80.1 114 {{image reference="AddQuestionProperty.PNG"/}}
Silvia Macovei 48.4 115 )))
Manuel Smeria 80.1 116 * Click on the "+" icon to expand the options for the newly created property
Vincent Massol 111.1 117 * Change the value of the "Pretty Name" field to "Question"(capital Q):(((
Manuel Smeria 80.1 118 {{image reference="QuestionProperty.PNG"/}}
Silvia Macovei 48.4 119 )))
Manuel Smeria 80.1 120 * Now create another property called //answer// the same way that you did for the previous "question" property (choose TextArea for the property type)
121 * Expand it from the property list and change the value of the "Pretty Name" field to "Answer"
122 * When you are done adding and configuring the properties, click the "Save & View" button
Vincent Massol 1.1 123
Silvia Macovei 48.2 124 = Create the Page Design Sheet =
Vincent Massol 1.1 125
Vincent Massol 111.1 126 * After the previous step you are now on the FAQClass page which should look like this:(((
Manuel Smeria 80.1 127 {{image reference="FAQClass2.PNG"/}}
Silvia Macovei 48.4 128 )))
Manuel Smeria 80.1 129 * 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.
Vincent Massol 92.4 130 * 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. **What this does is important**:
Ogis Tarkan 98.1 131 ** It adds an object of type ##XWiki.ClassSheetBinding## to the ##FAQ.FAQClass" document. Basically it ties the FAQ Class to the Sheet.##
Vincent Massol 92.4 132 ** **It's because of this object that users will be sent to form edition mode when editing FAQ entries**
Vincent Massol 111.1 133 * Now click on "View the sheet document". This takes you to the ##FAQ.FAQSheet## page which you can edit in wiki mode and see its default content:(((
Silvia Macovei 48.1 134 {{code language="none"}}
Silvia Macovei 41.1 135 {{velocity}}
136 ## You can modify this page to customize the presentation of your object.
137 ## At first you should keep the default presentation and just save the document.
Anca Luca 14.1 138
Marius Dumitru Florea 116.1 139 ## We have to use wiki=true because $doc.display() can produce wiki syntax.
140 {{html wiki="true" clean="false"}}
141 ## Load the JavaScript code required to make the object properties editable in-place.
142 #set ($discard = $xwiki.jsfx.use('uicomponents/edit/editableProperty.js', {
143 'forceSkinAction': true,
144 'language': $xcontext.locale
145 }))
146 #set ($editing = $xcontext.action == 'edit')
147 ## The object to display.
148 #set ($xobject = $doc.getObject('FAQ.FAQClass'))
149 ## The class that describes the object properties.
150 #set ($xclass = $xobject.xWikiClass)
151 ## Make sure the following display* method calls use the right object.
152 #set ($discard = $doc.use($xobject))
153 ## Using the xform vertical form layout.
154 <div class="xform">
155 <dl>
156 #foreach ($property in $xclass.properties)
157 <dt #if (!$editing && $hasEdit)
158 class="editableProperty"
159 #set ($xobjectPropertyReference = $xobject.getProperty($property.name).reference)
160 data-property="$escapetool.xml($services.model.serialize($xobjectPropertyReference))"
161 data-property-type="object"#end>
162 ## This must match the id generated by the $doc.display() method below.
163 #set ($propertyId = "${xclass.name}_${xobject.number}_$property.name")
164 <label#if ($editing) for="$escapetool.xml($propertyId)"#end>
165 $escapetool.xml($property.translatedPrettyName)
166 </label>
167 ## Support for specifying a translation key as hint in the property definition.
168 <span class="xHint">$!escapetool.xml($services.localization.render($property.hint))</span>
169 </dt>
170 <dd>$doc.display($property.name)</dd>
171 #end
172 #if (!$xclass.properties || $xclass.properties.size() == 0)
173 ## Keep the empty definition term in order to have valid HTML.
174 <dt></dt>
175 <dd>$escapetool.xml($services.localization.render('xclass.defaultObjectSheet.noProperties'))</dd>
176 #end
177 </dl>
178 </div>
179 {{/html}}
Silvia Macovei 41.1 180 {{/velocity}}
Silvia Macovei 48.1 181 {{/code}}
Guillaume Lerouge 42.1 182
Marius Dumitru Florea 116.1 183 Let's take a moment now and analyze this code:
Silvia Macovei 48.1 184
Marius Dumitru Florea 116.1 185 * first, it loads the JavaScript required for in-place editing
186 * then it retrieves the FAQ object from the current page and the FAQ class defintion
187 * then it iterates through all the FAQ class properties displaying:
188 ** the translated pretty name
189 ** the translated hint
190 ** the value from the FAQ object in view mode, or the form field used to input or modify the value in edit mode
191 * it uses a definition list to display the FAQ object, following the [[Vertical Form>>xwiki:Documentation.DevGuide.FrontendResources.VerticalForms.WebHome]] layout
192
193 As we mentioned, XWiki provides a mechanism that helps us create sheets used for both view and edit mode. This is the ##display## function used in the line:
194
Manuel Smeria 83.1 195 {{code language="none"}}
Marius Dumitru Florea 116.1 196 <dd>$doc.display($property.name)</dd>
Manuel Smeria 83.1 197 {{/code}}
Silvia Macovei 48.1 198
Marius Dumitru Florea 116.1 199 It detects the current mode (edit or view) and displays the property referenced by its argument as the mode dictates:
Manuel Smeria 80.1 200
Marius Dumitru Florea 116.1 201 * in view mode it will display the value of the property
202 * in edit mode it will display a form field that will allow the user to edit it
Guillaume Lerouge 42.1 203
Vincent Massol 101.3 204 This way we can use a single Design Sheet to both display and edit our FAQ entries. See the [[XWiki API reference>>platform:DevGuide.API]] and [[XWiki Scripting>>platform:DevGuide.Scripting]] pages for more details about this.
Marius Dumitru Florea 116.1 205 )))
Guillaume Lerouge 42.1 206 * Click "Save & View"
207
Silvia Macovei 48.2 208 = Create the Authoring Template =
Vincent Massol 1.1 209
Vincent Massol 111.1 210 * Navigate back to the ##FAQ.FAQClass## document (you can use the arrows in the breadcrumb to do so). The document should look like this:(((
Manuel Smeria 80.1 211 {{image reference="FAQClass3.PNG"/}}
Silvia Macovei 48.4 212 )))
Manuel Smeria 80.1 213 * Click on the "Create the document template" button. The Authoring Template will be automatically created.
Vincent Massol 1.1 214
Vincent Massol 101.3 215 Note that earlier, we changed the space name preceding the page name because we wanted all of our FAQ pages to reside in a space named FAQ. 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>>platform:DevGuide.IncludeInVelocity]] for more information regarding this technique.
Guillaume Lerouge 42.1 216
Vincent Massol 92.8 217 Now we need to associate the prototype object with this document to turn it into a true authoring template:
218
219 * If you're on the template page, navigate back to the ##FAQ.FAQClass## document.
220 * At the bottom of the page, look for the following warning message: "The template does not contain an object of type FAQClass. Add a FAQ object to the template »."
Vincent Massol 111.1 221 * Click on "Add a FAQ object to the template »":(((
Manuel Smeria 80.1 222 {{image reference="FAQObject.png"/}}
223 )))
Manuel Smeria 83.1 224
Vincent Massol 92.8 225 Next, we want to remove the title for the newly created template:
Manuel Smeria 83.1 226
Vincent Massol 92.8 227 * Navigate to the ##FAQ.FAQTemplate## document (you can click on the "View the template page (FAQ / FAQ Template)" link for doing that for example.
Manuel Smeria 83.1 228 * Edit this document in Wiki mode
229 * Inside the Title field you have "FAQ Template" written -> delete this text
230 * Save & View
231
232 This step is needed so that all of our future entries don't have "FAQ Template" as their title.
233
234 Congratulations: you just created an Authoring Template! You're almost done now.
Vincent Massol 92.8 235
Manuel Smeria 80.1 236 {{image reference="FAQClass4.PNG"/}}
Ricardo Rodríguez 52.1 237
Alex Cotiugă 105.2 238 = Create the Template Provider =
239
Alex Cotiugă 105.3 240 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.
241 The template provider is created with some default values, but those can be updated to match the needs.
Alex Cotiugă 105.2 242
Alex Cotiugă 107.2 243 {{gallery}}
Alex Cotiugă 108.2 244 image:3-missingTemplateProvider.png
Alex Cotiugă 107.2 245 image:4-addedTemplateProvider.png
246 image:5-templateProviderView.png
247 {{/gallery}}
248
249
Silvia Macovei 48.2 250 = Create a home page for the FAQ application =
Silvia Macovei 38.1 251
Guillaume Lerouge 42.1 252 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 253
Vincent Massol 93.1 254 Thus we now need to create the ##FAQ.WebHome## page
Vincent Massol 1.1 255
Vincent Massol 93.1 256 * Click on "FAQ" in the breadcrumb to navigate to ##FAQ.WebHome## and notice that the page doesn't exist.
257 * Edit it in wiki mode
258 * Type in the title "FAQs"
259
Silvia Macovei 48.2 260 == Displaying existing FAQ entries ==
Vincent Massol 1.1 261
Michael Hamann 122.1 262 You have three options when it comes to displaying existing FAQ entries:
Guillaume Lerouge 55.2 263
Manuel Smeria 80.1 264 1. Use the livetable component
Michael Hamann 122.1 265 1. Use the Live Data macro
Manuel Smeria 80.1 266 1. Write custom code in order to display them
267
Guillaume Lerouge 55.2 268 === Using the Livetable component ===
269
270 In this section, we will show how to use the [[Livetable Macro>>extensions:Extension.Livetable Macro]] to display the existing questions and answers.
271
Guillaume Lerouge 56.1 272 The livetable component will give users the ability to easily list and filter through existing FAQ documents. The macro is made of 3 parts:
273
274 * 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
275 * 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
276 * 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)
277
278 Here is the resulting code:
279
280 {{code language="none"}}
281 {{velocity}}
Guillaume Lerouge 55.2 282 #set($columns = ["question", "doc.creationDate", "_actions"])
283 #set($columnsProperties = {
284 "question" : { "type" : "text", "link" : "view", "html" : "true", "sortable":true },
Guillaume Lerouge 56.1 285 "_actions" : {"actions": ["edit","delete"]}
Guillaume Lerouge 55.2 286 })
287 #set($options = {
288 "className":"FAQ.FAQClass",
289 "translationPrefix" : "faq.",
290 "tagCloud" : true,
291 "rowCount": 10
292 })
293 #livetable("faq" $columns $columnsProperties $options)
Neil Crow 57.1 294 {{/velocity}}
Guillaume Lerouge 55.2 295 {{/code}}
296
Vincent Massol 93.1 297 * Copy this code and paste it as Wiki content (inside ##FAQ.WebHome##)
Guillaume Lerouge 56.1 298 * Click "Save and View"
299 * New FAQ entries will now be displayed on the page once you create them
300
Vincent Massol 93.1 301 The ##FAQ.WebHome## page should look similar to this:
Manuel Smeria 80.1 302
303 {{image reference="FAQsLivetable.png"/}}
304
Vincent Massol 93.1 305 Notice how there are some translation keys displayed inside the livetable. Let's create a translations document and change those keys to actual text:
Manuel Smeria 83.1 306
Vincent Massol 93.1 307 * Create a new page inside the FAQ space called Translations, i.e. at ##FAQ.Translations## (using the "+" button)
Manuel Smeria 80.1 308 * Edit it in Wiki mode and paste this content inside:(((
309 {{code language="none"}}
310 faq.question=Question
311 faq.doc.creationDate=Creation Date
312 faq._actions=Actions
Manuel Smeria 83.1 313 {{/code}}
314 )))
Vincent Massol 93.1 315 * Click "Save & View"
316 * Edit it again in Object mode and add a new ##XWiki.TranslationDocumentClass## object to mark the page as a page containing translations. Make sure to select the right scope. Using "Global" means the translations would be visible to all wikis (and it requires having Programming Rights!) and "Wiki" means it's visible to the current wiki only. Choose "Wiki" as the scope.
317 * Click "Save & View" again
Manuel Smeria 80.1 318
Vincent Massol 93.1 319 Now the ##FAQ.WebHome## page should look like this (notice the translations instead of the keys):
Manuel Smeria 80.1 320
321 {{image reference="FAQsLivetableWithTranslations.png"/}}
322
Michael Hamann 121.1 323 === Using the Live Data macro ===
Michael Hamann 117.3 324
325 {{version since='13.0RC1'}}
Michael Hamann 121.1 326 The [[Live Data Macro>>extensions:Extension.Live Data Macro]] is a modern alternative to the Livetable macro that is more flexible. For example, users can rearrange columns, change the layout to a cards layout or even edit data directly in the table. In this section, we show how it can be used instead of the Livetable macro to give users the ability to easily list and filter the existing FAQ documents.
Michael Hamann 117.3 327
Michael Hamann 122.2 328 You will see many similarities to the Livetable macro in the Live Data macro's configuration as it is using the same data source and is intended to be an alternative to the Livetable macro. However, the configuration syntax is different as this is an XWiki macro instead of a Velocity macro. Apart from some parameters that can be directly supplied to the macro, it supports a JSON content that can contain advanced configurations. Here we configure it similar to the options above. We have:
Michael Hamann 120.1 329
330 * The id, here explicitly chosen to be different from the one above to ensure it is unique if both are on the same page
Michael Hamann 117.3 331 * The columns (properties) to display, here the question, creation date and the actions
332 * The data source, this should be ##liveTable##
333 * The source parameters, here specifying the class of objects to display and the translation prefix
Michael Hamann 120.1 334 * In the extended metadata, we only configure the displayer for the question and specify that the ##link##-displayer should be used, linking to the view action and enabling HTML content such that the HTML code of the question is not escaped but displayed. All other options are left at their default values.
Michael Hamann 117.3 335
336 The resulting code is:
337
338 {{code language="none"}}
339 {{liveData
340 id="faqLD"
341 properties="question, doc.creationDate, _actions"
342 source="liveTable"
343 sourceParameters="className=FAQ.FAQClass&translationPrefix=faq."
344 }}{
345 "meta": {
346 "propertyDescriptors": [
347 {
348 "id": "question",
349 "displayer":
350 {
351 "id": "link",
352 "linkType": "view",
353 "html": true
354 }
355 }
356 ]
357 }
358 }{{/liveData}}
359 {{/code}}
360
361 * Copy this code and paste it as Wiki content (inside ##FAQ.WebHome##)
362 * Click "Save and View"
Michael Hamann 121.1 363 * Unless you already created the translations for the Livetable macro in the section above, you also need to create the translations page as described there
Michael Hamann 117.3 364 * New FAQ entries will now be displayed on the page once you create them
365
366 The ##FAQ.WebHome## page should look similar to this (after creating the translations):
367
368 {{image reference="FAQsLiveData.png"/}}
369
370 {{/version}}
371
Guillaume Lerouge 55.2 372 === Using custom code ===
373
Guillaume Lerouge 42.1 374 You will need to write the following code:
Vincent Massol 1.1 375
Vincent Massol 93.2 376 * A XWQL query that will find all your FAQ documents. Check the [[Query API documentation>>extensions:Extension.Query Module]] to know more about it.
Vincent Massol 93.1 377 ** The XWQL query looks for all documents that have a ##FAQ.FAQClass## object other than the template
Guillaume Lerouge 42.1 378 ** If no document has been created yet, a warning message is displayed
Guillaume Delhumeau 59.2 379 * A piece of velocity code to display all those documents
Guillaume Lerouge 42.1 380 ** The velocity code loops in that list
381 ** For each item, the full document is loaded in memory so that values can be retrieved from it
382 ** For each document, the question is retrieved and displayed as a link towards the FAQ entry
Vincent Massol 1.1 383
Manuel Smeria 80.1 384 Here is the resulting code:
Vincent Massol 1.1 385
Silvia Macovei 48.1 386 {{code language="none"}}
Guillaume Lerouge 42.1 387 = Existing FAQ entries =
Vincent Massol 1.1 388
Guillaume Lerouge 42.1 389 {{velocity}}
Vincent Massol 93.1 390 #set($xwql = "from doc.object(FAQ.FAQClass) as faq where doc.fullName <> 'FAQ.FAQTemplate'")
391 #set($results = $services.query.xwql($xwql).execute())
Guillaume Lerouge 42.1 392 #if($results.empty)
Thibaut Camberlin 49.1 393 No FAQ has been created yet!
Guillaume Lerouge 42.1 394 #else
Thibaut Camberlin 49.1 395 #foreach ($item in $results)
396 #set($faq = $xwiki.getDocument($item))
Thibaut Camberlin 51.1 397 * [[${faq.display("question").replace("<p>", "").replace("</p>", "")}>>${item}]]
Thibaut Camberlin 49.1 398 #end
Guillaume Lerouge 42.1 399 #end
400 {{/velocity}}
Silvia Macovei 48.1 401 {{/code}}
Vincent Massol 1.1 402
Vincent Massol 93.1 403 * Copy this code and paste it as Wiki content inside ##FAQ.WebHome##
Guillaume Lerouge 42.1 404 * Click "Save and View"
405 * New FAQ entries will now be displayed on the page once you create them
Vincent Massol 1.1 406
Vincent Massol 93.1 407 The ##FAQ.WebHome## page should look similar to this:
Manuel Smeria 80.1 408
409 {{image reference="FAQsCustomCode.png"/}}
410
Silvia Macovei 48.2 411 == Creating new FAQ entries ==
Vincent Massol 1.1 412
Manuel Smeria 80.1 413 There are 2 ways for you to let your users create new FAQ entries:
Manuel Smeria 83.1 414
Manuel Smeria 80.1 415 1. Declare the FAQ as a template
416 1. Add a custom creation form
Anca Luca 14.1 417
Guillaume Lerouge 55.1 418 === Using a Template ===
419
Manuel Smeria 83.1 420 You will have to define a template provider [[as explained on this page>>extensions:Extension.Administration Application||anchor="HCreatethetemplateprovider"]]
Guillaume Lerouge 55.1 421
Alex Cotiugă 107.2 422 Go to your wiki's administration interface, in the "Templates" section (Administration -> Content -> Templates). Create a new template provider in the
Vincent Massol 94.1 423 ##FAQ## space and name it ##FAQTemplateProvider##
Guillaume Lerouge 55.1 424
425 You can then use the following values:
426
Vincent Massol 94.1 427 * Provider name: ##FAQ Template Provider##
428 * Template name: ##New FAQ entry##
429 * Template to use: ##FAQ.FAQTemplate##
Guillaume Lerouge 55.1 430
Vincent Massol 94.1 431 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.
Guillaume Lerouge 55.1 432
433 === Custom creation form ===
434
435 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:
436
Guillaume Lerouge 42.1 437 * The first part of the code checks whether the page has a parameter. If so:
438 ** The name of the document that will be created is computed
439 ** A check is done to verify the document doesn't exist yet
440 ** If everything's ok, the user is sent to the new document in inline edition mode
441 * The second part of the code is the actual FAQ creation form
Vincent Massol 94.1 442 ** It builds the name of the document to create it in the ##FAQ## space
Guillaume Lerouge 42.1 443 ** It sets the document parent as being the current document
444 ** It defines the template to use to create the new document
Vincent Massol 1.1 445
Silvia Macovei 48.1 446 {{code language="none"}}
Guillaume Lerouge 42.1 447 {{velocity}}
448 #if("$!request.docName" != '')
449 ## Request for creating a new instance
Clemens Robbenhaar 62.1 450 #set($docName = ${request.docName})
Guillaume Lerouge 47.1 451 #set($targetDocName = "${request.spaceName}.${docName}")
Clemens Robbenhaar 62.1 452 #if(!$xwiki.exists($targetDocName) && $xwiki.hasAccessLevel('edit', $xcontext.user, $targetDocName))
Clemens Robbenhaar 61.1 453 $response.sendRedirect($xwiki.getURL($targetDocName, 'inline', "template=${escapetool.url($request.template)}&parent=${escapetool.url($request.parent)}"))
Guillaume Lerouge 42.1 454 ## Stop processing, since we already sent a redirect.
455 #stop
456 #end
457 #end
Vincent Massol 1.1 458
Guillaume Lerouge 42.1 459 = Add a new question =
460
461 #if("$!targetDocName" != '' && $xwiki.exists($targetDocName))
462 {{warning}}The target document already exists. Please choose a different name, or [[view the existing document>>$targetDocName]]{{/warning}}
463 #elseif("$!targetDocName" != '')
464 {{warning}}You don't have permission to create that document{{/warning}}
465 #end
466
467 {{html}}
468 <form action="" id="newdoc" method="post">
469 <div>
470 <input type="hidden" name="parent" value="${doc.fullName}"/>
471 <input type="hidden" name="template" value="FAQ.FAQTemplate"/>
472 <input type="hidden" name="sheet" value="1"/>
473 <input type="hidden" name="spaceName" value="FAQ"/>
474 Document: <input type="text" name="docName" value="Enter your question here" class="withTip" size="50"/>
475 <span class="buttonwrapper"><input type="submit" value="Create this FAQ" class="button"/></span>
476 </div>
477 </form>
478 {{/html}}
479 {{/velocity}}
Silvia Macovei 48.1 480 {{/code}}
Vincent Massol 1.1 481
Vincent Massol 94.1 482 * Copy this code and paste it as Wiki content inside ##FAQ.WebHome##, below the code that's already there
Guillaume Lerouge 42.1 483 * Click "Save and View"
Vincent Massol 111.1 484 * A form to create new FAQ entries is now available on the page:(((
Manuel Smeria 80.1 485 {{image reference="FAQsWithForm.png"/}}
486 )))
Anca Luca 14.1 487
Silvia Macovei 48.2 488 = Test the Application =
jingbo 27.1 489
Manuel Smeria 80.1 490 Now let's just create a new document in our application to test it out.
Vincent Massol 94.1 491
Manuel Smeria 80.1 492 If you previously chose to use a "Custom creation form" for creating new FAQ entries, follow these steps:
Guillaume Lerouge 42.1 493
Vincent Massol 94.1 494 * Go to ##FAQ.WebHome##
Manuel Smeria 80.1 495 * Below the "Add a new question" header, enter a question (which will also be used as the document title) in the //Document// field
496 * Click //Create this FAQ//
Vincent Massol 111.1 497 * You can then enter your question in longer form using the //Question// field on the template, like this:(((
Manuel Smeria 80.1 498 {{image reference="FAQSheetEdit.PNG"/}}
Silvia Macovei 48.4 499 )))
Vincent Massol 111.1 500 * Click //Save & View// and then you will see the newly created document, like this:(((
Manuel Smeria 80.1 501 {{image reference="FAQSheetView.PNG"/}}
Silvia Macovei 48.4 502 )))
Vincent Massol 111.1 503 * Go back to the ##FAQ.WebHome## page (you can use the breadcrumbs) to see the list of existing questions(((
Manuel Smeria 80.1 504 {{image reference="FAQsWithEntry.png"/}}
505 )))
Guillaume Lerouge 42.1 506
Silvia Macovei 48.2 507 = Conclusion =
Vincent Massol 1.1 508
Manuel Smeria 80.1 509 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.
Vincent Massol 94.1 510
Manuel Smeria 80.1 511 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 512
513 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