Portlet Factory, Version 6.1.2

 

Techniques for data entry validation

You can manage the validation of user input on a data entry page created by Data Page builder or builders that use the Data Page builder. The following techniques are described.

These techniques also apply to pages created by any of the builders that use the Data Page builder, to include the Data View builder, the Bean Master Detail builder, the Domino View & Form builder, and the SAP View and Form builder.

A data entry page 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 builder to modify one of the fields to be data entry, even if the overall page is not set that way.)

The Data Page builder can manage presenting a data entry page to the end user and collecting and validating the user 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 in 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.

In the process of validating fields and displaying the results to the end user, you can control the following aspects:

  • 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 fails

  • Whether the field validators are 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 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 are explained through a series of examples. In all cases, the examples start with the sample model Service_Call which is in the gettingstarted folder. Install the Tutorials and Samples - Applications feature set to access this model.

Start by running this model unchanged. Notice that the first page contains four input fields, which are all defined (by the WSDL document which defined the service call) to be double-size floating point values. If you enter nonnumeric text in the fields and click the submit button, you get an error which says Not recognized as a Floating Point value. This error condition is the starting point for the discussion of the examples.

 

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 Edit Page. 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 builder call.

Open the Data Page builder for the inputPage and scroll down to 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 nonnumeric 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 continue, 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 fields empty, the service call produces an error. Avoid this problem by flagging the fields as required, and using the validation mechanism to enforce this for us. Create a new Data Field Modifier builder. You can select the fields in the following ways:

  • Select fields by name in List of Fields to be modified.

    If you use this technique, select each of the four fields on the inputPage in a different line in the list box.

  • Select all the fields that are type double.

    Change the Field Selector Tool to select by Type and then choose the type Double, which is 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 Field Settings 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. If you need to, change these and click OK.

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 see that those fields failed validation, and give you the appropriate error message.

 

Control success and failure actions

Generally, when the user completes filling out a Data Entry page and submits it, some action will run. Sometimes you 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. These entries are used in creating the method inputPage_NextAction, which you can see in the WebApp view. If you look at this method, you can see that all it does is test to see whether 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, or other mechanism. You can disable this behavior in the Data Page builder using the Validate From Schema setting, and the validators will not be automatically created. However, even if you disable it, 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 being invoked 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. Change the validator and run the model again to see the new validation strings.

 

Modify text for validation errors

In the Data Page builder, in Label Translation Settings, 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 Create Resource Bundle 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 you 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

You can control the behavior of a Post-Save method and 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 to your variable. The input Post-Save Method is the hook to use to add your Java code for this process. Also, if the work to do is additional validation of the data entry or 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;
    }

The code 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. (The exact name of those variables is known by looking in the WebApp view and selecting (not opening) the Service Call builder which created them.)

If the two values are the same, the code returns some text, which will be interpreted as an error message by the inputPage_SaveData method. If the two values are different, the code 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.

If you just want to make a Post-Save method that does some work and never returns errors, you 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, you 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 creates a linked Java object which acts as the error message manager. If you select the LJO inputPageError in the WebApp view, you can see the methods that are available. You can use these methods to set an individual field error message in your Post-Save method. Some developers set this in the Post-Save method since the case was too complex for an individual validator, or because they were planning to use a Post-Save method.

You can also get the individual messages directly to manage the display of the error messages yourself rather than let the Data Page builder manage the display. You can also clear the messages 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.

Parent topic: Overview: creating pages and forms

Library | Support |