Last modified by Simon Urli on 2023/10/10

<
From version < 46.1 >
edited by Vincent Massol
on 2009/11/16
To version < 48.1 >
edited by Silvia Macovei
on 2010/02/25
>
Change comment: Document converted from syntax xwiki/1.0 to syntax xwiki/2.0

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.SilviaRusu
Syntax
... ... @@ -1,1 +1,1 @@
1 -XWiki 1.0
1 +XWiki 2.0
Content
... ... @@ -1,43 +1,44 @@
1 -1 Creating a FAQ Application
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.
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.
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 6  
7 -1.1 Application Overview
7 +== Application Overview ==
8 8  
9 9  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.
10 10  
11 11  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.)
12 12  
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}
16 -1.1 Authoring Templates and Page Design Sheets
13 +* [[The FAQs Summary View>>attach:FAQsSummary.png]]
14 +* [[A Question and Answer Page in Display Mode>>attach:FAQSheetView.png]]
15 +* [[A Question and Answer Page in Edit Mode>>attach:FAQSheetEdit.png]]
17 17  
17 +== Authoring Templates and Page Design Sheets ==
18 +
18 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.
19 19  
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.
21 +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.
21 21  
22 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.
23 23  
24 24  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.
25 25  
26 -1.1 Go to the Class Editor Wizard
27 +== Go to the Class Editor Wizard ==
27 27  
28 28  Five pages, which collectively make up a Class Editor Wizard application, have been developed to assist you in this process. 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.
29 29  
30 -1.1 Create the FAQ Class
31 +== Create the FAQ Class ==
31 31  
32 32  * 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:
33 33  ** Space: FAQ
34 34  ** Class: FAQ
35 35  
36 -{image:CreateANewClass.PNG}
37 +image:CreateANewClass.PNG
37 37  
38 38  * Click the "Create this Class" button. You should then see a code page with the following code:
39 39  
40 -{code:none}
41 +{{code language="none"}}
41 41  {{velocity}}
42 42  ## Replace Main with the Space where you want your documents to be created.
43 43  ## Replace the default parent with the one of your choice and save the document.
... ... @@ -47,65 +47,57 @@
47 47  #set($defaultSpace = 'Main')
48 48  {{/velocity}}
49 49  {{include document="XWiki.ClassSheet"/}}
51 +{{/code}}
50 50  
51 -{code}
52 -
53 53  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:
54 54  
55 -{code:none}
56 -#set($defaultSpace = 'FAQ')
55 +{{code language="none"}}#set($defaultSpace = 'FAQ'){{/code}}
57 57  
58 -{code}
59 -
60 60  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:
61 61  
62 -{code:none}
63 -#set($defaultParent = 'FAQ.WebHome')
59 +{{code language="none"}}#set($defaultParent = 'FAQ.WebHome'){{/code}}
64 64  
65 -{code}
66 -
67 67  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:
68 68  
69 -{image:FAQClass1.PNG}
63 +image:FAQClass1.PNG
70 70  
71 -1.1 Add Properties to the Class
65 +== Add Properties to the Class ==
72 72  
73 73  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!
74 74  
75 75  * Click on the 'class editor' link: a list of existing XClasses will be displayed
76 -* 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.
70 +* 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.
77 77  
78 -In our document, we'll store both a ~~question~~ and an ~~answer~~. So we need a property for each.
72 +In our document, we'll store both a //question// and an //answer//. So we need a property for each.
79 79  
80 -* Enter the text ~~question~~ in the "NAME" field of the Class Editor panel: the "ADD PROPERTY" panel is in the right column.
74 +* Enter the text //question// in the "NAME" field of the Class Editor panel: the "ADD PROPERTY" panel is in the right column.
81 81  * 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.
82 82  
83 -{image:AddQuestionProperty.PNG}
77 +image: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 &ndash; all the rest are the default values):
79 +* 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 86  
87 -{image:QuestionProperty.PNG}
81 +image:QuestionProperty.PNG
88 88  
89 -* Now add a property called ~~answer~~ in the same way that you did for the "question" property (choosing TextArea for the property type)
90 -* 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
83 +* Now add a property called //answer// in the same way that you did for the "question" property (choosing TextArea for the property type)
84 +* 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
91 91  * When you are done adding and configuring the properties, click the "Save & View" button.
92 92  
93 -1.1 Create the Page Design Sheet
87 +== Create the Page Design Sheet ==
94 94  
95 95  * After the previous step you are now on the FAQClass page which should look like this:
96 96  
97 -{image:FAQClass2.PNG}
91 +image:FAQClass2.PNG
98 98  
99 99  * 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.
100 100  * Click on "View the sheet document"
101 101  * Edit that page in Object edition mode
102 102  * Using the menu on the right, add a XWiki.SheetClass object to the page
103 -** *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*
97 +** **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**
104 104  * Click "Save & View"
105 105  * If you edit the page in wiki mode, you will see the following code:
106 106  
107 -{code:none}
108 -
101 +{{code language="none"}}
109 109  {{velocity}}
110 110  ## You can modify this page to customize the presentation of your object.
111 111  ## At first you should keep the default presentation and just save the document.
... ... @@ -118,7 +118,7 @@
118 118   : $doc.display($prop.getName())
119 119  #end
120 120  {{/velocity}}
121 -{code}
114 +{{/code}}
122 122  
123 123  Let's take a moment now and analyze this code:
124 124  
... ... @@ -125,29 +125,30 @@
125 125  * The first line retrieves the FAQ.FAQClass from the wiki
126 126  * Then we iterate through all its properties and display their values for the current document in a definition list.
127 127  
128 -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} : $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:
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 +
129 129  * In view mode it will display the value of the property
130 130  * In edit mode it will display a form field that will allow the user to edit it
131 131  
132 -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.
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.
133 133  
134 134  * Click "Save & View"
135 135  
136 -1.1 Create the Authoring Template
132 +== Create the Authoring Template ==
137 137  
138 138  * Click on "FAQClass" in the breadcrumb. The document should look like this:
139 139  
140 -{image:FAQClass3.PNG}
136 +image:FAQClass3.PNG
141 141  
142 142  * Notice that now, there is a link for the FAQSheet in place of the button that was previously there
143 143  * 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:
144 144  
145 -{code:none}
146 -{{include document="FAQ.FAQSheet"/}}
147 -{code}
141 +{{code language="none"}}{{include document="FAQ.FAQSheet"/}}{{/code}}
148 148  
149 149  * 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
150 -* 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.
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 151  
152 152  Now we need to associate the prototype object with this document to turn it into a true authoring template.
153 153  
... ... @@ -156,9 +156,9 @@
156 156  * Click on "Add a FAQ object to the template ยป"
157 157  * Congratulations: you just created an Authoring Template! You're almost done now.
158 158  
159 -{image:FAQClass4.PNG}
153 +image:FAQClass4.PNG
160 160  
161 -1.1 Create a home page for the FAQ application
155 +== Create a home page for the FAQ application ==
162 162  
163 163  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.
164 164  
... ... @@ -165,7 +165,7 @@
165 165  * 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).
166 166  * Edit the page in Wiki model and input a title such as "FAQs" in the title field
167 167  
168 -1.1.1 Displaying existing FAQ entries
162 +=== Displaying existing FAQ entries ===
169 169  
170 170  You will need to write the following code:
171 171  
... ... @@ -179,7 +179,7 @@
179 179  
180 180  Here's the resulting code:
181 181  
182 -{code:none}
176 +{{code language="none"}}
183 183  = Existing FAQ entries =
184 184  
185 185  {{velocity}}
... ... @@ -194,13 +194,13 @@
194 194  #end
195 195  #end
196 196  {{/velocity}}
197 -{code}
191 +{{/code}}
198 198  
199 199  * Copy that code and paste it in your page
200 200  * Click "Save and View"
201 201  * New FAQ entries will now be displayed on the page once you create them
202 202  
203 -1.1.1 Creating new FAQ entries
197 +=== Creating new FAQ entries ===
204 204  
205 205  Now you 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:
206 206  
... ... @@ -214,12 +214,12 @@
214 214  ** It sets the document parent as being the current document
215 215  ** It defines the template to use to create the new document
216 216  
217 -{code:none}
211 +{{code language="none"}}
218 218  {{velocity}}
219 219  #if("$!request.docName" != '')
220 220   ## Request for creating a new instance
221 - #set($targetDocName = "${request.spaceName}.${request.docName}")
222 - #set($targetDocName = $targetDocName.replace("?", "").replace("#", "").trim())
215 + #set($docName = $util.clearName(${request.docName}))
216 + #set($targetDocName = "${request.spaceName}.${docName}")
223 223   #if(!$xwiki.exists($targetDocName) && $xwiki.hasAccessLevel('edit', $context.user, $targetDocName))
224 224   $response.sendRedirect($xwiki.getURL($targetDocName, 'inline', "template=${request.template}&parent=${request.parent}"))
225 225   ## Stop processing, since we already sent a redirect.
... ... @@ -248,30 +248,29 @@
248 248   </form>
249 249  {{/html}}
250 250  {{/velocity}}
251 -{code}
245 +{{/code}}
252 252  
253 253  * Copy that code and paste it in your page, below the code that's already there
254 254  * Click "Save and View"
255 255  * A form to create new FAQ entries is now available on the page
256 256  
257 -1.1 Test the Application
251 +== Test the Application ==
258 258  
259 259  Now let's just create a new document in our application to test it out.
260 260  
261 -* 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?~~.
262 -* You can then enter your question in longer form using the ~~Question~~ field on the template, like this:
255 +* 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?//.
256 +* You can then enter your question in longer form using the //Question// field on the template, like this:
263 263  
264 -{image:FAQSheetEdit.PNG}
258 +image:FAQSheetEdit.PNG
265 265  
266 -* Click ~~Save & View~~ and then you will see the newly created document, like this:
260 +* Click //Save & View// and then you will see the newly created document, like this:
267 267  
268 -{image:FAQSheetView.PNG}
262 +image:FAQSheetView.PNG
269 269  
270 270  * Go back to the "FAQ.WebHome" page to see the list of existing questions
271 271  
272 -1.1 Conclusion
266 +== Conclusion ==
273 273  
274 274  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.
275 275  
276 276  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.
277 -
XWiki.XWikiComments[0]
Comment
... ... @@ -1,2 +1,1 @@
1 1  When you edit a class to insert properties, It is best to define all the properites first because every time you add a new property the edits that have been made to previous properties are erased.
2 -
XWiki.XWikiComments[1]
Comment
... ... @@ -1,9 +1,5 @@
1 1  Following line of code will generate wrong links if a faq entry's question field contain character ">".
2 2  
3 -{code:none}
4 -[${faq.display("question")}>${item}]
5 -{code}
3 +{{code language="none"}}[${faq.display("question")}>${item}]{{/code}}
6 6  
7 -This happens because first > character between sqaure brackets [] is treated specially.
8 -This can happen if you format a question element. For example if you enter "I am *confused* " in question the resulting text would be something like "I am <strong>confused</strong>" which contains html tags including the character >.
9 -
5 +This happens because first > character between sqaure brackets [] is treated specially. This can happen if you format a question element. For example if you enter "I am **confused** " in question the resulting text would be something like "I am {{html clean="false" wiki="true"}}<strong>confused</strong>{{/html}}" which contains html tags including the character >.

Get Connected