Wiki source code of Scripting

Version 27.1 by Caleb James DeLisle on 2010/08/10

Hide last authors
OCTAGRAM 24.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Caleb James DeLisle 23.1 4
Vincent Massol 20.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.
Vincent Massol 1.1 6
Vincent Massol 20.4 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:
OCTAGRAM 24.1 8
Vincent Massol 20.4 9 * [[Velocity Macro>>code:Macros.VelocityMacro]] (installed by default in XWiki Enterprise)
10 * [[Groovy Macro>>code:Macros.GroovyMacro]] (installed by default in XWiki Enterprise)
11 * [[Python Macro>>code:Macros.PythonMacro]] (installed by default in XWiki Enterprise)
12 * [[Ruby Macro>>code:Macros.RubyMacro]] (not installed by default in XWiki Enterprise)
13 * [[PHP Macro>>code:Macros.PHPMacro]] (not installed by default in XWiki Enterprise)
14
OCTAGRAM 24.1 15 = XWiki Scripting API =
Caleb James DeLisle 20.1 16
OCTAGRAM 24.1 17
18
Caleb James DeLisle 20.1 19 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 [[Code Zone>>code:Main.WebHome]] area to see how others have figured out how to achieve a variety of results.
20
Vincent Massol 20.3 21 == [[Bindings>>code:Macros.ScriptMacro#HBindings]] ==
Caleb James DeLisle 20.1 22
23 These objects are available to you in scripting languages.
OCTAGRAM 24.1 24
Caleb James DeLisle 20.1 25 * [[The current Document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Document.html]]: **##doc##**
26 * [[The Context of the request>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Context.html]]: **##xcontext##**
27 * [[The Request object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiRequest.html]]: **##request##**
28 * [[The Response object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiResponse.html]]: **##response##**
29 * [[The XWiki object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/XWiki.html]]: **##xwiki##**
30
Vincent Massol 20.3 31 == [[XWiki Component>>code:Modules.ComponentModule]] Access ==
Caleb James DeLisle 20.1 32
33 You can also gain direct access to XWiki components using the following code snippet:
34 Also see: [[Accessing components from Groovy>>DevGuide.WritingComponents#HAccessingacomponentfromgroovy]]
35 Note: This snippet is written in Groovy and will have to be converted to your scripting language.
OCTAGRAM 24.1 36 {{code language="java"}}{{groovy}}
Caleb James DeLisle 20.1 37 def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class);
38 println greeter.sayHello();
OCTAGRAM 24.1 39 {{/groovy}}{{/code}}
Caleb James DeLisle 20.1 40
Vincent Massol 20.3 41 == XWiki Core Access ==
Caleb James DeLisle 20.1 42
Caleb James DeLisle 22.2 43 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 run. Using the core should be avoided if at all possible.
OCTAGRAM 24.1 44 {{code language="java"}}{{groovy}}
Caleb James DeLisle 20.1 45 def xc = xcontext.getContext();
46 def wiki = xc.getWiki();
47 def xdoc = doc.getDocument();
OCTAGRAM 24.1 48 {{/groovy}}{{/code}}
Caleb James DeLisle 20.1 49 After using this snippet, you will have 3 new objects:
OCTAGRAM 24.1 50
Caleb James DeLisle 20.1 51 * [[The underlying XWikiContext behind the Context object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/XWikiContext.html]]: **##xc##**
52 * [[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##**
53 * [[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##**
54
Caleb James DeLisle 22.2 55 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##**.
56
Caleb James DeLisle 22.1 57 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.
Caleb James DeLisle 20.1 58
Vincent Massol 23.2 59 == Querying XWiki's Model ==
60
61 From your script you can query the full XWiki's Model. Check the [[Query Guide>>QueryGuide]] for more information.
62
OCTAGRAM 24.1 63 {{id name="velocity"/}}
64
Vincent Massol 20.3 65 = Velocity Specific Information =
Vincent Massol 1.1 66
Caleb James DeLisle 20.1 67 Velocity is the only scripting language which can be used without Administration or Programming [[AdminGuide.Access Rights]]. This means you can save velocity scripts using a username with less permission and an exploit of your script is less of a security breach. Also if you are administrating a [[virtual wiki>>AdminGuide.Virtualization]] and you don't have programming rights, you can still do scripting in Velocity.
OCTAGRAM 24.1 68 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 has programming rights.
Vincent Massol 1.1 69
Caleb James DeLisle 20.1 70 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)
Vincent Massol 1.1 71
Caleb James DeLisle 20.1 72 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]].
Vincent Massol 1.1 73
Caleb James DeLisle 20.1 74 The following Velocity tools are also available in addition to the bindings.
OCTAGRAM 24.1 75
Caleb James DeLisle 16.1 76 * [[List Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/ListTool.html]]: **##$listtool##**
77 * [[Number Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/NumberTool.html]]: **##$numbertool##**
78 * [[Date Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/DateTool.html]]: **##$datetool##**
79 * [[Math Tool>>http://velocity.apache.org/tools/releases/1.4/generic/MathTool.html]]: **##$mathtool##**
80 * [[Escape Tool>>http://velocity.apache.org/tools/releases/1.4/generic/EscapeTool.html]]: **##$escapetool##**
81 * [[Sort Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/SortTool.html]]: **##$sorttool##**
Vincent Massol 21.2 82 * 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]].
Vincent Massol 9.1 83
OCTAGRAM 24.1 84 {{info}}
85 If you wish to add new Velocity tools you'll need to edit your ##xwiki.properties## file and follow the instructions in there.
86 {{/info}}
Vincent Massol 9.2 87
Caleb James DeLisle 16.1 88 To include Velocity scripts in other Velocity scripts, see [[How to include a velocity page into another page>>DevGuide.IncludeInVelocity]].
jeanvivienmaurice 1.20 89
Vincent Massol 20.3 90 == Other Velocity Variables ==
Vincent Massol 13.1 91
OCTAGRAM 24.1 92 {{info}}
93 These variables can be used but are subject to change in the future.
94 {{/info}}
Vincent Massol 13.1 95
OCTAGRAM 24.1 96 {{id name="HControllingwhethertodisplayCommentsHistoryAttachmentInformationsectionsornot"/}}
97
Vincent Massol 20.3 98 === Controlling Which Sections to Display ===
Vincent Massol 13.1 99
Caleb James DeLisle 20.1 100 You can control whether to display Comments/History/Attachment/Information sections or not by setting some velocity variable to "no":
Vincent Massol 13.1 101
Caleb James DeLisle 16.1 102 {{code}}
Vincent Massol 13.1 103 #set ($showcomments = "no")
104 #set ($showattachments = "no")
105 #set ($showhistory = "no")
106 #set ($showinformation = "no")
Caleb James DeLisle 16.1 107 {{/code}}
Vincent Massol 13.1 108
109 To remove them all you can set:
110
Caleb James DeLisle 16.1 111 {{code}}
Vincent Massol 13.1 112 #set($docextras = [])
Caleb James DeLisle 16.1 113 {{/code}}
Vincent Massol 13.1 114
Vincent Massol 20.3 115 = Groovy Specific Information =
Vincent Massol 1.1 116
Caleb James DeLisle 20.1 117 Currently all non Velocity scripting languages are only allowed for administrators of a wiki (or users having the 'programming' right).
Vincent Massol 1.1 118
Caleb James DeLisle 16.1 119 * See Groovy examples in the [[Code Zone>>code:Main.WebHome]], more specifically in the [[Code Snippets area>>code:Snippets.WebHome]]
120 * [[Feeling Groovy>>http://www-128.ibm.com/developerworks/java/library/j-alj08034.html]]
121 * [[MVC programming with Groovy templates>>http://www-128.ibm.com/developerworks/java/library/j-pg02155/]]
Vincent Massol 1.1 122
Vincent Massol 20.3 123 == Groovy Example ==
gfiorentino 1.17 124
Caleb James DeLisle 18.1 125 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##.
Vincent Massol 8.2 126
Caleb James DeLisle 19.1 127 Using XWiki Syntax 2.0:
128 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.
OCTAGRAM 24.1 129 {{code}}{{velocity}}
Caleb James DeLisle 19.1 130 #set($hostname = "www.xwiki.org")
131 Host Name: $hostname
132 $xcontext.put("hostname", $hostname)
133 {{/velocity}}
134 {{groovy}}
135 import java.net.InetAddress;
136 host = xcontext.get("hostname");
137 InetAddress addr = InetAddress.getByName(host);
138 String address = addr.getHostAddress();
139 xcontext.put("address", address);
140 {{/groovy}}
141 {{velocity}}
142 IP Address: $xcontext.get("address")
OCTAGRAM 24.1 143 {{/velocity}}{{/code}}
Caleb James DeLisle 19.1 144
Caleb James DeLisle 18.1 145 Using XWiki Syntax 1.0:
Caleb James DeLisle 19.1 146 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.
OCTAGRAM 24.1 147 {{code}}#set ($hostname = "www.xwiki.org")
Caleb James DeLisle 18.1 148 Host Name: $hostname
Vincent Massol 8.2 149 <%
150 import java.net.InetAddress;
151 vcontext = context.get("vcontext");
Caleb James DeLisle 18.1 152 host = vcontext.get("hostname");
153 InetAddress addr = InetAddress.getByName(host);
154 String address = addr.getHostAddress();
Vincent Massol 8.2 155 %>
OCTAGRAM 24.1 156 IP Address: $address{{/code}}
Caleb James DeLisle 20.1 157
Caleb James DeLisle 26.1 158 = Python Specific Information =
159 You can run python code in XWiki just like velocity or groovy.
OCTAGRAM 24.1 160 {{code language="python"}}{{python}}
Caleb James DeLisle 20.1 161 print "The full name of this document is " + doc.getFullName()
OCTAGRAM 24.1 162 {{/python}}{{/code}}
Caleb James DeLisle 20.1 163
Caleb James DeLisle 26.1 164 {{warning}}
Caleb James DeLisle 27.1 165 Versions prior to [[XWiki Enterprise 2.4>>xwiki:Main.ReleaseNotesXWikiEnterprise24]] have a bug which prevents you from having access to the default objects (doc, xcontext, request, etc.) a [[workaround is available in the code zone>>code:Snippets.AccessToBindingsInPythonSnippet]]
Caleb James DeLisle 26.1 166 {{/warning}}
167
Vincent Massol 20.3 168 = Scripting In XWiki Syntax 1.0 =
Caleb James DeLisle 20.1 169
Vincent Massol 20.5 170 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.
Caleb James DeLisle 20.1 171
172 * The only scripting languages available to you are Velocity and Groovy.
173 * In Groovy, the context is known as: **##context##** not **##xcontext##**
OCTAGRAM 24.1 174 * The beginning and end of Groovy scripts are denoted by <% and %> rather than through the [[code:Macros.GroovyMacro]] (using ~{~{groovy}} and ~{~{/groovy}})
175 * Velocity is parsed in a page no matter what (there is no need to invoke the [[code:Macros.VelocityMacro]] using ~{~{velocity}} and ~{~{/velocity}})
Caleb James DeLisle 20.1 176
177 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.

Get Connected