Using Form Elements
Web Form elements can be used in a Web Form or in a Capture OnTheGo Form (see Forms and Capture OnTheGo). This topic explains how to add these elements to a Form and how to prepare them so that when the Form is submitted, they provide valid data that can be handled easily.
For a description of all Form elements, see Form Elements.
Adding elements to a Form
To add an element to a Form or Fieldset, click inside the Form or Fieldset, select Insert > Form elements, and choose the respective element on the menu. Now you can change the element's settings:
- Add an ID (required) and, optionally, a class.
The ID will be copied to the name attribute of the element. The name attribute is what identifies the field to the receiving server-side script. To change the name, select the element after inserting it and type the new name on the Attributes pane. ID's and classes are also useful with regard to variable data (see Personalizing Content) and styling (see Styling templates with CSS files).
- Type a label, or choose No label under Style, to omit the label. (For Label elements there are no other options to be set.)
- If applicable, choose a style for the label (for the label of a Checkbox, for example, you can't set a style).
- The following options are only available for specific elements:
- For a Text Area you can specify a number of rows.
- For a Radio Button, the submit name indicates to which Radio Button Group the Radio Button belongs.
- For a Button, Checkbox, Hidden Field, and Radio Button you can set the value. The value is associated with the input and will be sent on submitting the Form.
For other Form elements, you can set the default value to be the value of a field in the record set; see Specifying a default value. - For a Checkbox or Radio Button you can check checked or selected respectively for the element to initially be checked/selected when the web page is shown.
- For a Button, you can set the button type:
- Submit: The button will validate the form data and if validation is successful, send the data to the provided URL (the action specified for the Form; see Changing a Form's properties).
- Reset: The button will reset the form to its original configuration, erasing any information entered and options provided. Note: This cannot be undone!
- Depending on the validation method of the form (see Changing a Form's validation method) and the type of element there are a number of options to set under Validation. With Browser validation you can only make a field required and set a maximum length.
- Required: Check if the field is required to submit the form. If a field is required but contains no data, a message will be shown to the user.
- Minimum and maximum length: Enter a numerical value for the minimum and maximum character length required for this field.
- Equal to: Use the drop-down to select another field that is already added to the same Form. The contents of both fields must match for the data to be validated. This is useful for confirmation fields such as for passwords, email addresses etc.
- Under Warnings, type the message that will be displayed to the user if the input is not valid.
The name attribute of Form elements is sent to the server (together with the input value) after the form has been submitted. When adding an element to a Form or Fieldset, you cannot specify a name; the ID will be copied to the element's name attribute. After adding the element to the Form or Fieldset you can change the name on the Attributes pane.
Specifying a default value
Attribute a default value to a Text, Textarea and other Form elements by dragging a field from the Data Model pane directly onto the field, once it has been created. This also works when dragging a field from a detail table in a record set into a Form element that is contained within a Dynamic Table.
Note that the default value doesn't disappear when the user clicks the field, as placeholders do. To insert a placeholder in a field, type a label and choose Use label as placeholder as its style when adding the element to the form; see Adding elements to a Form.
Making elements required
To change the validation of a COTG or Form element, right-click the element and choose Validation settings. Now you can change the Form's validation method and set the requirements per field; see Changing a Form's validation method.
Grouping data using arrays
A Job Data File is an XML file created by a Workflow process on submitting a Web Form or COTG Form. Grouping data in a Job Data File greatly simplifies both the Data Mapping workflow and looping over data in Designer scripts. A simple method to create arrays in that data file is to use two pairs of square brackets in the name of the form inputs. Put the name of the array between the first pair of square brackets. Between the second pair of square brackets, define the key to which the value belongs. Consider the following HTML form inputs: <input type="hidden" name="user_account" value="pparker@eu.objectiflune.com">
<input type="text" name="name" value="Peter Parker">
<input type="text" name="company" value="Objectif Lune">
<input type="text" name="pinElm1[pin_0][left]" value="122">
<input type="text" name="pinElm1[pin_0][top]" value="253">
<input type="text" name="pinElm1[pin_0][type]" value="dent">
<input type="text" name="pinElm1[pin_1][left]" value="361">
<input type="text" name="pinElm1[pin_1][top]" value="341">
<input type="text" name="pinElm1[pin_1][type]" value="dent">
The above HTML results in the following XML: <values count="4">
<user_account>pparker@eu.objectiflune.com</user_account>
<name>Peter Parker</name>
<company>Objectif Lune</company>
<pinElm1>
<pin_0>
<left>122</left>
<top>253</top>
<type>dent</type>
</pin_0>
<pin_1>
<left>361</left>
<top>341</top>
<type>dent</type>
</pin_1>
</pinElm1>
</values>
To enable submitting arrays, you need to check this option in the HTTP Server user preferences in (PlanetPress or PreS) Watch.
In case multiple fields with the same name are encountered the previous value is overwritten. This way only a single occurrence of that field name will we available in the data containing the value of the last encountered occurrence of that field. This behaviour is also seen in the PHP language.
For a detailed explanation of how to use this feature, see: Using The PHP Array Option.
Getting the status of unchecked checkboxes and radio buttons
Unchecked checkboxes and radio buttons are not submitted (as per standard HTML behavior), so how to get the state of those checkboxes and radio buttons? A common approach to get the state of unchecked checkboxes and radio buttons is to add a hidden field to the Form with the same name as the checkbox or radio button, for example: <input type="hidden" name="status_1" value="0" />
<input type="checkbox" id="status_1" name="status_1" value="1" />
When multiple fields with the same name are encountered, the previous value is overwritten. This way the values for unchecked checkboxes and radio buttons can be processed easily.
|