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 control 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 contains 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 contains //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 notice, 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 circounstances, 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 equals
		208	//!=//** : say if the variables are differents
		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 (bis) ===
		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	=== Example of lists ===
		287
		288	{{code language="velocity"}}
		289	$doc.getComments() ## will give all the comments of the current page !
		290	$doc.getAttachmentList() ## will give all the attachments of the current page
		291	$xwiki.getSpaces() ## will give the list of the different spaces of the wiki
		292	{{/code}}
		293
		294
		295	How could I know the number of spaces in the wiki?
		296
		297	{{code language="velocity"}}
		298	...
		299	{{/code}}
		300
		301
		302	How could I know if the space 'BlaBla' exists?
		303
		304	{{code language="velocity"}}
		305	...
		306	{{/code}}
		307
		308
		309	{{image reference="teacher.jpg"/}}
		310
		311	=== Example of lists ===
		312
		313	{{code language="velocity"}}
		314	$doc.getComments() ## will give all the comments of the current page !
		315	$doc.getAttachmentList() ## will give all the attachments of the current page
		316	$xwiki.getSpaces() ## will give the list of the different spaces of the wiki
		317	{{/code}}
		318
		319
		320	How could I know the number of spaces in the wiki?
		321
		322	{{code language="velocity"}}
		323	$xwiki.getSpaces().size()
		324	{{/code}}
		325
		326
		327	How could I know if the space 'BlaBla' exists?
		328
		329	{{code language="velocity"}}
		330	$xwiki.getSpaces().contains('BlaBla')
		331	{{/code}}
		332
		333
		334	{{image reference="goodmark.jpg"/}}
		335
		336	=== Foreach ===
		337
		338	* How can I display all the elements of a list in a nice way?
		339	** Use the //#foreach// loop, son.
		340	* Example:
		341
		342	{{code language="velocity"}}
		343	This is the list of all the spaces of the wiki
		344	#set($spaceList = $xwiki.getSpaces())
		345	#foreach($space in $spaceList)
		346	* $space
		347	#end
		348	{{/code}}
		349
		350	* Results:
		351	{{image reference="foreach1.png"/}}
		352
		353	== The API ==
		354
		355	=== ===
		356
		357	* XWiki offers a lot of objects with a lot of methods, to perform a lot of things !
		358	** Delete a document, add a tag to an other document, display the list of all blog entries, handle complex formulars, etc...
		359	* This objets & methods are called the API (as //Application Programming Interface//).
		360	* But how can I know what are theses objects and how to use it?
		361
		362	{{image reference="API.jpg"/}}
		363
		364	=== By using the XWiki Script Reference Documentation (SRD) ===
		365
		366	{{image reference="SRD.png"/}}
		367
		368	Go to the [[SRD>>xwiki:ScriptingDocumentation.WebHome]].
		369
		370	=== SRD ===
		371
		372	* The left column lists all the XWiki special variables that make the API.
		373	* Select one of them, and you will have all the methods this special variable offers
		374	** Examples:
		375	*** //$xwiki// offers a method //getDocument()//
		376	*** //$doc// has a method //addAttachment()//
		377	*** etc...
		378
		379	=== Is the API a mess? ===
		380
		381	* While looking at the SRD, we can ask youself //"how many special variables is there?"//
		382	* When we create a variable for our own usage, we have to be sure first to not call it as an existing special variable.
		383	** It's a mess!!!
		384
		385	{{image reference="mess.jpg"/}}
		386
		387	=== Introducing Script Services ===
		388
		389	* In order to make the things cleaner, the plan is to remove a lot of this special variables and replace them by //script services//.
		390	* Script services will become the only API in future.
		391	* All script services are prefixed by //$services//.
		392
		393	{{image reference="datacenter.jpg"/}}
		394
		395	=== ===
		396
		397	* To use a script service, you do it this way:
		398
		399	{{code language="velocity"}}
		400	$services.query ## to perform complicated researchs
		401	$services.localization ## to take care of the languages
		402	$services.officeimporter ## to import office documents
		403	...
		404	{{/code}}
		405
		406	* Of course, it is documented on the SRD!
		407
		408	{{image reference="wayne.jpg"/}}
		409
		410	=== ===
		411
		412	* Sometime, you have different ways to do the same thing:
		413	** Using an old method (which may be declared as //deprecated//).
		414	** Using a script service instead
		415	* Always perfers to use Script Service instead of deprecated APIs!!!
		416
		417	{{code language="velocity"}}
		418	$xwiki.searchDocument() ## allow us to perfom a query with the HQL language
		419	## now please use:
		420	$services.query.hql() ## allow us to perfom a query with the HQL language
		421	## or even better:
		422	$services.query.xwql() ## XWQL language is easier to use
		423	{{/code}}
		424
		425	* Because it's the future!
		426
		427	{{image reference="future.jpg"/}}
		428
		429	== Manipulation of XObjects ==
		430
		431	=== What is an XObject ? ===
		432
		433	* An //XObject// is an object that you can save in the wiki.
		434	* An XObject is attached on a document, and you can see them with the "objects editor" on the wiki.
		435
		436	{{image reference="edit_objects.png"/}}
		437
		438	=== ===
		439
		440	{{image reference="objects.png"/}}
		441
		442	=== XClass ===
		443
		444	* An //XClass// is a //class// (a //description//) for XObjects.
		445	** You can define them using the class editor.
		446	** Or by using //Application Within Minutes//!
		447
		448	=== Class Editor ===
		449
		450	{{image reference="class_editor.png"/}}
		451
		452	=== Application Within Minutes ===
		453
		454	{{image reference="appwithinminutes.png"/}}
		455
		456	=== Why using XClass and XObjects? ===
		457
		458	* It allows us to store structured informations.
		459	** A //Blog Post// (with a //title//, a //date//, a //content//, etc...)
		460	** An //Evaluation document// (with a //remark// for each //category//, a //mark//, etc...)
		461	** An //Holiday Request// (with //dates//, //status//, etc...)
		462
		463	* So the //information// is not lost in a giant document that holds only a big text...
		464	** And you can create //Applications//!
		465
		466	=== XClass is used //everywhere// ===
		467
		468	* Almost everything in XWiki is an XClass and stored as XObjects!
		469	** //Users//
		470	** //Groups//
		471	** //Comments//
		472	** //Tags//
		473	** //Access Rights//
		474	** ....
		475	* Learn to use //XClass// and you can control all your wiki.
		476
		477	=== A comment is an XObject ===
		478
		479	{{image reference="comments.png"/}}
		480
		481	=== A user is an XObject ===
		482
		483	{{image reference="user.png"/}}
		484
		485	=== How to get an XObject with Velocity? ===
		486
		487	{{code language="velocity"}}
		488	## First, get the object
		489	#set($object = $doc.getObject('XWiki.XWikiUsers'))
		490	## The parameter is the name of the class of the object you want to have
		491	## (a document can hold multiple objects of different classes)
		492	## The class name is the Document name where the class is defined
		493
		494	## Display a parameter:
		495	$object.display('first_name', 'view')
		496	## the parameter is the name of the field you want to display
		497	## if you are in "edit" mode, an HTML field will be displayed instead of the object value.
		498
		499	## Set values:
		500	$object.set('last_name', 'Bond')
		501	$object.set('first_name', 'James')
		502
		503	## Then save the document if you want your changes to be conserved
		504	## (you can add a comment when you save)
		505	$doc.save('I have changed the name of the user.')
		506	{{/code}}
		507
		508	=== You can rollback what your script have done ===
		509
		510	{{image reference="rollback.png"/}}
		511
		512	== Tips ==
		513
		514	=== How to get an other document? ===
		515
		516	* In the past, we used to do:
		517
		518	{{code language="velocity"}}
		519	#set($document = $xwiki.getDocument('Space.Page'))
		520	{{/code}}
		521
		522	* But it's not good, because what if the page name has a dot?
		523
		524	{{code language="velocity"}}
		525	#set($document = $xwiki.getDocument('Space.Pa.ge'))
		526	## ??? What is the Space ? What is the Page ?
		527	{{/code}}
		528
		529	* And what will happen if the document name have accents or weird characters?
		530
		531	=== Solution: use references ! ===
		532
		533	{{code language="velocity"}}
		534	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
		535	#set($document = $xwiki.getDocument($reference))
		536	{{/code}}
		537
		538	* It is better! The reference tool allow us to strictly separe what is the space and what is the page
		539	* And the reference tool will take care of weird characters !
		540
		541	{{code language="velocity"}}
		542	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Pa.ge'))
		543	#set($document = $xwiki.getDocument($reference))
		544	## Not a problem!!!
		545	{{/code}}
		546
		547	=== References ===
		548
		549	* You can get create references for documents in other wikis :
		550
		551	{{code language="velocity"}}
		552	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
		553	{{/code}}
		554
		555	* If you want to get a document in the current wiki, you can set an empty parameter:
		556
		557	{{code language="velocity"}}
		558	#set($reference = $services.model.createDocumentReference('', 'Space', 'Page'))
		559	## the reference point a document in the current wiki
		560	{{/code}}
		561
		562	=== Use case: changing the name of a user ===
		563
		564	{{code language="velocity"}}
		565	## First, create a reference to his user page
		566	#set($reference = $services.model.createDocumentReference('', 'XWiki', 'ldubost'))
		567	## Then, get its document
		568	#set($document = $xwiki.getDocument($reference))
		569	## Then, get the 'User' object
		570	#set($object = $document.getObject('XWiki.XWikiUsers'))
		571	## Then change his name
		572	$object.set('first_name', 'Harry')
		573	$object.set('last_name', 'Potter')
		574	## And save the document
		575	$document.save()
		576	{{/code}}
		577
		578	=== But remember we know who changes what! ===
		579
		580	{{image reference="history.png"/}}
		581
		582	(% style="text-align: right; margin-top: 20px;" %)
		583	"//I have your name and I know where you live...//"
		584
		585	== Going further ==
		586
		587	=== ===
		588
		589	* See the [[Velocity documentation>>http://velocity.apache.org/]] to have more details about the language itself
		590	* See the [[XWiki Script Guide>>doc:Documentation.DevGuide.Scripting.WebHome]] to have some informations about how to make scripts in XWiki
		591	* See the [[XWiki Query Module>>doc:extensions:Extension.Query Module]] to learn how to do advanced queries
		592	* See the [[XWiki Data Model>>doc:Documentation.DevGuide.DataModel]] to learn how to create your XWiki classes
		593
		594	But in general:
		595
		596	* practice and ask for help!!!
		597
		598	=== ===
		599
		600	* I hope you now have a better idea of what Velocity is and how you can use it in XWiki.
		601
		602	{{image reference="velocity.jpg"/}}