>> More NetBeans IDE/Visual Pack Documentation

How to Use Virtual Forms

Virtual Forms are a feature of the NetBeans integrated development environment (IDE). This technical article is written for developers who use the IDE and want to take advantage of this powerful mechanism.

For more information about NetBeans Visual Web Application Development, see the Support and Docs page on the NetBeans web site.

Contents

Installing the Example

Note: If you are using NetBeans/Visual Web 5.5.1, then you have the sample applications available to you via the New Project Wizard. Simply choose File > New Project > Samples > Visual Web > Movies Class Library and then File > New Project > Samples > Visual Web > Movies Administration and then continue with step 3 below.

1. Begin by unzipping the contents of the MovieAdmin.zip file, which contains two project folders: MovieAdmin and MoviesClassLibrary.
2. Start the IDE, close all projects, and open the MoviesClassLibrary project.

3. Open the MovieAdmin project.

   Note: An error occurs on Page1, because you need to resolve a library reference.
4. In the Projects window, right-click the MovieAdmin project node, and choose Properties.
5. In the Project Properties dialog box, select Libraries in the Categories tree, and then click the Add Project button.
6. In the Add Project dialog box, browse to and click on the MoviesClassLibrary project, and then click the Add Project JAR Files button.
7. In the Project Properties dialog box, click OK.
8. In the Projects window, right-click the MoviesClassLibrary project node, and select Build from the pop-up menu.
9. Exit the IDE, and then reopen the IDE to make the MoviesClassLibrary available to the MovieAdmin project.

Show Virtual Forms Button

After installing the example, click on the Page1.jsp tab. In the toolbar beneath the tab, you will see a set of buttons, including the Show Virtual Forms button . Click the button to show the virtual forms used on the page.

Movie Administration Overview

The Movie Administration example is a hypothetical administrative application for a movie rental business. The business maintains data about its movie collection in a data store, and the administrative application enables employees to make changes to that data. The business also has a separate external web site that enables customers to browse the collection. The same data store is used for the external web site.

Note: A real-world application would make use of a relational database or other external data store. However, in order to focus on virtual forms, the Movie Administration example simply stores the data as objects in the session.

The figure below shows Page1.jsp of the Movie Administration application in a browser. The employee can view the movies in a particular genre by making a selection in the Current Genre dropdown list. Within the table, the title, year, length in minutes, rating, image URL, and description fields can be edited; the changes are saved when the employee clicks the Update button or uses the table's paging controls (when available). The employee can remove a movie from the collection by clicking the Remove button in one of the rows. Clicking the Preview button in one of the rows navigates to Preview.jsp, which enables the employee to preview the detail page for a movie as it would be seen by a customer browsing the external web site. A separate set of controls appears below the table for adding a movie to the collection.

Tip: When you run the example and add movies to the collection, you can enter file-based URLs to image files on your machine instead of relative paths to image files in the project. This is a shortcut that enables you to forego adding those image files to the project.

Besides enabling the employee to preview the detail for a movie, the Preview page also enables the employee to revise the genre of the movie being previewed.

Selective Processing Requirements

Page1.jsp poses an interesting problem. When a new current genre is selected, we want the input from the Current Genre dropdown list to be processed, but not the other inputs on the page. If the other inputs were processed, any conversion or validation errors on those inputs would cause the submission to be rejected, which would prevent the genre change—which is not what we want. Similarly, when the Update button is clicked, we want the inputs within the table to be processed, but not the inputs in the Add Movie section. Any conversion or validation errors on the fields in the Add Movie section would cause the submission to be rejected, which would prevent the updates to the fields within the table—which is also undesired. The Preview, Remove, and Add buttons also have similar selective processing requirements.

In this way, selectively processing certain inputs when the user interacts with certain submission components is a common and critical requirement of web applications. Processing an input means converting and validating it, firing any value change events associated with the input, and mapping the input onto its binding target (if the component is bound). An input component is any component that accepts user input, such as a text field, text area, dropdown list, or radio button. (Technically, input components are those that implement the EditableValueHolder interface.) A submission component is any component that causes the web page to be submitted and thus initiates input processing; this includes not only buttons and links (which implement the ActionSource interface), but also input components with the Auto-submit On Change feature turned on. Thus, it is possible for a component to be both an input component and a submission component. The Current Genre dropdown list on Page1.jsp of the Movie Administration application is such a component.

The complete selective processing requirements for Page1.jsp are as follows:

• Current Genre dropdown list. When a new current genre is selected, the Current Genre; dropdown list should auto-submit the web page and the dropdown list's input should be processed exclusively, with the other inputs on the page being ignored.
• Update button. When the Update button is clicked, only the fields within the table should be processed and not the fields in the Add Movie section. When this occurs, the current genre selection need not be processed either since it did not change.
• Preview/Remove buttons. When a Preview or Remove button is clicked, no inputs whatsoever should be processed. No inputs need be processed in such a case because the Table component and DataProvider APIs provide access to the row where the button was clicked. Any inputs entered into the fields within the table or in the Add Movie section must be ignored. Again, the current genre selection need not be processed either since it did not change
• Add button. When the Add button is clicked, only the inputs in the Add Movie section should be processed.

Page1.jsp also has an additional selective processing requirement. When the table displays paging controls, interacting with them should cause only the inputs within the table to be processed. Otherwise, conversion and validation errors on fields outside the table would cause the submission to be rejected.

Without a sufficiently powerful selective processing mechanism, these requirements cannot be met. The immediate property on JavaServer Faces components offers some selective processing support, but not enough to build a GUI such as this. The problem is that in this GUI, there are multiple groups of input components that need to be selectively processed depending on which submission component the user engages. By setting the immediate property on certain components within a GUI, you can specify a single group of components to be selectively processed, but not multiple groups.

Introducing Virtual Forms

A virtual form defines a group of input and submission components on a page. The input components are said to participate in the virtual form. The submission components are said to submit it. When a web site user interacts with a component that submits a virtual form, the virtual form's participants will be processed while the remaining inputs on the page are ignored.

Note the following:

• A virtual form can have zero or more participants and one or more submitters.
• Only input components can participate in a virtual form. Since a submission component is by definition any component that can submit the web page (including input components with their Auto-submit On Change feature turned on), any such component can be a virtual form submitter.
• Virtual forms impose no topographical limitations; their participants and submitters need not appear visually near one another.
• An input component can participate in multiple virtual forms, but a submission component can submit at most one virtual form.
• An input component can both submit a virtual form and simultaneously participate in one or more virtual forms.
• If a submission component does not submit any virtual forms, then when the user interacts with it, the literal form will be submitted, as usual.

Unlike the immediate property which can define only one group, a page can make use of as many virtual forms as needed, making them a powerful solution. Also, whereas the immediate property alters the JavaServer Faces lifecycle and is therefore appropriate for advanced developers, virtual forms do not do so and are therefore easier to use.

Take a look at Figure 3, which shows Page1.jsp of the Movie Administration application in the Visual Editor of the IDE. The virtual forms are color coded; solid lines denote participation; dashed lines denote submission. Four virtual forms are used:

• genre. The Current Genre dropdown list both participates in and submits the genre virtual form (blue). To show that it both participates in and submits that virtual form, its north and west borders are solid and its south and east borders are dashed.
• update. Within the table, the title, year, length in minutes, rating, image URL, and description fields participate in the update virtual form (green), and the Update button submits it.
• preview/remove. The Preview and Remove buttons submit the preview/remove virtual form (red), which has no participants.
• add. In the Add Movie section, the genre, title, year, length in minutes, rating, image URL, and description fields all participate in the add virtual form (yellow), and the Add button submits it.

