xwiki开发者指南-脚本

脚本可以让你在XWiki页面(或者视图)无需编译代码或部署软件组件来创建基本到复杂的Web应用程序。换句话说，你可以除了wiki和HTML语法之外使用脚本语法来编写XWiki页面的内容。

XWiki集成了jsr-223 scripting。你可以使用通用的Script Macro来使用几种可用的语言或使用以下特定宏：

• Velocity Macro (XWiki Enterprise默认安装)
• Groovy Macro (XWiki Enterprise默认安装)
• Python Macro (XWiki Enterprise默认安装)
• Ruby Macro (XWiki Enterprise默认无安装)
• PHP Macro (XWiki Enterprise默认无安装)

权限

从XWiki 7.2M1开始，一个用户需要有Script权限来编写脚本。

另外，除了Velocity以外的所有脚本语言也需要编程权限（见下文有详细介绍）。

选择一个脚本语言

XWiki支持多种脚本语言。大部分由XWiki开发者编写代码是使用Velocity，有一些复杂的扩展是由Groovy编写；这两者脚本语言是久经考验和反复测试。而其他的语言应该也是可以正常使用的，但是只有少量的开发人员可以帮忙回答相应的问题。

Velocity

了解Velocity的第一件事情是它与其他脚本语言的2个不同方面：

• 这是一个模板语言，而不是一个纯粹的脚本语言，这意味着它的内容实际上是Velocity指令穿插wiki标记，而纯粹的脚本语言是该语言编写的，他们需要明确的输出wiki标记。例如： Velocity: {{velocity}} Your username is $xcontext.getUser(), welcome to the site. {{/velocity}} Groovy: {{groovy}} println("Your username is " xcontext.getUser() " welcome to the site."); {{/groovy}}
• 在沙盒里运行脚本是不需要权限，只能访问几个安全的对象，并且每个API调用需要检查在wiki配置里的权限，当前用户不允许执行将禁止对资源的访问或操作。其他的脚本语言要求编写脚本的用户有编程权限来执行它们，但是除了这个初始前提条件，服务器上的所有资源都是授予访问权限。注意，从XWiki 4.1我们引入了一个Sandbox for Groovy，但它仍在初期阶段。

作为一个模板引擎，Velocity不提供结构化代码。事实上，在这方面只有一个有用的指令，#macro。然而，因为它是一个模板引擎，它的语法更简单，更容易被非开发人员了解，这意味着它有更广泛的用户使用，无需编程背景。

没有编程权限，是不可能实例化新的对象，除了文字和那些由XWiki提供的安全的API。尽管如此，XWiki API是强大到足以允许安全地开发出了广泛的应用，前提是遵循“XWiki方式”。

Velocity在XWiki其他一些地方也可供选择：用此语言编写XWiki HTML UI模板，可以在皮肤扩展选择性激活。

最后，Velocity适合由小到中等复杂的项目，并且不需要访问其他资源除了XWiki提供的API和注册的脚本服务。它允许非常快速和轻松的开发，提供了良好的安全性和出色的性能，并且可以很容易地被包装为XAR。

Groovy

Groovy是一个成熟的脚本语言，它支持几乎所有的java语法，并提供了自己的语法，而且提供了增强Java语言的自定义API。虽然建议复杂的代码用Java编写然后通过脚本访问服务组件，但是Groovy的优点在于它可以在wiki编写，无需编译，部署和服务器重新启动，从而实现更快的开发。

当执行Groovy脚本时，XWiki API在上下文中是可以用的，但不像在Velocity，代码并不局限于API，可以自由地访问任何其他类或对象。新的类可以在Groovy进行定义，与Java类兼容，这使得可以写更多结构化代码，不像Velocity。它可以加载jar文件到classpath，这意味着一个wiki文档可以包含一个复杂的程序和平台没有提供的库。

总之，Groov的适合于复杂的项目或通过新的组件自定义增强wiki，它也可以很容易打包为XAR。

考虑到这些因素后，如果需要的编程权限不是你的问题，那么你应该挑选你最熟悉的脚本语言！

XWiki Scripting API

Scripting API文档是以Javadoc格式，具体访问XWiki API Javadoc。如果你不熟悉Java或面向对象编程，你可能会对API文档困惑。这不是在我们文档的范围之内教你所有关于Java或面向对象的编程细节。你可以在网上找到所有已经存在的信息。你还可以游览整个扩展wiki，看看别人是如何实现各种效果的页面代码。

我们还提供了一个API指南有关使用XWiki API的例子。

绑定

主要提供的对象：

• 当前文档：doc
• 请求的上下文：xcontext
• request对象：request
• Response对象：response
• XWiki对象：xwiki
• XWiki utils: util (已被弃用)
• 各种脚本服务: services

查看脚本参考文档的完整列表。

访问XWiki Component

从XWiki 4.1M2 开始，可以通过脚本服务访问Component Manager (也可以看下：通过Groovy访问components).

例如使用Groovy：

{{groovy}}

def greeter = services.component.getInstance(org.xwiki.component.HelloWorld.class)

println greeter.sayHello()

{{/groovy}}

你还可以通过以下获得ComponentManager：

{{groovy}}

def cm = services.component.componentManager

{{/groovy}}

低于XWiki 4.1M2版本的，你需要用以下方式（Groovy）：

{{groovy}}

def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class)

println greeter.sayHello()

{{/groovy}}

访问XWiki Core

有时XWiki API不提供你的应用程序需要的一些方法。你可以访问XWiki Core，但是它增加了安全风险，并且需要编程权限才能保存包含该脚本的页面(查看包含需要编程权限的脚本是不需要编程权限，只有在保存时才是需要)。

{{groovy}}

def xc = xcontext.getContext();

def wiki = xc.getWiki();

