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 list of Form elements, see Form Elements.
For a list of the extra elements that can be used in a Capture OnTheGo form, see COTG 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. (When the element isn't available via the menu, see the tip below.) Now you can change the element's settings:

1. 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).

2. Type a label, or choose No label under Style, to omit the label. (For Label elements there are no other options to be set.)
3. If applicable, choose a style for the label (for the label of a Checkbox, for example, you can't set a style).
   • Wrap input with label places the input element inside the Label element.
   • Attach label to input ties the label to the input element using the for attribute of the Label element.
   • Use label as placeholder inserts the given label text in the placeholder attribute of the field.
   • No style omits the label altogether.

     The first two label styles ensure that when the user clicks the label, the input element gets the focus.

4. 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!
5. 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.
6. 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.

Adding new HTML5 elements

HTML5 added several new input element types that can't be found in the Designer menu. To add such an element to a template you can do the following:

1. Add an input element from the menu, for example a Text or Button.
2. Select the element in the template.
3. On the Attributes pane, select the desired input type from the Type drop-down list.

Changing a form element

Once an element has been added to a Form, it can easily be changed: simply select the element in the template, go to the the Attributes pane, and edit the element. An input element can even be changed to another type of input element by selecting the desired input type from the Type drop-down list.

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

In a Connect solution, when a Web Form or COTG Form is submitted, there is a Workflow process that receives the data and creates a job data file (which is an XML file). Having arrays in the job data file greatly simplifies creating a data mapping configuration and looping over data in Designer scripts. Here's how to group data in the HTML so that they get submitted as arrays.

A simple method to create arrays in the job 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">

With the Use PHP arrays option enabled in Workflow, 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>

With the Use enhanced PHP arrays option, the XML looks similar, but in this case, the value between the first pair of square brackets is expected to consist of two parts, separated by an underscore (e.g. row_0). The first part becomes the element's name. All content after the first underscore (preferably an integer) is given as an attribute of the element (e.g. <row _idx=0>). 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 _idx=0>
        		<left>122</left>
        		<top>253</top>
        		<type>dent</type>
        	</pin>
        	<pin _idx=1>
        		<left>361</left>
        		<top>341</top>
        		<type>dent</type>
        	</pin>
        </pinElm1>
</values>

This option makes it easier to select all elements on the same level in a data mapping configuration, and to convert the XML to a JSON object.

You can try out this feature with the COTG Time Sheet template, as explained in this how-to: Using The PHP Array Option. The COTG Fields Table element (see Fields Table) in that template has an Add button to add rows to a table, and groups data following this approach.

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.