API

Formulare in JSPs einbinden

Um eine Formulardefinition zu laden, aus dieser eine Instanz zu erzeugen und deren Html-Repräsentation in eine JSP einzubinden sind nur wenige Handgriffe nötig.

Als erstes wird die Formulardefinition benötigt, die über die DefinitionFactory aus einer XML-Datei geladen werden kann. Die FormDefinition kann für weitere Formulare wiederverwendet werden. Daher wird sie auch von der DefinitionFactory mit Zuordnung zum angegebenen Dateipfad gecacht.

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

Aus dieser Definition werden dann die Formularinstanzen erzeugt. Eine Instanz wird für genau einen Bearbeitungszyklus verwendet. Beim Erzeugen der Instanz kann optional das Locale angeben werden, um die Sprache für auszugebenende Texte festzulegen. Ohne explizite Angabe wird das Locale anhand des Http-Request aus den Browser-Einstellungen des Clients ermittelt.

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

Abschließend wird der Html-Code für das Formular vom Renderer in den Writer der JSP geschrieben. Als optionaler Parameter kann eine Standard-Zielseite für das Formular-Submit angegeben werden. Diese kann aber durch weitere Funktionalitäten des Formulars kontextabhängig geändert werden. (siehe Submit-Beispiel)

Da ein Formular verschiedene weitere Resourcen benötigt, müssen diese zuvor im Html-Head inkludiert werden. Das geschieht intern über den ResourceFilter, der in der web.xml registriert sein muss und an dem anhand der Formulardefinition alle für das Formular benötigten Resourcen registriert werden. Aufgerufen werden muss eine Methode des FormContext.

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

Formulardefinition per API erstellen

Alternativ zur Definition des Formulars per XML kann eine Formulardefinition auch über die Java-API erzeugt werden. Für alle Tags und Attribute der XML-Definition stehen äquivalente Methoden zur Verfügung. Die Benutzung sieht dann vereinfacht dargestellt folgendermaßen aus.

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");
// ...