Wiki source code of Velocity Training

Version 36.4 by Ecaterina Moraru (Valica) on 2017/09/05

version	line-number	content
1.1	1	= How to use Velocity in XWiki pages =
36.1	2
1.1	3	by Guillaume Delhumeau
	4	July 2013
	5
	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:
36.1	16
1.1	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 ===
36.1	22
32.1	23	{{code language="velocity"}}
34.1	24	{{velocity}}
1.1	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
34.2	30	{{/velocity}}
32.1	31	{{/code}}
1.1	32
	33	Will output:
36.1	34	{{image reference="sample1.png"/}}
1.1	35
36.1	36	=== ===
	37
1.1	38	* With XWiki and Velocity, you can retrieve informations contained in other pages
	39
32.2	40	{{code language="velocity"}}
1.1	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()
32.2	45	{{/code}}
1.1	46
	47
33.1	48	{{image reference="serrure.jpg"/}}
1.1	49
36.1	50	=== ===
1.1	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
33.1	55	{{image reference="detective.jpg"/}}
1.1	56
	57	=== ===
36.1	58
1.1	59	* But XWiki also allows you to use Velocity to save things in the wiki.
	60
32.2	61	{{code language="velocity"}}
1.1	62	#set($object = $doc.getObject('XWiki.XWikiUsers'))
	63	$object.set('first_name', 'Nobody')
	64	$doc.save()
32.2	65	{{/code}}
1.1	66
	67
33.1	68	{{image reference="nobody.jpg"/}}
1.1	69
	70	== Principles ==
	71
	72	=== Lines ===
36.1	73
1.1	74	* A line begining by '#' is a Velocity instruction
	75	* All other lines are normal lines
	76
32.2	77	{{code language="velocity"}}
1.1	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
32.2	83	{{/code}}
1.1	84
	85	=== Variables ===
36.1	86
1.1	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
32.2	91	{{code language="velocity"}}
1.1	92	#set($myVar = 42)
32.2	93	{{/code}}
1.1	94
	95	* If a variable is inside a normal line, the content of the variable will be displayed:
	96
32.2	97	{{code language="velocity"}}
1.1	98	#set($myVar = 42)
	99	I am $myVar years old.
32.2	100	{{/code}}
1.1	101
	102	will display:
	103
33.1	104	{{image reference="variables.png"/}}
1.1	105
36.1	106	=== ===
	107
1.1	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:
36.1	112
1.1	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 ===
36.1	120
1.1	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
32.2	128	{{code language="velocity"}}
1.1	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()
32.2	137	{{/code}}
1.1	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
36.1	147	=== ===
	148
1.1	149	* You can use the following code to know what is the class of an object:
	150
32.2	151	{{code language="velocity"}}
1.1	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'
32.2	158	{{/code}}
1.1	159
	160
33.1	161	{{image reference="class.jpg"/}}
1.1	162
36.1	163	=== ===
	164
1.1	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
33.1	169	{{image reference="javadoc.png"/}}
1.1	170
36.1	171	=== ===
	172
1.1	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
33.1	177	{{image reference="java.jpg"/}}
1.1	178
	179	== Basic instructions ==
36.1	180
1.1	181	=== Conditions ===
36.1	182
1.1	183	* When you want to display something only under certain circounstances, you can use the //#if// command.
	184
32.2	185	{{code language="velocity"}}
1.1	186	#if($isGuest)
	187	Welcome visitor! You should subscribe to the wiki !
	188	#end
32.2	189	{{/code}}
1.1	190
	191	* You can also use the //#else// command:
	192
32.2	193	{{code language="velocity"}}
1.1	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
32.2	199	{{/code}}
1.1	200
	201
33.1	202	{{image reference="visitors.jpg"/}}
1.1	203
	204	=== Conditions (bis) ===
36.1	205
1.1	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 ===
36.1	220
32.2	221	{{code language="velocity"}}
1.1	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
32.2	238	{{/code}}
1.1	239
	240	=== Examples (bis) ===
36.1	241
32.2	242	{{code language="velocity"}}
1.1	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
32.2	258	{{/code}}
1.1	259
	260	=== Lists ===
36.1	261
1.1	262	* You can create a list of objects.
	263
