Using COTG Elements

Capture OnTheGo (COTG) elements are Web Form elements that are specially designed to be used in a Capture OnTheGo Form (see Capture OnTheGo). This topic explains how to add these elements to a Capture OnTheGo Form or 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 COTG elements, see COTG Elements.

Adding COTG elements to a Form

To add a COTG element to a Form or Fieldset, click inside the Form or Fieldset, select Insert > COTG elements, and choose the respective element on the menu. 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.

When you add a Capture OnTheGo (COTG) element to a template that you didn't start with a COTG template wizard, the Designer will automatically add the necessary JavaScript files: the jQuery library and the COTG library: cotg-2.0.0.js. (See: Using the COTG plugin: cotg-2.0.0.js.)

If a template contains an earlier version of the COTG library, the newest version will be added to the resources, but you will be asked which version of the library you prefer to use. Your preferred library will be included in the section (see: Includes dialog).

The Foundation JavaScript files and style sheets will not be added. You only get those automatically when you start creating a COTG template with a template wizard. (See: Using Foundation.)

Element specific settings

After inserting certain COTG elements, such as the Camera element, some important settings have to be made. These will appear when you right-click the element and select it from the short-cut menu.

Alternatively, you can make settings on the Source tab (see Changing widget settings in HTML).
The default settings can be changed in JavaScript; see Changing default settings for widgets.

Attributes

Some attributes (which aren't the same as the settings mentioned above) of a COTG element can be seen on the Attributes pane, after selecting the element (see Selecting an element).

All COTG elements have a role attribute. This attribute is not supposed to be edited: without the correct role attribute, the element won't function.

As noted, the name attribute is what identifies the element after submitting the form.

Use the Outline pane at the left to see which elements are present in the template and to select an element.

Use the Attributes pane at the right to see the current element's ID, class and some other properties.

Use the Styles pane next to the Attributes pane to see which styles are applied to the currently selected element.

Click the Edges button on the toolbar to make borders of elements visible on the Design tab. The borders will not be visible on the Preview tab.

How to make COTG elements required

To make a COTG element required, or to change the validation of a COTG Form, right-click the element and choose Validation settings. Set the Form's validation method to jQuery and set the requirements and a message per field. For an explanation see Changing a Form's validation method.

Changing widget settings in HTML

The Camera and Geolocation widgets have configurable options; you can decide which buttons will be visible in the Camera element, for example. A number of these options can be set via the user interface (see Element specific settings).
The settings are stored in JSON format in the data-params attribute of the element in the HTML, as you can see on the Source tab in the Designer after making a setting.
All options, including options that cannot be set via the user interface, can be set via this data-params attribute. To define a timeout of 6 seconds for a Geolocation element, for example, you could switch to the Source tab and change its HTML to:
<div id="geolocation1" role="cotg.Geolocation" data-params="{&quot;timeout&quot;:6000}">.
Settings in the HTML override the default settings for that element. They are applied to the widget when the Form is created and cannot be changed afterwards.

For a complete list of options see the Capture OnTheGo API: Capture OnTheGo API.

Settings for a dynamically added element can be made in code; see Dynamically adding COTG widgets.

The default settings that are specified in the COTG plugin can also be changed in code; see Changing default settings for widgets.

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: 09, November, 2017 09:29 AM
  • Last Published: 23, May, 2019 01:55 PM