Techniques for data entry validation

This topic details how we can manage the validation of user input on a data entry page created by Data Page builder. Note that the techniques described here also apply to pages created by any of the builders that use the Data Page builder internally. Some of these builders include the Data View builder, the Bean Master Detail builder, the Domino View and Form builder, and the SAP View and Form builder.

A "Data Entry" page is a page which is managed by the Data Page builder, on which ANY of the fields are set to Data Entry, even if the overall page is set to "Display Only." (This could happen if you used a Data Field Modifier to modify one of the fields to be Data Entry, even if the overall page were not set that way.)

The Data Page builder will manage several steps for you in this process of presenting a Data Entry page to the end user and collecting and validating the user s responses. It will generate the JSP for the page, according to your settings. It will generate a "SaveData" method which will collect the values from RequestInputs (where the J2EE server has put them) and save them back into your Variable. Finally, it will create for you validation operations for the individual fields, and it will add the validation error messages to the JSP page.

There are a number of elements we can control in the process of validating fields and displaying the results to the end user, including:

  • Content and placement of the string which signifies a "Required" field

  • Content and placement of the error strings

  • Placement of the "Full Error," which is the concatenation of all the individual field error messages, plus an additional overall error message

  • Code executed when validation succeeds and what will be executed if it fails

  • Whether or not the field validators will be automatically selected based on the schema, bean, or database reference

  • Set individual fields to be required or not, overriding the behavior from the schema

  • Select different field validators than the ones that are automatically selected for fields individually

  • Write your own field validators in Java and select them

  • Add a Post-Save method which can cause the validation to "fail" if some values are not correct by providing an error message string. This string is displayed to the user in the "Full Error" location.

  • Whether or not the Post-Save method is called when other fields have already failed validation.

  • Clear the error messages for a page, and perform other operations with the Error Message Manager, including adding error messages for individual fields in your Post-Save method.

These operations will be explained through a series of examples. In all cases, the examples will start with the sample model "Service_Call" which is in the gettingstarted folder. You will need to install the "Tutorials and Samples - Applications" Feature Set to access this model.

Start by running this model unchanged. You should see that the first page contains 4 input fields, which are all defined (by the WSDL document which defined the service call) to be double-size floating point values. Note that, if you enter non-numeric text in the fields and click the submit button, you will get an error which says that it was "Not recognized as a Floating Point value." This is our starting point.

 

Control Placement of Error Text and Add a Full Error Location.

First, edit the page to add a span where the Full Error text will go. [Open the Imported Page Builder, click the "Edit Page" button. Find the span named "data" and duplicate that entire line of HTML so it appears twice. Change the word "data" to be "fullError" in one of them and click OK on the buildercall.]

Now, open the Data Page builder for the inputPage and scroll down to the "Required Field and Input Validation Settings." Change the error placement to be "Separate Column Left of Field" and select "fullError" for the Full Error Placement. Now run the model again, and enter some non-numeric text in two of the fields and click submit. Note that the placement of the error message has moved, plus the error messages are duplicated in the "Full Error" location. [Before you go on, you may want to change the error placement back to the right of the field, where it makes more sense.]

 

Control "Required Field" Settings.

By default, the fields for this service call were assumed to be optional However, if you leave any of the fields empty, you will notice that the service call produces an ugly error. Avoid this problem by flagging the fields as required, and using the validation mechanism to enforce this for us. Here's how...

Create a new Data Field Modifier Builder. You can select the fields in two different ways. First, you select fields by name in the "List of Fields to be modified." If you use this technique, you should select each of the four fields on the inputPage in a different line in the list box. An alternative method is just to say that we want to select all the fields that are type "Double:" Change the Field Selector Tool to select "by Type" and then choose the type "Double," which will be the only one offered because it is the only data type that appears in this model. Now that you have selected the fields by one technique or another, look in the "Field Settings" group for the input named "Is Required." Set this to "Yes."   Click OK on the Data Field Modifier.

Now open the Data Page builder for the inputPage and again scroll down to the "Required Field and Input Validation Settings." Notice the settings for "Required (*) Placement" and "Required Prompt Text." Feel free to change these, as you like. and OK the buildercall.

Run the model again and notice that your Required Prompt Text is now displayed in the appropriate place relative to the input fields. Click "Submit" while some of the fields are empty and you will see that those fields have now failed validation, and give you the appropriate error message.

 

Control Success and Failure Actions

