End-User Rich Text Editor Component

Appian Max Team — Fri, 14 Jun 2024 20:07:11 GMT

Current Revision posted to Guide by Appian Max Team on 6/14/2024 8:07:11 PM

Starting in 24.2, the Styled Text Editor Component is available directly in the product. Consider using this component over the plug-in moving forward.

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅		✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

In order to provide table support, we needed to switch to a new underlying library that supports tables. This new library generates HTML that is different from the previous library. To prevent refactoring and unintended behavior for those using the plugin currently, we opted to keep the existing component as is If you want to migrate to the new component, refer to the How to migrate to fn!richTextFieldWithTables section below.

Also, the new component, fn!richTextFieldWithTables(), strictly uses standard HTML attributes for all formats, which should simplify complexities with passing the output HTML to downstream systems, such as email or document generation.

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

For the use case of searching or sorting against the rich text data, it is recommended to separately create a column in your CDT to store the raw text. The raw text column should be the same type and size of the HTML column. Whenever searching or sorting against the rich text data, search or sort against this column, not the HTML column.

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

To create database triggers to update this field on every INSERT or UPDATE to the database table, follow the instructions below for accomplishing this in MariaDB. For other databases, use the same design, just adjust to match your database’s syntax.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

When sending emails with the Send Email node, the HTML output is loaded and cached in the process execution engine as a string. Over time, the cached values accumulate in memory and can lead to memory resource issues.

It is recommended to perform non functional testing by sending representative emails at the expected email volume for at least 3 days to measure and evaluate the impacts on the system memory usage and ensure a scalable application in production.

To configure in process, in the Send Email node, either pass the HTML output as an expression to the ad-hoc message body, or pass the HTML output as an input parameter to the HTML template message body.

Allowed Formats

Only applicable for fn!richtextfield. This parameter to the function fn!richTextField() allows the designer to configure which formatting options are available to the end users when entering rich text into the field such as “bold”, “italic”, “list”, etc.

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Allowed format options should never be removed after users have already entered data in this field in a production setting (outside of special circumstances), since this means previously-entered text would not be backwards compatible with the updated component configuration. For example, if a user had formatted using a numbered list, and “list” was removed as an allowed format, then all numbered lists that were previously saved would render incorrectly in the updated component configuration.

If you do need to remove some allowed formats after users have already entered text in a production setting, it is recommended to pass the previously allowed formats to the component whenever it is rendered as read-only. For example, picture a comment thread that supported “list” for a while, then removed “list” format. The read-only fields, displaying previously-entered comments, could still support “list” while the editable field for new comments would no longer support “list”. However, this gets more complicated when editing of previously-entered data is considered (e.g. editing an existing comment).

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Note: only the URL to the uploaded image, not the image content itself, is stored in the generated HTML from fn!richTextField(). This means that if you use the generated HTML outside of Appian (e.g., in an email), the image will not display unless the outside viewer is already logged into Appian.

Migrate Components

If you have not yet used either component, you can use whichever one suits your needs best. However, be mindful that it is non-trivial to migrate between fn!richTextField and fn!richTextFieldWithTables and the latter will likely receive more enhancements over time, as the underlying library which renders it is kept up-to-date more.

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

If you'd like to migrate end-user formatting text to fn!richTextFieldWithTables, you can write an expression which updates the non-standard indentation attributes and div tags to be recognized by the new component. However this may be more involved for nested lists which will require a more complicated update than just find and replace.

Tags: Architecture, plugins

End-User Rich Text Editor Component

Appian Max Team — Tue, 23 Apr 2024 13:20:46 GMT

Revision 10 posted to Guide by Appian Max Team on 4/23/2024 1:20:46 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅		✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Migrate Components

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

Tags: Architecture, plugins

End-User Rich Text Editor Component

joel.larin — Tue, 19 Dec 2023 16:53:18 GMT

Revision 9 posted to Guide by joel.larin on 12/19/2023 4:53:18 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅		✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Migrate Components

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

Tags: Architecture, plugins

End-User Rich Text Editor Component

Kim Day — Tue, 31 Oct 2023 17:32:44 GMT

Revision 8 posted to Guide by Kim Day on 10/31/2023 5:32:44 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Migrate Components

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

Tags: Architecture, plugins

End-User Rich Text Editor Component

joel.larin — Thu, 26 Oct 2023 18:59:07 GMT

Revision 7 posted to Guide by joel.larin on 10/26/2023 6:59:07 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Migrate Components

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

End-User Rich Text Editor Component

joel.larin — Thu, 26 Oct 2023 18:57:50 GMT

Revision 6 posted to Guide by joel.larin on 10/26/2023 6:57:50 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Migrate Components

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

End-User Rich Text Editor Component

joel.larin — Thu, 26 Oct 2023 18:57:20 GMT

Revision 5 posted to Guide by joel.larin on 10/26/2023 6:57:20 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

Migrate Components

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

End-User Rich Text Editor Component

joel.larin — Thu, 26 Oct 2023 18:55:27 GMT

Revision 4 posted to Guide by joel.larin on 10/26/2023 6:55:27 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads

Only applicable for fn!richTextField. To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

How to migrate to fn!richTextFieldWithTables

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

End-User Rich Text Editor Component

joel.larin — Thu, 26 Oct 2023 18:52:15 GMT

Revision 3 posted to Guide by joel.larin on 10/26/2023 6:52:15 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

Plugin Components

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats (Only applicable for fn!richTextField)

This parameter to the function fn!richTextField() allows the designer to configure which formatting options are available to the end users when entering rich text into the field such as “bold”, “italic”, “list”, etc.

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads (Only applicable for fn!richTextField)

To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

How to migrate to fn!richTextFieldWithTables

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

End-User Rich Text Editor Component

joel.larin — Thu, 26 Oct 2023 18:50:53 GMT

Revision 2 posted to Guide by joel.larin on 10/26/2023 6:50:53 PM

This component is not part of the Appian base product. It is a component plugin managed by Appian Professional Services and it can be downloaded on the Appian AppMarket.

Please see the Component Plug-in Troubleshooting Guide if you have any issues. If you have further questions please email richtext-componentpluginsupport@appian.com.

What components does this plugin include?

As of version 1.5.3, this plugin includes two (2) components:

fn!richTextField() - This is the plugin’s original component.
fn!richTextFieldWithTables() - This component is new as of version 1.5.3.

Refer to the chart below to understand what formatting each component supports.

Component	Text Formatting	Table Formatting	Image Uploads
fn!richTextField()	✅	✅
fn!richTextFieldWithTables()	✅	✅

All information in this guide applies to both components, unless stated that it only applies to one of the components.

Why are there 2 components?

Parameters

Name	Keyword	Type	Applicable Component(s)	Description
Label	label	Text	Both	Optional text to display as the field label.
Label Position	labelPosition	Text	Both	Optional text to determine where the label appears. Valid values include "ABOVE" (default) Displays the label above the component. "ADJACENT" Displays the label to the left of the component. "COLLAPSED" Hides the label. The label will still be read by screen readers. "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions	instructions	Text	Both	Optional text displayed below the field's value.
Help Tooltip	helpTooltip	Text	Both	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required	required	Boolean	Both	Shows or hides the asterisk indicating if the component is required but does not enforce requiredness. To enforce requiredness, use the parameter "validations". To enforce requiredness only upon submission, use section or form-level validations.
Disabled	disabled	Boolean	Both	Determines if the user is prevented from changing the value. Default: false.
Validations	validations	Text Array	Both	Validation errors to be displayed below the field when the value is not null.
Height	height	Text	Both	Determines the field height. Valid values include "SHORT", "MEDIUM" (default), and "TALL".
Show When	showWhen	Boolean	Both	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.
Rich Text Value	richTextValue	Text	Both	Rich text to display in the field.
Rich Text Save Into	richTextSaveInto	Save Array	Both	One or more variables that are updated with the richText value when the user changes it. Use a!save() to save a modified or alternative value to a variable.
Read Only	readOnly	Boolean	Both	Determines if the field should display as not editable. Default: false.
Max Size	maxSize	Number (Integer)	Both	Maximum size of the HTML formatted rich text data (not number of characters). Default: 10000.
Placeholder	placeholder	Text	Both	Text to display in the field when it is empty. Does not show if the field is read only.
Enable Progress Bar	enableProgressBar	Boolean	fn!richTextField()	Whether to show the progress bar of what percent of rich text data users have entered. Default: true.
Allowed Formats	allowedFormats	Text Array	fn!richTextField()	Determines which format styles are allowed. Note: these must be set on page load and cannot change. Valid values: "header", "size", "bold", "italic", "underline", "strike", "color", "background", "link", "align", "indent", "list". Default: All styles. See more info below. Note that fn!richTextFieldWithTables() sets this parameter to "All styles" by default on the back-end as this is the most common setting in the older component. If you'd like to parameterize allowed styles, please reach out with a request.
Table Border Style	tableBorderStyle	Text	fn!richTextFieldWithTables()	Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT", "NONE".
Allow Images	allowImages	Boolean	fn!richTextField()	Determines if images are allowed. Default: false. See more info below. Note that fn!richTextFieldWithTables() does not support image upload at this time. If you'd like to allow this behavior, please reach out with a request.
Image Storage Connected System	imageStorageConnectedSystem	Connected System	fn!richTextField()	The instance of the Rich Text Editor Image Upload Connected System used to store images from the rich text editor. This is required if allowImages is set to true.
Uploaded Images	uploadedImages	Map Array	fn!richTextField()	An array of images uploaded during this session with metadata about the image. "wasRemovedFromField" is true when a user uploads an image but then removes it in the same session.

Notes

Due to the potential large size of the HTML output of this component, do not save this value into a process variable or a node parameter. Instead, use an expression to load and persist the HTML output directly on the user interface.
Do not use validations to validate the maximum length of the HTML formatted rich text value. Instead, use the parameter maxSize.
Use validations to validate the maximum length of characters that an end-user can enter in the component. To calculate the number of characters, using the functions fn!len() and fn!striphtml().
When the rich text field is displayed in a read-only format, set the parameter height to AUTO for optimal results.
The parameter required doesn’t actually validate that the richTextValue is not null. This is a limitation of the component plug-in framework. Use section-level or form-level validations to validate the requiredness of the richTextValue.

