About Virtual Forms

See Also | Tutorials

A virtual form is a technique you can use to limit the input fields that are processed when a web page is submitted. For example, you might have two input components, like a text field and a drop down list, that you want processed when the user clicks a certain button. However, you do not want anything else to be processed when the button is clicked. To get this behavior, you can create a virtual form and associate the text field, drop-down, and button with it.

Input and Submission Components

A virtual form defines a group of input and submission components on a page. Input components, such as text fields, text areas, drop down lists, checkboxes, listboxes, and radio buttons, participate in the virtual form. Submission components, such as buttons and hyperlinks, submit the virtual form. Most input components can both participate in and submit the virtual form, as described below in "Virtual Forms and Auto-submit On Change."

When a web site user submits a virtual form, only the virtual form's participants are processed. The remaining input components on the page are ignored, as though the components in the virtual form were on their own page.

Associating a Component With a Virtual Form

You add a component to a virtual form by right-clicking the component and choosing Configure Virtual Forms. When the dialog box opens, you see a row for each virtual form to which you can add the component. Each row has the virtual form's color, name, and a Participate and Submit cell. If the component can participate in the form, clicking that cell shows you a drop down list that enables you to change the setting to yes. The same is true for the Submit cell. If the component cannot submit or cannot participate, nothing happens when you click the cell.

Virtual Forms and Auto-Submit on Change

While button and hyperlink components are the most common submission components, an input component such as a drop down list can also be a submission component. A drop down list can both participate in and submit a virtual form. You configure the component's virtual form behavior in the Configure Virtual Forms dialog box. However, to make the drop down list actually submit the web page, it is also necessary to right-click the component and turn on the Auto-Submit on Change feature.

Retaining and Discarding Submitted Values

As part of the default behavior of the virtual forms implementation, 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 and display their submitted values rather than their values. The submitted values are the unconverted and unvalidated entries that are in the input fields when the user submits the web page. The values are the actual current values of the components. This default behavior of virtual forms prevents the unnecessary loss of any non-participating (and thus unprocessed) user entries when the page redisplays.

However, there are circumstances in which you must override the default behavior and explicitly discard the submitted values of non-participating input fields and instead display their values. An example is a master/detail scenario where the detail contains editable fields. When the user selects a new master, which in turn repopulates the data provider for the detail with new data, it is essential that the detail input fields show their values, the data for the new master, rather than their submitted values, the data for the old master.

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

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

General Guidelines

See Also
Virtual Forms Dialog Box
Configure Virtual Forms Dialog Box
Working With Components
Component Tasks: Quick Reference
About Pages
Tutorials

Legal Notices