xwiki开发者指南-脚本

最新推荐文章于 2020-02-12 23:05:37 发布

编程泓哥

最新推荐文章于 2020-02-12 23:05:37 发布

阅读量1.6k

点赞数 38

分类专栏： xwiki开发人员指南

本文链接：https://blog.csdn.net/qq_33873431/article/details/89136972

版权

xwiki开发人员指南专栏收录该内容

29 篇文章 10 订阅

订阅专栏

脚本可以让你在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: $hostname
$xcontext.put("hostname", $hostname)
{{/velocity}}
{{groovy}}
import java.net.InetAddress;
host = xcontext.get("hostname");
InetAddress addr = InetAddress.getByName(host);
String address = addr.getHostAddress();
xcontext.put("address", address);
{{/groovy}}
{{velocity}}
IP Address: $xcontext.get("address")
{{/velocity}}

使用XWiki语法1.0:

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

#set ($hostname = "www.xwiki.org")
Host Name: $hostname
<%
import java.net.InetAddress;
vcontext = context.get("vcontext");
host = vcontext.get("hostname");
InetAddress addr = InetAddress.getByName(host);
String address = addr.getHostAddress();
%>
IP Address: $address