Using Virtual Forms

January 2006 [Revision number: V2-2]

Copyright 2006 Sun Microsystems, Inc.

In this tutorial, you associate components on a login page with two virtual forms. One virtual form processes the information for creating a new login account and the other virtual form processes information for returning users. By associating the components that represent new users with one virtual form and the components that represent returning users with another virtual form, the application can process either group of components as if it were on its own separate page. Contents - About Virtual Forms - Opening the Example Login Project - Associating Components With a Virtual Form - Adding a Second Virtual Form to the Page - Testing the Application - Doing More: Retaining and Discarding Submitted Values - Rules for Associating a Component with a Virtual Form - A Note About Virtual Forms and Page Fragments Example used in this tutorial Login.zip included in the downloaded ZIP file.

About Virtual Forms

Virtual forms enable you to limit the input fields that are processed when a web page is submitted. Two essential elements of a virtual form are its input components and its submission components. Input components, such as text fields, text areas, drop-down lists, and radio buttons, participate in the virtual form. Submission components, most commonly buttons or links, submit the virtual form. When a virtual form is submitted, the virtual form's participants are processed while the other components on the page are ignored; essentially, the virtual form's participants are processed as if they were on their own page. You can include more than one virtual form on a page, and each virtual form is processed separately. This tutorial provides step-by-step instructions for creating two virtual forms on a page. For an introduction to virtual forms, see Virtual Forms in the Sun Java Studio Creator 2 IDE. For a complete sample application that uses virtual forms, including using a table component with virtual forms, see How to Use Virtual Forms.

Opening the Example Login Project

In this section, you open an example project that provides a login page. You use this project as a starting point for creating a virtual form. 1. Open the Login.zip file and extract its contents into the Java Studio Creator project directory. On Windows computers, this directory is typically C:\Documents and Settings\<user name>\My Documents\Creator\Projects. 2. In the Java Studio Creator IDE, choose File > Open Project, and open the Login project. 3. When the Login project appears in the Projects window, choose Run > Run Main Project (or click the Run Main Project button in the toolbar) to build and run the project. In the browser, you should see the welcome page for the Chimney Sweep Central application. 4. Click the Login link on the top left of the page. 5. In the Returning Customer section (the first section), enter admin in the User Name text field and admin in the Password text field. 6. Click the Login button. Figure 1 shows the results. All text fields on the page are validated, including the fields in the section for the new user account. These fields return an error because no value was entered. However, you want the application to process returning users and new users separately. The solution is to use virtual forms, as described in the following section.

Figure 1 : Login Application Without Virtual Forms

Associating Components With a Virtual Form

By associating the components that represent the returning users with one virtual form and the components that represent new users with another virtual form, you can process the input fields in either group of components as if they were their own separate page. In this section, you create and configure a virtual form for returning users. 1. In the Projects window of the IDE, expand Login > Web Pages and then double-click Login.jsp. 2. In the Login page, right-click an empty space and choose Virtual Forms from the pop-up menu. 3. Click New in the Virtual Forms dialog box. 4. Double-click in the Color field and choose the color red from the drop-down list. 5. Double-click in the Name field, type returningCustomer, and then press Enter. Figure 2 shows the Virtual Forms dialog box. Components associated with the returningCustomer virtual form will be identified with a red border.

Figure 2 : Virtual Forms Dialog Box 6. Click OK to apply the changes and close the dialog box. 7. Click the Show Virtual Forms button ( ) in the Visual Designer toolbar.