Generally, when the user has completed filling out a Data Entry page and submitted it, you will have some action you want to run. Sometimes you will also have a different action that you want to run if there were validation errors. In the Data Page builder, there are two inputs, "Success Action" and "Failure Action" which are currently set to "GoToResults" and nothing, respectively. These entries are used in creating the method inputPage_NextAction, which we can see in the WebApp view. If you look at this method, we can see that all it does is test to see if there were any validation errors for the page and then calls the appropriate action.

If you leave "Failure Action" empty, as in the sample, then the default failure action is to return to the same page.

 

Control Automatic Generation of Individual Field Validators

The individual field validators by default are generated based on the types of the fields as defined by the schema, WSDL document, etc. You can turn this behavior off in the Data Page builder using the "Validate From Schema" setting, and the validators will not be automatically created. However, even if you turn it off, you still can use Data Field Modifiers to manually set individual validators.

 

Manually Select Individual Field Validator

Create a new Data Field Modifier and select just one of the fields on the inputPage. Open the "Formatting" group and select the formatter com.bowstreet.builders.webapp.pageautomation.StandardFormatter. This should cause some additional inputs to appear, including "Validate Expression." Select your own validators (but remember that the service call we are calling is expecting a number for this field). Note that, if you choose "RegularExpression(RegExString)" then you are given a new input in which to enter a regular expression string. This setting will override the Required/Optional value for the field, since that choice is available here. Try changing the validator and running the model again to see the new validation strings.

 

Modify Text for Validation Errors

In the Data Page builder, in the "Label Translation Settings" section, are the inputs used to internationalize your model. Among the values that can be translated are the strings that are used for the error messages by the StandardFormatter class. Use the "Create Resource Bundle" button to create a resource bundle for this Data Page builder. If you open the bundle that was created (remember what directory it was in, and you may have to tell Eclipse to Refresh the project before we can see it) then you will see that it has added to the resource bundle the error message strings. If you change them, rebuild the project, and run it, you should see the new strings being used.

See Data Page builder help for "Label Translation Settings" for more information on how to use the resource bundle.

 

Add Post-Save Method and Control its Behavior. Use it to perform cross-field validation.

Sometimes you have additional work that you want your code to do after the data is saved from RequestInputs back into your Variable The input "Post-Save Method" is the hook you use to add your Java code for this process. Also, if the work that you want to do is additional validation of the data entry - perhaps something more complex than individual field validation - there is a way for your Post-Save Method to cause validation to fail (forcing the failure action to run) and to include an error message which will be displayed to the user.

Create a new Method builder, and give it the name TestLatitudes. Set the return type to "String" and fill the method body with these contents:

{

    double lat1 = webAppAccess.getVariables().getDouble("MyServiceCall_arg1_lat1");

    double lat2 = webAppAccess.getVariables().getDouble("MyServiceCall_arg3_lat2");

    

    if (lat1 == lat2)

    return "Make the latitudes different.";

    else

    return null;

}

This gets the value of the two latitude inputs from the variable (where they will already have been saved by the Data Page builder) and checks to see if they are the same. (We knew the exact name of those variables by looking in the WebApp view and selecting - not opening -- the Service Call builder which created them.)

If the two values are the same, it returns some text, which will be interpreted as an error message by the inputPage_SaveData method. If the two values are different, it returns a null, which the SaveData method will know means that your Post-Save method did not find any errors. Run the model and try setting the two values the same, and you will see the error message appear. Because this error is not associated with a specific field, the message will only show in the Full Error section, which we enabled in step #1.

If you just want to make a Post-Save method which just does some work and never returns errors, we can set its return type to void. Also, you may want your Post-Save method to be called only if the individual field validations have executed without error, or you may want it to be called regardless. In the Data Page builder, we can control this behavior with the input "Post-Save Method Behavior."

 

Interact with the Error Message Manager.

For every Data Entry page, the Data Page builder will create a linked Java object which acts as the error message manager. If you select the LJO inputPageError in the WebApp view, you will see the methods that are available. We can use these methods if, for example, you want to set an individual field error message in your Post-Save method. (Perhaps it was something that was too complex for an individual validator, or perhaps it was just more convenient to put here because you were making a Post-Save method anyway.)

We can also get the individual messages directly, if, for example, you want to manage the display of the error messages yourself instead of letting the Data Page builder manage it. We can also clear the messages, which you might want to do if you are returning to the page with fresh data, and you want to clear the messages that might be left over from the last time the page was visited (by the end user).