How to use validation events to check and correct data a user enters in a form.
You can run this technique code from:
NOTE First make sure that database is running on your localhost SilverStream Server | |
See the section on forms and data validation in the Form Basics chapter in the Programmer's Guide |
The frmValidateForm example illustrates how to use the validation events for a form. Four fields have validation code that calls the static methods for specifying validation failure, success, or correction (which corrects and succeeds). These static methods return an Exception object with appropriate settings. Your code throws this exception object to determine what happens next in the validation process.
Validation occurs at two different times. For individual fields, validationTest fires when the field loses focus. For the form, globalValidationTest fires when the user tries to leave the record. When happens next depends on which method you call to specify the status of the validation. For complete information, see the related reading in the Programmer's Guide.
In the example, there are four validation tests:
Related reading
correction() method converts it automatically without failing.
failure().
NOTE This example does not support letting the user type the full state name.
correction() method to insert a default value of USA.
Three fields on the form have code in their validationTest event.
For the company code field, the validationTest event throws a failure exception if the user's input is too long. This triggers the validationFailed event. If the first test passes, the code corrects the input to uppercase.
private void
handle_fldCompanyCode_validationTest(AgoPropertyChangeEvent evt)
throws AgoValidationException
{
System.out.println("validationTest fldCompanyCode");
String sVal = (String) evt.getNewValue();
if (sVal.length() > 6)
{
// failure() triggers validationFailed
throw AgoValidationException.failure(
"The company code must be 6 characters or less.");
}
String sValUpper = sVal.toUpperCase();
if (sValUpper != sVal)
{
// correction() causes the data to pass validation
throw AgoValidationException.correction(sValUpper);
}
}
In the cboxStateid control, if the user has entered 2 characters, the code assumes it is the state code and uses it to set the value in the combo box. If the call to setValue() matched a valid code, then the following call to getSelectedIndex() will return a valid index number. If not, the code throws a validation failure with a message.
private void
handle_cboxStateid_validationTest(AgoPropertyChangeEvent evt)
throws AgoValidationException
{
System.out.println("validationTest cboxStateid");
String sVal = (String)evt.getNewValue();
AgcJComboBox cbox = (AgcJComboBox) evt.getSource();
// if the user enters a 2-char state code (list storage value),
// find the corresponding name (list display value)
if (sVal.length() == 2)
{
cbox.setValue(sVal);
}
// for any typed input, make sure it's a valid state
if (sVal.length() > 0)
{
int index = cbox.getSelectedIndex();
if (index == -1)
{
throw AgoValidationException.failure(
"In the USA, enter a valid state code. Otherwise, leave blank.");
}
}
}
NOTE If the argument for setValue() doesn't match the storage value for an item on the list, getSelectedIndex() returns -1. A storage value is specified but is not an actual list item.
The cboxCountry control allows the user to select from a dropdown list. The validationTest event checks whether the value is blank, and if so, inserts the default value of USA. No validation failure occurs.
private void handle_cboxCountry_validationTest(AgoPropertyChangeEvent evt) throws AgoValidationException
{
if (evt.getNewValue().equals(""))
{
throw AgoValidationException.correction("USA");
}
}
In frmValidateForm, the validationFailed event occurs for bad values in fldCompanyCode and cboxStateid. The code for these events doesn't do anything fancy; it just displays a status message on the Java Console.
Because no further exceptions are thrown, the globalValidationFailed event occurs after validationFailed. Finally SilverStream displays a dialog box with the most recent error message for the validation exception.
If no exception is thrown, validationFailed fires globalValidationFailed and globalValidationFailed is followed by the error dialog box.
To halt prevent the validation process, which prevents the display of the error dialog box, your code can call success() and throw the returned exception object.
throw AgoValidationException.success();
In globalValidationTest, frmValidateForm verifies the format of the postal code if the country is USA. It is not appropriate to verify the postal code in control-level validation because the user may not have entered a country value yet.
Before globalValidationTest is fired, SilverStream fires validationTest for every control. During global validation, all data has passed the individual validation tests.
public void globalValidationTest() throws AgoValidationException
{
System.out.println("globalValidationTest");
String sCountry = (String) cboxCountry.getSelectedItem();
// For USA, check that postal code has 5 or 5+4 digits
String msg = "In the USA, the zip code must be \n"
+ "5 digits (xxxxx) or 5+4 digits (xxxxx-xxxx).";
if (sCountry.equals("USA"))
{
String sPostal = fldPostalCode.getText();
switch (sPostal.length() )
{
case 5: // input is 5 chars; needs to be digits
try
{ // try to convert to a number
Integer iVal = Integer.valueOf(sPostal);
}
catch (NumberFormatException e)
{
System.out.println(
"Couldn't convert 5-char string to integer.");
throw AgoValidationException.failure(msg);
}
break;
case 10: // input is 10 chars; needs to be 5+4 format
// 6th char must be a dash
if (sPostal.indexOf('-') != 5)
{
System.out.println("Sixth char is not a dash.");
throw AgoValidationException.failure(msg);
}
// get the 2 numeric substrings
String s1 = sPostal.substring(0,4);
String s2 = sPostal.substring(6,9);
try
{ // try to convert each substring to a number
Integer iVal;
iVal = Integer.valueOf(s1);
iVal = Integer.valueOf(s2);
}
catch (NumberFormatException e)
{
System.out.println(
"Couldn't convert 5-or 4-char string to integer.");
throw AgoValidationException.failure(msg);
}
break;
default:
System.out.println("Length is not 5 or 10");
throw AgoValidationException.failure(msg);
}
}
}
The globalValidationFailed event occurs after globalValidationTest if the postal code does not have a valid format. Then SilverStream displays a dialog box with the most recent error message for the validation exception.