XFDL function callsAdded by IBM on October 10, 2012 | Version 1 (Original)
|You can use XFDL function calls to design forms that include complex computations and calculations. XFDL function calls include: string functions, math functions, utility functions, time and date functions, header and footer functions, and bidirectional functions.
The Extensible Forms Description Language (XFDL) is an assertion-based language. Assertion-based languages include an engine that maintains statements in the code as true. The functions described in this section allow an XFDL form to perform procedural operations that would normally require complicated computations to achieve.
Function calls run code that can be external to the XFDL form definition. Below are the BNF rules for functions.
The LibName allows functions to be grouped into separate namespaces, but the predefined functions in this specification do not require a LibName. The LibName assigned to these predefined functions is system. Viewer functions enable form developers to trigger actions in the Viewer from within a form. The Viewer functions are compiled into a package called viewer, similar to the XFDLsystem package. Any user-defined package must contain an underscore in its name.
FunctionCall := (LibName '.')? FunctionName '(' (Compute
(',' Compute)*)? ')'
LibName ::= sid
FunctionName ::= sid
Calling a predefined function in the system namespace:
<custom:status xfdl:compute="toggle(field1.value, 'high', 'low')">
Calling a function in the viewer namespace:
Table 1. viewer namespace function calls
viewer.functionName(parameter_1, parameter_2 ... parameter_n)
Calling a user-defined function in a custom namespace:
|viewer||The name of the package that the function belongs to.|
|functionName||The name of the function.|
|parameter||A string representing the value of the parameter. Functions take zero or more parameters.|
<value compute="hr_funcs.holiday(field1.value, field2.value)"></value>
About parameters in XFDL
Parameters are variables that are passed to XFDL functions. These variables determine the result of the function. Parameter types include numbers, strings, Booleans, other functions, or references to values in a form.
In general, parameters are enclosed in single quotation marks, as shown:
Use empty quotation marks to represent null values.
In some cases you might want to copy a value from another element in the form. For example, you might want to use the value of a user-set field as the parameter in a function. This is called setting a reference. A reference is the “address” of an item, option, or argument in the form. For example, the reference to the value of a field called NameField on page 2 would be "page2.NameField.value".
When setting a reference, the parameter should not be enclosed in single quotation marks, as shown:
When the reference is evaluated, the value of the referenced item is retrieved and substituted for the reference, resulting in the following:
The function is then computed.
Optional parameters in viewer function calls are indicated with brackets ( [ ] ). For example:
function('param1', 'retrieved value')
In the function call above, the extfilter parameter is optional.
Reference strings In some cases, your function might require a reference to the actual address of an item, instead of the value contained by the item. This is called a reference string. For example, the second parameter of the measureHeight function allows you to specify which item should be measured by providing a reference to that item.
Usually, you would provide a reference string that is enclosed in single quotation marks, as shown:
The quotation marks indicate that the function should use the reference string as the final value. So in this case, the function will measure the height of the descriptionField.
Position of characters in strings
The position of the first character in a string is at position zero. For example, the capital T in the following string is at position zero.
String functions manipulate strings. For example, a string function could count lines and words or compare strings to other strings.
Math functions perform mathematical calculations, such as cosine, rounding, or factorial values.
Utility functions perform basic work functions, such as toggling switches, setting values, or counting children.
Time and date functions let you calculate dates and time. For example, a time and date function could calculate the current date and time or determine how much time has passed since a specified date.
This is a collection of functions that can be used within the printsettings option to add header and footer information to a form. These headers and footers do not appear on the screen, but do appear when the form is printed.
This is a collection of functions that can be used with bidirectional languages, such as Arabic and Hebrew.