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.
  1. 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!
  2. 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.
  3. 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

A Job Data File is an XML file created by a Workflow process upon 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 the Use PHP arrays option in the HTTP Server user preferences in Workflow; see Workflow Online Help.

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 be available in the data containing the value of the last encountered occurrence of that field. This behaviour is also seen in the PHP language.

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.

The Capture OnTheGo (COTG) plugin automatically adds a hidden field for every unchecked checkbox on a Form when the Form is submitted. It does this for every Form; the template doesn't have to be a COTG template. (See: Using the COTG plugin: cotg-2.0.0.js.)
  
  • Last Topic Update: 15, November, 2017 10:38 AM
  • Last Published: 23, May, 2019 01:55 PM