Wiki source code of XWiki Velocity Training

Version 33.1 by Guillaume Delhumeau on 2013/12/09

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

Wiki source code of XWiki Velocity Training

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected