bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic JSP

Using WebLogic JSP Form Validation Tags

The following sections describe how to use WebLogic JSP form validation tags:

- Overview of WebLogic JSP Form Validation Tags

- Validation Tag Attribute Reference

- Using WebLogic JSP Form Validation Tags in a JSP

- Creating HTML Forms Using the <wl:form> Tag

- Using a Custom Validator Class

- Sample JSP with Validator Tags

Overview of WebLogic JSP Form Validation Tags

WebLogic JSP form validation tags provide a convenient way to validate the entries an end user makes to HTML form text fields generated by JSP pages. Using the WebLogic JSP form validation tags prevents unnecessary and repetitive coding of commonly used validation logic. The validation is performed by several custom JSP tags that are included with the WebLogic Server distribution. The tags can

- Verify that required fields have been filled in (Required Field Validator class).

- Validate the text in the field against a regular expression (Regular Expression Validator class).

- Compare two fields in the form (Compare Validator class).

- Perform custom validation by means of a Java class that you write (Custom Validator class).

WebLogic JSP form validation tags include:

- <wl:summary>

- <wl:form>

- <wl:validator>

When a validation tag determines that data in a field is not been input correctly, the page is re-displayed and the fields that need to be re-entered are flagged with text or an image to alert the end user. Once the form is correctly filled out, the end user's browser displays a new page specified by the validation tag.

Validation Tag Attribute Reference

This section describes the WebLogic form validation tags and their attributes. Note that the prefix used to reference the tag can be defined in the taglib directive on your JSP page. For clarity, the wl prefix is used to refer to the WebLogic form validation tags throughout this document.

<wl:summary>

<wl:summary> is the parent tag for validation. Place the opening <wl:summary> tag before any other element or HTML code in the JSP. Place the closing </wl:summary> tag anywhere after the closing </wl:form> tag(s).

  name

  (Optional) Name of a vector variable that holds all validation error messages generated by the <wl:validator> tags on the JSP page. If you do not define this attribute, the default value, errorVector, is used. The text of the error message is defined with the errorMessage attribute of the <wl:validator> tag.

  To display the values in this vector, use the <wl:errors/> tag. To use the <wl:errors/> tag, place the tag on the page where you want the output to appear. For example:

  <wl:errors color="red"/>

  Alternately, you can use a scriptlet. For example:

  <% if (errorVector.size() > 0) {
  for (int i=0; i < errorVector.size(); i++) {
  out.println((String)errorVector.elementAt(i));
  out.println("<br>");
  }
  } %>

  Where errorVector is the name of the vector assigned using the name attribute of the <wl:summary> tag.

  The name attribute is required when using multiple forms on a page.

  headerText

  A variable that contains text that can be displayed on the page. If you only want this text to appear when when errors occur on the page, you can use a scriptlet to test for this condition. For example:

  <% if(summary.size() >0 ) {
  out.println(headerText);
  }
  %>

  Where summary is the name of the vector assigned using the name attribute of the <wl:summary> tag.

  redirectPage

  URL for the page that is displayed if the form validation does not return errors. This attribute is not required if you specify a URL in the action attribute of the <wl:form> tag.

  Note: Do not set the redirectPage attribute to the same page containing the <wl:summary> tag—you will create an infinite loop causing a StackOverFlow exception.

<wl:form>

The <wl:form> tag is similar to the HTML <form> tag and defines an HTML form that can be validated using the the WebLogic JSP form validataion tags. You can define multiple forms on a single JSP by uniquely identifying each form using the name attribute.

  method

  Enter GET or POST. Functions exactly as the method attribute of the HTML <form> tag.

  action

  URL for the page that is displayed if the form validation does not return errors. The value of this attribute takes precedence over the value of the redirectPage attribute of the <wl:summary> tag and is useful if you have multiple forms on a single JSP page.

  Note: Do not set the action attribute to the same page containing the <wl:form> tag—you will create an infinite loop causing a StackOverFlow exception.

  name

  Functions exactly as the name attribute of the HTML <form> tag. Identifies the form when multiple forms are used on the same page. The name attribute is also useful for JavaScript references to a form.