This action turns on the display of virtual forms. In the Visual Designer, you'll see a virtual forms legend that matches colors to particular virtual forms. The legend is especially useful if you have more than one virtual form on a page, as you will see in the following section. Now you will add components to the virtual form. 8. In the Visual Designer, hold down the Control key and click the User Name text field, Password text field, and the Remember My User Name checkbox in the Returning User section. 9. Right-click any of the three selected components and choose Configure Virtual Forms. 10. Ensure that retUserNameTextField, retPasswordField, and remUserNameCheckbox appear at the top of the Configure Virtual Forms dialog box, as shown in Figure 3. Then double-click in the Participate field, choose Yes from the drop-down list, and click OK. The User Name field, Password field, and Remember My User Name checkbox now have a solid red border to indicate that they participate in the returningCustomer virtual form. This means that these components will be processed when the virtual form is submitted. Note that only input components are eligible to participate in virtual forms. Other types of input components include text areas, drop-down lists, and radio buttons. Technically, an input component is a component that implements the EditableValueHolder interface.

Figure 3 : Configure Virtual Forms Dialog Box 11. In the Visual Designer, right-click the Login button and choose Configure Virtual Forms. 12. In the Configure Virtual Forms dialog box, ensure that loginButton appears at the top. Then set the Submit field to Yes and click OK. The Login button has a dashed border to indicate that it submits the returningCustomer virtual form. Buttons and links are the most common submission components. These components submit the web page because they implement the ActionSource interface. Figure 4 shows the returningCustomer virtual form's participants and submitters with color-coded borders.

Figure 4 : Virtual Form Color Coding

Adding a Second Virtual Form to the Page

Now you create a virtual form for the components in the New User section. The virtual form mechanism will process the participants of this virtual form while ignoring all other input components on the page, including the input components associated with the returningCustomer virtual form. This time you create the virtual form directly in the Configure Virtual Forms dialog box. 1. Ensure that none of the components are selected in the Returning Customer section by clicking once on the page. 2. Hold down the Control key and select the User Name, Password, and Password (Repeat) text fields in the New User section. 3. Right-click any of the three selected components and choose Configure Virtual Forms. Ensure that newPasswordRepeatField, newUserNameTextField, and newPasswordField, appear at the top of the Configure Virtual Forms dialog box. 4. Click New. A new virtual form is added to the dialog box. 5. Set the Color to green, the Name to newUser, and Participate to Yes and then click OK. The name and color of the new virtual form appear in the virtual form legend. The border of the three components changes to a solid green line.

6. Right-click the Create New Account button and choose Configure Virtual Forms. 7. In the entry for the newUser virtual form, set Submit to Yes and then click OK. The border of the button changes to a dashed green line.

Testing the Application

1. Run the application. 2. Click the Login link on the top left of the page. 3. In the Returning Customer section, enter admin in the User Name text field and admin in the Password text field, and then click the Login button. The application logs you in and opens the Welcome page. The input fields in the New User section are not validated. 4. Continue experimenting with the application by filling in the information for a new user account and then clicking the Create New Account button.

Doing More: Retaining and Discarding Submitted Values

By default, whenever the user submits a virtual form that causes the same page to be redisplayed, any input fields that do not participate in that virtual form retain their submitted values. To understand how this works, try the following: 1. Complete the three fields to create a new account. Before clicking the Create New Account button, however, you suspect you may have already created this user name and password for this application. 2. Without modifying the entries in the New User section, enter the same user name and password as a returning customer and click the Login button. A message appears indicating that the user name is not recognized. The input fields in the New User section retain and display their entries because they do not participate in the returningCustomer virtual form. Similarly, when you click the Create New Account button and submit the newUser virtual form, the input fields in the Returning Customer section retain and display their entries because they do not participate in the newUser virtual form. NOTE: There are circumstances under which you need to override the default behavior and explicitly discard the submitted values of nonparticipating input fields. You do this by calling methods of the Form component in the page bean code. For details on this technique, see the technical article How to Use Virtual Forms. 3. To finish signing up for the account, click the Create New Account button.

Rules for Associating a Component with a Virtual Form

Here are some rules you should follow when associating a component with a virtual form:
q

