sc-timer

This document is a user guide for the sc-timer component version 6.5.92.

1 Purpose

sc-timer places a read only timer field on a form. Typically, it is defined to automatically start running on load of the form, thereafter triggering regular updates (e.g. every 30 seconds) of the form's data and display. E.g. to trigger regular updates of a map or datatable field on the form, the sc-timer field's name would be included in their "updateWatchFields" array of values.

When used for this purpose, sc-timer field is typically defined with "visible": false and "disableSave": true so that:

• The sc-timer field is hidden and does not take up any space on the form.
• The sc-timer field's value is not saved in the document or database.

However within this document, to illustrate the behaviour of a hidden sc-timer field, the screenshots are of a visible sc-timer field. When the timer field is visible on a form:

• To start a stopped timer, the user would click the timer field's "Start Timer" button
• To stop a running timer, the user would click the timer field's "Stop Timer" button

sc-timer can be defined to:

• Count up to or down from a specified number of seconds.
• Stop running on counting up from 0 to a specified number of seconds, or down to 0 from a specified number of seconds.
• Reset and repeat the count on reaching a specified number of seconds.
• Either automatically start counting on load of the form or to start counting when the user clicks the timer field's "Start Timer" button.

The sc-timer definition provides fields for setting the properties of a timer field and is fully described below.

2 Definition

sc-timer is defined by a set of name/value pair fields consisting of:

• Required system fields
• Required customizable fields
• Optional customizable fields

Note:

1. Default values for fields described in the tables below are shown in bold text.

2.1 Required System Fields

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

3 Typical Definition

Below is the typical sc-timer definition to place on a form, a hidden timer field that automatically starts running on load of the form, therafter triggering regular updates of the form's data and display. It is defined with its required fields and any optional field whose value is typically other than its default value.

        {
            "componentName": "sc-timer",
            "name": "typicalDefnScTimer",
            "label": "Typical Defn sc-timer",
            "disableSave": true,
            "fullWidth": true,
            "timerAutoStart": true,
            "timerRepeat": true,
            "timerValue": 5,
            "visible": false
        }

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

            "timerDirection": "up",
            "enabled": false,
            "mandatory": true  

To trigger regular updates of a map or datatable field on the form, the sc-timer field's name would be included in their "updateWatchFields" array of values.

            "updateWatchFields": [
                "document.typicalDefnScTimer"
            ]

4 Examples

Example 1

A typical sc-timer definition to place on a form, a timer field that starts running on load of the form, thereafter triggering updates every 5 seconds of a map field on the form.

        {
            "componentName": "sc-timer",
            "name": "typicalDefnScTimer",
            "label": "Typical Defn sc-timer",
            "disableSave": true,
            "fullWidth": true,
            "timerAutoStart": true,
            "timerRepeat": true,
            "timerValue": 5
        }

The map field would be defined with:

            "updateWatchFields": [
                "document.typicalDefnScTimer"
            ]

Resulting field on the form:

On load of the form, the sc-timer field automatically starts counting down from 5 seconds to 0. Upon reaching 0, the map will be updated, the sc-timer field will automatically reset and commence another countdown from 5 seconds to 0. While counting down to 0, a visible sc-timer field displays the time remaining to 0 seconds, updating at 10 times a second i.e.

5000ms -> 4900ms -> 4800ms -> ... and so on to ... 0ms, upon which, it will reset to 5000ms and commence another countdown to 0.

Note:

1. As explained in Section 1 Purpose, the sc-timer field is typically defined to be hidden on the form. To illustrate its behaviour, it is defined here to be visible on the form.
2. As sc-timer is defined with "disableSave": true, on clicking the Save button, the sc-timer field's value (i.e the number of countdowns completed) would not be saved to the document or the database.

Example 2

A non-typical use of the sc-timer field defined as:

        {
            "componentName": "sc-timer",
            "name": "nonTypicalDefnScTimer",
            "label": "Nontypical Defn sc-timer",
            "fullWidth": true,
            "timerDirection": "up",
            "timerValue": 5
        }

Resulting field on the form:

Resulting field on the form on clicking the "Start Timer" button:

Clicking the "Start Timer" button will start the timer counting up from 0 to 5 seconds, displaying remaining time to 5 seconds.

On reaching 5 seconds (or on clicking the "Stop Timer" button before reaching 5 seconds), the timer will stop and display:

Resulting field in document and database after saving:

Senario 1:

The sc-timer field had automatically stopped upon completing the count to 5 seconds:

    "nonTypicalDefnScTimer": 5000

Senario 2:

The sc-timer field's Stop button was clicked before completing the count to 5 seconds:

    "nonTypicalDefnScTimer": 3800