Wiki source code of Creating a FAQ Application

Version 81.1 by Manuel Smeria on 2015/08/27

version	line-number	content
52.1	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
1.1	4
80.1	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.
1.1	6
80.1	7	= Prerequisites for following the tutorial =
54.2	8
	9	You should have [[installed XWiki>>AdminGuide.Installation]] and have a [[basic understanding of how to use it>>Features.WebHome]].
	10
54.3	11	All through this tutorial you should refer to the [[XWiki Data Model>>DevGuide.DataModel]] for information on XWiki's data model. You might also use the [[XWiki Scripting Guide>>DevGuide.Scripting]] to get you started with scripting in XWiki and manipulating XWiki objects. In addition, this tutorial will introduce the concepts of Authoring Templates and Page Design Sheets, patterns that you will find particularly useful in creating XWiki applications. Completing this tutorial is a recommended prerequisite for anyone who wants to build custom applications on the XWiki engine.
	12
48.2	13	= Application Overview =
1.1	14
42.1	15	The FAQ application allows users to post a question by entering the question into a simple form field and then submitting the form. The question then appears in a list along with all other questions that have been previously posted. Users can click on the questions to view both the question and answer in a consistently styled view. If the question has not yet been answered, any user can post an answer to the question by editing the page. In edit mode, the page will display a web form that is the same for every FAQ page.
1.1	16
80.1	17	Let us begin by taking a look at what we are going to build. The new application will have the following views:
1.1	18
80.1	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"/}}
1.1	25
48.2	26	= Authoring Templates and Page Design Sheets =
48.1	27
14.1	28	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.
1.1	29
48.1	30	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.
1.1	31
14.1	32	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.
1.1	33
31.6	34	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.
1.1	35
48.2	36	= Go to the Class Editor Wizard =
31.6	37
62.2	38	Five pages, which collectively make up a [[XClass application>>extensions:Extension.XClass Application]] (a.k.a Class Wizard or Class Editor Wizard), have been developed to assist you in this process. Those page are technical pages hidden by default. To navigate to the wizard home page, go to your profile page, select the Preferences tab, edit the page and choose to view Hidden Documents. Enter a search query for the keyword "XWikiClasses". This should return a document called ##XWikiClasses## in the ##XWiki## space (i.e. ##XWiki.XWikiClasses##). This is the homepage of the class wizard creator: you are now ready to start building your FAQs application.
1.1	39
48.2	40	= Create the FAQ Class =
1.1	41
32.1	42	* 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:
41.1	43	** Space: FAQ
52.1	44	** Class: FAQ(((
80.1	45	{{image reference="CreateANewClass.PNG"/}}
48.4	46	)))
80.1	47	* Click the "Create this Class" button. You should then see a page with the following content:(((
48.1	48	{{code language="none"}}
41.1	49	{{velocity}}
60.6	50	## Replace the default space with the space where you want your documents to be created.
41.1	51	## Replace the default parent with the one of your choice and save the document.
	52	##
60.6	53	#set($defaultSpace = $doc.space)
	54	#set($defaultParent = $doc.fullName)
41.1	55	{{/velocity}}
48.1	56	{{/code}}
48.4	57	)))
14.1	58
80.1	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:
1.1	61
52.1	62	{{code language="none"}}
	63	#set($defaultSpace = 'FAQ')
	64	{{/code}}
14.1	65
80.1	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:
1.1	68
52.1	69	{{code language="none"}}
	70	#set($defaultParent = 'FAQ.WebHome')
	71	{{/code}}
1.1	72
42.1	73	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:
28.1	74
80.1	75	{{image reference="FAQClass1.PNG"/}}
29.1	76
48.2	77	= Add Properties to the Class =
1.1	78
48.3	79	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!
1.1	80
80.1	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.
1.1	83
80.1	84	In our document, we'll store both a //question// and an //answer//. So we need to create a property for eachof them.
1.1	85
80.1	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"/}}
48.4	89	)))
80.1	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"/}}
48.4	93	)))
80.1	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
1.1	97
48.2	98	= Create the Page Design Sheet =
1.1	99
52.1	100	* After the previous step you are now on the FAQClass page which should look like this:(((
80.1	101	{{image reference="FAQClass2.PNG"/}}
48.4	102	)))
80.1	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.
44.1	104	* Click on "View the sheet document"
80.1	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
48.1	107	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**
44.1	108	* Click "Save & View"
52.1	109	* If you edit the page in wiki mode, you will see the following code:(((
48.1	110	{{code language="none"}}
41.1	111	{{velocity}}
	112	## You can modify this page to customize the presentation of your object.
	113	## At first you should keep the default presentation and just save the document.
14.1	114
41.1	115	#set($class = $doc.getObject('FAQ.FAQClass').xWikiClass)
12.1	116	#foreach($prop in $class.properties)
41.1	117	; $prop.prettyName
	118	: $doc.display($prop.getName())
12.1	119	#end
41.1	120	{{/velocity}}
48.1	121	{{/code}}
52.1	122	)))Let's take a moment now and analyze this code:
14.1	123
42.1	124	* The first line retrieves the FAQ.FAQClass from the wiki
	125	* Then we iterate through all its properties and display their values for the current document in a definition list.
	126
