小组件使用 Velocity 语言

小组件内容是使用 Velocity 模板语言的一个实现。

何时应使用 Velocity 模板语言？

Velocity 是小组件使用的服务器端模板语言。除了提供服务器端模板之外，Velocity 还用于小组件扩展 API（包括自定义小组件扩展）执行的服务器端请求。

Velocity 语言语法

变量、属性和方法

变量和扩展

$[!][{ ][a-z,A-Z][a-z,A-Z,0-9,-,_]*[ }]

变量和扩展名必须以美元符号和字母开头。

当变量的值为 null 时，$variable 将呈现变量的名称，而 $!variable 将不呈现任何内容。

${variable} 是变量的正规记法，用于区分文本中的变量引用，例如：see${variable}this。

属性

$[!][{ ][a-z,A-Z][a-z,A-Z,0-9,-,_]*.[a-z,A-Z][a-z,A-Z,0-9,-,_]*[ }]

点语法用于引用变量和扩展属性。

当属性的值为 null 时，$extension.Property 将呈现扩展名和属性的名称，而 $!extesion.Property 将不呈现任何内容。

${extension.Property} 是属性的正规记法，用于区分文本中的属性引用，例如：see${extension.Property}this。

方法

$[!][{ ][a-z,A-Z][a-z,A-Z,0-9,-,_]*.[a-z,A-Z][a-z,A-Z,0-9,-,_]*([可选参数列表])[ }]

点语法用于引用变量和扩展方法。

当该方法的返回值为 null 时，$extension.Method() 将呈现扩展名和方法的名称，而 $!extesion.Method() 将不呈现任何内容。如果返回值为 void，则不会呈现任何内容。

${extension.Method()} 是方法的正规记法，用于区分文本中的方法引用，例如：see${extension.Method()}this。

指令

#set

#set($reference = [argument])

将值赋给变量或属性，其中：

$reference 是变量或属性引用。
[argument]是：
- 方法、变量或属性引用
- 布尔值 (true 或 false)
- 数字 ([0-9]*.[0-9]*)
- 单引号或双引号的文本字符串
- 数组定义 ([$item1, $item2, $item3,... $itemN])
- 数学表达式：
  - 加法：#set($n = $n + 1)
  - 减法：#set($n = $n - 1)
  - 乘法：#set($n = $n * $x)
  - 除法: #set($n = $n / $x)
  - 模数：#set($n = $n % $x)

当 [argument] 是文本字符串时，双引号中的字符串将被解析，而单引号中的字符串将不会被解析。

#if

#if([condition1])
  [condition1 为 true，执行脚本]
[
#elseif([condition2])
  [condition2 为 true，执行脚本]
]*
[
#else
  [没有 condition 为 true，执行脚本]
]
#end

有条件地呈现模板，其中：

[condition]是：
- 布尔表达式：
  - 相等：#if($x == $y)
  - 大于：#if($x > $y)
  - 小于：#if($x < 100)
  - 大于等于：#if($x >= 100)
  - 小于等于：#if($x <= 100)
- 非布尔变量、属性、方法或文本引用（如果不是 null，则为 true，否则为 false）。
[脚本...]是任何 Velocity 或文本。

#foreach

#foreach($item in $items)
[#each]
  [执行每项目的脚本]
[
#before
  [每项目前执行的脚本]
]
[
#after
  [每项目后执行的脚本]
]
[
#between
  [每项目间执行的脚本]
]
[
#odd
  [每项目的位置为奇数时，执行脚本]
]
[
#even
  [每项目的位置为偶数时，执行脚本]
]
[
#nodata
  [没有项目时，执行脚本]
]
[
#beforeall
  [有项目时，在全部项目前执行脚本]
]
[
#afterall
  [有项目时，在全部项目后执行脚本]
]
#end

项目集合的每个项目呈现模板，其中：

$item 是 $items 集合的每个项目变量，用于执行 #each、#odd 和 #even 脚本。
$items 是能返回项目集合的变量、属性或方法。
[脚本...] 是任何 Velocity 或文本。

#each 是默认模板，因此，

#foreach($item in $items)
  $item.Name
#end

等同于：

#foreach ($item in $items)
#each
  $item.Name
#end

#registerEndOfPageHtml

#registerEndOfPageHtml([key])
  [HTML 页面底部执行的脚本]
#end

在已完成的 HTML 页面末注册一个 HTML 块，其中：

[key] 是一个可选的变量、属性或文本字符串值，用于标识当前注册的唯一键。
[脚本...] 是任何 Velocity 或文本。

如果未提供 [key]，则包含的脚本将始终添加到已完成的 HTML 页面的底部，脚本会重复执行。如果提供了 [key]，则执行的第一个 #registerEndOfPageHtml 指令会将其包含的脚本添加到已完成页面的底部。

#evaluate

#evaluate($script)

将字符串作为 Velocity 脚本执行，其中：

$script 是包含 Velocity 脚本的变量、属性或文本字符串。

#stop

#stop

立即停止执行小组件。

#stop 仅用于调试目的。要隐藏小组件，请使用 $limyee_v1_widget.Hide() 。

##

## [注释]

标识注释，其中：

[注释] 是一行不会执行的文本。

#*

#* [多行注释] *#

标识多行注释，其中：

[多行注释] 是一行或多行不会执行的文本。

小组件扩展使用 Velocity

大多数平台 API 都可用于 velocity 脚本，作为小组件的扩展，这些 API 在执行的 velocity 脚本上下文中自动可用。此外，velocity 脚本还可以访问自定义扩展。

有关更多信息，请参阅完整的小组件扩展。

当小组件扩展方法接受 IDictionary 参数时，可以使用 Velocity 语法传递这些选项

"%{ Key1 = $value1, Key2 = $value2 }"

请注意，整个 IDictionary 将作为格式化字符串传递。

示例小组件扩展使用

以下示例将检索并呈现当前博客的博客文章列表

## Retrieve the current blog. If there is none, hide the widget
#set ($currentBlog = $limyee_v1_blog.Current.Id)
#if (!$curentBlog)
	$limyee_v1_widget.Hide()
#end

## Retrieve the 5 latest blog posts
#set ($blogPosts = $limyee_v1_blogPost.List("%{ BlogId = $currentBlog.Id, PageSize = 5 }"))

#foreach ($blogPost in $blogPosts)
#beforeall
	<ul>
#each
		<li><a href="$limyee_v1_encoding.HtmlAttributeEncode($blogPost.Url)">$blogPost.Title</a></li>
#afterall
	</ul>
#nodata
	<span class="message">No blog posts</span>
#end

提示和技巧

获取当前 foreach 索引

如果要跟踪当前索引，则需要将索引存储为局部变量。下面是如何执行此操作的示例。

#set($index = 0)
#foreach($tag in $limyee_v1_tags.Current)
#each
    #set($index = $index + 1)
#end

串联字符串

通常，您需要组合两个或多个字符串并将结果作为参数传递给方法，为此，请将变量放在双引号内：

#set($newVal = "$val1$val2")

在 URL 末尾的点之前添加变量

您可能需要将 Velocity 变量作为 URL 的一部分传递，并且可能需要在 URL 的末尾传递点之前的变量。例如，如果要为 api/v1/groups/$groupId/members/users/$userId.json 创建一个 URL ，其中 $userId 是局部 Velocity 变量，则 $userId 格式不正确，因为它正在 $userId 上查找名为 json 的属性。要解决此问题，您可以对 Velocity 变量使用正规格式进行设置，如下所示：

api/v1/groups/$groupId/members/users/${userId}.json

使用 null 值

当 Velocity 评估时

#set ($variable = $someExtension.someMethod())

如果 $someExtension.someMethod() 的计算结果为 null，则不会更改 $variable。它仍将具有其以前的值。要重用 $variable 变量（例如，在 #foreach 中），请改用：

#set ($variable = false)
#set ($variable = $someExtension.someMethod())

以编程方式修改/构建 IDictionary 选项

已经可以进行这样的调用

$limyee_v1_foo.Bar(42, "%{ key1 = "value", key2 = "value2" }

有时，出于循环或逻辑原因，需要以编程方式构建选项。这可以按如下方式完成：

#set ($options = "%{}")
$options.Add(newKey, "newValue")