32.2	264	{{code language="velocity"}}
1.1	265	#set($myList = ['My first Item', 'My Second Item', 'My third item'])
32.2	266	{{/code}}
1.1	267
	268	* You can add a new element in the list:
	269
32.2	270	{{code language="velocity"}}
1.1	271	$myList.add('My fourth item')
32.2	272	{{/code}}
1.1	273
	274	* You can know how many objects are inside the list:
	275
32.2	276	{{code language="velocity"}}
1.1	277	$myList.size()
32.2	278	{{/code}}
1.1	279
	280	* You can ask if an object is inside the list
	281
32.2	282	{{code language="velocity"}}
1.1	283	$myList.contains('My Second Item') ## which tells me 'true' or 'false'
32.2	284	{{/code}}
1.1	285
	286	=== Example of lists ===
36.1	287
32.2	288	{{code language="velocity"}}
1.1	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
32.2	292	{{/code}}
1.1	293
	294
	295	How could I know the number of spaces in the wiki?
	296
32.2	297	{{code language="velocity"}}
1.1	298	...
32.2	299	{{/code}}
1.1	300
	301
	302	How could I know if the space 'BlaBla' exists?
	303
32.2	304	{{code language="velocity"}}
1.1	305	...
32.2	306	{{/code}}
1.1	307
	308
33.1	309	{{image reference="teacher.jpg"/}}
1.1	310
	311	=== Example of lists ===
36.1	312
32.2	313	{{code language="velocity"}}
1.1	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
32.2	317	{{/code}}
1.1	318
	319
	320	How could I know the number of spaces in the wiki?
	321
32.2	322	{{code language="velocity"}}
1.1	323	$xwiki.getSpaces().size()
32.2	324	{{/code}}
1.1	325
	326
	327	How could I know if the space 'BlaBla' exists?
	328
32.2	329	{{code language="velocity"}}
1.1	330	$xwiki.getSpaces().contains('BlaBla')
32.2	331	{{/code}}
1.1	332
	333
33.1	334	{{image reference="goodmark.jpg"/}}
1.1	335
	336	=== Foreach ===
36.1	337
1.1	338	* How can I display all the elements of a list in a nice way?
	339	** Use the //#foreach// loop, son.
	340	* Example:
	341
32.2	342	{{code language="velocity"}}
1.1	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
32.2	348	{{/code}}
1.1	349
	350	* Results:
33.1	351	{{image reference="foreach1.png"/}}
1.1	352
	353	== The API ==
	354
36.1	355	=== ===
	356
1.1	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
33.1	362	{{image reference="API.jpg"/}}
1.1	363
	364	=== By using the XWiki Script Reference Documentation (SRD) ===
	365
33.1	366	{{image reference="SRD.png"/}}
1.1	367
36.3	368	[[http:~~/~~/platform.xwiki.org/xwiki/bin/view/SRD/Navigation?xpage=embed>>doc:platform:SRD.Navigation\|\|queryString="xpage=embed"]]
1.1	369
	370	=== SRD ===
36.1	371
1.1	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
36.1	379	=== Is the API a mess? ===
	380
1.1	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
33.1	385	{{image reference="mess.jpg"/}}
1.1	386
	387	=== Introducing Script Services ===
36.1	388
1.1	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
33.1	393	{{image reference="datacenter.jpg"/}}
1.1	394
36.1	395	=== ===
	396
1.1	397	* To use a script service, you do it this way:
	398
32.2	399	{{code language="velocity"}}
1.1	400	$services.query ## to perform complicated researchs
	401	$services.localization ## to take care of the languages
	402	$services.officeimporter ## to import office documents
	403	...
32.2	404	{{/code}}
1.1	405
	406	* Of course, it is documented on the SRD!
	407
33.1	408	{{image reference="wayne.jpg"/}}
1.1	409
36.1	410	=== ===
	411
1.1	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
32.2	417	{{code language="velocity"}}
1.1	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
32.2	423	{{/code}}
1.1	424
	425	* Because it's the future!
	426
33.1	427	{{image reference="future.jpg"/}}
1.1	428
	429	== Manipulation of XObjects ==
36.1	430
1.1	431	=== What is an XObject ? ===
36.1	432
1.1	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
33.1	436	{{image reference="edit_objects.png"/}}
1.1	437
36.1	438	=== ===
	439
