Previous chapter | Next chapter
The first step in designing or building a form should not be to start programming, but to take an inventory of all the information that you would like to (or need to; it is bad practice to ask for information we have already) collect from the user. The model of the XForm will hold - among other things - the specification of the information we want to collect. In other words: the model contains the template for the data we intend to gather from the visitor.
Our form will collect information from applicants who want to organize events in a certain area. For these events (such as a marathon, concert, or a market) certain requirements may be imposed by local government, depending on the type of event, the exact location or the number of attendees that is expected.
Let us first look into the information we would like to collect about the applicant.
As the applicant could be either an individual citizen or a company, represented by one of its staff, we immediately need to offer a choice here: citizen or company. Assuming the user selects “citizen”, we will need to gather the following information:
The information we want to collect is specified in an instance in the XForms Model section, which we include in the head section of our document. At a later stage, we will expand the Model section, but for now it will consist of the following entities shown in the code section below.
In our model, we have now created an instance for citizen data and filled it with empty placeholders. For now, the instance does not have an id; it is the default instance. Notice that the instance has a single root node, applicationdata; its name is arbitrary. Later on in the process, we will have to complete the section in the model instance for company information and we will add a section for the actual event information as well.
Defining a model does not actually do anything: it is just a definition or a placeholder for the data that we will submit at a later point in time. By defining the instance we do however do what should be done when we start building a form: we think about the information to be collected rather than simply drawing a form with some inputs.
We have added the required attribute for a number of fields. This in itself does not do anything either, but it happens to be a convenient place to mark a field as required; we will demonstrate later how to benefit from this attribute.
Also, we included some typing information by adding a schema reference to the email field. We will use this later for validation purposes.
For form maintainability purposes, we have created another instance, with id="resources", to contain all textual information that will be displayed on the form. This will help us to keep all textual information together (which will assist us in consistency and internationalization of our form during one of the last steps of this tutorial). Of course, if you are just getting started with XForms, this may seem a little over the top. So for now you could also decide to put this information right into the body section, as we will see later.
For now, we have two sections in the resources instance: texts and options. The texts section contains the actual label (question) belonging to the input we want to display, and the hint, alert and help texts that are particular to a certain input. The option section contains the texts that will be displayed as options in a (dropdown, radio or check) list.
By keeping all texts together and separate from the data and logic sections, we create the possibility for a separation of concerns: textual editing is completely different from building logic statements.
Previous chapter | Next chapter
<xf:model id="model">
<xf:instance xmlns = "">
<applicationdata>
<citizen_company required="true" />
<citizen>
<citizen_firstname required="true" />
<citizen_middlename />
<citizen_lastname required="true"/>
<citizen_street required="true" />
<citizen_number required="true" />
<citizen_postalcode required="true" />
<citizen_city required="true" />
<citizen_phone />
<citizen_email xsi:type="xf:email" />
</citizen>
<company>
<company_name required="true" />
</company>
</applicationdata>
</xf:instance>
<xf:instance id="resources" xmlns="">
<resources>
<texts>
<citizen_company>
<label>Are you an individual citizen or representing a company?</label>
<hint>Please make a selection.</hint>
<alert>This selection is required.</alert>
<help>Indicate if you apply as a citizen or on behalf of a company.</help>
</citizen_company>
</texts>
<options>
<citizen_company>
<option value="">Please select...</option>
<option value="citizen">I am a citizen</option>
<option value="company">I represent a company</option>
</citizen_company>
</options>
</resources>
</xf:instance>
</xf:model>