Skip to Content

Wiki source code of Scripting

Version 34.1 by Vincent Massol on 2011/11/01
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 Scripting allows you to create basic to complex web applications at the XWiki page (or view) layer without the need for compiling code or deploying software components. In other words, you can use scripting syntax in addition to wiki and HTML syntax as the contents of an XWiki page.
6
7 XWiki integrates [[jsr-223>>http://scripting.dev.java.net/]] scripting. You can script using several available languages by using one of the following macros:
8
9 * [[Velocity Macro>>extensions:Extension.Velocity Macro]] (installed by default in XWiki Enterprise)
10 * [[Groovy Macro>>extensions:Extension.Groovy Macro]] (installed by default in XWiki Enterprise)
11 * [[Python Macro>>extensions:Extension.Python Macro]] (installed by default in XWiki Enterprise)
12 * [[Ruby Macro>>extensions:Extension.Ruby Macro]] (not installed by default in XWiki Enterprise)
13 * [[PHP Macro>>extensions:Extension.PHP Macro]] (not installed by default in XWiki Enterprise)
14
15 = XWiki Scripting API =
16
17 The API is documented in Javadoc format and can be accessed here: [[XWiki API Javadoc>>DevGuide.API]]. If you are not familiar with Java or object oriented programming, you will probably be confused by the API documentation. It is not within the scope of our documentation to teach you all the details about Java, or object oriented programming. You can find all of that information already online. You can also explore the page code found throughout the [[Extensions wiki>>extensions:Main.WebHome]] area to see how others have figured out how to achieve a variety of results.
18
19 == [[Bindings>>extensions:Extension.Script Macro#HBindings]] ==
20
21 These objects are available to you in scripting languages.
22
23 * [[The current Document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Document.html]]: **##doc##**
24 * [[The Context of the request>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Context.html]]: **##xcontext##**
25 * [[The Request object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiRequest.html]]: **##request##**
26 * [[The Response object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiResponse.html]]: **##response##**
27 * [[The XWiki object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/XWiki.html]]: **##xwiki##**
28 * [[The XWiki utils>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Util.html]]: **##util##**
29
30 == [[XWiki Component>>extensions:Extension.Component Module]] Access ==
31
32 You can also gain direct access to XWiki components using the following code snippet (also see: [[Accessing components from Groovy>>DevGuide.WritingComponents#HAccessingacomponentfromgroovy]]):
33
34 {{info}}This snippet is written in Groovy and will have to be converted to your scripting language.{{/info}}
35
36 {{code language="java"}}
37 {{groovy}}
38 def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class);
39 println greeter.sayHello();
40 {{/groovy}}
41 {{/code}}
42
43 == XWiki Core Access ==
44
45 Sometimes the XWiki Api doesn't provide the methods which you need for your application. You can gain raw access the core of XWiki but it presents an increased security risk and requires **Programming Rights** to be able to save the page containing the script (Programming Rights are not required for viewing a page containing a script requiring Programming Rights, rights are only needed at save time). Using the core should be avoided if at all possible.
46
47 {{code language="java"}}
48 {{groovy}}
49 def xc = xcontext.getContext();
50 def wiki = xc.getWiki();
51 def xdoc = doc.getDocument();
52 {{/groovy}}
53 {{/code}}
54
55 After using this snippet, you will have 3 new objects:
56
57 * [[The underlying XWikiContext behind the Context object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/XWikiContext.html]]: **##xc##**
58 * [[The underlying XWiki object which backs the **##xwiki##** object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/XWiki.html]]: **##wiki##**
59 * [[The underlying XWikiDocument behind the current Document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/doc/XWikiDocument.html]]: **##xdoc##**
60
61 You will find that many of the methods in **##wiki##** and **##xdoc##** require an instance of the XWikiContext, this is the underlying xcontext **##xc##** not the Api context **##xcontext##**.
62
63 Again, these methods are only for the rare cases when functionality is not provided by the public Api. We put a lot of effort into preserving the behavior of the public Api and much less into preserving the behavior of core methods so you may find that core methods are deprecated, removed, or their behavior is changed in subsequent versions.
64
65 == Querying XWiki's Model ==
66
67 From your script you can query the full XWiki's Model. Check the [[Query Guide>>QueryGuide]] for more information.
68
69 {{id name="velocity"/}}
70
71 = Velocity Specific Information =
72
73 Velocity is the only scripting language which can be used without Programming [[AdminGuide.Access Rights]]. This means you can save velocity scripts using a user with less permission and an exploit of your script is less of a security breach.
74
75 You can [[gain access to the XWiki core>>#HXWikiCoreAccess]] from Velocity but this will require Programming Rights. Strictly speaking, protected APIs are only available when the page that contains them was last saved by someone who had Programming Rights (see above).
76
77 In Velocity you can't import classes and as such you cannot gain direct access to XWiki components as shown [[above>>#HXWikiComponentAccess]]. This leaves you with the provided [[bindings>>#HBindings]] (NOTE: In Velocity, these bindings all start with **##$##** as with all other Velocity variables)
78
79 For more information about programming in the Velocity language, you can refer to the [[Velocity User Guide>>http://velocity.apache.org/engine/releases/velocity-1.6.2/user-guide.html]].
80
81 The following Velocity tools are also available in addition to the bindings.
82
83 * [[List Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/ListTool.html]]: **##$listtool##**
84 * [[Number Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/NumberTool.html]]: **##$numbertool##**
85 * [[Comparison Date Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/ComparisonDateTool.html]] (extends [[Date Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/DateTool.html]]): **##$datetool##**
86 * [[Math Tool>>http://velocity.apache.org/tools/releases/1.4/generic/MathTool.html]]: **##$mathtool##**
87 * [[Escape Tool>>http://velocity.apache.org/tools/releases/1.4/generic/EscapeTool.html]]: **##$escapetool##**
88 * [[Sort Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/SortTool.html]]: **##$sorttool##**
89 * Message Tool: **##$msg##** This tool is used to provide internationalized messages based on keys. For more details see the [[How to Write Internationalized Applications tutorial>>DevGuide.InternationalizingApplications]].
90
91 {{info}}
92 If you wish to add new Velocity tools you'll need to edit your ##xwiki.properties## file and follow the instructions in there.
93 {{/info}}
94
95 To include Velocity scripts in other Velocity scripts, see [[How to include a velocity page into another page>>DevGuide.IncludeInVelocity]].
96
97 == Other Velocity Variables ==
98
99 {{warning}}
100 These variables can be used but are subject to change in the future.
101 {{/warning}}
102
103 {{id name="HControllingwhethertodisplayCommentsHistoryAttachmentInformationsectionsornot"/}}
104
105 === Controlling Which Sections to Display ===
106
107 You can control whether to display Comments/History/Attachment/Information sections or not by setting some velocity variable to "no":
108
109 {{code language="velocity"}}
110 #set ($showcomments = "no")
111 #set ($showattachments = "no")
112 #set ($showhistory = "no")
113 #set ($showinformation = "no")
114 {{/code}}
115
116 To remove them all you can set:
117
118 {{code language="velocity"}}
119 #set($docextras = [])
120 {{/code}}
121
122 === Information about the current user ===
123
124 The following variables (set in the [[xwikivars.vm>>http://svn.xwiki.org/svnroot/xwiki/platform/web/trunk/standard/src/main/webapp/templates/xwikivars.vm]] template) are shortcuts for checking various information **for the current user**:
125
126 * ##$isGuest##: checks if the current user is ##XWiki.XWikiGuest##
127 * ##$isSuperAdmin##: checks if the current user is the special user ##superadmin##
128
129 * ##$hasComment##: checks comment rights on the current document
130 * ##$hasEdit##: checks edit rights on the current document
131 * ##$hasWatch##: checks if the user is authenticated and the watch service is available
132
133 * ##$hasAdmin##: checks admin rights on the current document
134 * ##$hasSpaceAdmin##: checks admin rights on the ##XWikiPreferences## document of the current space
135 * ##$hasGlobalAdmin##: checks admin rights on ##XWiki.XWikiPreferences##
136
137 * ##$hasCreateSpace##: checks edit rights on that page that does not exist, in a space that doesn't exist
138 * ##$hasCreatePage##: checks edit rights on that page that does not exist, in the current space
139
140 * ##$hasProgramming##: checks if the current user has programming rights
141
142 * ##$isAdvancedUser##: advanced users: ##superadmin##, users with the ##usertype## property set to "Advanced", guest users with admin rights
143
144 Example:
145
146 {{code language="velocity"}}
147 {{velocity}}
148 #if ($hasAdmin)
149 ## This link will only be visible to users that have admin rights on this document
150 [[Do some admin action>>Some.Document]]
151 #end
152 {{/velocity}}
153 {{/code}}
154
155 === Information about the current wiki ===
156
157 The following variables (set in the [[xwikivars.vm>>http://svn.xwiki.org/svnroot/xwiki/platform/web/trunk/standard/src/main/webapp/templates/xwikivars.vm]] template) are shortcuts for checking various information **about the current wiki**:
158
159 * ##$isReadOnly##
160 * ##$isInServletMode##
161 * ##$isInPortletMode##
162
163 = Groovy Specific Information =
164
165 {{info}}Currently all non Velocity scripting languages are only allowed users having Programming Rights.{{/info}}
166
167 * See Groovy examples in the [[Extensions wiki>>extensions:Main.WebHome]]
168 * [[Feeling Groovy>>http://www-128.ibm.com/developerworks/java/library/j-alj08034.html]]
169 * [[MVC programming with Groovy templates>>http://www-128.ibm.com/developerworks/java/library/j-pg02155/]]
170
171 == Groovy Example ==
172
173 The following example demonstrates how to use a groovy script to interact with velocity code in your page. This example performs a DNS lookup from the velocity variable ##$hostname## and stores the result in the variable ##$address##.
174
175 **Using XWiki Syntax 2.0:**
176
177 Objects can be passed back and forth between scripting languages by storing them in commonly available objects. One such commonly available object which only lasts the length of the request is the context object, known as xcontext.
178
179 {{code language="velocity"}}
180 {{velocity}}
181 #set($hostname = "www.xwiki.org")
182 Host Name: $hostname
183 $xcontext.put("hostname", $hostname)
184 {{/velocity}}
185 {{groovy}}
186 import java.net.InetAddress;
187 host = xcontext.get("hostname");
188 InetAddress addr = InetAddress.getByName(host);
189 String address = addr.getHostAddress();
190 xcontext.put("address", address);
191 {{/groovy}}
192 {{velocity}}
193 IP Address: $xcontext.get("address")
194 {{/velocity}}
195 {{/code}}
196
197 **Using XWiki Syntax 1.0:**
198
199 Because Groovy and Velocity code are parsed together, variables defined in Groovy can be used directly in velocity without storing in and retrieving from the context.
200
201 {{code language="velocity"}}
202 #set ($hostname = "www.xwiki.org")
203 Host Name: $hostname
204 <%
205 import java.net.InetAddress;
206 vcontext = context.get("vcontext");
207 host = vcontext.get("hostname");
208 InetAddress addr = InetAddress.getByName(host);
209 String address = addr.getHostAddress();
210 %>
211 IP Address: $address
212 {{/code}}
213
214 = Python Specific Information =
215
216 You can run Python code in XWiki just like Velocity or Groovy.
217
218 {{code language="python"}}
219 {{python}}
220 print "The full name of this document is " + doc.getFullName()
221 {{/python}}
222 {{/code}}
223
224 {{warning}}
225 Versions prior to [[XWiki Enterprise 2.4>>xwiki:ReleaseNotes.ReleaseNotesXWikiEnterprise24]] have a bug which prevents you from having access to the default objects (doc, xcontext, request, etc.) a [[workaround is available in the Extensions wiki>>extensions:Extension.Access To Bindings In Python]]
226 {{/warning}}
227
228 = Scripting In XWiki Syntax 1.0 =
229
230 XWiki Syntax 1.0 is rendered by an old rendering engine which still supported but for which no further development is planned (it will eventually be removed). Syntax 1.0 has some idiosyncrasies which were solved by syntax 2.0.
231
232 * The only scripting languages available to you are Velocity and Groovy.
233 * In Groovy, the context is known as: **##context##** not **##xcontext##**
234 * The beginning and end of Groovy scripts are denoted by <% and %> rather than through the [[extensions:Extension.Groovy Macro]] (using ~{~{groovy}} and ~{~{/groovy}})
235 * Velocity is parsed in a page no matter what (there is no need to invoke the [[extensions:Extension.Velocity Macro]] using ~{~{velocity}} and ~{~{/velocity}})
236
237 The last part is important because it means you need to be careful of using $ and # in your document. This is still true inside of <% and %> so you have to be careful writing Groovy.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected