Wiki source code of XWiki Scripting API Guide
Version 12.2 by Vincent Massol on 2012/05/11
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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]]. | ||
| 2 | |||
| 3 | {{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}} | ||
| 4 | |||
| 5 | Note that while most examples are written in Velocity you can use [[any other scripting language>>DevGuide.Scripting]] to access the same APIs. | ||
| 6 | |||
| 7 | = Querying documents = | ||
| 8 | |||
| 9 | See the [[Query Module>>extensions:Extension.Query Module]] for examples on how to perform queries on the wiki using a scripting language. | ||
| 10 | |||
| 11 | = Accessing the request = | ||
| 12 | |||
| 13 | You can access the HTTP Request by accessing the ##com.xpn.xwiki.web.XWikiServletRequest## object through the ##request## script variable. | ||
| 14 | |||
| 15 | for example in Velocity, to access an ##action## HTTP parameter passed in the request you would write: | ||
| 16 | |||
| 17 | {{code language="velocity"}} | ||
| 18 | $request.action | ||
| 19 | {{/code}} | ||
| 20 | |||
| 21 | Note that this is a shortcut to: | ||
| 22 | |||
| 23 | {{code language="velocity"}} | ||
| 24 | $request.get("action") | ||
| 25 | {{/code}} | ||
| 26 | |||
| 27 | = Getting external content = | ||
| 28 | |||
| 29 | You can use the following APIs to get content located at external URLs: | ||
| 30 | |||
| 31 | {{code language="java"}} | ||
| 32 | public String getURLContent(String surl, String username, String password) throws IOException | ||
| 33 | public String getURLContent(String surl) throws IOException | ||
| 34 | public String getURLContent(String surl, String username, String password, int timeout) throws IOException | ||
| 35 | public String getURLContent(String surl, int timeout) throws IOException | ||
| 36 | public byte[] getURLContentAsBytes(String surl, String username, String password) | ||
| 37 | public byte[] getURLContentAsBytes(String surl) throws IOException | ||
| 38 | {{/code}} | ||
| 39 | |||
| 40 | For example in Velocity: | ||
| 41 | |||
| 42 | {{code language="velocity"}}$xwiki.getURLContent("http://google.com"){{/code}} | ||
| 43 | |||
| 44 | = Add objects to a page = | ||
| 45 | |||
| 46 | Here a piece of Velocity script to show how is possible to store a new object in one page: | ||
| 47 | |||
| 48 | {{code language="velocity"}} | ||
| 49 | ## Create an object | ||
| 50 | #set($obj = $doc.newObject("XWiki.SomeClass")) | ||
| 51 | $obj.set("field1",$value1) | ||
| 52 | $obj.set("field2",$value2) | ||
| 53 | |||
| 54 | ## Save the object in the page | ||
| 55 | $doc.save() | ||
| 56 | {{/code}} | ||
| 57 | |||
| 58 | 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. | ||
| 59 | |||
| 60 | = Access objects in a page = | ||
| 61 | |||
| 62 | 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 : | ||
| 63 | |||
| 64 | {{code language="velocity"}} | ||
| 65 | ## Retrieve the first object (index [0]) among all objects attached to this page and of a certain class | ||
| 66 | #set($obj = $doc.getObject("SomeSpace.SomeClass")) | ||
| 67 | |||
| 68 | ## Retrieve the value of the propertty "field1" for this object, provided a property called "field1" is actually defined in the class of this object | ||
| 69 | #set($field1 = $obj.get("field1")) | ||
| 70 | SomeSpace.SomeClass[0] : field1 = "$field1" | ||
| 71 | {{/code}} | ||
| 72 | |||
| 73 | You can also go through all properties of an object, without knowing their name respective names. That's how the default Class Sheet works, when you create a class using the Class Wizard. | ||
| 74 | |||
| 75 | {{code language="velocity"}} | ||
| 76 | #set($class = $obj.xWikiClass) ## access the class object representing SomeSpace.SomeClass | ||
| 77 | #foreach($prop in $class.properties) ## go through all properties | ||
| 78 | <dt> *${prop.prettyName}* </dt> | ||
| 79 | <dd>$doc.display($prop.getName())</dd> | ||
| 80 | #end | ||
| 81 | {{/code}} | ||
| 82 | |||
| 83 | 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 you want to include somewhere else, and uses the {{html clean="false" wiki="true"}}<code>display(propertyName)</code> method to access properties of an object attached to the including page, you have to use the <code>includeForm()</code>{{/html}} Velocity macro in the including script : | ||
| 84 | |||
| 85 | {{code language="velocity"}}#includeForm("spacename.docname"){{/code}} | ||
| 86 | |||
| 87 | See [[the reference for the includeForm() macro>>extensions:Extension.Include Form Macro]]. | ||
| 88 | |||
| 89 | = Include a Velocity page into another Velocity page = | ||
| 90 | |||
| 91 | See [[Include In Velocity>>DevGuide.IncludeInVelocity]]. | ||
| 92 | |||
| 93 | = Redirecting to another page = | ||
| 94 | |||
| 95 | 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. | ||
| 96 | |||
| 97 | Example: | ||
| 98 | |||
| 99 | {{code language="velocity"}}$response.sendRedirect($xwiki.getURL("Space.Page")){{/code}} | ||
| 100 | |||
| 101 | For more examples, see the [[Redirect Snippet>>extensions:Extension.Redirect]]. |