Note: Page1.jsp features a Message List component embedded within a Group Panel. The Message List has a red border and the Group Panel displays a finely dashed border in the Visual Editor. Don't be confused by this—the borders of these components are not related to virtual forms.

It is worth repeating that, while a virtual form can have one or more submitters, any given submission component can submit at most one virtual form. So, for instance, the preview/remove virtual form has two submitters, namely, the Preview and Remove buttons. However, each of these buttons only submits that one virtual form—they cannot submit more than one virtual form. Also, though it does not occur in the Movie Administration application, it would be perfectly fine (and is fairly common) for an input component to participate in multiple virtual forms. Moreover, while the components associated with each virtual form on Page1.jsp tend to appear visually near one another, this is by no means a requirement of the virtual forms mechanism.

The four virtual forms used on Page1.jsp satisfy that page's selective processing requirements, as follows:

• genre. When the employee changes the selection in the Current Genre dropdown list, the genre virtual form is submitted. Since that dropdown list is the only participant in the virtual form, only its input is processed; other inputs on the page are ignored. As a result, converters and validators associated with those other inputs do not reject the submission.
• update. When the employee clicks the Update button, the update virtual form is submitted. Since only the inputs within the table participate in that virtual form, those inputs are processed while all other inputs are ignored. As a result, the converters and validators on fields in the Add Movie section do not reject the submission.
• preview/remove. When the employee clicks a Preview or Remove button, the preview/remove virtual form is submitted. No inputs are processed, since that virtual form contains no participants. As mentioned earlier, no inputs need be processed because the Table component and DataProvider APIs provide access to the row where the button was clicked. As a result, none of the converters or validators on the page reject the submission.
• add. When the employee clicks the Add button, the add virtual form is submitted. Since only the inputs in the Add Movie section participate in that virtual form, those inputs are processed while all other inputs are ignored. As a result, the converters and validators on fields within the table do not reject the submission.

Retaining and Discarding Submitted Values

If the user submits a virtual form that causes the same page to be redisplayed, the default behavior of the virtual forms implementation is to retain and display the submitted values of non-participants. This prevents the loss of any user entries that were not processed. For example, say the user enters some data into the fields in the Add Movie section. However, before clicking the Add button, the user decides to change the selection in the Current Genre dropdown or modify some data in the table and click the Update button. As a result, a virtual form will be submitted in which the input fields in the Add Movie section do not participate. In order not to lose the user's entries in those input fields, when the page redisplays, those input fields retain and display their submitted values rather than display their values. The submitted values are the unconverted and unvalidated entries in the input fields when the user submits the web page. The values are the actual current values of the components.

However, there are some user gestures for which we want to override the default behavior. In those cases, rather than retain and display the submitted values of some non-participants, we want explicitly to discard their submitted values and display their values instead. For example, the input fields within the table do not participate in the genre virtual form. Therefore, when the user changes the selection in the Current Genre dropdown and the page subsequently redisplays, the default behavior is for the input fields within the table to retain and display their submitted values. This is not what we want, since the movies in the old genre will appear in the table rather than those in the new genre. Therefore, it is necessary to override the default behavior by explicitly discarding those submitted values in the currentGenreDropDown_processValueChange method:

// the genre virtual form, in which only the currentGenreDropDown
// participates, has been submitted
// make sure the input fields in the movies table do not
// retain their submitted values
form1.discardSubmittedValues("update");

Here the participants in the update virtual form (namely, all the input fields within the table) explicitly discard their submitted values. As a result, they will instead display their values, which means that the table will display the movies in the new genre rather than the old genre.

The Form component contains the following methods to discard submitted values of non-participating input fields:

public void discardSubmittedValues(String virtualFormName)
public void discardSubmittedValue(EditableValueHolder inputField)

The first method above accepts a virtual form name. The participants in the virtual form specified will discard their submitted values. The virtual form specified cannot be the one that was submitted. This method throws an IllegalArgumentException if the virtual form specified was submitted during the current request.

