Skip to content

sc-ace-text

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

1 Purpose

This document is a user guide for the sc-ace-text component as of version 4.08.

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 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 editor field in the document and database.
Example: "name": "testScAceText"

2.3 Optional Customizable Fields

Field Valid Values Description
defaultValue Any text The value to initially load in the ace editor field.
Example: "defaultValue": ""**this is a comment\nnext line\nnext line**\n\nfunction test(){}""
Default value. The ace editor field displays no value.
disableSave true Editing the ace editor field does not trigger the Save icon to flash.
Exiting the form without saving the edited ace editor field does not trigger a warning message to display.
Example: "disableSave": true
false Default value. Editing the ace editor field does trigger the Save icon to flash.
Exiting the form without saving the edited ace editor field does trigger a warning message to display.
enabled false The ace editor field is greyed out..
A Stop icon appears on mouseover.
A value cannot be entered in the ace editor field.
Example: "enabled": false
true Default value. The ace editor field's value can be edited.
fontSize Any numeric pixel value Temporary test setting. The ace editor field text font size on the form.
Example: "fontSize": "16px"
Default value. The ace editor field's font size is set to 18px.
fullWidth true The ace editor field displays full width on the form.
Recommend displaying the ace editor field in full width.
Example: "fullWidth": true
false Default value. The ace editor field does not display full width on the form.
label Any value Defines the name of the ace text field on the form i.e. the field label.
Example: "label": "Test sc-ace-text"
Defaults to no field label is displayed.
liveUpdates true As changes occur to the ace text field value, they are automatically saved to the document.
Example: "liveUpdates": true
false Default value.
mandatory true The ace editor field displays as mandatory (i.e. label in red text with an asterisk) and the text 'This field is mandatory' displays below the ace editor field.
Example: "fullWidth": true
Saving without a value, a message prompts the user to enter a value for the field.
Example: "mandatory": true
false Default value. The ace editor 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 field.
scriptEditMode Any supported ace editor Mode Temporary test setting. Language used for checking if entered text complies with the coding rules.Refer to GitHub:ace editor mode
Example: "scriptEditMode": nools
Default value. The ace editor field's mode is set to javascript.
scriptEditTheme Any supported ace editor theme Temporary test setting. Theme to be applied to ace-editor field. Refer to GitHub:ace editor theme
Example: "scriptEditTheme": terminal
Default value. The ace editor field's Theme is set to twighlight.
showGutter false Temporary test setting. The ace editor field does not display line numbers at the left hand side.
Example: "showGutter": false
true Default value. The ace 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"
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.
Example: "textFormat": "text"
visible false The sc-ace-text field is not visible on the form.
Example: "visible": false
true Default value. The ace editor field is visible on the form.

 

3 Typical sc-ace-text 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": "testScAceText",
            "label": "Test sc-ace-text",
            "scriptEditTheme": "dawn",
            "scriptEditMode": "nools",
            "textFormat": "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.

            "fontSize": "16px"
            "defaultValue": "alert('Write something here...');",
            "disableSave": true,
            "enabled": false,
            "liveUpdates": true,
            "mandatory": true,
            "showGutter": false,
            "visible": false,

 

3 Examples

Example 1

sc-ace-text defined with the typically needed fields and having "textFormat": "text".

 

        {
            "componentName": "sc-ace-text",
            "name": "testScAceTextWithTextFormatText1",
            "scriptEditTheme": "dawn",
            "scriptEditMode": "nools",
            "textFormat": "text",
            "fullWidth": true,
            "label": "Test sc-ace-text with textFormat Text",
            "fontSize": 18
        }

Resulting field on the form:

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

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:

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

 

Example 2

sc-ace-text defined with the typically needed fields and having "textFormat": "raw-json".

        {
            "componentName": "sc-ace-text",
            "name": "testScAceTextWithTextFormatRawJson1",
            "scriptEditTheme": "dawn",
            "scriptEditMode": "nools",
            "textFormat": "raw-json",
            "fullWidth": true,
            "fontSize": 18,
            "label": "Test sc-ace-text with textFormat raw-json"
        }

Resulting field on the form:

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

Resulting field on the form before saving the entered value:

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

Resulting field on the form after saving the entered value:

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

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

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

 

Example 3

sc-ace-text defined with the typically needed fields and having "textFormat": "json".

 

        {
            "componentName": "sc-ace-text",
            "name": "testScAceTextWithTextFormatJson1",
            "scriptEditTheme": "dawn",
            "scriptEditMode": "nools",
            "textFormat": "json",
            "fullWidth": true,
            "fontSize": 18,
            "label": "Test sc-ace-text with textFormat json"
        }

Resulting field on the form:

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

Resulting field on the form before saving the entered value:

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

Resulting field on the form after saving the entered value:

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

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

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