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.

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 a 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 current 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 are used by either the web block or a Client Action.

• Configuration is used by the web block to set certain metadata of the editor.

• EditorConfiguration is used by the GetEditorConfiguration Client Action and contains data of the editor in question.

Web Block explanation

The CKEditor5Classic web block has several input parameters and one event

The input parameters are as follows;

• 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 that contains the internal name of the editor. You will need to use this name for all interactions with the editor so be sure to store it in a local variable!

Usage 

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

• Add the CKEditor5Classic 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.

Sample

There is an extra webblock available in this component. If you want to see how the editor works, you can add the SampleCK in one screen in your application and see it in action.

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