Wiki source code of Velocity Training

Last modified by Simpel on 2024/01/03

version	line-number	content
37.3	1	{{box cssClass="floatinginfobox" title="Contents"}}
37.6	2	{{toc depth="2" start="2"/}}
37.3	3	{{/box}}
	4
1.1	5	= How to use Velocity in XWiki pages =
36.1	6
1.1	7	== What is it? ==
	8
38.3	9	=== ===
1.1	10
	11	* Velocity is a template language.
	12	* It describes what your page should be.
38.4	13	Which means it controls what you display**.
1.1	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
38.1	87	* A //variable// is like a box that can contain data: text, numbers, objects, etc...
1.1	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
38.1	121	* Some variable are //objects//. An object can contain //variables// and //methods//.
1.1	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//.
38.1	143	* A //class// is like a model that describes what the object will have.
1.1	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)
38.1	153	$myVar.class.name ## will display 'java.lang.Integer'
1.1	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
38.1	173	* As you may have noticed, the classes come from the //Java// world.
	174	* The documentation about the java classes is called //Javadoc//.
1.1	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
38.1	183	* When you want to display something only under certain circumstances, you can use the //#if// command.
1.1	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:
38.1	207	//==//** : compare if the variables are equal
	208	//!=//** : say if the variables are different
1.1	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
38.1	240	=== Examples (continued) ===
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
36.1	286
33.1	287	{{image reference="teacher.jpg"/}}
1.1	288
	289	=== Example of lists ===
36.1	290
32.2	291	{{code language="velocity"}}
1.1	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
32.2	295	{{/code}}
1.1	296
	297
	298	How could I know the number of spaces in the wiki?
	299
32.2	300	{{code language="velocity"}}
1.1	301	$xwiki.getSpaces().size()
32.2	302	{{/code}}
1.1	303
	304
	305	How could I know if the space 'BlaBla' exists?
	306
32.2	307	{{code language="velocity"}}
1.1	308	$xwiki.getSpaces().contains('BlaBla')
32.2	309	{{/code}}
1.1	310
	311
33.1	312	{{image reference="goodmark.jpg"/}}
1.1	313
	314	=== Foreach ===
36.1	315
1.1	316	* How can I display all the elements of a list in a nice way?
	317	** Use the //#foreach// loop, son.
38.1	318	* Example:
1.1	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
36.1	333	=== ===
	334
1.1	335	* XWiki offers a lot of objects with a lot of methods, to perform a lot of things !
38.3	336	** Delete a document, add a tag to another document, display the list of all blog entries, handle complex formulars, etc...
38.1	337	* This objects & methods are called the API (as //Application Programming Interface//).
1.1	338	* But how can I know what are theses objects and how to use it?
	339
33.1	340	{{image reference="API.jpg"/}}
1.1	341
	342	=== By using the XWiki Script Reference Documentation (SRD) ===
	343
33.1	344	{{image reference="SRD.png"/}}
1.1	345
37.7	346	Go to the [[SRD>>xwiki:ScriptingDocumentation.WebHome]].
1.1	347
	348	=== SRD ===
36.1	349
1.1	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
38.1	352	** Examples:
1.1	353	*** //$xwiki// offers a method //getDocument()//
	354	*** //$doc// has a method //addAttachment()//
	355	*** etc...
	356
36.1	357	=== Is the API a mess? ===
	358
38.1	359	* While looking at the SRD, we can ask youself //"how many special variables are there?"//
1.1	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
33.1	363	{{image reference="mess.jpg"/}}
1.1	364
	365	=== Introducing Script Services ===
36.1	366
1.1	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
33.1	371	{{image reference="datacenter.jpg"/}}
1.1	372
36.1	373	=== ===
	374
1.1	375	* To use a script service, you do it this way:
	376
32.2	377	{{code language="velocity"}}
1.1	378	$services.query ## to perform complicated researchs
	379	$services.localization ## to take care of the languages
	380	$services.officeimporter ## to import office documents
	381	...
32.2	382	{{/code}}
1.1	383
	384	* Of course, it is documented on the SRD!
	385
33.1	386	{{image reference="wayne.jpg"/}}
1.1	387
36.1	388	=== ===
	389
1.1	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
32.2	395	{{code language="velocity"}}
1.1	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
32.2	401	{{/code}}
1.1	402
	403	* Because it's the future!
	404
33.1	405	{{image reference="future.jpg"/}}
1.1	406
	407	== Manipulation of XObjects ==
36.1	408
1.1	409	=== What is an XObject ? ===
36.1	410
1.1	411	* An //XObject// is an object that you can save in the wiki.
38.1	412	* An XObject is attached to a document, and you can see them with the "objects editor" on the wiki.
1.1	413
33.1	414	{{image reference="edit_objects.png"/}}
1.1	415
36.1	416	=== ===
	417
33.1	418	{{image reference="objects.png"/}}
1.1	419
	420	=== XClass ===
36.1	421
1.1	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 ===
36.1	427
33.1	428	{{image reference="class_editor.png"/}}
1.1	429
	430	=== Application Within Minutes ===
36.1	431
33.1	432	{{image reference="appwithinminutes.png"/}}
1.1	433
	434	=== Why using XClass and XObjects? ===
36.1	435
1.1	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// ===
36.1	445
1.1	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 ===
36.1	456
33.1	457	{{image reference="comments.png"/}}
1.1	458
	459	=== A user is an XObject ===
36.1	460
33.1	461	{{image reference="user.png"/}}
1.1	462
	463	=== How to get an XObject with Velocity? ===
	464
32.2	465	{{code language="velocity"}}
1.1	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:
38.2	473	$object.get('first_name')
1.1	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)
38.1	483	$doc.save('I have changed the name of the user.')
32.2	484	{{/code}}
1.1	485
38.1	486	=== You can rollback what your script has done ===
36.1	487
33.1	488	{{image reference="rollback.png"/}}
1.1	489
	490	== Tips ==
	491