<wl:validator>

Use one or more <wl:validator> tags for each form field. If, for instance, you want to validate the input against a regular expression and also require that something be entered into the field you would use two <wl:validator> tags, one using the RequiredFieldValidator class and another using the RegExpValidator class. (You need to use both of these validators because blank values are evaluated by the Regular Expression Field Validator as valid.)

  errorMessage

  A string that is stored in the vector variable defined by the name attribute of the <wl:summary> tag.

  expression

  When using the RegExpValidator class, the regular expression to be evaluated.

  If you are not using RegExpValidator, you can omit this attribute.

  fieldToValidate

  Name of the form field to be validated. The name of the field is defined with the name attribute of the HTML <input> tag.

  validatorClass

  The name of the Java class that executes the validation logic. Three classes are provided for your use. You can also create your own custom validator class. For more information, see Using a Custom Validator Class.

  The available validation classes are:

  weblogicx.jsp.tags.validators.RequiredFieldValidator

  Validates that some text has been entered in the field.

  weblogicx.jsp.tags.validators.RegExpValidator

  Validates the text in the field using a standard regular expression.

  Note: A blank value is evaluated as valid.

  weblogicx.jsp.tags.validators.CompareValidator

  Checks to see if two fields contain the same string. When using this class, set the fieldToValidate attribute to the two fields you want to compare. For example:

  fieldToValidate="field_1,field_2"

  Note: If both fields are blank, the comparison is evaluated as valid.

  myPackage.myValidatorClass

  Specifies a custom validator class.

Using WebLogic JSP Form Validation Tags in a JSP

To use a validation tag in a JSP:

1. Write the JSP.

   1. Enter a taglib directive to reference the tag library containing the WebLogic JSP Form Validation Tags. For example:

      >     <%@ taglib uri="tagl" prefix="wl" %>

      Note that the prefix attribute defines the prefix used to reference all tags in your JSP page. Although you may set the prefix to any value you like, the tags referred to in this document using the wl prefix.

   2. Enter the <wl:summary> ... </wl:summary> tags.

      Place the opening <wl:summary ...> tag before any HTML code, JSP tag, scriptlet, or expression on the page.

      Place the closing </wl:summary> tag anywhere after the </wl:form> tag(s).

   3. Define an HTML form using the <wl:form> JSP tag that is included with the supplied tag library. For more information, see <wl:form> and Creating HTML Forms Using the <wl:form> Tag. Be sure to close the form block with the </wl:form> tag. You can create multiple forms on a page if you uniquely define the name attribute of the <wl:form> tag for each form.

   4. Create the HTML form fields using the HTML <input> tag.

   5. Add <wl:validator> tags. For the syntax of the tags, see <wl:validator>. Place <wl:validator> tags on the page where you want the error message or image to appear. If you use multiple forms on the same page, place the <wl:validator> tag inside the <wl:form> block containing the form fields you want to validate.

      The following example shows a validation for a required field:

      >     <wl:form name="FirstForm" method="POST" action="thisJSP.jsp">

      >     <wl:validator
      >      errorMessage="Field_1 is required" expression=""
      >      fieldToValidate="field_1"
      >      validatorClass=
      >       "weblogicx.jsp.tags.validators.RequiredFieldValidator"
      >     >
      >       <img src="images/warning.gif">
      >       <font color=red>Field 1 is a required field</font>
      >     </wl:validator>

      >     <p> <input type="text" name = "field_1">  </p>
      >     <p> <input type="text" name = "field_2">  </p>
      >     <p> <input type="submit" value="Submit FirstForm">  </p>
      >     </wl:form>

      If the user fails to enter a value in field_1, the page is redisplayed, showing a warning.gif image, followed by the text (in red) "Field 1 is a required field," followed by the blank field for the user to re-enter the value.

