setAdded by IBM on October 10, 2012 | Version 1 (Original)
|Sets the value of an XFDL form option or an element in the XForms model.
Table 1. set parameters
set(reference, value, referenceType, scheme)
|reference||Reference string||A reference to the option or data element to set.
If setting an XFDL option, use XFDL referencing. For example, to set the value of "Field1", the reference would be "Field1.value". Note that the reference must be contained in quotes.
When setting a string in an element in the XForms data model, use XPath referencing. For example, to set the value of the ZIP element, the reference might be address/zip.
|value||String||The reference’s new value. For example, to set the reference’s new value to silver, the value would be silver; to set the value of a check box to off, the value would be off.|
|referenceType||String||Optional. Identifies the type of reference used in the reference parameter. To indicate a reference to an option node, use option. To indicate a reference to a node below the option level, use array. To indicate a reference to the XForms data model, use "" (empty string).|
|scheme||String||Optional. The referencing scheme used. Valid options are XFDL and xforms. The default value is XFDL .
If you need to refer to a particular data model, you must use a MIME type format instead, as shown: application/xforms; model=ID
Set this to the ID of the model you want to work with. If you do not specify a model, the first model in the form is used.
Note: If you provide a scheme, you must also provide the referenceType parameter.
Returns "1" if the operation completed successfully, "0" if an error occurred. An error occurs if the specified form option could not be set to the specified value.
Examples In this example, the result of set is "1" and the value of Field1 is set to "silver".
In this example, if a form user selects the "CHECK1" check box (thereby turning its value on), the set function sets the value of "CHECK2" to off.
<value compute="set('Field1.value', 'silver')"></value>
The following sample demonstrates how to use the set function to set a value ("Tatyana Kartoff") in the XForms data model element "name":
<custom:set xfdl:compute="value == 'on' ?
set('CHECK2.value', 'off') : ''"></custom:set>
<custom:set xfdl:compute="value == 'on' ?
set('CHECK1.value', 'off') : ''"></custom:set>
...other data model elements...
- The set function does not support XPath referencing for the entire form. Use XPath references only when setting data in the XForms model.
- If the option you are setting does not exist, the set function creates it only when the containing page and item already exist. The set function does not create elements in the XForms model.
- If you set the value of an XFDL option that has a compute, the compute is destroyed.
- You can use the set function to create "grouped" check boxes. For example, if a form user selects one check box (thereby turning its value on), the set function can turn the value of another check box off.
- When you use a set function to turn a radio button on (or off), you must also use a set function to turn all of the other radio buttons in the same group off (or on).
- When a compute within the set function causes a change to the form, the form checks for other computes referenced by the set function and evaluates them immediately.
- If you use the instance function to access a particular data instance, you must use the escape sequence for the quotations marks (") that appear around the parameter. For example:
set('instance("loan")/Borrower/Name', 'Bill Smith',
- If you intend to use the XForms scheme, you must surround the parameter with single quotation marks. For example:
- The set function does not work on values that are set to be read-only in the XForms model; however, it does work on values that are set to be read-only through the readonly option.
- If you attempt to set the value of an element in the XForms data model, and that element is a parent (that is, it contains child elements), then the value of the first child text node is set.
- For security reasons, the set function is not allowed to change the value of an option or suboption in an XForms-associated item (that is, an XFDL item that contains an XForms control or an XFDL item that has been created by an xforms:group, xforms:switch, xforms:repeat, xforms:select1, or xforms:select.
- The get and set functions are the only XFDL functions that you should use to modify the XForms data model.