A virtual form can have zero or more participants. A virtual form can have one or more submitters. An input component can participate in multiple virtual forms. A submission component can submit only one virtual form. Only input components are eligible to participate in virtual forms. Likewise, in order for a component to be eligible to submit a virtual form, it must be a submission component. An input component can both participate in and submit a virtual form. For an input component to submit a web page, you must turn on the component's Auto-Submit on Change feature, available on the component's pop-up menu. A component that both participates in and submits a virtual form has a solid border on the left and top sides and a dashed border on the right and bottom sides. A drop-down list is the most common

input component that both participates in and submits a virtual form.

q

Components associated with a virtual form can appear anywhere on a page and need not be co-located.

A Note About Virtual Forms and Page Fragments

In the Java Studio Creator 2 IDE, there is no support for virtual forms within a page fragment. To configure selective processing on components in a page fragment, you must set the immediate property to True on those components. This solution is sufficient to cover a number of uses cases; however, it is still limited insofar as it can only configure selective processing on one group of components. See Also:
q q q

How to Use Virtual Forms Virtual Forms in the Sun Java Studio Creator 2 IDE Using Page Fragments

This page was last modified: January 25, 2006

Sun and Third-party Trademarked Terminology

The following Sun trademarked terms might be used in the Sun Java(tm) Studio Creator tutorials:
q q q q q q q q q

Sun Java Studio Creator integrated development environment (IDE) Sun Java System Application Server version number (Application Server) Java Platform, Standard Edition technology (Java SE(tm) platform) JavaServer(tm) Faces technology JavaServer Pages(tm) technology (JSP(tm) technology) Sun Java System Web Server version number (Web Server) Java Database Connectivity software (JDBC software) Enterprise JavaBeans(tm) specification (EJB(tm) specification) Solaris(tm) Operating System software (Solaris OS software)

The following third-party trademarked terms might be used in the Sun Java Studio Creator tutorials:
q q

UNIX(R) software SPARC(R) processor

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. Sun, Sun Microsystems, the Sun logo, Java and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. Note: Sun is not responsible for the availability of third-party web sites mentioned in this document and does not endorse and is not responsible or liable for any content, advertising, products, or other materials on or available from such sites or resources. Sun will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services available on or through any such sites or resources.

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, tats-Unis. Tous droits rservs. Sun Microsystems, Inc. dtient les droits de proprit intellectuels relatifs la technologie incorpore dans le produit qui est dcrit dans ce document. En particulier, et ce sans limitation, ces droits de proprit intellectuelle peuvent inclure un ou plus des brevets amricains lists l'adresse http://www.sun. com/patents et un ou les brevets supplmentaires ou les applications de brevet en attente aux tats-Unis et dans les autres pays. L'utilisation est soumise

aux termes de la Licence. Sun, Sun Microsystems, le logo Sun, Java et le logo Java Coffee Cup sont des marques de fabrique ou des marques dposes de Sun Microsystems, Inc. aux tats-Unis et dans d'autres pays.Ce produit est soumis la lgislation amricaine en matire de contrle des exportations et peut tre soumis la rglementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nuclaires,des missiles, des armes biologiques et chimiques ou du nuclaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou rexportations vers les pays sous embargo amricain, ou vers des entits figurant sur les listes d'exclusion d'exportation amricaines, y compris, mais de manire non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une faon directe ou indirecte, aux exportations des produits ou des services qui sont rgis par la lgislation amricaine en matire de contrle des exportations et la liste de ressortissants spcifiquement dsigns, sont rigoureusement interdites. Sun Microsystems n'est pas responsable de la disponibilit de tiers emplacements d'enchanement mentionns dans ce document et n'approuve pas et n'est pas responsable ou iresponsable d'aucun contenu, de la publicit, de produits, ou d'autres matriaux dessus ou fournis par de tels emplacements ou ressources. Sun ne sera pas responsable ou iresponsable d'aucuns dommages ou perte causs ou allgus pour tre caus par ou en liaison avec l'utilisation de ce produit ou la confiance dans des tels contenu, marchandises, ou services disponibles sur ou par des tels emplacements ou ressources.