Previous chapter | Next chapter
So far, we have actively used two types of controls: single selects (select1) and text inputs, for both of which we have applied different kinds of validation. Also, we used the label, hint, help and alert controls (although we did not yet see the full benefit of them). And we have embedded a Trigger and a Submit control. Now, let us explore some of the other controls that are available to us.
Remember that controls have an appearance property, which will give the XForms engine which actually renders the form a clue about the way we expect the form to be rendered. The three possible values for appearance are:
As the name implies, this control provides ways to enter secret information, most likely a password. The simplest way to embed a Secret control is by using the code below (with password being an element under the event node in the default instance of the model):
<xf:secret ref="event/password">
<xf:label>Enter your password</xf:label>
</xf:secret>
The textarea control can be used to input multiline sections of text. Description is an element under the event node in the default instance of the model.
<xf:textarea ref="event/description">
<xf:label>Give a short description of the event</xf:label>
<xf:hint>Enter your description here</xf:hint>
</xf:textarea>
The Output control is generally used to display information. We may for instance use the Output control to display instructions or to summarize all user input in a last step before submission (assuming number_visitors is an element in the model instance):
<xf:output value="number_visitors" />
The Output Mediatype option offers a way to vary the format of the information displayed. Look at the example below, which refers to an image element in the model, containing a file path to an image:
<image>../assets/images/acme.png</image>
This is how we can render this information with XForms:
<xf:group>
<xf:output ref="event/plan" mediatype="image/*" appearance="minimal"/>
<xf:output ref="event/plan" mediatype="text/*" appearance="minimal"/>
</xf:group>
The above code first displays the image itself (mediatype image), then it displays the file name of the image (mediatype text).
Many applications need to be completed with some additional documents, such as scans, pictures, plans or PDF files. The Upload control is very straightforward, as is illustrated by the code below.
<xf:upload ref="event/plan" incremental="true" mediatype="image/*">
<xf:label>Plan of the location</xf:label>
<xf:filename ref="@filename"/>
<xf:mediatype ref="@mediatype"/>
</xf:upload>
referring to this line in the model, declaring the plan element to be a base64-encoded document:
<plan xsi:type="xsd:base64Binary" filename="" mediatype=""/>
Now combine this control with the xf:output control and you will see a preview of the uploaded document. Note: make sure only harmless documents can be uploaded. The maximum size of the uploaded document is usually determined by the web server (such as Microsoft IIS).
The range control is aptly named: it provides an input for a value in a certain range. Let us assume we want to know the birth year of a (living) person. If we would use a regular input (with integer typing using xsi:integer) -3, 578 and 2026 would all be valid entries, even though they would be meaningless. The same holds true for an age input: valid figures would be between 0 and maybe 120.
<xf:range ref="event/visitors" incremental="true" start="0" step="100" end="2000" appearance="minimal">
<xf:label ref="instance('resources')/texts/event_visitors/label"/>
<xf:hint ref="instance('resources')/texts/event_visitors/hint" />
<xf:alert ref="instance('resources')/texts/event_visitors/alert"/>
<xf:help ref="instance('resources')/texts/event_visitors/help"/>
</xf:range>
In HTML, the XForms engine may present this as a slider input if scripting is enabled, but as a simple input if it is not.
A trigger control in XForms is an abstracted button. In its simplest form, you can add a trigger using the code section below:
<xf:trigger>
<xf:label>Some label text</xf:label >
<xf:action ev:event="DOMActivate">Do something here, like a submission</xf:action>
</xf:trigger> >
We have already used the trigger control to study the interaction between server and client.
The XForms engine that serves your forms to visitors will convert the input control into a HTML representation. If the type of information is defined in the model instance, the XForms engine may be able to use this and offer a specific representation. For example, we want a check box that the applicant will have to tick in order to indicate he has entered all information truthfully. In the instance, we may add:
<agree xsi:type="xf:boolean" />
and in the form we may enter:
<xf:input ref="event/agree" incremental="false">
<xf:label ref="instance('resources')/texts/event_agree/label"/>
<xf:hint ref="instance('resources')/texts/event_agree/hint" />
<xf:alert ref="instance('resources')/texts/event_agree/alert"/>
<xf:help ref="instance('resources')/texts/event_agree/help"/>
</xf:input>
The XForms engine may then present this as a checkbox in the HTML output. This should work in the same way for datatypes such as dates. Of course, the alternative is to add a class to an input and use client-side enrichment to create a jQuery calendar that way:
<date xsi:type="xsd:date" required="true" />
The date element has been typed as a date in the model instance
<xf:input ref="event/date" incremental="false" appearance="full" class="ui-date-picker">
<xf:label ref="instance('resources')/texts/event_date/label"/>
<xf:hint ref="instance('resources')/texts/event_date/hint" />
<xf:alert ref="instance('resources')/texts/event_date/alert"/>
<xf:help ref="instance('resources')/texts/event_date/help"/>
</xf:input>
And a class has been added for client-side enrichment.
So far, we have used a Select1 control to offer a choice between citizen and company. Default, this control behaves like a “closed” control. You can use the selection attribute and set it to “open” if you want the user to enter his own information.
The Select control offers the possibility to select multiple entries from a list. Depending on the appearance of the form, the XForms engine will either show a list or a group of checkboxes (appearance set to “full”).
It might be more elegant to offer a dual selection list, where the user can move items from one list (not selected) to the other list (selected). This will involve the use of custom controls in the appearance attribute and is something for later exploration.
Our form has now been extended with some other controls.