2. Copy the weblogic-vtags.jar file from the ext directory of your WebLogic Server installation into the WEB-INF/lib directory of your Web Application. You may need to create this directory.

3. Configure your Web Application to use the tag library by adding a <taglib> element to the web.xml deployment descriptor for the Web Application. For example:

   >     <taglib>
   >       <taglib-uri>tagl</taglib-uri>
   >       <taglib-location>
   >         /WEB-INF/lib/weblogic-vtags.jar
   >       </taglib-location>
   >     </taglib>

   For more information on Web Application deployment descriptors, see Writing Web Application Deployment Descriptors.

Creating HTML Forms Using the <wl:form> Tag

This section contains information on creating HTML forms in your JSP page. You use the <wl:form> tag to create a single form or multiple forms on a page.

Defining a Single Form

Use the <wl:form> tag that is provided in the weblogic-vtags.jar tag library: For example:

>     <wl:form method="POST" action="nextPage.jsp">
>     <p> <input type="text" name ="field_1">  </p>
>     <p> <input type="text" name ="field_2">  </p>
>     <p> <input type="submit" value="Submit Form">  </p>
>     </wl:form>

For information on the syntax of this tag see <wl:form>.

Defining Multiple Forms

When using multiple forms on a page, use the name attribute to identify each form. For example:

>     <wl:form name="FirstForm" method="POST" action="thisJSP.jsp">
>     <p> <input type="text" name="field_1">  </p>
>     <p> <input type="text" name="field_2">  </p>
>     <p> <input type="submit" value="Submit FirstForm">  </p>
>     </wl:form>

>     <wl:form name="SecondForm" method="POST" action="thisJSP.jsp">
>     <p> <input type="text" name="field_1">  </p>
>     <p> <input type="text" name="field_2">  </p>
>     <p> <input type="submit" value="Submit SecondForm">  </p>
>     </wl:form>

Re-Displaying the Values in a Field When Validation Returns Errors

When the JSP page is re-displayed after the validator tag has found errors, it is useful to re-display the values that the user already entered, so that the user does not have to fill out the entire form again. Use the value attribute of the HTML <input> tag or use a tag library available from the Apache Jakarta Project. Both procedures are described next.

Re-Displaying a Value Using the <input> Tag

You can use the javax.servlet.ServletRequest.getParameter() method together with the value attribute of the HTML <input> tag to re-display the user's input when the page is re-displayed as a result of failed validation. For example:

<input type="text" name="field_1"
value="<%= request.getParameter("field_1") %>" >

To prevent cross-site scripting security vulnerabilities, replace any HTML special characters in user-supplied data with HTML entity references. For more information, refer to Securing User-Supplied Data in JSPs.

Re-Displaying a Value Using the Apache Jakarta <input:text> Tag

You can also use a JSP tag library available free from the Apache Jakarta Project, which provides the <input:text> tag as a replacement for the HTML <input> tag. For example, the following HTML tag:

>     <input type="text" name="field_1">

could be entered using the Apache tag library as:

>     <input:text name="field_1">

For more information and documentation, download the Input Tag library.

To use the Apache tag library in your JSP:

1. Copy the input.jar file from the Input Tag Library distribution file into the WEB-INF/lib directory of your Web Application.

2. Add the following directive to your JSP:

   >     <%@ taglib uri="input" prefix="input" %>

3. Add the following entry to the web.xml deployment descriptor of your Web Application:

   >     <taglib>
   >         <taglib-uri>input</taglib-uri>
   >         <taglib-location>/WEB-INF/lib/input.jar</taglib-location>
   >     </taglib>

Using a Custom Validator Class

To use your own validator class:

1. Write a Java class that extends the weblogicx.jsp.tags.validators.CustomizableAdapter abstract class. For more information, see Extending the CustomizableAdapter Class.

2. Implement the validate() method. In this method:

   1. Look up the value of the field you are validating from the ServletRequest object. For example:

      >     String val = req.getParameter("field_1");

   2. Return a value of true if the field meets the validation criteria.

