⚠️ The contents of this repo have been migrated to theliferay/liferay-frontend-projectsmonorepo and more specifically to the to theguidelines/directory. Maintenance will continue there, and this repo will be archived (ie. switched to read-only mode). Depending on whether files have moved in the new repo, you may be able to see the current version of this page at this location.
Currently, there are three different Rich Text Editors supported out-of-the-box in Liferay DXP:
If you need to use a WYSIWYG editor in your application, please identify the different use cases before making a decision.
Depending on the use case, your application needs likely fall in one of these categories
| Rich Text Needs | Solution |
|---|---|
| No need for rich text features (bold, links...) | Use simple input elements like <aui:input /> or <input /> |
| Basic Rich Text Features (text formatting, links, images...) | Use <liferay-ui:input-editor /> (deprecated) or the <Editor /> React component |
| Contextual Inline Editing Experience (page-editing, blogs...) | Use <liferay-ui:input-editor type="balloon" /> (deprecated) or the <BallonEditor /> React component |
Rich Text Editors in DXP offer a variety of APIs that can be used depending on the context.
Traditionally, the most common way to instantiate a Rich Text Editor is through a JSP. There are 2 main JSP APIs you can use:
Creates an input field for editing rich text
<%@ taglib uri="http://liferay.com/tld/editor" prefix="liferay-editor" %>
<liferay-editor:editor
contents="Initial Text"
editorName="ckeditor"
name="content"
/>The provided EditorTag tracks available instances of EditorRenderer and defers the rendering and initialization of the Rich Text Editors to an existing registered renderer whose name attribute matches the provided editorName value.
Warning: The tag
liferay-ui:input-editorwas deprecated inDXP 7.1. However, many occurrences might still be found. When possible, favour the usage ofliferay-editor:editorover the deprecated version of the tag
Loads the necessary scripts and styles of an editor
This tag was initially created to provide a new tag to be able to include input-editors JavaScript alone (without the HTML). It allows the developer of an app to include all the necessary scripts that power a Rich Text Editor (CKEditor, TinyMCE, AlloyEditor...) so that their global APIs are later present in the global object for a deferred usage.
<%@ taglib uri="http://liferay.com/tld/editor" prefix="liferay-editor" %>
<liferay-editor:resources editorName="ckeditor" />const newEditor = AlloyEditor.editable(wrapperRef.current, {
...editorConfig,
enterMode: 1,
startupFocus: autoFocus,
title: false
});Warning: Whenever possible, analyze and use one of the new JavaScript APIs that offer out-of-the-box React components to integrate in your React Applications
From Liferay DXP 7.3 forward, the module frontend-editor-ckeditor-web exposes React versions of CKEditor adapted to different scenarios:
| Rich Text Needs | Solution |
|---|---|
| Basic Rich Text Features (text formatting, links, images...) | Use the <Editor /> React component |
| Contextual Inline Editing Experience (page-editing, blogs...) | Use the <BallonEditor /> React component |
| Default Inline Editing Experience (single fixed toolbar) | Use the <InlineEditor /> React component |
Please, read through our General Guidelines to pick the necessary component for your needs and then use it accordingly:
<Editor
autoFocus={autoFocus}
configurationName='comment'
id={id}
initialValue={textareaContent}
onChange={onTextareaChange}
placeholder={Liferay.Language.get('type-your-comment-here')}
/>The following are the main 2 Java interfaces to know when dealing with Rich Text Editor in DXP:
Defines an available Rich Text Editor
Implement EditorRenderer in the unlikely event that you need to create a new Rich Text Editor.
@Component(
property = "name=ckeditor", service = {Editor.class, EditorRenderer.class}
)
public class CKEditorEditor implements Editor, EditorRenderer {
[...]
}You can read more about this API below.
Provides an interface for setting the editor's configuration
Currently, you can implement EditorConfigContributor to Modify an Editor's Configuration.
@Component(
property = {"editor.name=ckeditor"},
service = EditorConfigContributor.class
)
public class MyEditorConfigContributor extends BaseEditorConfigContributor {
@Override
public void populateConfigJSONObject(JSONObject jsonObject) {
// Modifies `jsonObject` in place for the desired configuration
}
}Warning: Keep in mind that Editor Config Contributors stack on top of each other following a specificity algorithm. All Config Contributors that apply to a given editor will run over the
jsonObjectobject mutating it in place, in order.
Editor implementations are usually implemented as independent modules inside the frontend-editor folder.
As we're moving towards a single editor module, here's a detailed explanation of the frontend-editor-ckeditor-web module.
As stated in the Java section, one of the most important Services in Rich Text Editor modules are the public implementations of EditorRenderer.
This module exposes the following EditorRenderer implementations:
| File | Editor Name | Extra Plugins | Description |
|---|---|---|---|
| CKEditorEditor.java | ckeditor | Default editor for HTML | |
| CKEditorBBCodeEditor.java | ckeditor_bbcode | bbcode | Editor with added BBCode support for Message Boards |
| CKEditorCreoleEditor.java | ckeditor_creole | creole | Editor with added Creole support for Wiki |
As an addition to 7.3, this module also exports some useful React components to instantiate CKEditor directly from a React Application:
| File | API | Description |
|---|---|---|
| Editor.js | import {Editor} from 'frontend-editor-ckeditor-web'; |
Default boxed editor |
| InlineEditor.js | import {InlineEditor} from 'frontend-editor-ckeditor-web'; |
Inline Editor with fixed toolbar |
Note: The provided React components are simple wrappers around our common patched CKEditor offering. That is, they will load all the scripts and resources provided by the OSGi module rather than fetching them from CKEditor's CDN
The EditorRenderer interface defines 2 important methods:
Defines a path to a JSP that can be rendered to include all the necessary scripts, resources and styles of an editor.
This is the JSP that gets rendered when liferay-editor:resources is called with editorName="ckeditor".
In all cases, resources.jsp is used which includes the CKEditor scripts plus necessary setup and teardown general logic.
Defines a path to a JSP that can be rendered to instantiate an editor.
This is the JSP that gets rendered when liferay-editor:editor is called with editorName="ckeditor".
In all cases, ckeditor.jsp is used which includes resources.jsp plus the necessary instance configuration and initialization logic.
- ckeditor4-react: Powers the React-based components that wrap up CKEditor.
- liferay-ckeditor: Fork of CKEditor where we push temporary patches until they are fixed upstream.
- scayt plugin: A Spell Checker as You Type plugin.
- wsc plugin: A Spell Checker Dialog plugin.
In some cases, the editor that will be used can also be configured in portal.properties. This, however, depends on the apps using the liferay-editor:editor tag providing the proper support for it.
The default WYSIWYG when no specific editor is passed is ckeditor.
Depending on the content you're editing, you may want to modify the editor to provide a better configuration for your needs. This is done by implementing the EditorConfigContributor interface.
The configuration for a given editor instance is aggregated inside InputEditorTag and sent through to the specific editor being instantiated.
You can read more about this in the Modifying an Editor's Configuration tutorial.