API

Embedding forms into JSPs

Only few handle needed to load a form definition, generate a new instance and integrate their HTML representation into a JSP.

First of all the form definition is required, it can be loaded via the DefinitionFactory from a XML file. The FormDefinition can be reused for other forms. For this purpose the definition is cached by the DefinitionFactory with the allocation and data path.

DefinitionFactory factory = DefinitionFactory.getInstance();
FormDefinition formDefinition = factory.loadDefinition(formFilePath);

From this definition, form instance will be generated. An instance is used for exactly one processing cycle. Optionally the Locale can be set by instantiation, to choose the language of the output text. Without explicit specification the Locale is determined by the information the HTTP request.

FormContext form = FormContext.createFormContext(request, formDefinition);

Finally the renderer writes the HTML code for the form in the JSP Writer. As an optional parameter a standard target page can be declared for the form-submit. This can be changed depending on context by other functionality in the form. (see submit example)

Various resources needed in a form must be included in the HTML head. This takes place via an internal method of the ResourceFilter which must be registered in the web.xml and where all needed resources are registered according the definition of a form. A method of the FormContext must be called.

<%= form.getAllResourceIncludes(request) %>
...
HtmlFormRenderer renderer = new HtmlFormRenderer();
renderer.renderForm(form, out, "submission.jsp");

Create a form definition by API

Alternatively to XML, a form definition can be generated via Java-API. Equivalent methods are available for all tags and attributes of the XML definition. Simplified the usability looks like this.

FormDefinition definition = new FormDefinition();
HierarchicName name = new HierarchicName("/componentName1");

ComponentDefinition component = definition.addComponentDefinition(name1, "integer");
component.setLabelKey("component1.label");
component.setValidator(...);
component.setRenderer(...);
// ...

HierarchicName repeatName = new HierarchicName("/repeat");
RepeatDefinition repeat = (RepeatDefinition)
definition.addComponentDefinition(repeatName, "repeat");
// ...
HierarchicName subName = new HierarchicName("/repeat/subComponent");
ComponentDefinition repeat = (RepeatDefinition)
definition.addComponentDefinition(subName, "text");
// ...