Wiki source code of Velocity Training

Last modified by Vincent Massol on 2021/05/01
Show last authors
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"/}}

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected