Using the COTG plugin: cotg-2.0.0.js

A Capture OnTheGo (COTG) Form may contain special COTG input elements, like a Signature, Geolocation, or Camera element. These elements do not function without the COTG JavaScript library. It is this library that links the controls with hardware features on the mobile device.

As of Connect 1.8, cotg-2.0.0.js replaces the cotg-1.x.js versions of the library. The new COTG plugin introduces options and custom events for COTG widgets. This greatly simplifies event-based programming in Capture OnTheGo Forms. For example: your code can now automatically set a date for a Date field and retrieve the Geolocation as soon as a form has been signed.
All available options and events are listed in the Capture OnTheGo API: Capture OnTheGo API.

This topic explains in detail how to add the COTG plugin, how to change the defaults for COTG widgets and how to use events.
How to add COTG elements to a Form dynamically is explained in another topic: Dynamically adding COTG widgets.

It is assumed that you have a basic understanding of HTML forms, CSS, JavaScript, and jQuery. Examples on this page use jQuery.

About jQuery

This version of the COTG library is entirely based on jQuery. jQuery is a JavaScript library that makes it very easy to select elements in a web page using HTML and CSS selectors, and to manipulate those elements. You will need to use jQuery to dynamically add widgets to a COTG Form. If you are new to it, spend a few minutes on learning it - it's that easy. For more information, see: https://jquery.com/. and http://learn.jquery.com/.

Adding the plugin

When you create a template with a COTG Template Wizard (see Capture OnTheGo template wizards), the Designer automatically adds the jQuery library and the COTG library: cotg-2.0.0.js.
This also happens when you add a Capture OnTheGo (COTG) element to a template that you didn't start with a COTG template wizard.

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

When this library is included in a Web template instead of a COTG template, it won't affect the template, except when the user submits a Form. At that moment the plugin will automatically add a hidden field for every unchecked checkbox on the Form.

Changing default settings for widgets

The Camera and Geolocation widgets have options that you can configure per element. You can decide, for example, which buttons will be visible in a specific Camera element (see Element specific settings).
The default settings for these options are specified in the COTG plugin. It is possible to change these defaults without modifying the plugin itself.
To do that, create a JavaScript file (see Adding JavaScript files to the Resources) and specify the desired default settings in that file like this:

$.fn.widget.defaults.setting = value;

Make sure to include your JavaScript file in the Web context or in the Web section that contains the COTG Form (see Including a JavaScript file in a Web context).
All available settings are listed in the Capture OnTheGo API: Capture OnTheGo API.

Example

The following code sets the default timeout and accuracy for Geolocation objects. and the default maximum height and width for Camera widgets.

$.fn.cotgGeolocation.defaults.timeout = 6000; // 6 secs
$.fn.cotgGeolocation.defaults.enableHighAccuracy = true;
$.fn.cotgPhotoWidget.defaults.width = 1024;
$.fn.cotgPhotoWidget.defaults.height = 768;
$.fn.cotgPhotoWidget.defaults.quality = 60;

Reacting to, or triggering, widget events

The new COTG plugin introduces custom events for COTG controls. You can trigger and/or react to them as the user interacts with the Form.

• Use jQuery’s .on() method to attach an event handler to an element (or set of elements). Call this function on the $(document).ready event, which is triggered when the Form is loaded in the app.
• Use the .trigger() method to trigger an element's event.

The events of all COTG widgets are listed in the Capture OnTheGo API: Capture OnTheGo API.

Examples

The sample below attaches an event handler to the "set" event of a Signature element. Once the signature is set (that is, after the user has clicked the Done button), the event handler triggers events of the Date and Geolocation elements. The Date element is set with today's date and the Geolocation element is updated with the current location.

$(document).ready(function() {

	$('#signature').on("set.cotg", function() {

		$("#date").trigger("set.cotg", new Date()); // set current date

		$("#geolocation").trigger("update.cotg"); // get current geolocation

	});

});

The following example invokes the Date dialog when the user clicks a button.

$(document).ready(function() {

	$('#my-datepicker-button').on('click', function() {

		$('#date1').trigger("show-date-picker.cotg", new Date("2018-01-01"));

	});

});