checkValidFormats

Checks the formatted items in the form and returns the number of items whose format is not valid. You can also reduce the scope of the validation check by checking specific pages or individual items. Furthermore, you can set the function to create a list of the items that are not valid.

Syntax

   checkValidFormats(listReference, optionName, validationReference, 
      referenceType, schema)

Table 1. checkValidFormats parameters
Parameter	Type	Description
listReference	Reference string	Optional. A reference to an option that will contain the list of items that are not valid. For example, if you called the function from a label item, you might create the following custom option: <label sid="numberInvalid"> <custom:list> In this case, you would use the following reference: custom:list The function creates the option if it does not already exist. The function then populates the option with a list of references to the items that are not valid. For example, if two fields were not valid you would get a list like this: <custom:list> <custom:invalidref>Page1.Field1 </custom:invalidref> </custom:invalidref>Page1.Field2 </custom:invalidref> </custom:list> If this parameter is not specified in the call, the function still validates all form items but does not create a list of references to invalid items.
optionName	String	optional. Sets the tag that is used to store each item in the list of not valid items. This parameter is useful when you need to set a particular namespace for the list. For example, if you store your list in a custom:list option, you might set the following tag: custom:invalidref Doing this ensures that the list is stored in the same namespace as the containing element. Default: xfdl:option
validation Reference	Reference string	optional. A reference to the section of the form that you want to validate. For example, "PAGE1.FIELD1". If " " or an empty string is used, this function checks the current object.
referenceType	String	optional. Defines the type of reference used by the validation reference parameter. Valid settings are form, page, or item.
schema	Reference string	optional. Defines the format of the reference. If not specified, the default of XFDL is applied.

Returns

Returns the number of items that failed the validity check. If all items are valid, the function returns 0.

Example

The following sample form shows how you can use the checkValidFormats function to specify custom behaviors when a form with values that are not valid is submitted. Note that the format of FIELD2 is checked even if it is not currently displayed.

   <?xml version="1.0"?>
   <XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/8.0"
      xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/8.0"
      xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom">
      <globalpage sid="global">
         <global sid="global"></global>
      </globalpage>
      <page sid="PAGE1">
         <global sid="global"></global>
         <field sid="FIELD1">
            <format>
               <datatype>date</datatype>
               <constraints>
                  <mandatory>on</mandatory>
               </constraints>
            </format>
         </field>
         <field sid="FIELD2">
            <value>4.00</value>
            <format>
               <datatype>dollar</datatype>
               <constraints>
                  <mandatory>on</mandatory>
                  <applyifinvisible>on</applyifinvisible>
               </constraints>
            </format>
         </field>
         <button sid="BUTTON1">
            <value>Submit</value>
            <type>done</type>
            <url>http://localhost/cgi-bin/test.pl</url>
            <custom:checkIfValid xfdl:compute=
               "toggle(BUTTON1.activated, 'off', 'on') == '1' ? &#xA;
               (checkValidFormats('custom:brokenOptions', &#xA;
               'custom:invalidref') != '0' ? &#xA;
               set('BUTTON1.activated', 'off') + &#xA;
               viewer.messageBox('Unable to send because at ' &#xA;
               +. 'least ' +. custom:brokenOptions[0] +. &#xA;
               'item is invalid.') : '') : ''"></custom:checkIfValid>
         </button>
      </page>
   </XFDL>

The format option for FIELD1 specifies that this item must contain a date and cannot be blank. If a user submits the form without correctly completing this field, the checkValidFormats function prevents the submission. Instead, the function creates a new option called brokenOptions:

   <custom:brokenOptions>
      <custom:invalidref>PAGE1.FIELD1</custom:invalidref>
   </custom:brokenOptions>

The remaining code uses the information in brokenOptions to display a context-sensitive message to the user.

Usage details

Use checkValidity instead of checkValidFormats, especially if a form uses page loading or contains an XForms bind that uses the required, type, or constraint properties.
Use checkValidFormats in a compute on individual pages. As a result, the function is run only when the user leaves that page. Performance is then improved.
If page loading is enabled, validation checks can only be performed on pages that have been loaded into memory. If a validation check is made when the loadallbefore parameter is used, then all pages in the form are checked.
Custom items are always excluded from validation checks.
Use the format constraint, applyifinvisible, to include invisible or inactive items in the validation check.
The checkValidFormats function reports validation failures on specified pages defined in the form global settings. The pageloading option is used to specify which pages are loaded in the IBM® Forms Viewer and IBM Forms Server – Webform Server. These specified pages are stored into memory to improve the loading performance of large complete forms. The specified pages are checked for validation. If page loading is not enabled, all items are checked.
Items with display, visible, and active options set to off are excluded from the validation checks.