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:

Add an ID (required) and, optionally, a class.

Note: 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).
- 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.
  
  Note: 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.1.0.js. (See: Using the COTG plugin.)

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.

Tip: 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.

Tip: Click the Edges button on the toolbar temporarily adds a frame to certain elements on the Design tab. These will not Print or output.

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="{"timeout":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

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.

Note: To enable submitting arrays, you need to check the Use PHP arrays or Use enhanced PHP arrays option in the HTTP Server user preferences in Workflow; see Workflow Online Help.

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

Tip: 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.)