fc.web.forms

Interface Dependency

All Known Implementing Classes:

TestDependency

public interface Dependency

A dependency changes the values or state of some form element based on the user selection or choice of some other form element.

A typical example includes filling later select/popup values based on the user chosen value of an earlier select in the form. So, for example, if the user chooses a country, then the later select shows the states just for that country.

There are several ways to handle dependency changes:

1. The data for some fields (like database based lookup tables) can be looked up every time.
2. All possible options can be looked up ahead of time and then a subset displayed accordingly. This can be done on the server side (on form submit) or by client side javascript (using various javascript arrays containing different sets of data, the arrays are written out by the server as part of the page and swapped out by client side js).

   Orthogonal to all this is field and form validation. Validation only makes sense after we have displayed the updated fields to the user For example, initially a country popup may be empty and a state popup may be empty. When the user selects a country, then the form is submitted. At that point, the states popup is still empty and we should *not* validate the states data (i.e., not show the user a message that a state must be chosen or show a validation error for any other fields which the user hasn't filled out yet).

   Validation can always be controlled by enabled/disabled flag on the field since field validators are not run for fields that are disabled. In addition, any time a field has new dependent values, the form is not validated by field validators.

Method Summary

Modifier and Type	Method and Description
Object	getInitialValues(Field f) Returns the initial values for the target field These are the values that are displayed when the form is first rendered.
boolean	isSubmitDataValid(FormData fd) Returns true if the submitted values are in a valid range of values.
void	renderDependencyData(FormData fd, Writer writer) Writes out data to keep track of dependency state.
void	setDependencyDataFromSubmit(FormData fd, javax.servlet.http.HttpServletRequest req) The inverse of renderDependencyData, sets any depedency data submitted as part of the form.
void	updateValues(FormData fd, javax.servlet.http.HttpServletRequest req) Sets new values for target field in the FormData object.

Method Detail

updateValues

void updateValues(FormData fd,
                  javax.servlet.http.HttpServletRequest req)
           throws DependencyException

Sets new values for target field in the FormData object. The target field then uses those values to render itself to the client. The data should be saved in FormData with the field name as the key.

Note:This method must invoke FormData.setDependencyUpdated() if it sets new values in the formdata object. New values are values that are different from the values that were last displayed to the client.

There are 2 conditions that typically must be satisfied for this to be true:

1. Source not null: The source fields must have some data. For example, a country popup needs to be selected to some country value before the target dependent field (a state popup) can be populated. If no country is selected, we cannot calculate a dependent state value.
2. Source changed: The source fields must have different data than the last time the form was rendered (which means that the client made a different selection/choice). For example, previously, the source field could have been 'usa'. The client then either changes that to 'uk' or leaves it alone. The last_value (which is rendered as a hidden field in the form) in conjunction with the submittd value of the source field(s) can be used to figure out if there was a dependency change. If the source value is 'usa' and the last_value is 'usa', then we know there is no need for any dependency updates (since the usa values are already shown to the user).

Throws:

DependencyException

setDependencyDataFromSubmit

void setDependencyDataFromSubmit(FormData fd,
                                 javax.servlet.http.HttpServletRequest req)

The inverse of renderDependencyData, sets any depedency data submitted as part of the form. This data is set in the specified FormData object and can be later used by the updateValues method.

renderDependencyData

void renderDependencyData(FormData fd,
                          Writer writer)
                   throws SQLException,
                          IOException

Writes out data to keep track of dependency state. This data is typically the last selected values of some source field (say last selected source country for a target dependent state field) and usually written out as a hidden field in the form.

Throws:

SQLException

IOException

getInitialValues

Object getInitialValues(Field f)

Returns the initial values for the target field These are the values that are displayed when the form is first rendered. The returned object is of a type that is suitable for the data of the target field. (typically an instance of a static inner data class of that field).

If there is no initial data, the returned object can also be null or an empty data object, depending on what the target field expects when there is no data.

isSubmitDataValid

boolean isSubmitDataValid(FormData fd)

Returns true if the submitted values are in a valid range of values. For ultra-secure applications, the validity can be computed every time by recomputing/retrieving the dependent data and of-course, database constraints should always be employed.

If this method is not applicable, this method should return true every time.