3. Compile the validator class and place the compiled .class file in the WEB-INF/classes directory of your Web Application.

4. Use your validator class in a <wl:validator> tag by specifying the class name in the validatorClass attribute. For example:

   >     <wl:validator errorMessage="This field is required" fieldToValidate="field_1" validatorClass="mypackage.myCustomValidator">

Extending the CustomizableAdapter Class

The CustomizableAdapter class is an abstract class that implements the Customizable interface and provides the following helper methods:

  getFieldToValidate()

  Returns the name of the field being validated (defined by the fieldToValidate attribute in the <wl:validator> tag)

  getErrorMessage()

  Returns the text of the error message defined with the errorrMessage attribute in the <wl:validator> tag.

  getExpression()

  Returns the text of the expression attribute defined in the <wl:validator> tag.

Instead of extending the CustomizableAdapter class, you can implement the Customizable interface. For more information, see the Javadocs for weblogicx.jsp.tags.validators.Customizable.

Sample User-Written Validator Class

Listing 5-1 Example of a User-written Validator Class

>     import weblogicx.jsp.tags.validators.CustomizableAdapter;

>     public class myCustomValidator extends CustomizableAdapter{

>         public myCustomValidator(){
>     	super();
>         }

>         public boolean validate(javax.servlet.ServletRequest req)
>     	throws Exception {
>     	String val = req.getParameter(getFieldToValidate());
>             // perform some validation logic
>             // if the validation is successful, return true,
>              // otherwise return false

>     	if (true) {
>     	    return true;
>     	}
>     	return false;
>         }

>     }

Sample JSP with Validator Tags

This sample code shows the basic structure of a JSP that uses the WebLogic JSP form validation tags. A complete functioning code example is also available if you installed the examples with your WebLogic Server installation. Instructions for running the example are available at samples/examples/jsp/tagext/form_validation/package.html, in your WebLogic Server installation.

Listing 5-2 JSP with WebLogic JSP Form Validation Tags

>     <%@ taglib uri="tagl" prefix="wl" %>
>     <%@ taglib uri="input" prefix="input" %>

>     <wl:summary
>     name="summary	"
>     headerText="<font color=red>Some fields have not been filled out correctly.</font>"
>     redirectPage="successPage.jsp"
>     >

>     <html>
>     <head>
>     <title>Untitled Document</title>
>     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
>     </head>

>     <body bgcolor="#FFFFFF">

>     <% if(summary.size() >0 )   {
>         out.println("<h3>" + headerText + "</h3>");
>     } %>

>     <% if (summary.size() > 0) {
>     	out.println("<H2>Error Summary:</h2>");
>     	for (int i=0; i < summary.size(); i++) {
>     	out.println((String)summary.elementAt(i));
>     	out.println("<br>");
>     	}
>     } %>

>     <wl:form method="GET" action="successPage.jsp">

>      User Name: <input:text name="username"/>
>      <wl:validator
>        fieldToValidate="username"
>        validatorClass="weblogicx.jsp.tags.validators.RequiredFieldValidator"
>        errorMessage="User name is a required field!"
>      >
>        <img src=images/warning.gif> This is a required field!
>      </wl:validator>

>     <p>

>      Password: <input type="password" name="password">
>      <wl:validator
>        fieldToValidate="password"
>        validatorClass="weblogicx.jsp.tags.validators.RequiredFieldValidator"
>        errorMessage="Password is a required field!"
>      >
>        <img src=images/warning.gif> This is a required field!
>      </wl:validator>

>      <p>

>      Re-enter Password: <input type="password" name="password2">
>      <wl:validator
>        fieldToValidate="password,password2"
>        validatorClass="weblogicx.jsp.tags.validators.CompareValidator"
>        errorMessage="Passwords don't match"
>      >
>        <img src=images/warning.gif> Passwords don't match.
>      </wl:validator>

>      <p>

>      <input type="submit" value="Submit Form">  </p>

>     </wl:form>

>     </wl:summary>

>     </body>
>     </html>