Wiki source code of Velocity Training

Last modified by Ecaterina Moraru (Valica) on 2017/09/06
Hide line numbers
  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"/}}
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
