Tag Library

The previous pages illustrated some important concepts of the Calyxo Forms component with a focus on configuration. We will now have a look at the way the Calyxo Forms component supports you, when writing your JSP pages. It offers an extensive set of JSP tags, designed to integrate the Calyxo Forms features with a minimal effort.

In the table below you find a list of commonly used tags from the Calyxo Forms tag library (a complete list is available in the reference section).

JSP Tags

TagDescription
form Defines an HTML form.
text Renders a text input field.
checkbox Renders a checkbox input field.
radio Renders a radio button input field.
group Container for checkbox or radio items.
checkboxitem Renders a checkbox input field contained in a group.
radioitem Renders a radio button input field contained in a group.
select Renders a menu or selection list.
option Renders a select option.

In the following paragraphs we will give an overview of the tags' attributes and look at a few simple examples illustrating the usage of these tags. The next page will then examine a more sophisticated approach for selections (incl. checkboxes and radio buttons) using list models to deliver dynamic option values instead of the static examples shown below.

Attributes

The exact list of attributes for a given tag together with a short description can be found in the reference section. As a rule of thumb we can say: the attribute list for one of the above tags contains the attributes of the corresponding HTML tag plus a core set of Calyxo Forms specific attributes.

All input tags (e.g. the <text>, <checkbox>, <radio>, or <select> tags) have to be embedded in a <form> tag and do require the name attribute, which defines the inputs's name (thus linking it to the corresponding input validations in the configuration file):

AttributeDescription
name Required - Mapped to the HTML attribute of the same name.

Almost all of the HTML attributes are simply passed through (exceptions occur, when form data is available and used to override given default values, as is the case for the checked attribute of the <checkbox> or <radio> tags.)

There are four Calyxo Forms specific attributes, which are available for almost all Calyxo Forms tags. They are used to define the appearance of input fields, whose values did not pass the configured validation. One can separately define the class or style of input fields with data violating a single-field validation (validator) or a multiple-field validation (assertion). This is done by using one of the following four attributes.

AttributeDescription
errorClass Appended to the HTML class attribute, if the validation of this input field failed.
errorStyle Appended to the HTML style attribute, if the validation of this input field failed.
assertClass Appended to the HTML class attribute, if an assertion concerning this input field failed.
assertStyle Appended to the HTML style attribute, if an assertion concerning this input field failed.

If these attributes are not used for an input field, their values are derived from the embedding form (i.e., either a defined attribute value from the form is used or the form's default attribute value, which does result in a red background for failed single-field validations and in an orange background for failed multiple-field validations).

Forms

For the rest of this page we assume, that the Calyxo Forms tag library has been made available by declaring the namespace http://calyxo.odysseus.de/jsp/forms. In a JSP document, this is done by associating that namespace with a prefix as in:

<jsp:root xmlns:forms="http://calyxo.odysseus.de/jsp/forms" ... >

Alternatively, since the tags are only used inside an embedding <form> tag, the namespace declaration could be located inside the <form> tag as well:

<forms:form xmlns:forms="http://calyxo.odysseus.de/jsp/forms" ... >

Anyway, as a result all of the above tags will to be used with a forms: prefix.

In the following examples we assume, that the embedding form of the used input tag is linked to the embedding form of the field validation as described. This link is established as follows:

  1. The form tag's action attribute connects the form to the action, that will be invoked when submitting the form:
    <forms:form action="/foo" ...> ... </forms:form>
    
  2. The corresponding action configuation associates its inputs to a Calyxo Forms form definition named bar in a way depending on the controller implementation:
    • In a Calyxo Control action configuration, this is done in the forms filter's form parameter:
      <action path="/foo" ...>
        <filter name="forms">
          <param name="form" value="bar">
          ...
        </filter>
        ...
      </action>
      
    • In a Struts action configuration, this is done by specifying a form bean whose name is equal to the name of the form definition to be used.
      <action path="/foo" input="bar" ...>
        ...
      </action>
      
    Please refer to the section on Integration for further details on Calyxo Forms related controller configuration.

We are now ready to focus on some of the usage scenarious for the various input tags provided by the Calyxo Forms tag library.

Text Fields

The most frequently used input fields are text fields, so this is a natural starting point for our tag examples. Here you see the <text> tag in action:

Please enter your departure date: <forms:text name="departure"/>

As mentioned, the above line has to be embedded in a <form> tag. The corresponding lines from your configuration file could look like this:

<field property="departure">
  <convert name="date">
    <message>
      <arg name="field" value="departure"/>
    </message>
  </convert>
</field>

Now your input field is linked to the corresponding field validation via its name (and the correspondence of the embedding forms). As a result, the entered string will be converted to a date and formatted in a standard way, if the input was valid. In case it was invalid the specified message is displayed and the input field is marked by a red background.

As an advanced feature you may map the result of a set of text input fields into an array result, instead of separate scalar values. This is especially helpful when handling tabular data. It is achieved by assigning the same name to all of the affected text input fields and adding an index attribute, starting with zero:

Please enter your children's names:
1. <forms:text name="children" index="0"/>
2. <forms:text name="children" index="1"/>
3. <forms:text name="children" index="2"/>

Our configuration file reflects the array result by embedding the <field> element into an <input> element, which allows us to set the array attribute for this input field to true:

<input name="children" array="true">
  <field property="children">
    <convert name="string"/>
  </field>
</input>

Checkboxes

We have three different approaches for checkboxes. The first one maps a single checkbox to a single boolean variable. It works as follows:

<forms:checkbox name="save"/>Please save my data for future visits.

The above tag from your JSP page is rendered into an HTML checkbox with attributes name="save" and value="true" (default). It is accompanied with a validation configuration like

<field property="save">
  <convert name="checkbox"/>
</field>

The checkbox converter converts the browser value (i.e., nothing or the string "true") to a boolean value (false or true, respectively).

The second approach, using a so called checkbox group, is designed to implement a set of checkboxes (i.e., an input field where one can choose multiple answers). If we used the technique described above, we would end up with a set of boolean values (one with an own name for every checkbox). Alternatively, we may prefer an array result, containing a specific string for every checked checkbox. To achieve this, we use the <group> tag, which defines the name of the input variable and use nested <checkboxitem> tags to associate a specific string value with every checkbox:

Please choose your favorite color(s):
<forms:group name="colors">
  <forms:checkboxitem value="red"/>Red
  <forms:checkboxitem value="blue"/>Blue
  <forms:checkboxitem value="green"/>Green
  <forms:checkboxitem value="yellow"/>Yellow
</forms:group>

This group is rendered into four HTML checkboxes with attributes name="colors" and value as defined (the value attribute is required). The configuration file shows the conceptual change by setting the array attribute to true (which requires the use of the input element) and using the string converter for the array values.

<input name="colors" array="true">
  <field property="colors">
    <convert name="string"/>
  </field>
</input>

A third alternative is required, if you intend to implement a set of checkboxes, which shall map to an array result, but your JSP page structure doesn't allow the usage of the <group> tag, since it would overlap with another XML element (e.g. a table row or another checkbox group). In this case we use a more HTML-like approach, implementing every checkbox separately and linking them together via a common name attribute:

Please choose your favorite color(s):
<forms:checkbox name="colors" value="red"/>Red
<forms:checkbox name="colors" value="blue"/>Blue
<forms:checkbox name="colors" value="green"/>Green
<forms:checkbox name="colors" value="yellow"/>Yellow

Since this JSP fragment is rendered exactly as the checkbox group shown above, the configuration file for the string array result has not to be changed. Now one could ask why we suggest to use the <group> tag, if possible. Well, there are mainly two reasons:

  • It extracts common attributes from the contained checkboxes. Not only the name attribute as seen above, but also the four attributes defining the validation error appearance.
  • It is required to use list models, which deliver dynamic checkbox values, as explained on the selections page.

Radio Buttons

The usage of radio buttons shows some parallels to that of checkboxes, which we have seen in the previous section. There is no need for a single radio button, so we simply have to make our decision between two variants: with or without the <group> tag. First, let's look at typical radio button group, which is implemented using Calyxo Forms:

Please choose your favorite color:
<forms:group name="color">
  <forms:radioitem value="red" checked="checked"/>Red
  <forms:radioitem value="blue"/>Blue
  <forms:radioitem value="green"/>Green
  <forms:radioitem value="yellow"/>Yellow
</forms:group>

This group is rendered into four HTML radio buttons with attributes name="color" and value as defined (again, the value attribute is required). Since only a single selection is possible, there is no need to map the result into an array, so we end up with a single string containing the value of the chosen radio button. Thus, our configuration file looks like this:

<field property="color">
  <convert name="string"/>
</field>

As mentioned in the checkbox section, we might encounter situations where we would prefer an equivalent JSP page for the last example without grouping the radio buttons explicitly by using the <group> tag. Again, this can easily be done in a more HTML-like style:

Please choose your favorite color:
<forms:radio name="color" value="red" checked="checked"/>Red
<forms:radio name="color" value="blue"/>Blue
<forms:radio name="color" value="green"/>Green
<forms:radio name="color" value="yellow"/>Yellow

Since this JSP extract is rendered exactly like the grouped variant, the configuration file is not affected by the change.

Selections

Finally, we come to the selection lists. We illustrate the two main cases, single selection lists and multiple selection lists. Since the field's result type (scalar or array) is determined by the chosen list type, the difference between the two cases does not affect the JSP page, but only the configuration file. Let's look at an example:

Please choose a month:
<forms:select name="month">
  <forms:option value="1" selected="selected">January</forms:option>
  <forms:option value="2">February</forms:option>
  ...
  <forms:option value="12">December</forms:option>
</forms:select>

This JSP fragment could be used for a single selection list as well as a multiple selection list (the Calyxo Forms <select> tag has no multiple attribute, but generates the HTML attribute as required). We can turn the above example into a single selection list by defining a scalar result type with a configuration file entry like:

<field property="month">
  <convert name="integer"/>
</field>

This results in an HTML <select> tag without a multiple attribute, which is usually rendered as a drop-down list. If we prefer a real list instead of a drop-down list, we could have set the size attribute to a value of 5 for example, which would have been passed right through to the HTML <select> tag.

The next example illustrates a multiple selection list:

Please choose your favorite music styles:
<forms:select name="style" size="4">
  <forms:option value="1" selected="selected">Pop</forms:option>
  <forms:option value="2">Rock</forms:option>
  <forms:option value="3">Jazz</forms:option>
  <forms:option value="4">R&amp;B</forms:option>
  <forms:option value="5">Reggae</forms:option>
  <forms:option value="6">World</forms:option>
  <forms:option value="7">Classic</forms:option>
</forms:select>

Here we set the size attribute to a value of 4, but this is purely for presentational reasons, it's not the crucial difference, which makes the selection list multiple. This is found in the configuration file, where we declare an array result for the input variable called style:

<input name="style" array="true">
  <field property="style">
    <convert name="integer"/>
  </field>
</input>

There is one last advanced case left, which needs to be mentioned here: we can combine a set of single selection lists, so that their result values will end up in an array result instead of separate scalar values. What is this good for? It's the same reason, which already caused us to introduce arrays of text fields: the handling of tabular data. This leads to the same solution as for text fields: the single selection lists, which shall be grouped together, are assigned the same name and different index values:

Please enter your children's genders:
1. <forms:select name="gender" index="0">
     <forms:option value="F" selected="selected">Female</forms:option>
     <forms:option value="M">Male</forms:option>
   </forms:select>
2. <forms:select name="gender" index="1">
     <forms:option value="F" selected="selected">Female</forms:option>
     <forms:option value="M">Male</forms:option>
   </forms:select>
3. <forms:select name="gender" index="2">
     <forms:option value="F" selected="selected">Female</forms:option>
     <forms:option value="M">Male</forms:option>
   </forms:select>

The configuration file shows the corresponding result array:

<input name="gender" array="true">
  <field property="gender">
    <convert name="string"/>
  </field>
</input>

This results in three HTML <select> tags without a multiple attribute and with a size attribute of 1. (So the exact conditions for the generation of multiple selection lists are: the configuration file must define an array result and the JSP page's <select> tag must not have an index attribute.)