80.1	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:
48.1	129
80.1	130	{{code language="none"}}: $doc.display($prop.getName()){{/code}}
48.1	131
80.1	132	It detects the current mode (Edit or View) and displays the property referenced by its argument as the mode dictates:
	133
42.1	134	* In view mode it will display the value of the property
	135	* In edit mode it will display a form field that will allow the user to edit it
	136
48.1	137	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.
42.1	138
	139	* Click "Save & View"
	140
80.1	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
48.2	146	= Create the Authoring Template =
1.1	147
52.1	148	* Click on "FAQClass" in the breadcrumb. The document should look like this:(((
80.1	149	{{image reference="FAQClass3.PNG"/}}
48.4	150	)))
80.1	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.
1.1	153
80.1	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.
42.1	156	Now we need to associate the prototype object with this document to turn it into a true authoring template.
	157
	158	* If you're on the template page, click on "FAQClass" in the breadcrumb to get back to the FAQ Class page
	159	* 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 »."
80.1	160	* Click on "Add a FAQ object to the template »":(((
	161	{{image reference="FAQObject.png"/}}
	162	)))
52.1	163	* Congratulations: you just created an Authoring Template! You're almost done now.(((
80.1	164	{{image reference="FAQClass4.PNG"/}}
48.4	165	)))
52.1	166
48.2	167	= Create a home page for the FAQ application =
38.1	168
42.1	169	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.
80.1	170	We need to create the FAQ.WebHome page
1.1	171
80.1	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"
1.1	178
48.2	179	== Displaying existing FAQ entries ==
1.1	180
80.1	181	You have 2 options when it comes to displaying existing FAQ entries:
55.2	182
80.1	183	1. Use the livetable component
	184	1. Write custom code in order to display them
	185
55.2	186	=== Using the Livetable component ===
	187
	188	In this section, we will show how to use the [[Livetable Macro>>extensions:Extension.Livetable Macro]] to display the existing questions and answers.
	189
56.1	190	The livetable component will give users the ability to easily list and filter through existing FAQ documents. The macro is made of 3 parts:
	191
	192	* 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
	193	* 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
	194	* 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)
	195
	196	Here is the resulting code:
	197
	198	{{code language="none"}}
	199	{{velocity}}
55.2	200	#set($columns = ["question", "doc.creationDate", "_actions"])
	201	#set($columnsProperties = {
	202	"question" : { "type" : "text", "link" : "view", "html" : "true", "sortable":true },
56.1	203	"_actions" : {"actions": ["edit","delete"]}
55.2	204	})
	205	#set($options = {
	206	"className":"FAQ.FAQClass",
	207	"translationPrefix" : "faq.",
	208	"tagCloud" : true,
	209	"rowCount": 10
	210	})
	211	#livetable("faq" $columns $columnsProperties $options)
57.1	212	{{/velocity}}
55.2	213	{{/code}}
	214
80.1	215	* Copy this code and paste it as Wiki content inside FAQ.WebHome
56.1	216	* Click "Save and View"
	217	* New FAQ entries will now be displayed on the page once you create them
	218
80.1	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
55.2	240	=== Using custom code ===
	241
42.1	242	You will need to write the following code:
1.1	243
42.1	244	* A HQL query that will find all your FAQ documents
	245	** The HQL query looks for all documents that have a FAQ.FAQClass object other than the template
	246	** If no document has been created yet, a warning message is displayed
59.2	247	* A piece of velocity code to display all those documents
42.1	248	** The velocity code loops in that list
	249	** For each item, the full document is loaded in memory so that values can be retrieved from it
	250	** For each document, the question is retrieved and displayed as a link towards the FAQ entry
1.1	251
80.1	252	Here is the resulting code:
1.1	253
48.1	254	{{code language="none"}}
42.1	255	= Existing FAQ entries =
1.1	256
42.1	257	{{velocity}}
50.1	258	#set($sql = ", BaseObject as obj where obj.name = doc.fullName and obj.className = 'FAQ.FAQClass' and obj.name <> 'FAQ.FAQTemplate'")
42.1	259	#set($results = $xwiki.searchDocuments($sql))
	260	#if($results.empty)
49.1	261	No FAQ has been created yet!
42.1	262	#else
49.1	263	#foreach ($item in $results)
	264	#set($faq = $xwiki.getDocument($item))
51.1	265	* [[${faq.display("question").replace("<p>", "").replace("</p>", "")}>>${item}]]
49.1	266	#end
42.1	267	#end
	268	{{/velocity}}
48.1	269	{{/code}}
1.1	270
80.1	271	* Copy this code and paste it as Wiki content inside FAQ.WebHome
42.1	272	* Click "Save and View"
	273	* New FAQ entries will now be displayed on the page once you create them
1.1	274
80.1	275	The FAQ.WebHome page should look similar to this:
	276
	277	{{image reference="FAQsCustomCode.png"/}}
	278
48.2	279	== Creating new FAQ entries ==
1.1	280
80.1	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
14.1	284
55.1	285	=== Using a Template ===
	286
80.1	287	You will have to define a template provider [[as explained on this page>>extensions:Extension.Administration Application\|\|anchor=HCreatethetemplateprovider]]
55.1	288
80.1	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"
55.1	290
	291	You can then use the following values:
	292
	293	* Provider name: "FAQ Template Provider"
	294	* Template name "New FAQ entry"
60.8	295	* Template to use: "FAQ.FAQTemplate"
55.1	296
80.1	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.
55.1	298
	299	=== Custom creation form ===
	300
	301	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:
	302
42.1	303	* The first part of the code checks whether the page has a parameter. If so:
	304	** The name of the document that will be created is computed
	305	** A check is done to verify the document doesn't exist yet
	306	** If everything's ok, the user is sent to the new document in inline edition mode
	307	* The second part of the code is the actual FAQ creation form
	308	** It builds the name of the document to create it in the "FAQ" space
	309	** It sets the document parent as being the current document
	310	** It defines the template to use to create the new document
1.1	311
48.1	312	{{code language="none"}}
42.1	313	{{velocity}}
	314	#if("$!request.docName" != '')
	315	## Request for creating a new instance
62.1	316	#set($docName = ${request.docName})
47.1	317	#set($targetDocName = "${request.spaceName}.${docName}")
62.1	318	#if(!$xwiki.exists($targetDocName) && $xwiki.hasAccessLevel('edit', $xcontext.user, $targetDocName))
61.1	319	$response.sendRedirect($xwiki.getURL($targetDocName, 'inline', "template=${escapetool.url($request.template)}&parent=${escapetool.url($request.parent)}"))
42.1	320	## Stop processing, since we already sent a redirect.
	321	#stop
	322	#end
	323	#end
1.1	324
42.1	325	= Add a new question =
	326
	327	#if("$!targetDocName" != '' && $xwiki.exists($targetDocName))
	328	{{warning}}The target document already exists. Please choose a different name, or [[view the existing document>>$targetDocName]]{{/warning}}
	329	#elseif("$!targetDocName" != '')
	330	{{warning}}You don't have permission to create that document{{/warning}}
	331	#end
	332
	333	{{html}}
	334	<form action="" id="newdoc" method="post">
	335	<div>
	336	<input type="hidden" name="parent" value="${doc.fullName}"/>
	337	<input type="hidden" name="template" value="FAQ.FAQTemplate"/>
	338	<input type="hidden" name="sheet" value="1"/>
	339	<input type="hidden" name="spaceName" value="FAQ"/>
	340	Document: <input type="text" name="docName" value="Enter your question here" class="withTip" size="50"/>
	341	<span class="buttonwrapper"><input type="submit" value="Create this FAQ" class="button"/></span>
	342	</div>
	343	</form>
	344	{{/html}}
	345	{{/velocity}}
48.1	346	{{/code}}
1.1	347
80.1	348	* Copy this code and paste it as Wiki content inside FAQ.WebHome, below the code that's already there
42.1	349	* Click "Save and View"
80.1	350	* A form to create new FAQ entries is now available on the page:(((
	351	{{image reference="FAQsWithForm.png"/}}
	352	)))
14.1	353
48.2	354	= Test the Application =
27.1	355
80.1	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:
42.1	358
80.1	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//
52.1	362	* You can then enter your question in longer form using the //Question// field on the template, like this:(((
80.1	363	{{image reference="FAQSheetEdit.PNG"/}}
48.4	364	)))
52.1	365	* Click //Save & View// and then you will see the newly created document, like this:(((
80.1	366	{{image reference="FAQSheetView.PNG"/}}
48.4	367	)))
80.1	368	* Go back to the "FAQ.WebHome" page to see the list of existing questions(((
	369	{{image reference="FAQsWithEntry.png"/}}
	370	)))
42.1	371
48.2	372	= Conclusion =
1.1	373
80.1	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.
1.1	376
	377	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.

Wiki source code of Creating a FAQ Application

Quick Links

Let us know

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected