XForms xpath使用手冊

本文所描述的所有函數為XForms 1.1所提供的xpath函數，這些函數隻能在GForms的xpath編輯器中可用，這樣才能在運作時識别并執行。

不可在XMLUtil、标準XML DOM中使用這些函數。

GForms平台提供xpath編輯器，該編輯器可以協助開發者完成大多數xpath表達式開發：

1、節點函數

1.1、instance函數

node-set instance(string?)

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

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

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

Example:

For instance data corresponding to this XML:

<xforms:instancexmlns="" id="orderform">

  <orderForm>

    <shipTo>

      <firstName>John</firstName>

    </shipTo>

  </orderForm>

</xforms:instance>

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

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

2、字元串函數

2.1、if函數

string if(boolean, string, string)

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

2.2、property函數

string property(string)

This function accepts a string identifying a property name. If theproperty name is not recognized, empty string is returned. The propertydefinitions 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

3、數值函數

3.1、avg

number avg(node-set)

Function avg returns the arithmetic average of the result of converting thestring-values of each node in the argument node-set to a number. The sum iscomputed 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 nodesevaluate to NaN, the return value is NaN.

3.2、number

number min(node-set)

 Function min returns the minimum value of the result of converting thestring-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 thenodes evaluate to NaN, the return value is NaN.

3.3、max

number max(node-set)

Function max returns the maximum value of the result of converting thestring-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 thenodes evaluate to NaN, the return value is NaN.

3.4. count-non-empty

number count-non-empty(node-set)

Function count-non-empty returns the number ofnon-empty nodes in argument node-set. A node isconsidered non-empty if it is convertible into a string with a greater-thanzero length.

 3.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 forthe identifiedrepeat—see 9.3.1 The repeat Element for details on repeat and its associated repeat index. If the specified argument doesnot identify a repeat, the function returns NaN.

Note:

The IDREF obtained from the function parameter may not uniquelyidentify the desired repeat if the repeat element bearing the matching ID resides in a repeating constructsuch 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 ShoppingCart</xforms:label>

  <xforms:insertev:event="DOMActivate" position="after"

                 nodeset="items/item"at="index('cartUI')"/>

</xforms:trigger>

3.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 anddur>0 and rate>0, prin*rate/(1-power(1+rate, -dur)), 0)

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

3.7. random

number random(boolean?)

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

Example:

random()

could return 0.14159265358979

3.8. compare

number compare(string, string)

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

Example:

compare('apple','orange')

returns -1

 4、布爾函數

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 whenreferencing a Schema xsd:boolean datatype in an XPath expression. If the parameter string matchesnone of the above strings, according to a case-insensitive comparison, thereturn value is false.

5、時間函數

時間的格式處理，為了簡化本地化時間處理，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。

5.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以友善本地化程式設計處理。

5.2、local-date函數

string local-date()

将傳回與XSD資料類型xsd:date格式一緻的字元串，該時間為本本地區時間，而非UTC時間，在GForms中将根據confgi_xx.xslt中的date配置格式進行格式化傳回。

local-date()

傳回格式 2006-10-13

5.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。

5.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，即小時、分鐘及秒被忽略掉。

5.5、days-to-date

string  days-to-date( number)

把輸入的天數轉換為時間字元串，天數将從 1970-01-01之後開始計算，如果輸入的天數非法，則傳回空字元串。

days-to-date(11688)

傳回 2002-01-01

days-to-date(-1)

傳回 1969-12-31

 6、工具函數

6.1、加密函數digest

string digest(string, Algorithm, encoding?)

對輸入的字元串按照加密算法Algorithm加密并使用編碼算法encoding進行編碼，并把計算結果傳回。

其中Algorithm目前支援MD5、SHA-1兩種加密算法，encoding支援的有base64、hex，預設為base64。

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

将傳回： a9993e364706816aba3e25717850c26c9cd0d89d.

 6.2、比對函數match

boolean  match( node,  regex)

根據正規表達式校驗輸入的模型執行個體節點node是否滿足regex。

這裡的regex需要進行轉義處理，如：

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

需要編寫為：

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

6.3、事件函數event

 object event(propertyName)

得到目前最新事件屬性值，如：

event('response-reason-phrase')

如果後端發生内部錯誤，則得到的資訊為一個字元串值：Internal Server Error

具體事件的可用屬性資訊是不一樣的，可以參考相關控件。

  6.4、合法性校驗is-valid

boolean is-valid(nodeSet)

校驗所輸入的節點是否合法，如果合法則傳回true，否則傳回false。

根據資料節點的綁定、schema等進行校驗。

7.  xpath特殊字元

如果需要在xpath中輸出這些特殊字元必須在xpath中使用轉義字元。

特殊字元	特殊含義	實體編碼
>	開始标記	>
<	結束标記	&lt;
"	引号	&quot;
'	撇号	&apos;
&	"&"符	&amp;

8.  參考手冊

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/