Web Home

How to create an ErrorPage^? with in your WorkPlaceForms

This page is a walk-through to generate an ErrorPage^? in your forms so the form user would access before finalizing the form (either submit or sign).

There are a few steps before we start. It also worth mentioning that this is not the only method to generate or warn the error to users but to the best of my knowledge it was the most creative way to warn and direct the FormUser^? to the errors he/she made while filling the form.

To start we need to know a few background on the form error types and how to approach the problem:

• the common source of errors are:
  • Leaving a mandatory field blank (UnfilledFields)
  • Filling a field with incorrect format
  • Signiture Buttons which are set to be mandatory

The key function to start error checking with is called checkValidFormats(). calling this function inside a properly made compute (say when checkerrors button is pressed) will generate asearchable array of errors in runtime. The programer can refer/search and deal with the errors by looking into this array. The following code, if placed inside a button, will find all the errors within your form and generate the related array:

<custom:on_click xfdl:compute="toggle(BUTTON1.activated) == '1' ? &#xA;
(checkValidFormats('global.global.custom:errorsFound')!='0' ?    &#xA;
set('BUTTON1.value',global.global.custom:errorsFound[0])  :        &#xA;
set('BUTTON1.value','No Error')) : ''"></custom:on_click>   

If you try the code you will realize that button's value also set to the first error found in the form. This is because global.global.custom:errorsFound array elements holds all the errors found in the form. inorder to access these errors you should refer to array elements starting from 0 upto the number of errors found in the form minus one.

Another useful function is countChildren(). We can use this function to count the number of errors found in the form. combining this function with forloops (for()) and strstr() functions can help us find exactly where the errors was found.

Spotting errors in a single page

There are occasions that we are only interested in the errors found in a particular page. Unfortunately as to this date, there is no option available within functions of WorkPlaceForms^? (WPF 2.6.1) to target only errors in one page. However, there is an efficient way to target these errors.

The following code explains it better:

      <action sid="myAction">
         <custom:Num_Errors>-1</custom:Num_Errors>
         <custom:loopCounter>-1</custom:loopCounter>
         <custom:errorsFound_array>NA</custom:errorsFound_array>
         <custom:onActivated xfdl:compute="&#xA;
            (toggle(active, 'off', 'on') == '1') &#xA;
            ?  checkValidFormats('custom:errorsFound_array') &#xA;
              +. set('custom:Num_Errors', '-1') &#xA;
              +.for('custom:loopCounter','0',(countChildren('custom:errorsFound_array')-'1')) &#xA;
              +. set('custom:loopCounter', '-1') &#xA;
              +. set('active', 'off') &#xA;
            : ''">2</custom:onActivated>
         <custom:searchArray xfdl:compute="&#xA;
            (toggle(custom:loopCounter) == '1') and (custom:loopCounter != '-1') &#xA;
            ?strstr(get('custom:errorsFound_array['+.custom:loopCounter +.']'),'myPAGE')!='-1' &#xA;
            ? set('custom:Num_Errors', custom:Num_Errors + '1') &#xA;
            : '' &#xA;
            : ''">2</custom:searchArray>
         <custom:activateTheButton xfdl:compute="&#xA;
            ((toggle(custom:Num_Errors) == '1') and (custom:Num_Errors != '-1')) &#xA;
            ? set('PAGE2.myBUTTON.active', 'off') &#xA;
            : set('PAGE2.myBUTTON.active', 'on') &#xA;
            ">2</custom:activateTheButton>
         <active>off</active>
      </action>

Assume the form consist of few pages. we are interested in the errors in myPAGE and we want the next button (for simplicity we refer to it as myBUTTON) only activated when there is no error in the page. In given code we set an action (called myAction) to first find about any possible error in the whole form. Then we set a for loop up to the last element in the errorsFound_array array and with in the for loop we search the sid of the elements using strstr() function. If the sid of the desired page (myPAGE) was found we dissable myBUTTON.

The code is written inside an action and action triggeres every time the focuse of the fields changed inside form. When the action is triggered the number of errors found inside the myPAGE page will be updated. inorder to trigger the action this line of code shgould also be included in the global part of the myPAGE page:

         <custom:on_fouce xfdl:compute="toggle(myPAGE.global.focuseditem) == '1' ="&#xA;
                  ? (set('myPAGE.myAction.active', 'on')) : ''"></custom:on_fouce>

for an alternative approach please refer to this page.

Creating a list of errors

A more fancy approach to excite the form user is to enable him to see all the errors he/she made within the form and ask him/her to go back and correct them. The way to do this for the whole form is a little tricky and we should use a more complex code with in the ErrorPage^? we create.

To make this happen we basically need to creat a few items on the page. on following I have addeded a ToDO^? list of elements which should apper in your error page as well as on all pages which an error might exist. When all these are completed the form enable the user to see the errors he made, he click on it and the form automatically will take the user to the corresponding field.

The items to be added in the error page:

• a list with a group name so we can add cells to it later. Make the list long enough so it could show at list 10 errors at the time. Here is sample code:

      <list sid="myLIST">
         <itemlocation>
            <x>100</x>
            <y>100</y>
            <width>500</width>
            <height>150</height>
         </itemlocation>
         <group>ERROR_LIST_GROUP</group>
         <value></value>
         <custom:on_click xfdl:compute="toggle(value) == '1' and strlen(value) > '0' &#xA;
            ? set('errPAGE.goToError.custom:current_item_ref',value->custom:item_sid) &#xA;
               +. set('value','') &#xA;
               +. set('errPAGE.goToError.activated','on') &#xA;
            : '' ">2</custom:on_click>
      </list>

