Skip to content

sc-timer

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

go-to-typical-definition

sc-timer-Example-2-Image-1

sc-timer-Example-1-Image-1


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 sc-timer-start-button
  • To stop a running timer, the user would click the timer field's "Stop Timer" button sc-timer-stop-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

Field Valid Values Description
componentName sc-timer The component name.
Example:
"componentName": "sc-timer"

2.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case. Defines the name of the sc-timer field in the document and database.

Example:
"name": "typicalDefnScTimer"

2.3 Optional Customizable Fields

Field Valid Values Description
disableSave true Setting the sc-timer field value (i.e. by running the timer) does not trigger the Save icon to flash.
Exiting the form without saving changes to the sc-timer field value does not trigger a warning message to display.
In the Angular version of the sc-timer component, clicking the Save icon will not save the sc-timer field value to the document.
In the AngularJS version of the sc-timer component, clicking the Save icon will save the sc-timer field value to the document.

Example:
"disableSave": true
false Default value.
Setting the sc-timer field value (i.e. by running the timer) does trigger the Save icon to flash.
Exiting the form without saving changes to the sc-timer field value does trigger a warning message to display.
In both the Angular and AngularJS versions of the sc-timer component, clicking the Save icon will save the sc-timer field value to the document.
enabled false The sc-timer field on the form is greyed out.
A Stop icon appears on mouseover of the sc-timer field.
The sc-timer field cannot be started.

Example:
"enabled": false
true Default value.
The sc-timer field on the form is not greyed out.
A Stop icon does not appear on mouseover of the sc-timer field.
The sc-timer field value can be started and stopped.
fullWidth true The sc-timer field displays full width on the form.

*Example:
"fullWidth": true
false Default value.
The sc-timer field does not display full width on the form.
label Any value Defines the name of the sc-timer field on the form i.e. the field label.
Note:
  1. Unlike other components, the sc-timer field label does not display on the form, instead text indicating the status of the timer is displayed e.g. "Timer is not running", "1400ms remaining" .
  2. Like other components, the sc-timer field label is used in the warning message indicating that a mandatory sc-timer field has no value i.e. timer has not run.

Example:
"label": "Typical Defn sc-timer"
Default behaviour:
  1. sc-timer field displays on the form with text indicating the status of the timer e.g. "Timer is not running", "1400ms remaining" .
  2. the sc-timer field's name is used in the warning message indicating that a mandatory sc-timer field has no value i.e. timer has not run.
mandatory true The sc-timer field displays as mandatory (i.e. red text with an asterisk indicating the status of the timer e.g. "Timer is not running", "1400ms remaining" ).
Saving without running the sc-timer field, a message prompts the user to run the sc-timer field.
Example:
"mandatory": true
false Default value.
The sc-timer field displays as optional (i.e. black text without an asterisk indicating the status of the timer e.g. "Timer is not running", "1400ms remaining" ).
Saving without running the sc-timer field, a message does not prompt the user to run the sc-timer field.
timerAutoStart true The sc-timer field will automatically start when initialised i.e. on load of the form.

Example:
"timerAutoStart": true
false Default value.
The sc-timer field will not automatically start when initialised i.e. on load of the form.
To start the timer, the user must click the sc-timer field "Start Timer" button.
timerDirection up The timer counts up from 0 to the number of seconds defined by the timerValue field's value.

Example:
"timeDirection": "up"
down Default value.
The timer counts down to 0 from the number of seconds defined by the timerValue field's value.
timerRepeat true If "timerDirection": "up", then on counting up to the number of seconds defined by the timerValue field's value, the sc-timer field will reset and repeat the count.
If "timerDirection": "down", then on counting down to 0 from the number of seconds defined by the timerValue field's value, the sc-timer field will reset and repeat the count.

Example:
"timeRepeat": true

Note:
  1. If "disableSave": false, then the number of counts completed is written to sc-timer name field.
  2. If "disableSave": true, then the number of counts completed is not written to sc-timer name field.
false Default value.
If "timerDirection": "up", then on counting up to the number of seconds defined by the timerValue field's value, the sc-timer field stops i.e. does not reset and repeat the count.
If "timerDirection": "down", then on counting down to 0 from the number of seconds defined by the timerValue field's value, the sc-timer field stops i.e. does not reset and repeat the count.

Note:
  1. If "disableSave": false and the non-repeating sc-timer counts down to zero or counts up to the number of seconds defined by the timerValue field's value or is stopped before completing the count, the finishing time is written to the document's sc-timer name field.
  2. If "disableSave": true and the non-repeating sc-timer counts down to zero or counts up to the number of seconds defined by the timerValue field's value or is stopped before completing the count, the finishing time is not written to sc-timer name field.
timerValue Numeric An integer or decimal number indicating the number of seconds to run the the timer for.

Example:
"timerValue": 5
0 Default value.
The timer field runs for 0 seconds i.e. does not run.
visible false The sc-timer field is not visible on the form.

Example:
"visible": false
true Default value.
The sc-timer field is visible on the form.


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.

sc-timer-Example-1-Image-1

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:

sc-timer-Example-2-Image-1-and-3

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.

sc-timer-Example-1-Image-1

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

sc-timer-Example-2-Image-1-and-3

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