Styled Text Editor Component

About the styled text editor component

Allows users to enter and view styled text. Text is stored with HTML formatting.

The styled text editor component and the rich text display component serve different purposes:

• Styled text editor component: Use to capture and display user-entered content.
• Rich text display component: Use to build static design elements in your interface, such as stylized labels or inline icons.

See Choosing which text input to use for guidance on when to use this component versus a paragraph component.

Where to use the styled text editor component

Use a!styledTextEditorField() in the following components:

• a!formLayout(): contents parameter.
• a!headerContentLayout(): contents parameter, or in the header parameter (inside a!cardLayout()).
• a!pane(): contents parameter (inside a!paneLayout()).
• a!wizardStep(): contents parameter (inside a!wizardLayout()).
• a!boxLayout(): contents parameter.
• a!cardLayout(): contents parameter.
• a!columnLayout(): contents parameter (inside a!columnsLayout()).
• a!sectionLayout(): contents parameter.
• a!sideBySideItem(): item parameter (inside a!sideBySideLayout()).
• a!tabItem(): contents parameter (inside a!tabLayout()).
• a!sidebarTemplate(): additionalContents parameter (inside a!formLayout() or a!wizardLayout()).

Parameters

a!styledTextEditorField( label, labelPosition, instructions, helpTooltip, value, saveInto, readOnly, required, requiredMessage, disabled, validations, validationGroup, showWhen, accessibilityText, height, sizeLimit, placeholder, refreshAfter, allowedFormats, marginAbove, marginBelow )

Using the styled text editor component

The following sections cover important details about the styled text editor component.

Supported text formatting

The styled text editor supports the following text formatting:

• Bold text
• Italic text
• Underline text
• Strikethrough text
• Color format: Text and highlight color
• Subscript
• Superscript
• Links
• Text alignment
• Bulleted lists
• Numbered lists
• Tables

The following formatting is also available using keyboard shortcuts only:

• List item indents
  • Increase indent (Ctrl+] or Cmd+])
  • Decrease indent (Ctrl+[ or Cmd+[)
• Undo (Ctrl+Z or Cmd+Z)
• Redo (Ctrl+Shift+Z / Ctrl+Y or Cmd+Shift+Z / Cmd+Y)

Additionally, the styled text editor supports the following Markdown formatting:

To keep the Markdown characters in your text without applying the formatting, after the formatting is applied, select the backspace key. The effect will be removed and the Markdown characters will be visible as plain text. This must be done right after the effect appears. After you move the cursor away from the formatted text, selecting backspace will no longer revert the formatting.

Inputting and formatting text

The styled text editor uses standard HTML to format text. For example, when a user applies underline formatting to text, behind the scenes the styled text editor wraps the value in HTML tags like this: <u>Text</u>.

Because of this, users can copy and paste text from other programs, such as documents and emails, and the supported text formatting will be preserved. Any unsupported formatting will be removed. For example, if someone copies and pastes text with different font sizes, the size formatting will be removed, but any supported formatting, such as bold text or links, will be preserved.

If users copy and paste or manually type HTML tags, the tags will be treated as plain text. When the value is stored, the less-than (<) and greater-than (>) symbols in the HTML tags will be replaced with their character reference—< for < and > for >.

For example, if a user types or pastes <u>Text</u>, it will be saved as <u>Text</u>. However, if a user copies "Text" into a styled text editor, it will be saved as <u>Text</u>.

When the text that the user is inputting reaches 100,000 bytes, the styled text editor will prevent them from entering more text.

Displaying styled text editor values

Displaying the read-only value

When you need to display the styled text editor value in an interface, display it in a styled text editor component with the readOnly parameter set to true. If you try to display it in any other component, it will display with the HTML tags.

The below screenshot shows the difference between displaying the value in rich text display, paragraph, and styled text editor components.

To avoid unexpected formatting loss, make sure the allowedFormats values on the read-only component match the allowedFormats values on the corresponding editable component.

See Displaying read-only styled text editor values for guidance on displaying read-only values so that they are set apart from other formatted text in the interface.

Displaying the value in a grid

By default, displaying the value from a styled text editor component in a grid includes the HTML tags used for formatting.

If you need to display a styled text editor value in a grid, save an alternate value using stripHtml() to a separate field in your database. Use the alternate value for the sortField and value parameters in the grid column.

For considerations about using the value from a styled text editor in a grid, see Choosing which text input to use.

Displaying the value in emails

Because emails sent from Appian use HTML for formatting, you can use the styled text editor value in a Send E-Mail node and it will display with the user's formatting applied to the text.

Using the sizeLimit parameter

The size limit value

The value of the sizeLimit parameter is in bytes, not characters. Most characters are one byte. However, certain characters are more than one byte, including emojis and some characters from non-Latin alphabets. So if you set the sizeLimit parameter to 4,000, you are allowing 4,000 bytes, not necessarily 4,000 characters.

Keep in mind that the HTML tags that are saved with the styled text editor value are included in the size limit. So even if a user enters exactly 4,000 characters, when they add any formatting, they will exceed the size limit.

Matching the size limit to the database field

Make sure the value you set for the sizeLimit parameter matches the length of the field in your data source. For example, most standard Text fields have a 255 character limit.

Size limit validations

When a user approaches the size limit, the styled text editor displays the remaining percentage of text they have left. When they exceed the size limit, it displays the percentage of how far they are over the size limit and a size limit validation message appears below the component.

Using a large size limit or no size limit

Whenever possible, set the sizeLimit parameter to 4,000 or less.

If you need to allow users to enter more text, avoid using the value in a process model. To save the value to a database, write it directly from the interface using a!writeToDataStoreEntity() or a!writeRecords() in the saveInto parameter of a button component.

Using the allowedFormats parameter

By default, users are allowed to use all formats except color format, subscript, superscript, text alignment, and tables.

To enable these formats, add the allowedFormats parameter and enter a list of all the valid values listed in the parameter description.

For example, the following expression displays all supported formatting options:

1
2
3
4
5
6
7
8
9
10
11
{
  a!styledTextEditorField(
    label: "Styled Text Editor",
    labelPosition: "ABOVE",
    saveInto: {},
    sizeLimit: 4000,
    height: "MEDIUM",
    validations: {},
!    allowedFormats: {"BOLD", "ITALIC", "UNDERLINE", "STRIKETHROUGH", "COLOR_FORMAT", "SUBSCRIPT", "SUPERSCRIPT", "LINK", "TEXT_ALIGNMENT", "NUMBERED_LIST", "BULLETED_LIST", "TABLE"}
  )
}

To avoid unexpected formatting loss, make sure the allowedFormats values on the read-only component match the allowedFormats values on the corresponding editable component.

Using the readOnly parameter

When the readOnly parameter is set to true, the component's value displays without a box around it. This is how you display user-entered styled text in an interface.

If you pass the same local variable to value and saveInto when readOnly is set to false, you can use the user's input in the component to modify the interface.

Examples

The following examples demonstrate the styled text editor component.

Use the interactive editor to experiment with examples.

Read-only styled text editor component

See Displaying read-only styled text editor values for guidance on displaying read-only values so that they are set apart from other formatted text in the interface.

Storing styled text editor value in a local variable

Feature compatibility

Feedback