How to use CKEditor 5 for OutSystems

This document will describe on how to use CKEditor 5 and how to display the HTML content you generate with CKEditor 5.

Installation

Please install CKEditor 5 from the Forge into your own environment via the for you available methods.

Contents

CKEditor 5 currently only contains the classic build of CKEditor 5. More builds like Inline, Balloon or Decoupled will arrive in the near future.

Web Blocks

CKEditor 5 for OutSystems has 2 web blocks.

CKEditor5Classic is the web block you will need to use to allow edit capabilities. Note that this web block has one event that needs to be handled since this will return the internal name of the editor that needs to be used for interaction.
CKEditor5CSSStyles is the web block you will need to use on all pages that display content created with CKEditor 5

Client Actions

CKEditor 5 also has several Client Actions that are used to interact with the editor. Note that all of these Client Actions have an mandatory input parameter called EditorName. This is the name that is returned by the IsReady event of the CKEditor5Classic web block.

• GetContent is used to get the HTML content from the editor that the end-user added.
• SetContent is used to set the (HTML) content to the editor. Use this if you want to dynamically overwrite the current data.
• GetEditorState is used to check if the editor is in Edit mode or in Read Only mode.
• SetEditorState is used to set the editor is either Edit mode or in Read Only mode.
• LoadHTMLIntoContainer is used to display the data created with CKEditor 5 on a screen.

There are also 2 Client Actions that you, as a developer, can use to get more information about the editor.

• GetEditorConfiguration shows the currently configuration of CK Editor 5 and all available modules.
• GetToolbarOptions shows all possible toolbar icons you can add to the toolbar. With this you can easily create your own toolbar.

Structures

CKEditor 5 also has 2 structures that is used by either the web block or an Client Action.

• Configuration is used by the web block to set certain meta data of the editor.
• EditorConfiguration is used by the GetEditorConfiguration Client Action and contains data of editor in question.

Web Block explanation

The CKEditor5Classic web block has several input parameters and one event

The input parameters are as follows;

• Id is mandatory and will need to contain the Widget Id of the Container or Text Area where CKEditor 5 is being bound to.
• InitialData is optional and can contain the HTML that will be edited. Please use this for initialization instead of the SetContent Client Action.
• Configuration is optional and contains the different configuration capabilities of CKEditor 5.

There is also one mandatory Event is will be triggered when CKEditor 5 is fully loaded and available for use. This event has one parameter then contains the internal name for the editor. You will need to use this name for all interaction with the editor so be sure to store it in a local variable!

Usage 

CKEditor 5 can be used to bind to two different widgets.

• It can be bound to a Container. This is the preferred method.
• It can be bound to a TextArea widget.

The only time you would want to use the TextArea widget is when you want Service Studio to give you a better representation of the actual page. In OutSystems the native behavior of CKEditor5 with Forms in combination with the TextArea widget doesn’t work as expected so it’s only a visual change.

The steps that you will need to follow to add CKEditor 5 to your Screen is as follows.

• Add a Container widget or TextArea widget to your screen
• Give this widget a unique name
• Place the CKEditor5Classic web block underneath the widget that is being bound to
• Add the Widget Id (use the expression editor) to the Id input parameter of the web block
• Create a local variable to hold the editors name (Recommendation is EditorName)
• Create a client action with an input parameter named Name
• In this Client Action assign the value of Name to EditorName
• Use this Client Action for the IsReady Event of the web block

Now you have a working CKEditor 5 screen where you can create or edit HTML data.

When you want to save the data the end-user has created follow these steps;

• Add a button called “Save” on the Screen
• Double-click on the button to create a Client Action
• In this Client Action use the GetContent Client Action to retrieve the data in HTML format
• Store this HTML data wherever you want. For example in a Entity, file or send it to a REST endpoint.

View the content

To display the HTML content created with CKEditor 5 you need to create a new Screen or Web Block that contains the following.

• A named container
• The CKEditor5CSSStyles web block

After retrieving the HTML content load it into the container using the LoadHTMLIntoContainer Client Action.

And that’s it. You now have a working implementation of CKEditor 5. Be sure to check out the Demo for more implementation details.

Known issues

This section describes the following known issues.

Issue: The width and height is being reused for all CKEditor 5 instances throughout the application.
Cause: This is because CKEditor5 uses only one CSS Class for its editor (ck-editor__editable). After this CSS class is set CKEditor5 will no longer change this class based on the configuration options provided. There is no fix is available at the current time