xwiki开发者指南-脚本API指南

本次指南覆盖main XWiki，可以在wiki页面通过脚本使用的API。这并不意味着全面。对于其他你需要查看XWiki参考API页面。

请注意，虽然大多数的例子都用Velocity编写，但你可以使用任何其他脚本语言来访问相同的API。

查询文档

查看查询模块了解有关如何在wiki使用脚本语言执行查询的例子。 

创建一个新文档

Velocity的例子：

## Note that getDocument() creates a Document if it doesn't exist. This can be checked with $newDoc.isNew()
#set ($newDoc = $xwiki.getDocument('MySpace.MyPage'))
## Set its content (for example)
#set ($discard = $newDoc.setContent("new content"))
## The second parameter to save() indicates whether the save is a minor edit or not
#set ($discard = $newDoc.save("some comment explaining the save", true)

访问请求

你可以通过request脚本变量访问com.xpn.xwiki.web.XWikiServletRequest对象来访问HTTP请求。

例如，在Velocity，访问请求中传递的action HTTP参数，可以这样写：

$request.action

请注意，这有一个快捷方式：

$request.get("action")

获取外部内容

你可以使用下面的API来获取位于外部URL的内容：

public String getURLContent(String surl, String username, String password) throws IOException
public String getURLContent(String surl) throws IOException
public String getURLContent(String surl, String username, String password, int timeout) throws IOException
public String getURLContent(String surl, int timeout) throws IOException
public byte[] getURLContentAsBytes(String surl, String username, String password)
public byte[] getURLContentAsBytes(String surl) throws IOException

Velocity例子：

$xwiki.getURLContent("http://google.com")

添加对象到页面

这里是Velocity脚本来显示如何在一个页面存储新的对象：

## Create an object
#set($obj = $doc.newObject("XWiki.SomeClass"))
$obj.set("field1",$value1)
$obj.set("field2",$value2)

## Save the object in the page
$doc.save()

"XWiki.SomeClass"类必须创建（通过类编辑）：field1和field2是类是属性。目前，该代码只有在当前登录的用户中有该页面的编辑权限时可以正常生效，否则Document.save()将无效。

访问一个页面的对象

这里是Velocity脚本来显示它是如何访问附在页面的对象，并读取其字段：

## Retrieve the first object (index [0]) among all objects attached to this page and of a certain class 
#set($obj = $doc.getObject('SomeSpace.SomeClass'))

## Retrieve the raw value of the propertty "field1" for this object, provided
## a property called "field1" is actually defined in the class of this object
#set($rawValue = $obj.getProperty('field1').value)
SomeSpace.SomeClass[0] : field1 = "$rawValue"

## return the property type: String, TextAreaDate, Boolean, ...
$obj.get('field1').classType

你也可以在不知道它们各自的名字的情况下获得对象的所有属性。当你使用类向导创建一个类时，下面是默认Class Sheet的方式：

#set($class = $obj.xWikiClass) ## access the class object representing SomeSpace.SomeClass
#foreach($prop in $class.properties) ## go through all properties
 <dt> *${prop.prettyName}* </dt>
 <dd>$doc.display($prop.getName())</dd>
#end

实际上$doc.display(propertyName) 可以显示属性值或者生成页面输入字段，映射到其名称作为参数传递（当inline模式编辑页面）的属性。如果你有一个Velocity脚本，使用display(propertyName)方法来访问包含页面的一个对象的属性，你想在其他地方include，你必须使用includeForm() Velocity宏：

#includeForm("spacename.docname")

查看includeForm()宏了解更多信息。

从任何页面访问对象和在相同类遍历所有对象

这里是Velocity脚本来显示它是如何从另一个页面访问页面中的对象，并读取其字段：
(类似于先前的代码，除了你需要在$xwiki.getDocument之前"call"页面)

## get the document which has the object (only one here) - this is the page where I can see things in the object editor
## Retrieve the first object (index [0]) among all objects attached to the page MySpace.MyDocWithMyClassObjects and of a certain class MySpace.MyClass
#set( $MyDoc = $xwiki.getDocument("MySpace.MyDocWithMyClassObjects"))
## get the document wich contains the class definition: this page has entries in the class editor
#set( $class = $xwiki.getClass("MySpace.MyClass"))
#foreach($prop in $class.properties) ## go through all properties
  * ${prop.prettyName} : $MyDoc.display($prop.getName())
#end

如果MySpace.MyDocWithMyClassObjects有许多MySpace.MyClass类的对象(不一样的值)
 

## if you have more than one object on a page, you will have to loop over them and use "$doc.use"
#set($MyDoc = $xwiki.getDocument("MySpace.MyDocWithMyClassObjects"))
#set($class = $xwiki.getClass("MySpace.MyClass"))
## loop over all objects
#foreach($obj in $MyDoc.getObjects("MySpace.MyClass"))
  * Object number $velocityCount
 #set($discard = $MyDoc.use($obj))
 #foreach($prop in $class.properties) ## go through all properties
    ** ${prop.prettyName} : $MyDoc.display($prop.getName())
 #end
#end

在其他Velocity页面引用一个Velocity页面

查看Velocity引用教程。

重定向到另一个页面

例如：当一个页面已经被删除，你要让旧的页面重定向到新的页面。

例子：

$response.sendRedirect($xwiki.getURL("Space.Page"))

有关更多示例，请参阅重定向Snippet.

为页面添加附件

Velocity例子：

{{velocity}}
#set($content = "This is some small arbitrary content")
#set($discard = $doc.addAttachment("myfile.txt", $content.getBytes()))
#set($discard = $doc.save("some comment"))
{{/velocity}}