sc-phone-number
1 Purpose
This document is a user guide for the sc-party component as of version 5.12.
sc-phone-number places a phone number field on a form, allowing the the user to enter a phone number. If a phone number field has a value, a hyperlink will display below the phone number field, which when clicked will initiate a phone call on devices with call capability (eg. mobile phone).
The sc-phone-number definition provides fields for setting the properties of a phone number field and is fully described below.
2 Definition
sc-phone-number 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-phone-number | The component name. Example: "componentName": "sc-phone-number" |
2.2 Required Customizable Fields
Field | Valid Values | Description |
---|---|---|
name | Any value written in camel case. | Defines the name of the phone number field in the document and database. Example: "name": "testScPhoneNumber" |
2.3 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
defaultValue | Any value | The value to initially load in the phone number field. Example: "defaultValue": "03 1234 5678" |
Defaults to no value is initially loaded. | ||
disableSave | true | Changing the sc-phone-number field value (i.e. entering or editing a phone number) does not trigger the Save icon to flash. Exiting the form without saving changes to the sc-phone-number field value does not trigger a warning message to display. In the Angular version of the sc-phone-number component, clicking the Save icon will not save the sc-phone-number field value to the document. In the AngularJS version of the sc-phone-nuumber component, clicking the Save icon will save the sc-phone-number field value to the document. Example: "disableSave": true |
false | Default value. Changing the sc-phone-number field value (i.e. entering or editing a phone number) does trigger the Save icon to flash. Exiting the form without saving changes to the sc-phone-number field value does trigger a warning message to display. In both the Angular and AngularJS versions of the sc-phone-number component, clicking the Save icon will save the sc-phone-number field value to the document. |
|
enabled | false | The phone number field is greyed out. A Stop icon appears on mouseover. A value cannot be entered in the phone number field. Example: "enabled": false |
true | Default value. A value can be entered in the phone number field. | |
fullWidth | true | The phone number field displays full width on the form. Example: "fullWidth": true |
false | Default value. The phone number field does not display full width on the form. | |
label | Any value | Defines the name of the phone number field on the form i.e. the field label. Example: "label": "Test sc-phone-number" |
Defaults to no field label is displayed. | ||
mandatory | true | The phone number 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 phone number field. Example: "mandatory": true |
false | Default value. The phone number field displays as optional (i.e. label in black text). | |
visible | false | The phone number field is not visible on the form. Example: "visible": false |
true | Default value. The phone number field is visible on the form. |
3 Phone Number Validation
The following checks are applied to verify if a value entered into a phone number field is a valid phone number.
# | Validation Rule | Behaviour |
---|---|---|
1. | A phone number can only contain numerals OR numerals with imbedded spaces AND may have one "+" as the first character. | Entry of invalid characters is prevented. |
2. | A phone number must contain at least one numeral. | Entry of just space(s) or just a "+" character is prevented. |
3. | The first character of a phone number must be a numeral OR the "+" character. | Entry of an invalid first character is prevented. |
4. | A phone number cannot contain 2 consecutive space characters. | Entry of 2 consecutive space characters is prevented. |
5. | A last character of a phone number cannot be a space character. | On save, trailing space characters are removed. |
6. | Phone numbers can have at most 20 characters, with the "+" character and all Spaces included in the count. | Entry of more than 20 characters is prevented. |
4 Typical Definition
Below is a typical sc-phone-number definition, defined with its required fields plus any optional field whose value is typically other than its default value.
{
"componentName": "sc-phone-number",
"name": "testScPhoneNumber",
"label": "Test sc-phone-number"
}
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": "09 9999 9999",
"disableSave":true,
"enabled":false,
"visible":false
5 Examples
Example 1
sc-phone-number defined with the typically needed fields.
{
"componentName": "sc-phone-number",
"name": "testScPhoneNumber",
"label": "Test sc-phone-number"
}
Resulting field on the form:
Resulting field on the form after entered data:
Resulting field in the document and database:
"testScPhoneNumber": "03 1234 5678"
Example 2
sc-phone-number defined with the typically needed fields plus the optional fields "mandatory" and "defaultValue".
{
"componentName": "sc-phone-number",
"label": "Test sc-phone-number",
"name": "testScPhoneNumber",
"mandatory": true,
"defaultValue": "09 9999 9999"
}
Resulting field on the form: