Velocity Training (XWiki.org)

author	version	line-number	content
		1	{{box cssClass="floatinginfobox" title="Contents"}}
		2	{{toc depth="2" start="2"/}}
		3	{{/box}}
		4
		5	= How to use Velocity in XWiki pages =
		6
		7	== What is it? ==
		8
		9	=== ===
		10
		11	* Velocity is a template language.
		12	* It describes what your page should be.
		13	Which means it controls what you display**.
		14
		15	Examples:
		16
		17	* display the name of the user
		18	* display an image under certain circonstances only
		19	* display a list of all the blog categories
		20
		21	=== Example ===
		22
		23	{{code language="velocity"}}
		24	{{velocity}}
		25	Welcome $xcontext.user !
		26	#if($hasAdmin)
		27	You will see the following picture because you are an administrator:
		28	image:picture.jpg
		29	#end
		30	{{/velocity}}
		31	{{/code}}
		32
		33	Will output:
		34	{{image reference="sample1.png"/}}
		35
		36	=== ===
		37
		38	* With XWiki and Velocity, you can retrieve informations contained in other pages
		39
		40	{{code language="velocity"}}
		41	#set($docRef = $services.model.createDocumentReference('', 'OtherSpace', 'OtherPage'))
		42	#set($document = $xwiki.getDocument($docRef))
		43	The content of the other document is:
		44	$document.getContent()
		45	{{/code}}
		46
		47
		48	{{image reference="serrure.jpg"/}}
		49
		50	=== ===
		51
		52	* or do advanced searches throught the wiki (via the //Query Module//) :
		53	** //« give me all the blog entries posted during the month of july 2012 and that are not archived and that have at least 3 comments and... »//
		54
		55	{{image reference="detective.jpg"/}}
		56
		57	=== ===
		58
		59	* But XWiki also allows you to use Velocity to save things in the wiki.
		60
		61	{{code language="velocity"}}
		62	#set($object = $doc.getObject('XWiki.XWikiUsers'))
		63	$object.set('first_name', 'Nobody')
		64	$doc.save()
		65	{{/code}}
		66
		67
		68	{{image reference="nobody.jpg"/}}
		69
		70	== Principles ==
		71
		72	=== Lines ===
		73
		74	* A line begining by '#' is a Velocity instruction
		75	* All other lines are normal lines
		76
		77	{{code language="velocity"}}
		78	## This is a velocity comment - a comment is never displayed and is used to
		79	## add useful information inside a source code.
		80	#set($myVar = 42)
		81	## The line above was a velocity instruction
		82	This line is a normal line
		83	{{/code}}
		84
		85	=== Variables ===
		86
		87	* A //variable// is like a box that can contain data: text, numbers, objects, etc...
		88	* A variable is always prefixed by a dollar '$'.
		89	* To create a variable, just use the //#set()// Velocity instruction
		90
		91	{{code language="velocity"}}
		92	#set($myVar = 42)
		93	{{/code}}
		94
		95	* If a variable is inside a normal line, the content of the variable will be displayed:
		96
		97	{{code language="velocity"}}
		98	#set($myVar = 42)
		99	I am $myVar years old.
		100	{{/code}}
		101
		102	will display:
		103
		104	{{image reference="variables.png"/}}
		105
		106	=== ===
		107
		108	Some variables are already created by XWiki when you write a Velocity code, and you can use them.
		109
		110
		111	This is some of them:
		112
		113	* //$hasEdit// : this variable tells us if the current user has the edit rights on the current page
		114	* //$isGuest// : this variable tells us if the current user is a guest
		115	* //$doc// : this variable represents the current document.
		116	* //$xwiki// : this special variable is a tool to perform complicated stuffs
		117	* //$request// : gives a lot of informations about the current request (like the referer, the query string, etc...)
		118
		119	=== Methods ===
		120
		121	* Some variable are //objects//. An object can contain //variables// and //methods//.
		122	* A method is like an //action// that the object can perform.
		123	* Some actions give you an information, some just perform something.
		124	* To call them, you write //$someObject.someMethod()// - with the '()'.
		125
		126	Examples:
		127
		128	{{code language="velocity"}}
		129	## will save the current document:
		130	$doc.save()
		131	## will give you the content of the document:
		132	$doc.getContent()
		133	## this method takes a "parameter", a text, which will be the new title:
		134	$doc.setTitle("My new title")
		135	## will give you the current skin
		136	$xwiki.getSkin()
		137	{{/code}}
		138
		139	=== Class ===
		140
		141	* Every object is different, they don't have the same variables and methods.
		142	* But every object is an //instance// of a //class//.
		143	* A //class// is like a model that describes what the object will have.
		144	** For example, the //Document// class has a //save// method, so every objects that are //instances// of //Document// will have the //save// method.
		145	** The //String// class has a //length// variable, so every instances of //String// will have this variable too.
		146
		147	=== ===
		148
		149	* You can use the following code to know what is the class of an object:
		150
		151	{{code language="velocity"}}
		152	#set($myVar = 42)
		153	$myVar.class.name ## will display 'java.lang.Integer'
		154	#set($myVar2 = "This is a text")
		155	$myVar2.class.name ## will display 'java.lang.String'
		156	$doc.class.name ## will display 'com.xpn.xwiki.api.Document'
		157	$xwiki.class.name ## will display 'com.xpn.xwiki.api.XWiki'
		158	{{/code}}
		159
		160
		161	{{image reference="class.jpg"/}}
		162
		163	=== ===
		164
		165	* Now that you know the class of your object, you can google it to have its documentation!
		166	* With this documentation, you will be able to knows what method you can use.
		167	** Example with //java.lang.String//
		168
		169	{{image reference="javadoc.png"/}}
		170
		171	=== ===
		172
		173	* As you may have noticed, the classes come from the //Java// world.
		174	* The documentation about the java classes is called //Javadoc//.
		175	* So you can use the the //Javadoc// for Velocity too!
		176
		177	{{image reference="java.jpg"/}}
		178
		179	== Basic instructions ==
		180
		181	=== Conditions ===
		182
		183	* When you want to display something only under certain circumstances, you can use the //#if// command.
		184
		185	{{code language="velocity"}}
		186	#if($isGuest)
		187	Welcome visitor! You should subscribe to the wiki !
		188	#end
		189	{{/code}}
		190
		191	* You can also use the //#else// command:
		192
		193	{{code language="velocity"}}
		194	#if($isGuest)
		195	Welcome visitor! You should subscribe to the wiki !
		196	#else
		197	Hello $xcontext.user! I'm happy to see a registred user, I hate visitors!
		198	#end
		199	{{/code}}
		200
		201
		202	{{image reference="visitors.jpg"/}}
		203
		204	=== Conditions (bis) ===
		205
		206	* You can compare variables, with the following operators:
		207	//==//** : compare if the variables are equal
		208	//!=//** : say if the variables are different
		209	//>//** : say if the variable is superior to the other
		210	//<//** : do the oposite
		211	//>=//** : say if the variable is superior or equal to the other
		212	//<=//** : say if the variable is inferior or equal to the other
		213
		214	* You can create complicated conditions, with the logic operators:
		215	//&&// : which means "AND"**.
		216	//\|\|// : which means "OR"**.
		217	//!// : which means "NOT"**.
		218
		219	=== Examples ===
		220
		221	{{code language="velocity"}}
		222	#set($a = 12)
		223	#set($b = 28)
		224
		225	#if($a < $b)
		226	A is inferior
		227	#else
		228	B is inferior
		229	#end
		230
		231	#if($a < 20 && $b > 17)
		232	A is inferior than 20 AND B is superior than 17
		233	#end
		234
		235	#if($a == 15 \|\| $b <= 2)
		236	A equals 15 OR B is inferior than 2 or equal
		237	#end
		238	{{/code}}
		239
		240	=== Examples (continued) ===
		241
		242	{{code language="velocity"}}
		243	#set($c = true)
		244
		245	#if($c)
		246	C is true
		247	#end
		248
		249	#if($doc.isNew())
		250	The document is New
		251	#else
		252	The document is an old document
		253	#end
		254
		255	#if(!$doc.isHidden())
		256	The document is NOT hidden
		257	#end
		258	{{/code}}
		259
		260	=== Lists ===
		261
		262	* You can create a list of objects.
		263
		264	{{code language="velocity"}}
		265	#set($myList = ['My first Item', 'My Second Item', 'My third item'])
		266	{{/code}}
		267
		268	* You can add a new element in the list:
		269
		270	{{code language="velocity"}}
		271	$myList.add('My fourth item')
		272	{{/code}}
		273
		274	* You can know how many objects are inside the list:
		275
		276	{{code language="velocity"}}
		277	$myList.size()
		278	{{/code}}
		279
		280	* You can ask if an object is inside the list
		281
		282	{{code language="velocity"}}
		283	$myList.contains('My Second Item') ## which tells me 'true' or 'false'
		284	{{/code}}
		285
		286
		287	{{image reference="teacher.jpg"/}}
		288
		289	=== Example of lists ===
		290
		291	{{code language="velocity"}}
		292	$doc.getComments() ## will give all the comments of the current page !
		293	$doc.getAttachmentList() ## will give all the attachments of the current page
		294	$xwiki.getSpaces() ## will give the list of the different spaces of the wiki
		295	{{/code}}
		296
		297
		298	How could I know the number of spaces in the wiki?
		299
		300	{{code language="velocity"}}
		301	$xwiki.getSpaces().size()
		302	{{/code}}
		303
		304
		305	How could I know if the space 'BlaBla' exists?
		306
		307	{{code language="velocity"}}
		308	$xwiki.getSpaces().contains('BlaBla')
		309	{{/code}}
		310
		311
		312	{{image reference="goodmark.jpg"/}}
		313
		314	=== Foreach ===
		315
		316	* How can I display all the elements of a list in a nice way?
		317	** Use the //#foreach// loop, son.
		318	* Example:
		319
		320	{{code language="velocity"}}
		321	This is the list of all the spaces of the wiki
		322	#set($spaceList = $xwiki.getSpaces())
		323	#foreach($space in $spaceList)
		324	* $space
		325	#end
		326	{{/code}}
		327
		328	* Results:
		329	{{image reference="foreach1.png"/}}
		330
		331	== The API ==
		332
		333	=== ===
		334
		335	* XWiki offers a lot of objects with a lot of methods, to perform a lot of things !
		336	** Delete a document, add a tag to another document, display the list of all blog entries, handle complex formulars, etc...
		337	* This objects & methods are called the API (as //Application Programming Interface//).
		338	* But how can I know what are theses objects and how to use it?
		339
		340	{{image reference="API.jpg"/}}
		341
		342	=== By using the XWiki Script Reference Documentation (SRD) ===
		343
		344	{{image reference="SRD.png"/}}
		345
		346	Go to the [[SRD>>xwiki:ScriptingDocumentation.WebHome]].
		347
		348	=== SRD ===
		349
		350	* The left column lists all the XWiki special variables that make the API.
		351	* Select one of them, and you will have all the methods this special variable offers
		352	** Examples:
		353	*** //$xwiki// offers a method //getDocument()//
		354	*** //$doc// has a method //addAttachment()//
		355	*** etc...
		356
		357	=== Is the API a mess? ===
		358
		359	* While looking at the SRD, we can ask youself //"how many special variables are there?"//
		360	* When we create a variable for our own usage, we have to be sure first to not call it as an existing special variable.
		361	** It's a mess!!!
		362
		363	{{image reference="mess.jpg"/}}
		364
		365	=== Introducing Script Services ===
		366
		367	* In order to make the things cleaner, the plan is to remove a lot of this special variables and replace them by //script services//.
		368	* Script services will become the only API in future.
		369	* All script services are prefixed by //$services//.
		370
		371	{{image reference="datacenter.jpg"/}}
		372
		373	=== ===
		374
		375	* To use a script service, you do it this way:
		376
		377	{{code language="velocity"}}
		378	$services.query ## to perform complicated researchs
		379	$services.localization ## to take care of the languages
		380	$services.officeimporter ## to import office documents
		381	...
		382	{{/code}}
		383
		384	* Of course, it is documented on the SRD!
		385
		386	{{image reference="wayne.jpg"/}}
		387
		388	=== ===
		389
		390	* Sometime, you have different ways to do the same thing:
		391	** Using an old method (which may be declared as //deprecated//).
		392	** Using a script service instead
		393	* Always perfers to use Script Service instead of deprecated APIs!!!
		394
		395	{{code language="velocity"}}
		396	$xwiki.searchDocument() ## allow us to perfom a query with the HQL language
		397	## now please use:
		398	$services.query.hql() ## allow us to perfom a query with the HQL language
		399	## or even better:
		400	$services.query.xwql() ## XWQL language is easier to use
		401	{{/code}}
		402
		403	* Because it's the future!
		404
		405	{{image reference="future.jpg"/}}
		406
		407	== Manipulation of XObjects ==
		408
		409	=== What is an XObject ? ===
		410
		411	* An //XObject// is an object that you can save in the wiki.
		412	* An XObject is attached to a document, and you can see them with the "objects editor" on the wiki.
		413
		414	{{image reference="edit_objects.png"/}}
		415
		416	=== ===
		417
		418	{{image reference="objects.png"/}}
		419
		420	=== XClass ===
		421
		422	* An //XClass// is a //class// (a //description//) for XObjects.
		423	** You can define them using the class editor.
		424	** Or by using //Application Within Minutes//!
		425
		426	=== Class Editor ===
		427
		428	{{image reference="class_editor.png"/}}
		429
		430	=== Application Within Minutes ===
		431
		432	{{image reference="appwithinminutes.png"/}}
		433
		434	=== Why using XClass and XObjects? ===
		435
		436	* It allows us to store structured informations.
		437	** A //Blog Post// (with a //title//, a //date//, a //content//, etc...)
		438	** An //Evaluation document// (with a //remark// for each //category//, a //mark//, etc...)
		439	** An //Holiday Request// (with //dates//, //status//, etc...)
		440
		441	* So the //information// is not lost in a giant document that holds only a big text...
		442	** And you can create //Applications//!
		443
		444	=== XClass is used //everywhere// ===
		445
		446	* Almost everything in XWiki is an XClass and stored as XObjects!
		447	** //Users//
		448	** //Groups//
		449	** //Comments//
		450	** //Tags//
		451	** //Access Rights//
		452	** ....
		453	* Learn to use //XClass// and you can control all your wiki.
		454
		455	=== A comment is an XObject ===
		456
		457	{{image reference="comments.png"/}}
		458
		459	=== A user is an XObject ===
		460
		461	{{image reference="user.png"/}}
		462
		463	=== How to get an XObject with Velocity? ===
		464
		465	{{code language="velocity"}}
		466	## First, get the object
		467	#set($object = $doc.getObject('XWiki.XWikiUsers'))
		468	## The parameter is the name of the class of the object you want to have
		469	## (a document can hold multiple objects of different classes)
		470	## The class name is the Document name where the class is defined
		471
		472	## Display a parameter:
		473	$object.get('first_name')
		474	## the parameter is the name of the field you want to display
		475	## if you are in "edit" mode, an HTML field will be displayed instead of the object value.
		476
		477	## Set values:
		478	$object.set('last_name', 'Bond')
		479	$object.set('first_name', 'James')
		480
		481	## Then save the document if you want your changes to be conserved
		482	## (you can add a comment when you save)
		483	$doc.save('I have changed the name of the user.')
		484	{{/code}}
		485
		486	=== You can rollback what your script has done ===
		487
		488	{{image reference="rollback.png"/}}
		489
		490	== Tips ==
		491
		492	=== How to get a document? ===
		493
		494	* In the past, we used to do:
		495
		496	{{code language="velocity"}}
		497	#set($document = $xwiki.getDocument('Space.Page'))
		498	{{/code}}
		499
		500	* But it's not good, because what if the page name has a dot?
		501
		502	{{code language="velocity"}}
		503	#set($document = $xwiki.getDocument('Space.Pa.ge'))
		504	## ??? What is the Space ? What is the Page ?
		505	{{/code}}
		506
		507	* And what will happen if the document name have accents or weird characters?
		508
		509	=== Solution: use references ! ===
		510
		511	{{code language="velocity"}}
		512	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
		513	#set($document = $xwiki.getDocument($reference))
		514	{{/code}}
		515
		516	* It is better! The reference tool allow us to strictly separate what is the space and what is the page
		517	* And the reference tool will take care of weird characters !
		518
		519	{{code language="velocity"}}
		520	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Pa.ge'))
		521	#set($document = $xwiki.getDocument($reference))
		522	## Not a problem!!!
		523	{{/code}}
		524
		525	=== References ===
		526
		527	* You can get create references for documents in other wikis :
		528
		529	{{code language="velocity"}}
		530	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
		531	{{/code}}
		532
		533	* If you want to get a document in the current wiki, you can set an empty parameter:
		534
		535	{{code language="velocity"}}
		536	#set($reference = $services.model.createDocumentReference('', 'Space', 'Page'))
		537	## the reference point to a document in the current wiki
		538	{{/code}}
		539
		540	=== Use case: changing the name of a user ===
		541
		542	{{code language="velocity"}}
		543	## First, create a reference to their user page
		544	#set($reference = $services.model.createDocumentReference('', 'XWiki', 'ldubost'))
		545	## Then, get its document
		546	#set($document = $xwiki.getDocument($reference))
		547	## Then, get the 'User' object
		548	#set($object = $document.getObject('XWiki.XWikiUsers'))
		549	## Then change their name
		550	$object.set('first_name', 'Harry')
		551	$object.set('last_name', 'Potter')
		552	## And save the document
		553	$document.save()
		554	{{/code}}
		555
		556	=== But remember we know who changes what! ===
		557
		558	{{image reference="history.png"/}}
		559
		560	(% style="text-align: right; margin-top: 20px;" %)
		561	"//I have your name and I know where you live...//"
		562
		563	== Going further ==
		564
		565	=== ===
		566
		567	* See the [[Velocity documentation>>http://velocity.apache.org/]] to have more details about the language itself
		568	* See the [[XWiki Script Guide>>doc:Documentation.DevGuide.Scripting.WebHome]] to have some informations about how to make scripts in XWiki
		569	* See the [[XWiki Query Module>>doc:extensions:Extension.Query Module]] to learn how to do advanced queries
		570	* See the [[XWiki Data Model>>doc:Documentation.DevGuide.DataModel]] to learn how to create your XWiki classes
		571
		572	But in general:
		573
		574	* practice and ask for help!!!
		575
		576	=== ===
		577
		578	* I hope you now have a better idea of what Velocity is and how you can use it in XWiki.
		579
		580	{{image reference="velocity.jpg"/}}