Last modified by Simon Urli on 2023/10/10

<
From version < 40.8 >
edited by Silvia Macovei
on 2009/09/29
To version < 42.1 >
edited by Guillaume Lerouge
on 2009/09/29
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.SilviaRusu
1 +XWiki.GuillaumeLerouge
Content
... ... @@ -6,7 +6,7 @@
6 6  
7 7  1.1 Application Overview
8 8  
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 always consistent for every FAQ page.
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  
... ... @@ -23,40 +23,14 @@
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
26 26  
27 -1.1 Get Set with the Class Editor Wizard
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.
28 28  
29 -Five pages, which collectively make up a Class Editor Wizard application, have been developed to assist you in this process. Your first task is to see if you have these pages in your XWiki already. If so, you'll make a link to the wizard app so that you can always access it easily from an administrative page. If you do not have all five pages of the wizard, you'll need to make the missing pages using code provided by this tutorial.
30 -
31 -* 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 first of the five pages that make up the wizard and it is the main entry page to the wizard application.
32 -* Take a moment to bookmark this page or, even better, create a link to it from an administrative page so you can access it more easily in the future.
33 -* Navigate to the XWiki.XWikiClasses page.
34 -
35 -Now, you just need to verify that you have the other four pages that make up the wizard app and create them if you do not. Check if the following classes are listed on the XWikiClasses page:
36 -
37 -* ClassSheet
38 -* ClassTemplate
39 -* ClassItemSheet
40 -* ClassItemTemplate
41 -
42 -If they're not showing up or if they are showing up, but with question marks, you do not have the pages in your XWiki database.
43 -You can either use this provided {attach:ClassWizard.xar} to import the documents in your wiki (see the [Import guide> AdminGuide.ImportExport#HImportingXWikipages] in the XWiki Administration Guide for details on this operation) or copy the page contents from the links below and paste them into the respective pages in your XWiki instance (create them as children of the XWikiClasses page) to ensure that you have all the parts that make up the wizard:
44 -
45 -* Get the [XWikiClasses>http://www.xwiki.org/xwiki/bin/view/XWiki/XWikiClasses?viewer=code&showlinenumbers=0] page code.
46 -* Get the [ClassSheet>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassSheet?viewer=code&showlinenumbers=0] page code
47 -* Get the [ClassTemplate>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassTemplate?viewer=code&showlinenumbers=0] page code.
48 -* Get the [ClassItemSheet>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassItemSheet?viewer=code&showlinenumbers=0] page code.
49 -* Get the [ClassItemTemplate>http://www.xwiki.org/xwiki/bin/view/XWiki/ClassItemTemplate?viewer=code&showlinenumbers=0] page code.
50 -
51 -Once you have all of these pages in place, you are ready to start building your FAQs application.
52 -
53 -Keep in mind that you should always use the Wiki editing mode when editing scripts inside documents.
54 -
55 -
56 56  1.1 Create the FAQ Class
57 57  
58 58  * 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:
59 -** Space: FAQs
33 +** Space: FAQ
60 60  ** Class: FAQ
61 61  
62 62  {image:CreateANewClass.PNG}
... ... @@ -64,60 +64,58 @@
64 64  * Click the "Create this Class" button. You should then see a code page with the following code:
65 65  
66 66  {code:none}
67 -## replace Main with the Space where you want your documents to be created
68 -## replace the default parent with the one of your choice
69 -## Save this template using the ?Save? button
70 -#set( $class = $doc.name.substring(0,$doc.name.indexOf("Class")))
71 -#set($defaultparent = "XWiki.${class}Class")
72 -#set($defaultweb = "Main")
73 -#includeForm("XWiki.ClassSheet")
41 +{{velocity}}
42 +## Replace Main with the Space where you want your documents to be created.
43 +## Replace the default parent with the one of your choice and save the document.
44 +##
45 +#set($className = $doc.name.substring(0, $doc.name.indexOf("Class")))
46 +#set($defaultParent = "${doc.space}.${className}Class")
47 +#set($defaultSpace = 'Main')
48 +{{/velocity}}
49 +{{include document="XWiki.ClassSheet"/}}
74 74  
75 75  {code}
76 76  
77 -In the code, change the word "Main" with the name of the space where you want you FAQ pages to be created as the commented instructions in the page code suggest. Replace the word "Main" with the word "FAQs". The line of code should now look like this:
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:
78 78  
79 79  {code:none}
80 -#set($defaultweb = "FAQs")
56 +#set($defaultSpace = 'FAQ')
81 81  
82 82  {code}
83 83  
84 -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:
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:
85 85  
86 -{image:FAQClass1.PNG}
62 +{code:none}
63 +#set($defaultParent = 'FAQ.WebHome')
87 87  
65 +{code}
88 88  
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:
89 89  
69 +{image:FAQClass1.PNG}
90 90  
91 -
92 -
93 -
94 -
95 95  1.1 Add Properties to the Class
96 96  
97 -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." So, let's just follow those instructions!
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!
98 98  
99 -* Click on the 'class editor' link; a blank page will be displayed.
100 -* Note that the link trail in the header is something like "FAQ: XWiki Space » Data types » FAQClass". Even though the page is blank, this shows you are indeed on the class page.
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.
101 101  
102 102  In our document, we'll store both a ~~question~~ and an ~~answer~~. So we need a property for each.
103 103  
104 -* Enter the text ~~question~~ in the Property Name field of the Class Editor panel (in the column on the right).
105 -* 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.
80 +* Enter the text ~~question~~ in the "NAME" field of the Class Editor panel: the "ADD PROPERTY" panel is in the right column.
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.
106 106  
107 107  {image:AddQuestionProperty.PNG}
108 108  
109 -* Configure this property with the following values (actually, if you are using the current XWiki version, you don't need to change anything else but the Pretty name &ndash; all the rest are the default values):
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):
110 110  
111 111  {image:QuestionProperty.PNG}
112 112  
113 -* Now add a property called ~~answer~~ in the same way that you did for the 'question' property (choosing TextArea for the property type).
114 -* 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.
115 -* When you are done adding and configuring the properties, click the 'Save & View' button.
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
91 +* When you are done adding and configuring the properties, click the "Save & View" button.
116 116  
117 -
118 -
119 -
120 -
121 121  1.1 Create the Page Design Sheet
122 122  
123 123  * After the previous step you are now on the FAQClass page which should look like this:
... ... @@ -124,105 +124,176 @@
124 124  
125 125  {image:FAQClass2.PNG}
126 126  
127 -* Click the first button to create the document sheet (the Page Design Sheet). This sheet determines how your page objects will be rendered to the user. You should see the following page code for the document sheet:
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. If you click on "View the sheet document" and edit that page in wiki mode, you will see the following code:
128 128  
129 129  {code:none}
130 130  
131 -11. You can modify this page to customize the presentation of your object
132 -11. at first you should keep the default presentation.
133 -11. Save this template using the save button.
103 +{{velocity}}
104 +## You can modify this page to customize the presentation of your object.
105 +## At first you should keep the default presentation and just save the document.
106 += Document $doc.name =
134 134  
135 -1 Document $doc.name
108 +#set($class = $doc.getObject('FAQ.FAQClass').xWikiClass)
136 136  
137 -## Change class name to your class name
138 -#set($class = $doc.getObject("XWiki.MyClass").xWikiClass)
139 -#set($hasProps = false)
140 140  #foreach($prop in $class.properties)
141 - #if($velocityCount == 1)
142 - #set($hasProps = true)
143 - <dl>
144 - #end
145 -<dt> ${prop.prettyName} </dt>
146 -<dd>$doc.display($prop.getName())</dd>
111 + ; $prop.prettyName
112 + : $doc.display($prop.getName())
147 147  #end
148 -#if($hasProps)
149 - </dl>
150 -#end
114 +{{/velocity}}
151 151  {code}
152 152  
153 -* Change the class name ~~XWiki.MyClass~~ in the code to ~~FAQ.FAQClass~~ so that the line looks like this:
117 +Let's take a moment now and analyze this code:
154 154  
155 -{code:none}
156 -## Change class name to your class name
157 -#set($class = $doc.getObject("FAQ.FAQClass").xWikiClass)
158 -{code}
119 +* The first line retrieves the FAQ.FAQClass from the wiki
120 +* Then we iterate through all its properties and display their values for the current document in a definition list.
159 159  
160 -* Let's take a moment now and analyze the code: with the line we just modified we retrieve the FAQ.FAQClass from the wiki and then we iterate through all its properties and display their values for the current document in a definition list. As we mentioned, XWiki provides a mechanism that help us create sheets used for both view and edit mode: this is the display function used in the line: {code:none}<dd>$doc.display($prop.getName())</dd>{code} It detects the current mode (edit or view) and displays the property referenced by it's argument as the mode dictates: for view, it is the value of the property, for edit it is a form field that will allow the user to edit it. This way we can use a single Design Sheet for both displaying and editing our FAQs. See the [XWiki API reference > DevGuide.API] and [XWiki Scripting > DevGuide.Scripting] pages for more details.
122 +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:
123 +* In view mode it will display the value of the property
124 +* In edit mode it will display a form field that will allow the user to edit it
161 161  
162 -* Click 'Save & View'.
126 +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.
163 163  
128 +* Click "Save & View"
129 +
164 164  1.1 Create the Authoring Template
165 165  
166 -* Search for the keywords 'FAQ.FAQClass' and click on the document to open it in XWiki again, or click the FAQClass in the breadcrumbs. The document should look like this:
132 +* Click on "FAQClass" in the breadcrumb. The document should look like this:
167 167  
168 168  {image:FAQClass3.PNG}
169 169  
170 -* Notice that now, there is a link for the FAQSheet in place of the button that was previously there.
171 -* Click on the 'Create the document template' button. The Authoring Template will be created with the following page code:
136 +* Notice that now, there is a link for the FAQSheet in place of the button that was previously there
137 +* 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:
172 172  
173 173  {code:none}
174 -## Replace MyName with the real class name.
175 -## Save this template using the save button.
176 -#includeForm("XWiki.MyNameSheet")
140 +{{include document="FAQ.FAQSheet"/}}
177 177  {code}
178 178  
179 -* As the comments instruct, change the words ~~MyName~~ with ~~FAQ~~ so that instead of having ~~XWiki.MyNameSheet~~, you will have ~~FAQ.FAQSheet~~. In this case, we changed the space preceding the page name also because we want all of our FAQ page objects to reside in a unique wiki web space.
180 -* Click 'Save & Continue' to save the document. Remember that all our documents will be copies of the Authoring Template used as a prototype so the content we just saved will be copied in all our FAQs documents and will execute the Design Sheet code in the context of the current document. See the [dedicated page > DevGuide.IncludeInVelocity] for more information regarding this technique.
181 -* Now, we need to associate the prototype object with this document to turn it into a true authoring template.
182 -* On the right side, in the Choose editor list, click ~~Objects~~.
183 -* In the Add Object panel on the right, select FAQ.FAQClass from the drop-down and then click 'Add Object from this Class'. The ~~Question~~ and ~~Answer~~ form fields appear on the page.
184 -* Click 'Save & View'. Congratulations; You just created an Authoring Template!
185 -* Click the FAQ.FAQClass link in the header breadcrumb trail. As you can see, you are almost done!
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.
186 186  
187 -{image:FAQClass4.PNG}
146 +Now we need to associate the prototype object with this document to turn it into a true authoring template.
188 188  
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 »"
151 +* Congratulations: you just created an Authoring Template! You're almost done now.
189 189  
190 -1.1 Test the Application
153 +{image:FAQClass4.PNG}
191 191  
192 -Now let's just create a new document in our application to test it out.
155 +1.1 Create a homepage for your application
193 193  
194 -* Under the "Create a new document" header, enter a document title in the ~~Document~~ field and click ~~Create this document~~. For example, enter ~~What is the meaning of life?~~.
195 -* You can then enter your question in longer form using the ~~Question~~ field on the template, like this:
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.
196 196  
197 -{image:FAQSheetEdit.PNG}
159 +* Go to the "FAQ.WebHome" page
160 +* Edit that page in wiki mode
161 +* Input a title such as "FAQs" in the title field
198 198  
199 -* Click ~~Save & View~~ and then you will see the newly created document, like this:
163 +1.1.1 Displaying existing FAQ entries
200 200  
201 -{image:FAQSheetView.PNG}
165 +You will need to write the following code:
202 202  
203 -* Open the FAQClass document again. You can now see that the FAQ documents you are creating will build in a list on the main entry page to the application, like this:
167 +* A HQL query that will find all your FAQ documents
168 +** The HQL query looks for all documents that have a FAQ.FAQClass object other than the template
169 +** If no document has been created yet, a warning message is displayed
170 +* A piece of velocity tode to display all those documents
171 +** The velocity code loops in that list
172 +** For each item, the full document is loaded in memory so that values can be retrieved from it
173 +** For each document, the question is retrieved and displayed as a link towards the FAQ entry
204 204  
205 -{image:FAQClass5.PNG}
175 +Here's the resulting code:
206 206  
207 -1.1 Displaying the FAQ Questions as summary
177 +{code:none}
178 += Existing FAQ entries =
208 208  
209 -If you want to display the FAQ question instead of the FAQ document name in the summary area, you can proceed as follows:
210 -* Edit the content of the FAQ.FAQClass page
211 -* Replace the #\include\Form("XWiki.ClassSheet") with the content of the XWiki.ClassSheet (go to the XWiki.ClassSheet, edit the content and paste it instead of the #\includeForm command
212 -* Then, after the {code:none}#foreach ($item in $xwiki.searchDocuments($sql)){code} command add the following line {code:none}#set ($faq=$xwiki.getDocument(${item})){code} and replace the {code:none}[$item]{code} with {code:none}[${faq.display("question")}>${item}]{code} The line we added retrieves the document using the document name while the line we replaced displays the "question" property for the document instead of the document name.
213 -* Click "Save & View" and enjoy your new FAQ application.
180 +{{velocity}}
181 +#set($sql = ", BaseObject as obj where obj.name=doc.fullName and obj.className='FAQ.FAQClass' and obj.name<>'FAQ.FAQTemplate'")
182 +#set($results = $xwiki.searchDocuments($sql))
183 +#if($results.empty)
184 +No FAQ has been created yet!
185 +#else
186 +#foreach ($item in $results)
187 +#set($faq = $xwiki.getDocument($item))
188 +* [[${faq.display("question").replace("<p>", "").replace("</p>", "")}>>${item}]]
189 +#end
190 +#end
191 +{{/velocity}}
192 +{code}
214 214  
194 +* Copy that code and paste it in your page
195 +* Click "Save and View"
196 +* New FAQ entries will now be displayed on the page once you create them
215 215  
216 -1.1 Finally, link to the FAQ.FAQClass page
198 +1.1.1 Creating new FAQ entries
217 217  
218 -We don't want our users to have to search for this page using the search engine, so finally pick a spot on your Wiki and make a user-friendly link to FAQ.FAQClass. For example:
200 +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:
219 219  
202 +* The first part of the code checks whether the page has a parameter. If so:
203 +** The name of the document that will be created is computed
204 +** The name is cleaned to remove extra characters
205 +** A check is done to verify the document doesn't exist yet
206 +** If everything's ok, the user is sent to the new document in inline edition mode
207 +* The second part of the code is the actual FAQ creation form
208 +** It builds the name of the document to create it in the "FAQ" space
209 +** It sets the document parent as being the current document
210 +** It defines the template to use to create the new document
211 +
220 220  {code:none}
221 -[Frequently Asked Questions (FAQs) > FAQ.FAQClass]
213 +{{velocity}}
214 +#if("$!request.docName" != '')
215 + ## Request for creating a new instance
216 + #set($targetDocName = "${request.spaceName}.${request.docName}")
217 + #set($targetDocName = $targetDocName.replace("?", "").replace("#", "").trim())
218 + #if(!$xwiki.exists($targetDocName) && $xwiki.hasAccessLevel('edit', $context.user, $targetDocName))
219 + $response.sendRedirect($xwiki.getURL($targetDocName, 'inline', "template=${request.template}&parent=${request.parent}"))
220 + ## Stop processing, since we already sent a redirect.
221 + #stop
222 + #end
223 +#end
224 +
225 += Add a new question =
226 +
227 +#if("$!targetDocName" != '' && $xwiki.exists($targetDocName))
228 + {{warning}}The target document already exists. Please choose a different name, or [[view the existing document>>$targetDocName]]{{/warning}}
229 +#elseif("$!targetDocName" != '')
230 + {{warning}}You don't have permission to create that document{{/warning}}
231 +#end
232 +
233 +{{html}}
234 + <form action="" id="newdoc" method="post">
235 + <div>
236 + <input type="hidden" name="parent" value="${doc.fullName}"/>
237 + <input type="hidden" name="template" value="FAQ.FAQTemplate"/>
238 + <input type="hidden" name="sheet" value="1"/>
239 + <input type="hidden" name="spaceName" value="FAQ"/>
240 + Document: <input type="text" name="docName" value="Enter your question here" class="withTip" size="50"/>
241 + <span class="buttonwrapper"><input type="submit" value="Create this FAQ" class="button"/></span>
242 + </div>
243 + </form>
244 +{{/html}}
245 +{{/velocity}}
222 222  {code}
223 223  
248 +* Copy that code and paste it in your page, below the code that's already there
249 +* Click "Save and View"
250 +* A form to create new FAQ entries is now available on the page
224 224  
252 +1.1 Test the Application
225 225  
254 +Now let's just create a new document in our application to test it out.
255 +
256 +* 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?~~.
257 +* You can then enter your question in longer form using the ~~Question~~ field on the template, like this:
258 +
259 +{image:FAQSheetEdit.PNG}
260 +
261 +* Click ~~Save & View~~ and then you will see the newly created document, like this:
262 +
263 +{image:FAQSheetView.PNG}
264 +
265 +* Open the FAQClass document again. You can now see that the FAQ documents you are creating will build in a list on the main entry page to the application, like this:
266 +
267 +{image:FAQClass5.PNG}
268 +
226 226  1.1 Conclusion
227 227  
228 228  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.

Get Connected