>> More NetBeans IDE/Visual Pack Documentation
How to Use Virtual Forms
Contributed and maintained by
August [Revision number: V5.5.1]
This publication is applicable to the NetBeans IDE/Visual Web Pack 5.5.1 release.
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.
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
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.
- Begin by unzipping the contents of the MovieAdmin.zip file, which contains two project folders: MovieAdmin and MoviesClassLibrary.
- Start the IDE, close all projects, and open the MoviesClassLibrary project.
Open the MovieAdmin project.
Note: An error occurs on Page1, because you need to resolve a library reference.
- In the Projects window, right-click the MovieAdmin project node, and choose Properties.
- In the Project Properties dialog box, select Libraries in the Categories tree, and then click the Add Project button.
the Add Project dialog box, browse to and click on the
MoviesClassLibrary project, and then click the Add Project JAR Files
- In the Project Properties dialog box, click OK.
- In the Projects window, right-click the MoviesClassLibrary project node, and select Build from the pop-up menu.
- Exit the IDE, and then reopen the IDE to make the MoviesClassLibrary available to the MovieAdmin project.
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.
Figure 1: Show Virtual Forms Button
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.
Figure 2: Page1.jsp in a Web Browser (Click to enlarge)
Page1.jsp in a Web Browser" class="thumbimage" style="margin: 5px auto;" height="442" width="600">
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.
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
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.
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.
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
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:
|Code Example 1: 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
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:
|Code Example 2: 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 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
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.
Figure 4: Virtual Forms Dialog Box
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
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.
Figure 5: Configure Virtual Forms dialog box
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.
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.
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:
|Code Example 3:
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).
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.
>> More NetBeans IDE Documentation