COTG Elements

With the Designer you can create Capture OnTheGo templates. COTG templates are used to generate forms for the Capture OnTheGo mobile application. This topic is about Capture OnTheGo form elements. For more information about the application refer to these websites: Capture OnTheGo and Capture OnTheGo in the Resource Center.

Capture OnTheGo (COTG) elements can only be added within a Form element in a Web context; see COTG Forms. For information about how to add and use COTG Elements, see Using COTG Elements.

It is also possible to add COTG Elements dynamically, to set defaults for COTG elements and to react to custom events that occur when a user interacts with a COTG element. For more information see: Using the COTG plugin and Dynamically adding COTG widgets.

Barcode Scanner

The Barcode Scanner element adds a button to trigger the device to scan a barcode. A very large variety of barcode types are supported. Once the barcode has been scanned, the data from the barcode will be added to the COTG Form and submitted along with it.

Note: Using the Barcode Scanner element requires the installation of the ZXing Barcode Scanner application on Android devices. The application returns the barcode data after scanning.

Camera

The Camera element adds a group of buttons to capture or select an image. Once the image is selected via the camera or the device's library (aka "gallery"), it is saved within the Form data.

When the form is submitted, the image is sent in a base64-encoded string format. To learn how to add Camera data to a template, see Adding ​​​Camera data to the template.

The Camera element has a number of options, of which most can be set in the Design view. These options are described below.
All options, including options that cannot be set via the Design view, can be set via the Source view or in code; see Changing default settings for widgets.

Buttons

By default, the Camera element adds three buttons to the form:

  • Take now: Opens the device's default Camera application to take a picture using the device's camera. Capture OnTheGo has no impact on the device's applications, so the features available (quality, orientation, filters) are dependent on the device itself. You can, however, set the format, quality and scaling for images that are submitted by the Camera element, as explained below.
  • Library: Opens the device's default library or gallery application to select a single image that is then saved in the form data. The accessible images and navigation depend on the device itself.
  • Clear: Removes any existing image data from the Camera element.

To omit the Take now or Library button, edit the Camera element's properties: right-click the Camera element after adding it to the form, select Camera properties and then use the Source drop-down to select which buttons will be available: Take, Pick from library, or both.

Annotations

Annotations can make a picture much more informative: an arrow, showing in which direction a car was driving; a circle, where the car has been damaged... To allow the user to make annotations, right-click the Camera element after adding it to the form, select Camera properties, and then check Allow annotations.
Clicking (or rather, touching) the image will bring up the annotation dialog. Annotations can be made in a Marker (semi-transparent) or Pencil (solid) style, in different colors and with different widths.
Annotations are submitted in SVG format by a hidden input added to the Camera element. The name of that input is the ID of the Camera element, followed by "-note-data", for example camera1-note-data.

Cropping/editing/deskewing

To allow the user to crop, edit and deskew the image after taking or selecting it, select Camera properties, and then check Edit Image and/or Allow Deskew. Which editing options the user actually gets and how they are presented to the user depends on the operating system of the device. On an Android device for example, the user may be able only to crop the image, while the user of an iOS device may select part of the image and rotate that selection.

Image format

You can set the format, quality and scaling for images that are submitted by the Camera element. Right-click the Camera element after adding it to the form, select Camera properties and edit the Image properties:

  • Format: The image format can be PNG or JPG.
  • Quality: Set the compression in a percentage.
  • Scale Image: Check this option to enable image scaling. Then set the maximum width and height of images before they are sent to the server. Note that only the smallest of these is applied and the size ratio is always maintained.

Time stamp

A time stamp can be added to each picture taken. Right-click the Camera element after adding it to the form, select Camera properties, and then check Add Time Stamp.
The time stamp will be added to the bottom left of the picture, with medium font size, and long date format (for example: 6/15/2009 1:45 PM). These settings can only be changed via the Source tab or in code; see Changing default settings for widgets and the Capture OnTheGo API: Camera.

Note: The Time stamp feature doesn't work in versions of the app prior to 10.6.

How to use the captured or selected image in a template

After a user has submitted the form and the data has been extracted, you may want to display the captured or selected image in a Designer template, for example in a letter or on a web page. To do this:

  1. Load the data mapping configuration (or at least the data model).

  2. Insert a dummy image in the template.

  3. Right-click the dummy image and select Dynamic Image. The Text Script Wizard appears.

  4. Under Field select the field that contains the base64-encoded string. The script puts the given string in the source (src) attribute of the image (<img>).

Instead of using the Text Script Wizard, you could also write a script yourself; see Writing your own scripts.

Date and Formatted Date

The Date element and the Formatted Date element display the current date on the device when the form is first opened. When the element is touched, a date selector appears so the user can modify this date. The Formatted Date element displays dates in a format that depends on the locale of the device on which the user is viewing the form. A Date Element displays dates in the ISO 8601 format: YYYY-MM-DD.

