XForms XPath函数使用手册

1. 概要

本文所描述的所有函数为XForms 1.1所提供的xpath函数，这些函数只能在GForms的xpath编辑器中可用，这样才能在运行时识别并执行。

不可在XMLUtil、标准XML DOM中使用这些函数。

GForms平台提供xpath编辑器，该编辑器可以协助开发者完成大多数xpath表达式开发：

2. 节点函数

2.1. instance

node-set instance(string?)

An XForms Model can contain more than one instance. This function allows access to instance data, within the same XForms Model, but outside the instance data containing the context node.

If the argument is omitted or is equal to the empty string, then the root element node (also called the document element node) is returned for the default instance in the model that contains the current context node.

Otherwise, the argument is converted to a string as if by a call to the string function. This string is treated as an IDREF, which is matched against instance elements in the containing document. If a match is located, and the matching instance data is associated with the same XForms Model as the current context node, this function returns a node-set containing just the root element node (also called the document element node) of the referenced instance data. In all other cases, an empty node-set is returned.

Example:

For instance data corresponding to this XML:

 1 <xforms:instance xmlns="" id="orderform"> 2  3 <orderForm> 4  5 <shipTo> 6  7 <firstName>John</firstName> 8  9 </shipTo>10 11 </orderForm>12 13 </xforms:instance>

The following expression selects the firstName node. Note that the instance function returns an element node, effectively replacing the leftmost location step from the path:

ref="instance('orderform')/shipTo/firstName"

3. 字符串函数

3.1. if

string if(boolean, string, string)

Function if evaluates the first parameter as boolean, returning the second parameter when true, otherwise the third parameter.

3.2. property

string property(string)

This function accepts a string identifying a property name. If the property name is not recognized, empty string is returned. The property definitions for this function are as follows:

Property	Return Value
version	1.1
conformance-level	full, basic or a string beginning with full or basic
Any other NCName	Reserved. Their use results in an exception (see 7.5 The XForms Function Library for the exception type)
QNameButNotNCName	An implementation-specific property value, such as a locale or timezone for the user agent. If the implementation does not support the property, then empty string is returned.

Examples:

property('version')

returns 1.1

property('conformance-level')

may return full

4. 数值函数

4.1. avg

number avg(node-set)

Function avg returns the arithmetic average of the result of converting the string-values of each node in the argument node-set to a number. The sum is computed with sum(), and divided with div by the value computed with count(). If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.

4.2. The min() Function

number min(node-set)

Function min returns the minimum value of the result of converting the string-values of each node in argument node-set to a number. "Minimum" is determined with the < operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.

4.3. max

number max(node-set)

Function max returns the maximum value of the result of converting the string-values of each node in argument node-set to a number. "Maximum" is determined with the < operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.

4.4. count-non-empty

number count-non-empty(node-set)

Function count-non-empty returns the number of non-empty nodes in argument node-set. A node is considered non-empty if it is convertible into a string with a greater-than zero length.

4.5. index

number index(string)

Function index takes a string argument that is the IDREF of a repeat and returns the current 1-based position of the repeat index for the identifiedrepeat—see 9.3.1 The repeat Element for details on repeat and its associated repeat index. If the specified argument does not identify a repeat, the function returns NaN.

Note:

The IDREF obtained from the function parameter may not uniquely identify the desired repeat if the repeat element bearing the matching ID resides in a repeating construct such as element repeat. The general method described in 4.7 Resolving ID References in XForms is used to determine the desired run-time repeat object.

index

<xforms:trigger><xforms:label>Add to Shopping Cart</xforms:label><xforms:insert ev:event="DOMActivate" position="after"nodeset="items/item" at="index('cartUI')"/></xforms:trigger>

 

4.6. power

number power(number, number)

Raises the first argument to the power of the second argument, returning the result. If the calculation does not result in a real number, then NaNis returned.

Examples:

power(2, 3)

returns 8

power(-1, 0.5)

returns NaN.

if (prin>0 and dur>0 and rate>0, prin*rate/(1-power(1+rate, -dur)), 0)

returns a compounded interest payment value given a non-zero principal (prin), duration (dur) and periodic interest rate (rate).

4.7. random

number random(boolean?)

This function generates and returns a uniformly distributed random or pseudorandom number in the range from 0.0 up to but excluding 1.0. This function accepts an author-optional boolean parameter that is false by default. If true, the random number generator for this function is first seeded with a source of randomness before generating the return value. A typical implementation may seed the random number generator with the current system time in milliseconds when random(true) is invoked, and it may apply a linear congruential formula to generate return values on successive invocations of the function.

Example:

random()

could return 0.14159265358979

4.8. compare

number compare(string, string)

This function returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of second argument based on lexicographic comparison using Unicode code point values [Unicode Collation Algorithm].

Example:

compare('apple', 'orange')

returns -1

5. 布尔函数

