<
From version < 23.3 >
edited by Vincent Massol
on 2010/06/21
To version < 24.1 >
edited by OCTAGRAM
on 2010/07/07
>
Change comment: programming rights remark

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.OCTAGRAM
Content
... ... @@ -1,8 +1,11 @@
1 -{{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}
1 +{{box cssClass="floatinginfobox" title="**Contents**"}}
2 +{{toc/}}
3 +{{/box}}
2 2  
3 3  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.
4 4  
5 5  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 +
6 6  * [[Velocity Macro>>code:Macros.VelocityMacro]] (installed by default in XWiki Enterprise)
7 7  * [[Groovy Macro>>code:Macros.GroovyMacro]] (installed by default in XWiki Enterprise)
8 8  * [[Python Macro>>code:Macros.PythonMacro]] (installed by default in XWiki Enterprise)
... ... @@ -9,13 +9,16 @@
9 9  * [[Ruby Macro>>code:Macros.RubyMacro]] (not installed by default in XWiki Enterprise)
10 10  * [[PHP Macro>>code:Macros.PHPMacro]] (not installed by default in XWiki Enterprise)
11 11  
12 -= XWiki Scripting API =
15 += XWiki Scripting API =
13 13  
17 +
18 +
14 14  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.
15 15  
16 16  == [[Bindings>>code:Macros.ScriptMacro#HBindings]] ==
17 17  
18 18  These objects are available to you in scripting languages.
24 +
19 19  * [[The current Document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Document.html]]: **##doc##**
20 20  * [[The Context of the request>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Context.html]]: **##xcontext##**
21 21  * [[The Request object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiRequest.html]]: **##request##**
... ... @@ -27,24 +27,21 @@
27 27  You can also gain direct access to XWiki components using the following code snippet:
28 28  Also see: [[Accessing components from Groovy>>DevGuide.WritingComponents#HAccessingacomponentfromgroovy]]
29 29  Note: This snippet is written in Groovy and will have to be converted to your scripting language.
30 -{{code language=java}}
31 -{{groovy}}
36 +{{code language="java"}}{{groovy}}
32 32  def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class);
33 33  println greeter.sayHello();
34 -{{/groovy}}
35 -{{/code}}
39 +{{/groovy}}{{/code}}
36 36  
37 37  == XWiki Core Access ==
38 38  
39 39  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.
40 -{{code language=java}}
41 -{{groovy}}
44 +{{code language="java"}}{{groovy}}
42 42  def xc = xcontext.getContext();
43 43  def wiki = xc.getWiki();
44 44  def xdoc = doc.getDocument();
45 -{{/groovy}}
46 -{{/code}}
48 +{{/groovy}}{{/code}}
47 47  After using this snippet, you will have 3 new objects:
50 +
48 48  * [[The underlying XWikiContext behind the Context object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/XWikiContext.html]]: **##xc##**
49 49  * [[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##**
50 50  * [[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##**
... ... @@ -57,11 +57,12 @@
57 57  
58 58  From your script you can query the full XWiki's Model. Check the [[Query Guide>>QueryGuide]] for more information.
59 59  
60 -{{id name=velocity /}}
63 +{{id name="velocity"/}}
64 +
61 61  = Velocity Specific Information =
62 62  
63 63  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.
64 -You can [[gain access to the XWiki core>>#HXWikiCoreAccess]] from Velocity but this will require programming rights.
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.
65 65  
66 66  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)
67 67  
... ... @@ -68,6 +68,7 @@
68 68  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]].
69 69  
70 70  The following Velocity tools are also available in addition to the bindings.
75 +
71 71  * [[List Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/ListTool.html]]: **##$listtool##**
72 72  * [[Number Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/NumberTool.html]]: **##$numbertool##**
73 73  * [[Date Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/DateTool.html]]: **##$datetool##**
... ... @@ -76,15 +76,20 @@
76 76  * [[Sort Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/SortTool.html]]: **##$sorttool##**
77 77  * 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]].
78 78  
79 -{{info}}If you wish to add new Velocity tools you'll need to edit your ##xwiki.properties## file and follow the instructions in there.{{/info}}
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}}
80 80  
81 81  To include Velocity scripts in other Velocity scripts, see [[How to include a velocity page into another page>>DevGuide.IncludeInVelocity]].
82 82  
83 83  == Other Velocity Variables ==
84 84  
85 -{{info}}These variables can be used but are subject to change in the future.{{/info}}
92 +{{info}}
93 +These variables can be used but are subject to change in the future.
94 +{{/info}}
86 86  
87 -{{id name=HControllingwhethertodisplayCommentsHistoryAttachmentInformationsectionsornot /}}
96 +{{id name="HControllingwhethertodisplayCommentsHistoryAttachmentInformationsectionsornot"/}}
97 +
88 88  === Controlling Which Sections to Display ===
89 89  
90 90  You can control whether to display Comments/History/Attachment/Information sections or not by setting some velocity variable to "no":
... ... @@ -116,8 +116,7 @@
116 116  
117 117  Using XWiki Syntax 2.0:
118 118  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.
119 -{{code}}
120 -{{velocity}}
129 +{{code}}{{velocity}}
121 121  #set($hostname = "www.xwiki.org")
122 122  Host Name: $hostname
123 123  $xcontext.put("hostname", $hostname)
... ... @@ -131,13 +131,11 @@
131 131  {{/groovy}}
132 132  {{velocity}}
133 133  IP Address: $xcontext.get("address")
134 -{{/velocity}}
135 -{{/code}}
143 +{{/velocity}}{{/code}}
136 136  
137 137  Using XWiki Syntax 1.0:
138 138  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.
139 -{{code}}
140 -#set ($hostname = "www.xwiki.org")
147 +{{code}}#set ($hostname = "www.xwiki.org")
141 141  Host Name: $hostname
142 142  <%
143 143  import java.net.InetAddress;
... ... @@ -146,8 +146,7 @@
146 146  InetAddress addr = InetAddress.getByName(host);
147 147  String address = addr.getHostAddress();
148 148  %>
149 -IP Address: $address
150 -{{/code}}
156 +IP Address: $address{{/code}}
151 151  
152 152  = Python Specific Information =
153 153  
... ... @@ -154,8 +154,7 @@
154 154  In Python, you have all of the powers available in Groovy but the default bindings are not available due to a [[bug in Jython>>http://bugs.jython.org/issue1426]] There is a workaround snippet which manually loads the context, document, wiki object, request and response available [[here>>code:Snippets.AccessToBindingsInPythonSnippet]].
155 155  
156 156  Example Snippet:
157 -{{code language=python}}
158 -{{python}}
163 +{{code language="python"}}{{python}}
159 159  import com.xpn.xwiki.web.Utils as Utils
160 160  import org.xwiki.context.Execution as Execution
161 161  import com.xpn.xwiki.api.Context as Context
... ... @@ -163,8 +163,7 @@
163 163  xcontext = Context(Utils.getComponent(Execution).getContext().getProperty("xwikicontext"))
164 164  doc = Document(xcontext.getDoc(), xcontext.getContext())
165 165  print "The full name of this document is " + doc.getFullName()
166 -{{/python}}
167 -{{/code}}
171 +{{/python}}{{/code}}
168 168  
169 169  = Scripting In XWiki Syntax 1.0 =
170 170  
... ... @@ -172,7 +172,7 @@
172 172  
173 173  * The only scripting languages available to you are Velocity and Groovy.
174 174  * In Groovy, the context is known as: **##context##** not **##xcontext##**
175 -* The beginning and end of Groovy scripts are denoted by <% and %> rather than through the [[code:Macros.GroovyMacro]] (using ~{{groovy}} and ~{{/groovy}})
176 -* Velocity is parsed in a page no matter what (there is no need to invoke the [[code:Macros.VelocityMacro]] using ~{{velocity}} and ~{{/velocity}})
179 +* The beginning and end of Groovy scripts are denoted by <% and %> rather than through the [[code:Macros.GroovyMacro]] (using ~{~{groovy}} and ~{~{/groovy}})
180 +* Velocity is parsed in a page no matter what (there is no need to invoke the [[code:Macros.VelocityMacro]] using ~{~{velocity}} and ~{~{/velocity}})
177 177  
178 178  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