Skip to content

sc-numeric

sc-numeric-field-Example-2-Image-2

1 Purpose

This document is a user guide for the sc-numeric component as of version 5.12.

sc-numeric places a numeric field on a form, allowing the the user to enter a numeric value. The user can enter a numeric value or use the displayed arrows to increment or decrement the current value.

The sc-numeric definition provides fields for setting the properties of the numeric field and is fully described below. These properties include the display format, minimum and maximum values and the step size of the arrows.

Formatting is applied when a document is loaded. Then on giving a numeric field focus, all formatting is cleared to allow entry or editing and is reapplied when focus is lost or the document saved. The format only applies to the display state of the entered value, whereas it is the entered value that is saved.

If a min and/or max value is defined, an empty numeric field will display a hint of the values allowed. If these values are exceeded then a warning message is displayed.

 

2 Definition

sc-numeric 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-numeric   The component name.
Example: "componentName": "sc-numeric"

2.2 Required Customizable Fields

Field  Valid Values Description
name   Any value written in camel case.   Defines the name of the numeric field in the document and database.
Example: "name": "testScNumeric"

2.3 Optional Customizable Fields

Field Valid Values  Description
defaultValue   A numeric The value to initially load in the numeric field.
The value displays in accordance with the definition fields "step", "format", "min" and "max".
Example: "defaultValue": 5
If no default value is defined, the field label is displayed within the field.
disableSave true Entering a value in the numeric field does not trigger the Save icon to flash.
Exiting the form without saving the entered value does not trigger a warning message to display.
Example: "disableSave": true
false Default value. Entering a value in the numeric field triggers the Save icon to flash.
Exiting the form without saving the entered value triggers a warning message to display.
enabled false The numeric field is greyed out.
A Stop icon appears on mouseover.
A value cannot be entered in the numeric field.
Example:"enabled": false
true Default value. A value can be entered in the numeric field.
fullWidth true The numeric field displays full width on the form.
Example: "fullWidth": true
false Default value. The numeric field does not display full width on the form.
format Defines the display format for the numeric field.
Note:
The format is applied to the display state of the entered value, whereas it is the entered value that is saved.
Formatting is applied when a document is loaded.
When a numeric field is given focus, all formatting is cleared to allow entry or editing and is reapplied when focus is lost or the document is saved.
0 Display with no commas, no decimal places, rounded to the nearest integer.
Example: "format": "0"
1000.53 displays as 1001, saves as 1000.53
1000.49 displays as 1000, saves as 1000.49
-1000.53 displays as -1001, saves as -1000.53
+0 Display positive numbers prefixed with a "+" sign, no commas, no decimal places, rounded.
Example: "format": "+0"
1000.53 displays as +1001, saves as 1000.53
(0.0) Display negatives numbers within brackets, no commas, 1 decimal place, rounded.
Example: "format": "(0.0)"
-1000.53 displays as (1000.5), saves as -1000.53
0.0000 Display with no commas, 4 decimal places, rounded.
Example: "format": "0.0000"
1000 displays as 1000.0000 saves as 1000.0000
1000.53 displays as 1000.5300, saves as 1000.53
1000.53124 displays as 1000.5312, saves as 1000.53124
1000.53125 displays as 1000.5313, saves as 1000.53125
0[.]000 Display integers with no decimal places, decimals with 3 decimal places, rounded.
Example: "format": "0[.]000"
1000 displays as 1000, saves as 1000
1000.53 displays as 1000.530, saves as 1000.53
1000.53124 displays as 1000.531, saves as 1000.53124
.00 Display only the decimal component, 2 decimal places, rounded.
Example:: "format": ".00"
-1000.531 displays as -.53, saves as -1000.531
0.0[000] Display at least 1 decimal place, optionally 4 decimal places, rounded.
Example:: "format": "0.0[000]"
-1000.531 displays as -1000.531, saves as -1000.531
1000 displays as 1000.0, saves as 1000
0,0 Display with commas, no decimal places, rounded.
Example: "format": "0,0"
1000.53 displays as 1,001, saves as 1000.53
0.0a Display as an order of magnitude using symbols k, m, b and t , 1 decimal place, rounded.
Where k, m, b, and t indicate size in thousands, millions, billions and trillions respectively.
Example: "format": "0.0a"
1264 displays as 1.3k, saves as 1264
1964 displays as 2.0k, saves as 1964
196400 displays as 196.4k, saves as 196400
+19640000 displays as +19.6m, saves as 19640000
0.00 a Display as an order of magnitude with a space separator, 2 decimal places, rounded.
Example: "format": "0.00 a"
1964300000 displays as 1.96 b, saves as 1964300000
-1968300000000 displays as -1.97 t, saves as -1968300000000
0o Display as an ordinal number with no spaces separator, 0 decimal places, rounded.
Example: "format": "0o"
1 displays as 1st, saves as 1
2 displays as 2nd, saves as 2
3 displays as 3rd, saves as 3
4 displays as 4th, saves as 4
101 displays as 101st, saves as 101
-1968300000000 displays as -1968300000000th, saves as -1968300000000
$0,0.00 Display as currency, prefix with $, display commas, 2 decimal places, rounded.
Example: "format": "$0,0.00"
1000.536 displays as -$1000.54, saves as 1000.536
-1968300000000 displays as -$1,968,300,000,000.00, saves as -1968300000000
0.000% Display as a percentage, 3 decimal places, rounded.
Example: "format": "0.000%"
1 displays as 100.000%, saves as 1
0.973878234 displays as 97.388%, saves as 0.973878234
00:00:00 Display a number of seconds as a time in hours, minutes and seconds, rounded.
Example:: "format": "00:00:00"
25 displays as 0:00:25, saves as 25
238 displays as 0:03:58, saves as 358
63846 displays as 17:44:06, saves as 63846
0,0e+0 Display in exponential notation, with commas, 0 decimal places, rounded.
Example:: "format": "0,0e+0"
1123456789 displays as 1e+9, saves as 1123456789
0.00e+0 Display in exponential notation, without commas, 2 decimal places, rounded.
Example: "format": "0.00e+0"
12398734.202 displays as 1.24e+7, saves as 12398734.202
0.000e+0 Display in exponential notation, without commas, 3 decimal places, rounded.
Example: "format": "0.000e+0"
0.000123987 displays as 1.240e-4, saves as 0.000123987
Defaults to display the value as saved in the database.
label Any value Defines the name of the numeric field on the form i.e. the field label.
Example: "label": "Test sc-numeric"
If the 'defaultValue' field below is not defined, then the field label is also displayed within the field.
"name" field value Defaults to the value defined for the 'name' field, with the first letter displayed in upper case and any upper case letters displayed in lower case prefixed with an underscore.
Example: "Test_sc_numeric" is the default value if the "name" field value was "testScNumeric".
mandatory true The numeric field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value, a message prompts the user to enter a value for the numeric field.
Example: mandatory": true
false Default value. The numeric field displays as optional (i.e. label in black text).
max A numeric The maximum value allowed.
If this value is exceeded, a warning message is displayed.
Example: "max": 100
Default is no maximum value.
min A numeric The minimum value allowed.
If this value is exceeded, a warning message is displayed.
Example:"min": -100
Default is no minimum value.
step A numeric The step size of the up/down arrow.
Example: "step": 2
1 Defaults to 1
visible false The numeric field is not visible on the form.
Example: "visible": false
true Default value. The numeric field is visible on the form.

 