33.1	440	{{image reference="objects.png"/}}
1.1	441
	442	=== XClass ===
36.1	443
1.1	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 ===
36.1	449
33.1	450	{{image reference="class_editor.png"/}}
1.1	451
	452	=== Application Within Minutes ===
36.1	453
33.1	454	{{image reference="appwithinminutes.png"/}}
1.1	455
	456	=== Why using XClass and XObjects? ===
36.1	457
1.1	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// ===
36.1	467
1.1	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 ===
36.1	478
33.1	479	{{image reference="comments.png"/}}
1.1	480
	481	=== A user is an XObject ===
36.1	482
33.1	483	{{image reference="user.png"/}}
1.1	484
	485	=== How to get an XObject with Velocity? ===
	486
32.2	487	{{code language="velocity"}}
1.1	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.')
32.2	506	{{/code}}
1.1	507
	508	=== You can rollback what your script have done ===
36.1	509
33.1	510	{{image reference="rollback.png"/}}
1.1	511
	512	== Tips ==
	513
	514	=== How to get an other document? ===
36.1	515
1.1	516	* In the past, we used to do:
	517
32.2	518	{{code language="velocity"}}
1.1	519	#set($document = $xwiki.getDocument('Space.Page'))
32.2	520	{{/code}}
1.1	521
	522	* But it's not good, because what if the page name has a dot?
	523
32.2	524	{{code language="velocity"}}
1.1	525	#set($document = $xwiki.getDocument('Space.Pa.ge'))
	526	## ??? What is the Space ? What is the Page ?
32.2	527	{{/code}}
1.1	528
	529	* And what will happen if the document name have accents or weird characters?
	530
36.1	531	=== Solution: use references ! ===
1.1	532
32.2	533	{{code language="velocity"}}
1.1	534	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
	535	#set($document = $xwiki.getDocument($reference))
32.2	536	{{/code}}
1.1	537
35.1	538	* It is better! The reference tool allow us to strictly separe what is the space and what is the page
1.1	539	* And the reference tool will take care of weird characters !
	540
32.2	541	{{code language="velocity"}}
1.1	542	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Pa.ge'))
	543	#set($document = $xwiki.getDocument($reference))
	544	## Not a problem!!!
32.2	545	{{/code}}
1.1	546
	547	=== References ===
36.1	548
1.1	549	* You can get create references for documents in other wikis :
	550
32.2	551	{{code language="velocity"}}
1.1	552	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
32.2	553	{{/code}}
1.1	554
	555	* If you want to get a document in the current wiki, you can set an empty parameter:
	556
32.2	557	{{code language="velocity"}}
1.1	558	#set($reference = $services.model.createDocumentReference('', 'Space', 'Page'))
	559	## the reference point a document in the current wiki
32.2	560	{{/code}}
1.1	561
27.2	562	=== Use case: changing the name of a user ===
1.1	563
32.2	564	{{code language="velocity"}}
1.1	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()
32.2	576	{{/code}}
1.1	577
27.2	578	=== But remember we know who changes what! ===
36.1	579
33.1	580	{{image reference="history.png"/}}
1.1	581
	582	(% style="text-align: right; margin-top: 20px;" %)
	583	"//I have your name and I know where you live...//"
	584
	585	== Going further ==
36.1	586
	587	=== ===
	588
1.1	589	* See the [[Velocity documentation>>http://velocity.apache.org/]] to have more details about the language itself
36.4	590	* See the [[XWiki Script Guide>>doc:Documentation.DevGuide.Scripting]] to have some informations about how to make scripts in XWiki
36.3	591	* See the [[XWiki Query Module>>doc:extensions:Extension.Query Module]] to learn how to do advanced queries
36.4	592	* See the [[XWiki Data Model>>doc:Documentation.DevGuide.DataModel]] to learn how to create your XWiki classes
1.1	593
	594	But in general:
36.1	595
1.1	596	* practice and ask for help!!!
	597
36.1	598	=== ===
	599
1.1	600	* I hope you now have a better idea of what Velocity is and how you can use it in XWiki.
	601
33.1	602	{{image reference="velocity.jpg"/}}

Wiki source code of 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