Skip to content

sc-ace-text

This document is a user guide for the sc-ace-text component release version 7.1.26

go-to-typical-definition

sc-ace-text-field-Example-1-Image-1

 

1 Purpose

sc-ace-text places an Ace code editor field on a form. Ace is an embeddable code editor written in JavaScript. It matches the features and performance of native editors such as Sublime, Vim and TextMate. It can be easily embedded in any web page and JavaScript application. Ace is maintained as the primary editor for Cloud9 IDE and is the successor of the Mozilla Skywriter (Bespin) project.

The sc-ace-text definition provides fields for setting the properties of an ace text editor field and is fully described below.

 

2 Definition

sc-ace-text 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-ace-text The component name.

Example:
"componentName": "sc-ace-text"

2.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case Defines the name of the ace text editor field in the document and database.

Example:
"name": "typicalDefnScAceText"

2.3 Optional Customizable Fields

Field Valid Values Description
aceTextOptions Set of name/value fields A set of name/value pairs, each defining an ace text editor field property.
Section 2.4 aceTextOptions Field lists and describes each of these name/value pair fields.
defaultValue Any text The value to initially load in the ace text editor field.

Example:
"defaultValue": "this is a comment\nnext line\nnext line\n\nfunction test(){}"
Defaults to no value is initially loaded in the ace text editor field.
disableSave true Changing the ace text editor field value (i.e. entering or editing a value) does not trigger the Save icon to flash.
Exiting the form without saving changes to the ace text editor field value does not trigger a warning message to display.
In the Angular version of the sc-ace-text component, clicking the Save icon will not save the ace text editor field value to the document.
In the AngularJS version of the sc-ace-text component, clicking the Save icon will save the ace text editor field value to the document.

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

Example:
"enabled": false
true Default value.
The ace text editor field is not greyed out.
A Stop icon does not appear on mouseover.
A value can be entered in the ace text editor field.
fontSize Any numeric pixel value The ace text editor field text font size on the form.

Example:
"fontSize": "22px"
18px Default value.
fullWidth true The ace text editor field displays full width on the form.
Recommend displaying the ace text editor field in full width.

Example:
"fullWidth": true
false Default value.
The ace text editor field does not display full width on the form.
label Any value Defines the name of the ace text editor field on the form i.e. the field label.

Example:
"label": "Typical Defn sc-ace-text"
Defaults to no field label is displayed.
liveUpdates false As changes occur to the ace text editor field value, they are not automatically saved to the document.

Example:
"liveUpdates": false
true Default value.
As changes occur to the ace text editor field value, they are automatically saved to the document.
mandatory true The ace text editor field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a ace text editor field value, a pop-up message displays prompting the user to enter a value for the ace text editor field.
Removing the ace text editor field value, "This field is required" in red text will display below the ace text editor field

Example:
"mandatory": true
false Default value.
The ace text editor field displays as optional (i.e. label in black text).
Saving without a value, a pop-up message does not display prompting the user to enter a value for the ace text editor field.
Removing a ace text editor field value, "This field is required" in red text will not display below the ace text editor field
scriptEditMode Any supported ace editor Mode Language used for checking if entered text complies with the coding rules.
Refer to GitHub:ace editor mode

Examples:
"scriptEditMode": nools
"scriptEditMode": "markdown"
javascript Default value.
scriptEditTheme Any supported ace editor theme Theme to be applied to ace text editor field.
Refer to GitHub:ace editor theme

Examples:
"scriptEditTheme": "dawn"
"scriptEditTheme": "terminal"
"scriptEditTheme": "iplastic"
"scriptEditTheme": "clouds"
twilight Default value.
showGutter false The ace text editor field does not display line numbers at the left hand side.

Example:
"showGutter": false
true Default value.
The ace text editor field displays line numbers at the left hand side.
textFormat Sets how the entered data is saved to the resulting document.
json The entered value will be treated as a stringified json field and saved in the document as a json text field with delimited quotes and newlines.

Example:
"textFormat": "json"
raw-json The entered value is saved in the document as a json object.

Example:
"textFormat": "raw-json"
text Default value.
The entered value is saved in the document as a text field.
visible false The ace text editor field is not visible on the form.

Example:
"visible": false
true Default value.
The ace text editor field is visible on the form.

2.4 aceTextOptions Field

2.4.1 Optional Customizable Fields

The aceTextOptions field listed in section 2.3 Optional Customizable Fields is a set of name/value pairs, each defining a ace text editor field property. This section lists and describes each of these name value pair fields (currently only one).

Field Valid Values Description
maxLines Integer Defines the maximum number of lines the ace text editor field can display at one time, beyond which scrolling is needed to enter or view any additional lines.
This affects the height of the ace text editor field but does not limit thenumber of lines that can be entered.
As lines are entered, the ace text editor field increases in height up to the defined maximum number, after which scrolling is needed to enter or view any additional lines.

Example:
"maxLines": 30
OR
"maxLines": "30"

Note:
1. The integer value can be defined without or with quotes.
2. Performance may degrade when the ace text editor field is configured to display a very large or an infinite (the default) number of lines. In which case, it may be necessary to set the "maxLines" field to a lesser value.
"Infinity" Default value.

 

3 Typical Definition

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

       {
            "componentName": "sc-ace-text",
            "name": "typicalDefnScAceText",
            "label": "Typical Defn sc-ace-text",
            "fullWidth": true
        }

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.

            "aceTextOptions": {
                "maxLines": "30"
            }
            "defaultValue": "this is a comment\nnext line\nnext line\n\nfunction test(){}",
            "disableSave": true,
            "enabled": false,
            "fontSize": "22px"
            "liveUpdates": false,
            "mandatory": true,
            "scriptEditMode": "nools",
            "scriptEditTheme": "dawn",
            "showGutter": false,
            "textFormat": "raw-json",
            "visible": false,

 

4 Examples

Example 1

sc-ace-text defined with the typically needed fields.

       {
            "componentName": "sc-ace-text",
            "name": "typicalDefnScAceText",
            "label": "Typical Defn sc-ace-text",
            "fullWidth": true
        }


Resulting field on the form:

sc-ace-text-field-Example-1-Image-1

To enter fullscreen, click the fullscreen icon Icon-enter-full-screen in the top right corner of the ace text editor field.


Resulting field on the form before saving the entered value:

sc-ace-text-field-Example-1-Image-2


Resulting field on the form after saving the entered value:

sc-ace-text-field-Example-1-Image-3


Resulting field in the document and database after saving the document:

    "typicalDefnScAceText": "{\"type\": \"vehicle\", \"vehicleType\": \"bus\", \"isElectric\": true, \"seats\": 34}"

 

Example 2

sc-ace-text defined as:

        {
            "componentName": "sc-ace-text",
            "name": "nonTypicalDefnScAceText",
            "label": "Nontypical Defn sc-ace-text",
            "fontSize": "22px",
            "mandatory": true,
            "scriptEditMode": "nools"
            "scriptEditTheme": "dawn",
            "textFormat": "raw-json"
        }


Resulting field on the form:

sc-ace-text-field-Example-2-Image-1