3 Typical sc-numeric Definition

Below is a typical sc-numeric definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-numeric",
    "label": "Test sc-numeric",
    "name": "testScNumeric"
 }

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.

    "mandatory": true,
    "defaultValue": 0,
    "format":"$0,0.00",
    "max":100,
    "min":10,
    "step":5,
    "disableSave":true,
    "enabled":false,
    "visible":false

 

4 Examples

Example 1

sc-numeric defined with the typically needed fields.

{
    "componentName": "sc-numeric",
    "label": "Test sc-numeric",
    "name": "testScNumeric"
}

Resulting field on the form:

sc-numeric-field-Example-1-Image-1

Resulting field on the form with the 23.53647 entered:

sc-numeric-field-Example-1-Image-2

Resulting field in document and database on saving the entered value:

"testScNumeric": 23.53647

Example 2

sc-numeric defined with the typically needed fields plus two optional fields "format" and "mandatory".

 

{
    "componentName": "sc-numeric",
    "label": "Test sc-numeric",
    "name": "testScNumeric",
    "format": "$0,0.00",
    "mandatory": true
 }

Resulting field on the form:

sc-numeric-field-Example-2-Image-1

![alt text] [3]

Resulting field on the form with the value 1234.5683 entered and the field given focus:

sc-numeric-field-Example-2-Image-2

Resulting field on the form with the value 1234.5683 entered and the field not given focus:

sc-numeric-field-Example-2-Image-3

Resulting field in document and database on saving the entered value:

"testScNumeric": 1234.5683