When the form is submitted, the date data is sent as plain text. A Formatted Date element submits the date in two formats: in the format that depends on the device's regional and language settings and in the ISO format mentioned above (using a hidden field). A Date element sends the date in the ISO format only.

Device Info

The Device Info Element adds a field that contains some information about the device (phone or tablet) that is submitting the COTG Form. This includes the device's type (Android or iOS), operating system version, device model and its UUID (Universally Unique Identifier). This information can be useful for both troubleshooting, if errors occur on specific device types for example, as well as for security validation: it is possible to maintain a list of device UUIDs that are allowed access, to prevent unauthorized use even if someone has a user name and password to a repository.

Document ID

The Document ID element retrieves the Document ID of the form currently viewed by the app. You could put the Document ID in a hidden input, so that when the form is submitted, the Document ID is submitted as well. A Document ID can be used on the server side to check (in the Connect database) if the data has already been submitted.

Fields Table

The Fields Table element adds a table with two rows, a Delete button at the end of the first row and an Add button at the end of the second row. Inside the rows you can put whatever elements you need. The user can click (or rather, touch) the Add button to add a row to the table. The new row will contain the same elements as the first row.
The names of all elements in the first row will be extended with __0, while the names of the elements in the second row will be extended with __1, etc. (This means that the submitted data can be grouped; see Grouping data using arrays.)
Nested tables - i.e. Fields Tables used within a Fields Table - are supported as of version 2021.1. They follow the same naming pattern, for example: level1[row_0][level2][row_1][name].

Geolocation

The Geolocation Element adds a button to read the device's current GPS coordinates and save them in a form field. When the button is pressed, the GPS coordinates are requested and saved. When the form is submitted, the Geolocation data is sent in plain text.

High accuracy

By default, devices attempt to retrieve a position using network-based methods. To tell the framework to use more accurate methods, such as satellite positioning, the High Accuracy setting has to be enabled on the Geolocation element.
To make this setting, right-click the Geolocation element (or select it on the Outline pane) after adding it to the form, select Geolocation properties and check the High Accuracy option.

Note: The Geolocation element has several options, of which only one can be set via the user interface. All options, including those that cannot be set in Design view, can be set via the data-params attribute in the HTML, or in code; see Changing default settings for widgets.

Image & Annotation

The Image & Annotation element is meant to be used with an image that needs input from the user. When inserting an Image & Annotation element you have to select the image. The user can simply click (or rather, touch) the image to bring up the annotation dialog. Annotations can be made in a Marker (semi-transparent) or Pencil (solid) style, in different colors and with different widths.
Annotations are submitted in SVG format by a hidden input. The name of that input is the ID of the Image & Annotation element, followed by "-note-data", for example image_annotation1-note-data.

Locale

The Locale Element does not have a UI element in the form. Inserting it adds a hidden input field that will contain the device's set locale when the form is submitted. This data is sent in plain text format and is available when processing the form data. The format is defined by the device.

Repository ID

The Repository ID element retrieves the repository ID (read only) from the app based on the currently logged on COTG user. You could put the Repository ID in a hidden input, so that when the form is submitted, the Repository ID is submitted as well. This information can be used on the server side to take specific actions, such as sending properly branded emails.

Signature

The Signature Element adds a signature box to a COTG form. These signatures are filled in via touch input, either with a finger or capacitive pen. Touching the signature box opens up a fullscreen box used to sign (generally more useful in Landscape mode depending on the device); after confirming, the dialog saves the data into the Form.
Signature data is transmitted in SVG plain text format. This type of data can be stored in a data field in a Data Mapping and dragged from the Data Model into a template as is. In Preview mode it will be displayed as an image because the Designer, just like web browsers, knows how to display this kind of data.

Note: The Signature data returned by the COTG app (as of Android 10.6.0, iOS 10.6.0, and Windows 6.0) is formatted so that the signature will automatically be scaled to fit in the containing box in a template. With previous versions of the app, the format of returned signatures could vary.

Time and Formatted Time

The Time element and the Formatted Time element display the current time on the device when the form is first opened. When the element is touched, a time selector appears so the user can modify this time. The Formatted Time element displays times in a format that depends on the locale of the device on which the user is viewing the form. A Time Element displays dates in the ISO 8601 format: HH:MM.

When the form is submitted, the time data is sent as plain text. A Formatted Time element submits the time in both the ISO format mentioned above and in the format that depends on the device's regional and language settings. A Time element sends the time in the ISO format only.

User Account

The User Account Element adds a read only field that contains the Capture OnTheGo user account (an email address) that was used to submit the form to the server. This is useful if a form is available to many different users, to detect who submitted it.
If desired the field can be hidden; it will still be submitted.