Wiki source code of Velocity Training

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