5.1. boolean-from-string

boolean boolean-from-string(string)

Function boolean-from-string returns true if the required parameter string is "true" or "1", or false if parameter string is "false", or "0". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression. If the parameter string matches none of the above strings, according to a case-insensitive comparison, the return value is false.

6. 时间函数

时间的格式处理，为了简化本地化时间处理，gforms提供对时间的格式进行了可配置处理，按照xsd:date、xsd:dateTime，时间的字符串中会包含T、z等字符串信息，而在大多数编程场景下，一般不需要处理T、z信息，所以为了提供编程开发人员处理时间的效率，GForms对xsd:dateTime的合法格式进行可配置化。

系统默认时间格式：

格式类型	标准格式	GForms格式
xsd:date	yyyy-MM-ddz	yyyy-MM-dd
xsd:dateTime	yyyy-MM-ddThh:mm:ssz	yyyy-MM-dd hh:mm:ss

上述时间格式配置在GForms应用的<webContent>/ghorse/js/conf/config_xx.xsl文件中的date及dateTime。

6.1. now

string now()

得到当前UTC时间字符串，字符串格式与XSD的数据类型xsd:dateTime格式一致，而在GForms中所返回的时间字符串是按照config_xx.xslt中的dateTime格式进行格式化。

now()

按标准应该返回：2014-03-14T01:04:17Z，但在GForms中将根据config_xx.xslt中的dateTime配置进行返回：2014-03-14 01:04:17以方便本地化编程处理。

6.2. local-date

string local-date()

将返回与XSD数据类型xsd:date格式一致的字符串，该时间为本本地区时间，而非UTC时间，在GForms中将根据confgi_xx.xslt中的date配置格式进行格式化返回。

local-date()

返回格式 2006-10-13

6.3. local-dateTime

string local-dateTime()

返回与xsd:daeTime格式一致的当前本地区时间，在gforms平台中，该时间将根据config_xx.xslt中的dateTime进行格式化返回。

local-dateTime()

按标准应该返回： 2006-10-13T16:04:17-07:00

但在GForms中如果是中国地区则会返回： 2006-10-13 16:04:17。

6.4. days-from-date

number days-from-date(string)

返回输入时间字符串所含有的天数，输入的时间字符串必须符合xsd:date或xsd:dateTime格式，但在GForms中要求输入字符串符合config_xx.xslt中的date、dateTime格式规范。

将把输入的时间转换为UTC格式，然后计算与 1970-01-01时间之间的天数。

如果输入的字符串参数不满足条件则返回NaN.

days-from-date("2002-01-01")

返回：11688

days-from-date("2002-01-01-07:00")

返回：11688，即小时、分钟及秒被忽略掉。

6.5. ays-to-date

string days-to-date(number)

把输入的天数转换为时间字符串，天数将从 1970-01-01之后开始计算，如果输入的天数非法，则返回空字符串。

days-to-date(11688)

返回 2002-01-01

days-to-date(-1)

返回 1969-12-31

7. 工具函数

7.1. digest

string digest(string, Algorithm, encoding?)

对输入的字符串按照加密算法Algorithm加密并使用编码算法encoding进行编码，并把计算结果返回。

其中Algorithm目前支持MD5、SHA-1两种加密算法，encoding支持的有base64、hex，默认为base64。

digest('abc', 'SHA-1', 'hex')

将返回： a9993e364706816aba3e25717850c26c9cd0d89d.

7.2. match（GForms扩展）

boolean match(node, regex)

根据正则表达式校验输入的模型实例节点node是否满足regex。

这里的regex需要进行转义处理，如：

/^[\w-]+(\.[\w-]+)*@[\w-]+(\.[\w-]+)+$/

需要编写为：

match( node, '^[\\w-]+(\\.[\\w-]+)*@[\\w-]+(\\.[\\w-]+)+$' )

7.3. event

object event(propertyName)

得到当前最新事件属性值，如：

event( 'response-reason-phrase')

如果后端发生内部错误，则得到的信息为一个字符串值：Internal Server Error

具体事件的可用属性信息是不一样的，可以参考相关控件。

7.4. is-valid

boolean is-valid (nodeSet)

校验所输入的节点是否合法，如果合法则返回true，否则返回false。

根据数据节点的绑定、schema等进行校验。

8. xpath特殊字符

如果需要在xpath中输出这些特殊字符必须在xpath中使用转义字符。

特殊字符	特殊含义	实体编码
>	开始标记	>
<	结束标记	&lt;
"	引号	&quot;
'	撇号	&apos;
&	"&"符	&amp;

9. 参考手册

1. XForms提供的XPath函数详解请参考XForms标准：

http://www.w3.org/TR/2009/REC-xforms-20091020/#expr

2. XPath2.0标准：

http://www.w3.org/TR/xpath20/

3. xpath使用手册

http://www.w3school.com.cn/xpath/