38.3	492	=== How to get a document? ===
36.1	493
1.1	494	* In the past, we used to do:
	495
32.2	496	{{code language="velocity"}}
38.1	497	#set($document = $xwiki.getDocument('Space.Page'))
32.2	498	{{/code}}
1.1	499
	500	* But it's not good, because what if the page name has a dot?
	501
32.2	502	{{code language="velocity"}}
1.1	503	#set($document = $xwiki.getDocument('Space.Pa.ge'))
38.1	504	## ??? What is the Space ? What is the Page ?
32.2	505	{{/code}}
1.1	506
	507	* And what will happen if the document name have accents or weird characters?
	508
36.1	509	=== Solution: use references ! ===
1.1	510
32.2	511	{{code language="velocity"}}
1.1	512	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
38.1	513	#set($document = $xwiki.getDocument($reference))
32.2	514	{{/code}}
1.1	515
38.1	516	* It is better! The reference tool allow us to strictly separate what is the space and what is the page
1.1	517	* And the reference tool will take care of weird characters !
	518
32.2	519	{{code language="velocity"}}
1.1	520	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Pa.ge'))
38.1	521	#set($document = $xwiki.getDocument($reference))
1.1	522	## Not a problem!!!
32.2	523	{{/code}}
1.1	524
	525	=== References ===
36.1	526
1.1	527	* You can get create references for documents in other wikis :
	528
32.2	529	{{code language="velocity"}}
1.1	530	#set($reference = $services.model.createDocumentReference('Wiki', 'Space', 'Page'))
32.2	531	{{/code}}
1.1	532
	533	* If you want to get a document in the current wiki, you can set an empty parameter:
	534
32.2	535	{{code language="velocity"}}
1.1	536	#set($reference = $services.model.createDocumentReference('', 'Space', 'Page'))
38.1	537	## the reference point to a document in the current wiki
32.2	538	{{/code}}
1.1	539
27.2	540	=== Use case: changing the name of a user ===
1.1	541
32.2	542	{{code language="velocity"}}
38.1	543	## First, create a reference to their user page
1.1	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'))
38.1	549	## Then change their name
1.1	550	$object.set('first_name', 'Harry')
	551	$object.set('last_name', 'Potter')
	552	## And save the document
	553	$document.save()
32.2	554	{{/code}}
1.1	555
27.2	556	=== But remember we know who changes what! ===
36.1	557
33.1	558	{{image reference="history.png"/}}
1.1	559
	560	(% style="text-align: right; margin-top: 20px;" %)
	561	"//I have your name and I know where you live...//"
	562
	563	== Going further ==
36.1	564
	565	=== ===
	566
1.1	567	* See the [[Velocity documentation>>http://velocity.apache.org/]] to have more details about the language itself
37.1	568	* See the [[XWiki Script Guide>>doc:Documentation.DevGuide.Scripting.WebHome]] to have some informations about how to make scripts in XWiki
36.3	569	* See the [[XWiki Query Module>>doc:extensions:Extension.Query Module]] to learn how to do advanced queries
36.4	570	* See the [[XWiki Data Model>>doc:Documentation.DevGuide.DataModel]] to learn how to create your XWiki classes
1.1	571
	572	But in general:
36.1	573
1.1	574	* practice and ask for help!!!
	575
36.1	576	=== ===
	577
1.1	578	* I hope you now have a better idea of what Velocity is and how you can use it in XWiki.
	579
33.1	580	{{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