• a number of cells with the same group name. Here is one cell but if you are willing to show 10 errors at the time you should repeat this for the 9 more cells (but with different arbitrary values:

      <cell sid="ERROR_0">
         <group>ERROR_LIST_GROUP</group>
         <value></value>
         <custom:item_sid></custom:item_sid>
      </cell>

      <cell sid="ERROR_1">
        .
        .
        .

• an action for setting the items inside the error list. The code is given bellow:

<action sid="myAction">
 <custom:onActivated xfdl:compute="&#xA;
  (toggle(active, 'off', 'on') == '1') &#xA;
  ? set('custom:counter', '1') &#xA;
  +.set('custom:invalid_items_total',checkValidFormats('custom:invalid_items_array')) &#xA;
  +. set('errPAGE.Num_Errors.value',countChildren('custom:invalid_items_array','option')) &#xA;
  +.((countChildren('custom:invalid_items_array','option')-'1'>'9')?set('custom:numErrors','9') &#xA;
  : set('custom:numErrors',countChildren('custom:invalid_items_array','option') - '1') )&#xA;
  +. for('custom:counter', '0', '9') &#xA;
  +. set('active', 'off') &#xA;
  : ''">2</custom:onActivated>
 <custom:numErrors>9</custom:numErrors>
 <custom:counter>9</custom:counter>
 <custom:forLoopAction xfdl:compute="  &#xA;
   toggle(custom:counter) == '1' and custom:counter &lt;= custom:numErrors &#xA;
   ?  set('errPAGE.ERROR_' + custom:counter + '.custom:item_sid', &#xA;
   get('custom:invalid_items_array[' + custom:counter + ']')) &#xA;
   +.((strlen(get(get('custom:invalid_items_array['+ custom:counter +']')+'.value'))!= '0') &#xA;
   ? set('errPAGE.ERROR_' + custom:counter + '.value', get(get('custom:invalid_items_array[' +&#xA;
   custom:counter + ']')+ '.custom:errorMessage') + ' an Invalid form item entry.')  &#xA;
   : set('errPAGE.ERROR_' + custom:counter + '.value', get(get('custom:invalid_items_array[' + &#xA;
   custom:counter+']')+'.custom:errorMessage')+' a Mandatory form item and it\'s not filled.')) &#xA;
   : set('errPAGE.ERROR_' + custom:counter + '.custom:item_sid', 'errPAGE.LIST1') &#xA;
   +. set('errPAGE.ERROR_' + custom:counter + '.value', '')  &#xA;
   ">2</custom:forLoopAction>
 <custom:invalid_items_total>4</custom:invalid_items_total>
 <custom:invalid_items_array>
            <ae>a</ae>
            <ae>b</ae>
            <ae>c</ae>
            <ae>d</ae>
 </custom:invalid_items_array>
</action>

• Customize the array of possible errors inside myAction. The name of array is important and also each entry should have an arbitrary value. There should be one array entry per any possible error. Therefore, the number of entries in the array should be equal to the total form errors if nothing is filled in the form. An example for a form with possible 4 errors came below:

         <custom:invalid_items_array>
            <ae>a</ae>
            <ae>b</ae>
            <ae>c</ae>
            <ae>d</ae>
         </custom:invalid_items_array>

(bug report: if you enter "2" as the value of the second array entry the code will crash. Could be a bug in the API behind it)

• Another action to take you where the error has happened. The code is given below:

<action sid="goToError">
 <active>off</active>
 <custom:current_item_ref>a</custom:current_item_ref>
 <custom:dest_page_sid>b</custom:dest_page_sid>
 <custom:dest_item_sid>c</custom:dest_item_sid>
 <custom:onActivated xfdl:compute="&#xA;
  (toggle(activated, 'off', 'on') == '1') &#xA;
  ?  set('custom:dest_page_sid', substr(custom:current_item_ref, '0', strstr &#xA;
  (custom:current_item_ref, '.') - '1')) &#xA;
  +. set('custom:dest_item_sid', substr(custom:current_item_ref, strstr &#xA;
  (custom:current_item_ref, '.') + '1', strlen(custom:current_item_ref))) &#xA;
  +. ((custom:dest_page_sid != getReference('', 'page', 'page')) &#xA;
  ? set('goToPage_BUTTON.custom:next_page', custom:dest_page_sid) &#xA;
  +. set(custom:dest_page_sid +. '.global.custom:invalid_item', custom:dest_item_sid) &#xA;
  +. set('goToPage_BUTTON.activated', 'on') &#xA;
  : set(custom:dest_item_sid +. '.focused', 'on')) &#xA;
  +. set('active', 'off') &#xA;
  : ''"></custom:onActivated>
</action>

• Also to any page that we set a field to be mandatory or we set a format for the field we should add the folloing code to the global part of the page:

         <custom:invalid_item></custom:invalid_item>
         <custom:goTo_invalidItem xfdl:compute="&#xA;
            ((toggle(focused, 'off', 'on') == '1') &#xA;
             and (custom:invalid_item != '') &#xA;
            ) &#xA;
            ? set(custom:invalid_item +. '.focused', 'off') &#xA;
              +. set(custom:invalid_item +. '.focused', 'on') &#xA;
              +. set('custom:invalid_item', '') &#xA;
            : ''"></custom:goTo_invalidItem>

• Last but not least, we add the following code to any field which is mandatory or have a defined format:

         <custom:errorMessage>The field  'Field Name'  on 'Field Page' is</custom:errorMessage>

After you apply the given changes to your form you should have an ErrorPage^? set up in your form. For more information I have also attached a testform with an ErrorPage^? which is created by applying the above changes to the form.

Finally, I should thank and credit this work to the following names which helped me in coding and/or ideas needed to make an ErrorPage^?: Cayce Marston Matt Campbel Ed Lowe Christopher Dawes

This is YourOwnSandBox topic.