def xdoc = doc.getDocument();

{{/groovy}}

使用这个代码片段后，你将有3个新的对象：

• 上下文对象的底层XWikiContext: xc
• 底层XWiki对象: wiki
• 当前文档的底层XWikiDocument: xdoc

你会发现，在wiki的许多方法和xdoc需要XWikiContext的实例，这是底层的xcontext XC不是API上下文的xcontext。

再次，当功能不提供公共Api时，这些方法仅用于极少情况下。我们投入了大量的精力维护公共API，少量精力维护核心方法，所以你可能会发现，核心方法已被弃用，删除或在后续版本中改变。

查询XWiki Model

从你的脚本，你可以查询所有XWiki Model。查看Query Module以获取更多信息。

Velocity具体信息

Velocity是当前唯一不需要编程权限的脚本语言。这意味着你可以使用较少的权限的用户来保存Velocity脚本，没有人可以利用你的脚本来执行安全漏洞。

你可以用Velocity获得访问XWiki core，但这需要编程权限。严格地说，受保护的API可用仅当页面最后一次是具体编程权限的人保存。

在Velocity，你不能导入类，因此你不能访问XWiki components。你需要提供绑定。(注意: 在Velocity， 这些绑定都以$开始和其他Velocity变量)

有关Velocity语言编程的更多信息，可以参考Velocity用户指南。也可以查看Velocity练习。

更多有关详细使用Velocity，查看Velocity模块文档，包含完整的Velocity工具的完整列表。

如果要添加新的Velocity工具，你需要编辑你的xwiki.properties文件，并按照说明进行操作。

要在其他Velocity脚本引入Velocity脚本，查看这里。

其他Velocity变量

这些变量可以使用，但在未来会发生变化。

控制哪些部分显示

你可以控制 Comments/History/Attachment/Information部分，通过设置一些velocity变量为false：

#set (showcomments = false) #set ( showattachments = false) #set (showhistory = false) #set ( showinformation = false)

删除所有，你可以设置：

#set($docextras = [])

关于当前用户的信息

以下的变量(在xwikivars.vm 模板中设置)用于查看当前用户各种信息的快捷方式：

• $isGuest: 检查当前用户是不是XWiki.XWikiGuest
• $isSuperAdmin: 检查当前用户是不是特殊用户superadmin
• $hasComment: 检查当前文档是否有评论权限
• $hasEdit: 检查当前文档是否有编辑权限
• $hasWatch: 检查用户是否经过身份验证，并提供watch服务
• $hasAdmin: 检查当前文档是否有admin权限
• $hasSpaceAdmin: 检查当前空间的XWikiPreferences文档的admin权限
• $hasGlobalAdmin: 检查XWiki.XWikiPreferences的admin权限
• $hasCreateSpace: 在不存在的空间，检查是否有对不存在的页面有编辑权限
• $hasCreatePage: 在当前空间检查是否有对不存在的页面有编辑权限
• $hasProgramming: 检查当前用户是否有编程权限
• $isAdvancedUser: 高级用户： superadmin，用户的用户类型属性设置为“Advanced”，拥有管理员权限的游客

例如：

{{velocity}}

#if ($hasAdmin)

This link will only be visible to users that have admin rights on this document

[Do some admin action>>Some.Document]

#end

{{/velocity}}

关于当前wiki的信息

以下变量(在xwikivars.vm 模板中设置)用于查看当前wiki各种信息的快捷方式：

• $isReadOnly
• $isInServletMode
• $isInPortletMode

Groovy具体信息

目前所有使用非Velocity脚本语言需要用户有编程权限。

• 在扩展wiki查看Groovy代码片段(在标签云点击"Groovy"标签)
• Groovy网站

Groovy例子

下面的例子演示了如何使用Groovy脚本在你的页面与velocity代码交互。以下例子通过DNS查找IP，通过velocity变量hostname以及把结果存储在变量 address里。

使用XWiki语法2.0:

对象可以在脚本语言间被来回传递，通过存储在对象。

{{velocity}} #set(hostname = "www.xwiki.org") Host Name: $``$xcontext.put("hostname",

使用XWiki语法1.0:

由于是一起解析Groovy和Velocity代码，在Groovy中定义的变量可以直接在velocity使用，从上下文获取。

#set (hostname = "www.xwiki.org") Host Name:

Python具体信息

你可以在XWiki运行Python代码，就如Velocity或者Groovy一样。

{{python}}

print "The full name of this document is " doc.getFullName()

{{/python}}

语言之间共享变量

大多数基于JSR223脚本语言可以重新注入创建的变量到当前ScriptContext中，这意味着你可以在Groovy脚本定义一个变量，并在例如Python脚本重用。

从4.1M2开始，这个桥梁已经为Velocity （这不是基于JSR223），以允许它访问当前ScriptContext中的变量，所以你可以这样写：

{{groovy}}

var = "toto"

{{/groovy}}

{{velocity}}

$var

{{/velocity}}

请注意，你也可以通过在XWiki上下文（xcontext绑定）设置他们来共享变量。

XWiki语法1.0 脚本

XWiki语法1.0在旧的渲染引擎还是支持的，但是在未来开发中是没有计划（最终被删除）。语法1.0的一些特性在语法2.0中解决。

• 只提供给Velocity和Groovy脚本语言。
• 在Groovy，上下文为：context不是xcontext
• Groovy脚本的开头和结尾的标记为<%和%>而不是通过Groovy宏 (使用{{groovy}}和{{/groovy}})
• Velocity在页面可以直接解析(不需要引入Velocity宏，使用{{velocity}}和{{/velocity}})

最后这一部分是很重要的，因为这意味着你需要小心当你的文档中使用$和# 的时候。在<%和%>中这些会生效，所以你写Groovy脚本的时候要小心。