sc-numeric
This document is a user guide for the sc-numeric component release version 7.1.25.
1 Purpose
The sc-numeric component places a numeric field on a form, allowing the the user to enter a numeric value. The user can enter either a numeric value directly into the field or use the "Increment/Decrement Numeric Value" button 
to increment or decrement the current numeric value.
The sc-numeric component definition provides fields for setting the properties of the numeric field and is fully described below. These properties include defining a display format, a minimum value, a maximum value and the step size of the "Increment/Decrement Numeric Value" button (only visible when the sc-numeric field has focus).
The display format only applies to the display state of the numeric value, whereas it is the entered numeric value that is saved to the document and database.
If sc-numeric component is defined with a minimum value and/or a maximum value, then an error message will display if either value is exceeded.
2 Definition
The sc-numeric component is defined by a set of name/value pair fields consisting of:
- Required system fields
- Required customizable fields
- Optional customizable fields
Note:
- 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": "scNumericTypicalDefn" |
2.3 Optional Customizable Fields
| Field | Valid Values | Description |
|---|---|---|
| afterStr | string value | Defines a string value to display in the right-hand end of the sc-numeric field.Example: In the right-hand end of the sc-numeric field, display kg as the unit of measure."afterStr": "kg"Note:
|
Defaults to no string value is displayed in the right-hand end of the sc-numeric field. |
||
| beforeStr | string value | Defines a string value to display in the left-hand end of the sc-numeric field.Example: "beforeStr": "Weight:"Note: The string value is for display purposes only i.e. only the entered numeric value is saved to the document and the database. |
Defaults to no string value is displayed in the right-hand end of the sc-numeric field. |
||
| defaultValue | numeric value (defined as a string) | The value to initially load in the numeric field. Note: The defaultValue field value:
Example: "defaultValue": "5" |
Defaults to no value is initially loaded into the sc-numeric field. |
||
| disableSave | true | Changing the sc-numeric field value (i.e. entering or editing a numeric value) does not trigger the Save icon to flash.Exiting the form without saving changes to the sc-numeric field value does not trigger a warning message to display.In the Angular version of the sc-numeric component, clicking the Save icon will not save the sc-numeric field value to the document.In the AngularJS version of the sc-numeric component, clicking the Save icon will save the sc-numeric field value to the document.Example: "disableSave": true |
| false | Default value. Changing the sc-numeric field value (i.e. entering or editing a numeric value) does trigger the Save icon to flash.Exiting the form without saving changes to the sc-numeric field value does trigger a warning message to display.In both the Angular and AngularJS versions of the sc-numeric component, clicking the Save icon will save the sc-numeric field value to the document. |
|
| enabled | false | The sc-numeric field is greyed out.A Stop icon appears on mouseover. A value cannot be entered in the sc-numeric field.Example: "enabled": false |
| true | Default value. A value can be entered in the sc-numeric field.A Stop icon does not appear on mouseover. A value can be entered in the sc-numeric field. |
|
| format | Defines the display format for the sc-numeric field value.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 sc-numeric field is given focus, all formatting is cleared to allow entry or editing of its value 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 dollar symbol, display commas, 2 decimal places, rounded. Example "format": "$0,0.00"1000.536 would display as $1,000.54, and save as 1000.536 |
|
| 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. | ||
| fullWidth | true | The sc-numeric field displays full width on the form.Example: "fullWidth": true |
| false | Default value. The sc-numeric field does not display full width on the form. |
|
| integerValueOnly | true | Only allow integer numeric values i.e. non-integer numeric values are not allowed Example: "integerValueOnly": trueNote: If a non-integer numeric value is entered, a warning message displays "Only integers can be saved" and the sc-numeric field is cleared. |
| false | Default value. Integer and non-integer numeric values are allowed. |
|
| label | Any value | Defines the name of the sc-numeric field on the form i.e. the field label.Example: "label": "sc-numeric Typical Defn" |
Defaults to the sc-numeric field displays without a field label on the form. |
||
| mandatory | true | The sc-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 sc-numeric field.Example: "mandatory": true |
| false | Default value. The sc-numeric field displays as optional (i.e. label in black text).Saving without a value, a message does not prompt the user to enter a value for the sc-numeric field |
|
| max | Numeric value | The maximum numeric value allowed. If this value is exceeded, a warning message is displayed. Example: "max": 100 |
| Default is no maximum numeric value. | ||
| min | Numeric value | The minimum numeric value allowed. If this value is exceeded, a warning message is displayed. Example: "min": -100 |
| Default is no minimum numeric value. | ||
| negativeOnly | true | Only allow negative numbers i.e. positive numbers and zero are not allowed. Example: "negativeOnly": trueNote: 1. If a positive number is entered, a warning message displays "Only negative numbers can be saved" and the entered positive number is replaced with its negative equivalent e.g. entering "5" will redisplay as "-5". 2. If zero is entered, a warning message displays "Only negative numbers can be saved" and the sc-numeric field is cleared.3. A leading zero before the decimal point cannot be entered. To enter "-0.05", enter "-.05" which will redisplay as "-0.05". |
| false | Default value. Negative numbers, positive numbers and zero are all allowed. |
|
| noZeroValue | true | Only allow positive and negative numbers i.e. zero is not allowed. Example: "noZeroValue": trueNote: If zero is entered, a warning message displays "You cannot enter zero. If you want a decimal, use . without zero" and the sc-numeric field is cleared. To enter "0.05", enter ".05" which will redisplay as "0.05". To enter "-0.05", enter "-.05" which will redisplay as "-0.05".< |
| false | Default value. Negative numbers, positive numbers and zero are all allowed. |
|
| positiveOnly | true | Only allow positive numbers and zero i.e. negative numbers are not allowed. Example: "positiveOnly": trueNote: If a negative number is entered, a warning message displays "Only positive numbers can be saved" and the entered negative number is replaced with its positive equivalent e.g. entering "-5" will redisplay as "5". |
| false | Default value. Negative numbers, positive numbers and zero are all allowed. |
|
| rightAlign | true | The entered numeric value is displayed right justified in the sc-numeric field.Example: "rightAlign": true |
Defaults to the entered numeric value is displayed left justified in the sc-numeric field. |
||
| step | Numeric value | The step size of the "Increment/Decrement Numeric Value" button . Example: "step": 5 |
| 1 | Defaults to 1 | |
| visible | false | The sc-numeric field is not visible on the form.Example: "visible": false |
| true | Default value. The sc-numeric field is visible on the form. |
3 Typical Definition
Below is a typical sc-numeric component definition, defined with its required fields plus any optional field whose value is typically other than its default value.
{
"componentName": "sc-numeric",
"label": "sc-numeric Typical Defn",
"name": "scNumericTypicalDefn"
}
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.
OPTIONAL CUSTOMIZABLE FIELDS:
"afterStr": "kg",
"beforeStr": "Weight",
"defaultValue": "0",
"disableSave": true,
"enabled": false,
"format": "$0,0.00",
"integerValueOnly": true,
"mandatory": true,
"max": 100,
"min": -100,
"negativeOnly": true,
"noZeroValue": true,
"noZeroValue": true,
"step": 5,
"visible":false,
4 Examples
Example 1
sc-numeric component defined with the typically needed fields.
{
"componentName": "sc-numeric",
"label": "sc-numeric Typical Defn",
"name": "scNumericTypicalDefn"
}
Resulting field on the form:
Clicking the sc-numeric field will give it focus and display its "Increment/Decrement Numeric Value" button
Resulting field on the form when the sc-numeric field has focus:
Resulting field on the form on entering 23.53647 into the sc-numeric field which remains in focus:
Resulting field on the form upon the sc-numeric field losing focus:
Resulting field in document and database on saving the entered value:
"scNumericTypicalDefn": 23.53654
Example 2
sc-numeric component defined with the typically needed fields plus three optional fields "defaultValue", "format" and "mandatory".
{
"componentName": "sc-numeric",
"label": "sc-numeric Non-typical Defn",
"name": "scNumericNontypicalDefn",
"defaultValue": "100",
"format": "$0,0.00",
"mandatory": true
}
Resulting field on the form:
Clicking the sc-numeric field will give it focus and display its "Increment/Decrement Numeric Value" button
Resulting field on the form when the sc-numeric field has focus:
Resulting field on the form after entering 1234.5683 into the sc-numeric field which remains in focus:
Resulting field on the form upon the sc-numeric field losing focus:
Resulting field in document and database on saving the entered value:
"scNumericNontypicalDefn": 1234.5678