Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

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