Data Storage

Database Column Type Options

There are two options for storing the HTML output of this component in your database; the considerations of which are listed below.

	VARCHAR column type, or equivalent	LONGTEXT column type, or equivalent
Max Size	Limits the maximum size of the HTML output to 4,000 characters (varies by database)	The maximum size of the HTML output can be as great as 50,000 characters, which is large enough to essentially be considered no limit to a user
Persistence	Designers can pass this output and the CDT with this field into process variables	It is strongly recommended to only use this option if you will be writing and reading from the database directly from SAIL interfaces; never pass data of this column type into process variables
Support	This is a standard database column type which can be exported, modified, and migrated easily	This is not a standard database column type, which could lead to difficulties when trying to export, modify, or migrate
Querying	Searching and sorting against this column type is performant (see Querying below for more information)	Searching and sorting against this column type is not performant, and might not be supported depending on your database

Querying Against The Rich Text Data

To populate the raw text column, there are two options:

Using the fn!striphtml() function in Appian. This is best used when the size of your data is small, or when the contents of the rich text editor never hits a process variable.
Using database triggers. This is best used when it's important to avoid increasing the memory consumption of the process engines, such as when the rich text editor contents are large and passed through process.

Replace [RAWTEXT_COL] with the name of your raw text column, [HTML_COL] with the name of your html column, and [TABLE_NAME] with the name of your table.

-- Create a function to strip html tags given a string

DELIMITER &&

CREATE FUNCTION `strip_tags`($str text) RETURNS text
BEGIN
   DECLARE $start, $end INT DEFAULT 1;
   LOOP
       SET $start = LOCATE("<", $str, $start);
       IF (!$start) THEN RETURN $str; END IF;
       SET $end = LOCATE(">", $str, $start);
       IF (!$end) THEN SET $end = $start; END IF;
       SET $str = INSERT($str, $start, $end - $start + 1, "");
       SET $str = REPLACE($str, " ", " ");
   END LOOP;
END&&

DELIMITER ;

-- Create triggers to execute strip_tags() on the html column with every insert or update, and store the raw text

DELIMITER &&

CREATE TRIGGER `store_raw_input_insert`
BEFORE INSERT ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

CREATE TRIGGER `store_raw_input_update`
BEFORE UPDATE ON `[TABLE_NAME]`
FOR EACH ROW BEGIN
    SET NEW.`[RAWTEXT_COL]` = strip_tags(NEW.`[HTML_COL]`);
END&&

DELIMITER ;

Sending Emails

For the use case of sending formatted emails created by end users, a designer must consider the maximum size of the HTML output as well as the expected email volume.

Allowed Formats (Only applicable for fn!richTextField)

Configuring this Parameter

For consistency and ease of development/maintenance across the platform, the allowed formats should be stored in a constant and used in all instances of the rich text editor.

Modifying Allowed Formats

Image Uploads (Only applicable for fn!richTextField)

To enable image uploads, you must do the following:

Install the Rich Text Editor Image Upload Connected System
Create a knowledge center and folder to store uploaded documents and note the new folder's UUID
Create a new connected system object which leverages the Rich Text Editor Image Upload Connected System
Enter the folder's UUID and the user context to use when uploading images
Create a new Connected System constant which points to the new Connected System object in your application
In your interface where you use fn!richTextField(), set allowImages to true and imageStorageConnectedSystem to the constant created in the previous step

How to migrate to fn!richTextFieldWithTables

The fn!richTextField component relied on non-standard HTML attributes to provide formatting, specifically indentation and nested list formatting:

Indentation: fn!richTextField uses the HTML class "ql-indent-N" (where N is the indentation level) for both line indents and for nested lists. fn!richTextFieldWithTables uses the HTML standard style='margin-left: Npx' for line indents and nested list tags for nested lists (e.g. <ul><li>Bullet<ul><li>Nested Bullet</li></ul></li></ul>). This means that if you were using fn!richTextField and saved end-user formatted indentation or nested lists, fn!richTextFieldWithTables will not recognize these specific formats when rendering and will drop the indentation and nested lists.
Paragraphs: fn!richTextField relies on <div> tags to separate paragraphs, while fn!richTextFieldWithTables relies on tags. This means that passing end-user formatting text from fn!richTextField to fn!richTextFieldWithTables will drop all paragraphs and carriage returns.
Font Color: fn!richTextField relies on tags with a style attribute for font color (e.g. ), while fn!richTextFieldWithTables relies on tags with a color attribute (e.g. ). This means that font colors will get dropped if you directly pass end-user formatting text from fn!richTextField to fn!richTextFieldWithTables.

End-User Rich Text Editor Component

joel.larin — Thu, 07 Sep 2023 16:06:29 GMT

Revision 1 posted to Guide by joel.larin on 9/7/2023 4:06:29 PM

dfsd