checkValidityAdded by IBM on August 8, 2013 | Version 1 (Original)
|Reports the validity of XForms data and the validity of items in the presentation layer.
Use the checkValidity
function to check the following form elements:
- XForms data
- presentation items that are bound to the XForms data
- presentation items that are not bound to XForms data
Table 1. checkValidity parameters
checkValidity(flags, dataScope, UIScope, UIReference)
|flags||String||Optional. A space separated list of values that control the behavior of the checkValidity function and the interpretation of the other parameters. If present, must be one or more of the following values:
- data-validation Validate XForms data only. Also causes checkValidity to return a space-separated list of XPath expressions that define the non-valid data nodes.
- UI-validation Validate XForms data and the format of XFDL items. Includes testing for XForms out-of-range conditions and validating the datatype and constraint settings of the XFDL format option. The UI-validation flag is ignored if the data-validation flag is present. Also causes checkValidity to return a space-separated list of XFDL references that define the non-valid items.
- ignore-relevance Validate non-relevant data nodes and disabled XForms UI controls.
- report-all Report all validation errors, not just the first one.
- report-item-reference Used with the data-validation flag. Causes the function to search for a UI control that is bound to the invalid data node. If a UI control is found, the function returns an XFDL reference to the UI control. If no UI control is bound to the invalid data node, the function returns an empty string.
- focus-item Used with the UI-validation flag or with the report-item-reference flag. Causes a form rendering application such as Viewer or Webform Server to attempt to set focus to the UI control that is bound to the invalid XForms data node.
|dataScope||XPath||Optional. An XPath expression that defines a nodeset that is in the XForms data. The nodeset limits the scope of XForms data validation.|
Default: All XForms data is validated.
|UIScope||String||Optional. An XFDL reference type that defines the UI scope. Used with the UI-validation flag or with the report-item-reference flag. If present, must have one of the following values:
|UIReference||XFDL reference||Optional. Used with UIScope to specify the page or item to check for validity. |
If not present, then the current page or item is checked. The current page or item is the page or item that contains the compute that calls the checkValidity function.
Returns a string. If validation errors are found, then a space separated list of references to the XFDL items or XForms data nodes is returned. The returned string contains either XFDL references or XPath expressions, depending on the content of the flags
If no validation errors are found, then an empty string is returned. An empty string is also returned when the following condition is met:
- the report-item-reference flag is used, and
- one or more XForms data nodes within the scope of the search are not valid, and
- all of the invalid XForms data nodes are not bound to a UI control that is in the scope of the search.
The following example returns the absolute XFDL reference to the first item on the current page that is bound to an invalid data node in the specified nodeset. If it does not find an item that meets the criteria, it returns an empty string.
"instance('data')/client/address[@type = 'US' or @type='Canada']", "page")
- Use checkValidity instead of checkValidFormats, especially when checking data validity in forms that use page loading.
- The checkValidity function stops at the first validation error that it finds, unless specified otherwise with the report-all flag.
- If the UIScope is item, and the item that is being checked for validity is a pane item or a table item, then the scope of the UI validation includes all contained items and their descendents.
- Except for the return type, checkValidity("UI-validation report-all") is functionally equivalent to checkValidFormats().
- When returning XFDL references, the function only reports items that meet one of the following conditions:
- The item is on a page that is loaded, and that item has a format option with the applyinvisible constraint setting of on.
- The item is on a page that is loaded, and has all of the following settings:
- The item is XForms enabled (unless the ignore-relevance flag is present)
- The visible option is on
- The active option is on
- The display option is on
Parent topic: XFDL utility functions
By default, all pages are loaded. For more information about this option, see pageloading