Form Example

Hello World

An XML form definition has the root element form. The XSD schema description can be found in the distribution in the package de.imatics.forms.schema in the file form.xsd. To use while development of a form the auto-completion of an XML-editor, the schema file should be assigned to the schema location http://www.imatics.de/forms/form.xsd used in the XML declaration. Since there is no mixing with other name-spaces can be waived on the use of name-space by the statement noNamespaceSchemaLocation.

The form element contains a list of component, group or repeat elements. The last two can contain as child element other components, groups or repeats. The first example creates a simple form for a text field that is initialized with the value "Hello World". 

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.imatics.de/forms/form.xsd">

  <component name="hello" type="text" label="Text">
    <default>Hello World</default>
  </component>
</form>

A component can contain other elements that define the constraints for the component. The most important of them will be explained:

  • validator Contains further sub-validators, which define the entry rules for the component. The names of the possible elements match the class name of the validator implementation in the package de.imatics.forms.validator. Capital letters in class names will be converted to lower case and separated by hyphens. By use of <multiple-of .../> the MultipleOfValidator will be used. Logical combinations of different validators can be created by a hierarchical XML structure with and- and or-elements. The validator element itself acts as the AND operation of the contained terms.
  • hidden / readonly These elements also include sub-validators. Depending on the results of the validation the component is shown not editable or hidden. If the elements do not contain a validator the result is always true, so that e.g. <hidden/> hide a field permanently.
  • renderer One or more renderers to be used for the display and input of the component value. If no renderer element is specified the default renderer is used for the component. The element renderer has the attribute type. With it conceptually renderers can be specify for different media. For HTML forms the value html is to be use. There exist currently only renderer for HTML forms, so the default render-type will be defined as the attribute in the form element.
    As class the full name of the used renderer class is specified. For renderers, which are in the standard package for html-renderer, also reaches the local class name without the name part renderer.
  • option-list Defines the options that are available for a component. These can be offered by different renderers to choose from (e.g. DropdownRenderer). The options can be specified by a fixed list of option elements or by a class that implements a OptionListFactory. Alternatively, a calculator can be specified, which generates a list of values.
    (see also the / examples)
  • option-list / option-tree Similar to the option-list some renderer can require options in a tree structure. This class implements an TreeFactory.
  • default Contains a calculator element that provides the default value for a component if it is empty when the form loads. The use of a simple text is parsed as ConstantCalculator, which returns the contained text.
  • calculator Contains a Calculator element that during the processing of the form calculates the value of the component based on other components. A calculator can get the values of other components as parameter. This calculator will be executed immediately once the value of a as parameter referenced component is changed.

The "Hello World" example can be extended in this way with validators and additional renderers with an options list. 

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.imatics.de/forms/form.xsd"
  render-type="html">

  <component name="hello" type="text" label="Text">
    <validator>
      <required/>
      <length min="3"/>
    </validator>
    <renderer type="html" class="Text"/>
    <renderer type="html" class="Dropdown"/>
    <option-list>
      <option value="Hello World"/>
      <option value="Hallo Welt"/>
    </option-list>
    <default>Hello World</default>
  </component>
</form>