Wiki source code of XWiki Scripting API Guide

Version 17.1 by Pascal Bastien on 2015/02/10

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 This guide covers the main XWiki APIs that you can use from scripts in wiki pages. It's not meant to be comprehensive. For that you'll need to check the [[XWiki Reference API page>>API]].
6
7 Note that while most examples are written in Velocity you can use [[any other scripting language>>DevGuide.Scripting]] to access the same APIs.
8
9 = Querying documents =
10
11 See the [[Query Module>>extensions:Extension.Query Module]] for examples on how to perform queries on the wiki using a scripting language.
12
13 = Create a new Document =
14
15 For example in Velocity:
16
17 {{code}}
18 #set ($newDoc = $xwiki.getDocument('MySpace.MyPage'))
19 ## The second parameter to save() indicates whether the save is a minor edit or not
20 #set ($discard = $newDoc.save("some comment explaining the save", true)
21 {{/code}}
22
23 = Accessing the request =
24
25 You can access the HTTP Request by accessing the ##com.xpn.xwiki.web.XWikiServletRequest## object through the ##request## script variable.
26
27 For example in Velocity, to access an ##action## HTTP parameter passed in the request you would write:
28
29 {{code language="velocity"}}
30 $request.action
31 {{/code}}
32
33 Note that this is a shortcut to:
34
35 {{code language="velocity"}}
36 $request.get("action")
37 {{/code}}
38
39 = Getting external content =
40
41 You can use the following APIs to get content located at external URLs:
42
43 {{code language="java"}}
44 public String getURLContent(String surl, String username, String password) throws IOException
45 public String getURLContent(String surl) throws IOException
46 public String getURLContent(String surl, String username, String password, int timeout) throws IOException
47 public String getURLContent(String surl, int timeout) throws IOException
48 public byte[] getURLContentAsBytes(String surl, String username, String password)
49 public byte[] getURLContentAsBytes(String surl) throws IOException
50 {{/code}}
51
52 For example in Velocity:
53
54 {{code language="velocity"}}
55 $xwiki.getURLContent("http://google.com")
56 {{/code}}
57
58 = Add objects to a page =
59
60 Here is a piece of Velocity script to show how is possible to store a new object in one page:
61
62 {{code language="velocity"}}
63 ## Create an object
64 #set($obj = $doc.newObject("XWiki.SomeClass"))
65 $obj.set("field1",$value1)
66 $obj.set("field2",$value2)
67
68 ## Save the object in the page
69 $doc.save()
70 {{/code}}
71
72 The "XWiki.SomeClass" class has to be created (through the class editor): field1 and field2 are property of the class. At the moment, this code works fine only if the user currently logged in has editing rights on the page, otherwise the Document.save() will not work.
73
74 = Access objects in a page =
75
76 Here is a piece of Velocity script to show how it is possible to access an object attached to the page, and read its fields :
77
78 {{code language="velocity"}}
79 ## Retrieve the first object (index [0]) among all objects attached to this page and of a certain class
80 #set($obj = $doc.getObject('SomeSpace.SomeClass'))
81
82 ## Retrieve the raw value of the propertty "field1" for this object, provided
83 ## a property called "field1" is actually defined in the class of this object
84 #set($rawValue = $obj.getProperty('field1').value)
85 SomeSpace.SomeClass[0] : field1 = "$rawValue"
86 {{/code}}
87
88 You can also go through all the properties of an object, without knowing their respective names. That's how the default Class Sheet works, when you create a class using the Class Wizard.
89
90 {{code language="velocity"}}
91 #set($class = $obj.xWikiClass) ## access the class object representing SomeSpace.SomeClass
92 #foreach($prop in $class.properties) ## go through all properties
93 <dt> *${prop.prettyName}* </dt>
94 <dd>$doc.display($prop.getName())</dd>
95 #end
96 {{/code}}
97
98 Actually the line {{code}}$doc.display(propertyName){{/code}} can either display the property value, or generate an input field in the page, mapped to the property whose name is passed as argument (when you edit the page in inline mode). If you have a Velocity script that uses the ##display(propertyName)## method to access properties of an object attached to the including page and you want to include it somewhere else you have to use the ##includeForm()## Velocity macro in the including script:
99
100 {{code language="velocity"}}
101 #includeForm("spacename.docname")
102 {{/code}}
103
104 See [[the includeForm() macro>>extensions:Extension.Include Form Macro]] for more information.
105
106 = Access objects from any page and loop over all objects of same Class =
107
108 Here is a piece of Velocity script to show how it is possible to access an object attached to the page from another page, and read its fields :
109 (It is similar than previous code except you must "call" page before with $xwiki.getDocument.)
110 {{code language="velocity"}}
111 ## get the document which has the object (only one here) - this is the page where I can see things in the object editor
112 ## Retrieve the first object (index [0]) among all objects attached to the page MySpace.MyDocWithMyClassObjects and of a certain class MySpace.MyClass
113 #set( $MyDoc = $xwiki.getDocument("MySpace.MyDocWithMyClassObjects"))
114 ## get the document wich contains the class definition: this page has entries in the class editor
115 #set( $class = $xwiki.getClass("MySpace.MyClass"))
116 #foreach($prop in $class.properties) ## go through all properties
117 * ${prop.prettyName} : $MyDoc.display($prop.getName())
118 #end
119 {{/code}}
120
121 If MySpace.MyDocWithMyClassObjects have many attached objects of MySpace.MyClass class (with different value)
122 [[image:ListProperties1.png||width="50%"]] [[image:ListProperties2.png||width="50%"]]
123 {{code language="velocity"}}
124 ## if you have more than one object on a page, you will have to loop over them and use "$doc.use"
125 #set($MyDoc = $xwiki.getDocument("MySpace.MyDocWithMyClassObjects"))
126 #set($class = $xwiki.getClass("MySpace.MyClass"))
127 ## loop over all objects
128 #foreach($obj in $MyDoc.getObjects("MySpace.MyClass"))
129 * Object number $velocityCount
130 #set($discard = $MyDoc.use($obj))
131 #foreach($prop in $class.properties) ## go through all properties
132 ** ${prop.prettyName} : $MyDoc.display($prop.getName())
133 #end
134 #end
135
136 {{/code}}
137
138 = Include a Velocity page into another Velocity page =
139
140 See the [[Include In Velocity tutorial>>DevGuide.IncludeInVelocity]].
141
142 = Redirecting to another page =
143
144 It's possible to redirect the user to another page. This is useful for example when a page has been removed and you have given the URL to someone so you want the old page to redirect to the new page.
145
146 Example:
147
148 {{code language="velocity"}}
149 $response.sendRedirect($xwiki.getURL("Space.Page"))
150 {{/code}}
151
152 For more examples, see the [[Redirect Snippet>>extensions:Extension.Redirect]].
153
154 = Add an Attachment to a page =
155
156 For example, in Velocity:
157
158 {{code}}
159 {{velocity}}
160 #set($content = "This is some small arbitrary content")
161 #set($discard = $doc.addAttachment("myfile.txt", $content.getBytes()))
162 #set($discard = $doc.save("some comment"))
163 {{/velocity}}
164 {{/code}}

Get Connected