The second method above accepts a single input field as an EditableValueHolder object. The input field specified will discard its submitted value. Note that the input field specified must be non-participating. This method throws an IllegalArgumentException if a virtual form was submitted and the input field specified participates in it.

The internalVirtualForm Property

The Table component has an internalVirtualForm property which is false by default. In the table on Page1.jsp, this property has been set to true. This causes the table to use a virtual form internally. As a result, when the paging controls are used, only the inputs within the table are processed. This prevents the converters and validators on fields outside the table from rejecting the submission.

Virtual Forms Dialog Box

Within the NetBeans IDE, you can create, delete, and rename virtual forms and change their color codes by right-clicking on the Visual Editor itself (not on any component) and choosing the Virtual Forms contextual menu item. The Virtual Forms dialog box opens, as shown in Figure 4.

Using this dialog box is fairly straightforward. To change the color associated with a virtual form, click the color cell and select a color from the list. To rename a virtual form, double click the name cell and edit the name. You can also create and delete virtual forms in this dialog box.

Configure Virtual Forms Dialog Box

While the Virtual Forms dialog box enables you to create, delete, and rename virtual forms and change their color codes, it does not let you configure the components that participate in and submit each virtual form. The Configure Virtual Forms dialog box enables you to do all of these things. To access that dialog box, select one or more components in the Visual Editor or Outline window, right-click, and choose the Configure Virtual Forms contextual menu item. The resulting dialog box enables you to specify the virtual forms in which the selected components participate. You may also specify a virtual form that the selected components submit. Like the Virtual Forms dialog box, the Configure Virtual Forms dialog box also enables you to create, delete, and rename virtual forms and change their color codes. The figure below shows the Configure Virtual Forms dialog box after having selected all the input components in the Add Movie section on Page1.jsp.

Virtual Forms and Autosubmit on change

While button and link components are the most common submission components, an input component such as a dropdown list can also be a submission component. On Page1.jsp of the Movie Administration example, the Current Genre dropdown list both participates in and submits the genre virtual form. It was configured this way using the Configure Virtual Forms dialog box. However, in order to make the dropdown list actually submit the web page, it was also necessary to right-click the component and turn on the Auto-submit On Change feature. Note that there is no Auto-submit On Change option for button and link components because they intrinsically submit the web page.

Virtual Forms and Page Fragments

In both NetBeans/Visual Web Pack 5.5.1 IDE and the NetBeans 6.0 IDE, there is no support for virtual forms within page fragments. To configure selective processing on components in a page fragment, you 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.

Virtual Forms and the Standard Data Table Component

Though not a common use case, it is worth noting that if you want a button or link within a standard Data Table component (not the new Table component) to submit a virtual form, you must add a bit of extra scripting to the button or link's onClick (or onclick) property. Say you have a Button component whose id property is button1 inside a standard Data Table component. You would need to add the following to the button's onClick property:

common_leaveSubmitterTrace(this.form,'button1');

Without this extra bit of scripting, the button would not be able to submit a virtual form. Again, this only applies to buttons and links (not input components) inside a standard Data Table component (not the new Table component).

Summary

This technical article explored the new Virtual Forms feature in the NetBeans IDE. A virtual form defines a group of input components ("participants") and submission components ("submitters") on a page, such that when the user interacts with one of the submitters, the participants are processed exclusively while the remaining inputs on the page are ignored. You also learned about:

• The selective processing requirements of the Movie Administration example application and witnessed how virtual forms provide a powerful and comprehensive solution for meeting those requirements.
• How to modify a page's virtual form configuration within the IDE via the Virtual Forms and Configure Virtual Forms dialog boxes.
• How input components can submit a virtual form if their Auto-submit On Change feature is turned on.
• That, the immediate property, virtual forms do not alter the JavaServer Faces lifecycle, and thus are easy to use.

top

>> More NetBeans IDE Documentation