Using an Editor Config Contributor Client Extension

Liferay DXP 2024.Q2+/Portal GA120+

Editor Config Contributor client extensions override existing CKEditor configuration in a ConfigContributor.java file. Start with a client extension (from the sample workspace).

Note

Some features used in the sample client extension only apply if your Liferay instance uses CKEditor 5. You must enable it to see those changes apply.

Prerequisites

To start developing client extensions,

1. Install a supported version of Java.

   Note

   Check the compatibility matrix for supported JDKs, databases, and environments. See JVM Configuration for recommended JVM settings.

2. Download and unzip the sample workspace:

   curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip
   

   unzip com.liferay.sample.workspace-latest.zip
   

Now you have the tools to deploy your first Editor Config Contributor client extension.

Examine and Modify the Client Extension

The Editor Config Contributor client extension is in the sample workspace’s client-extensions/liferay-sample-editor-config-contributor/ folder. It’s defined in the client-extension.yaml file:

liferay-sample-editor-config-contributor:
    editorConfigKeys:
        -   description
        -   fragmentEntryLinkRichTextEditor
        -   sampleAlloyEditor
        -   sampleClassicEditor
        -   sampleLegacyEditor
        -   sampleReactCKEditor5ClassicEditor
        -   sampleReactClassicEditor
    name: Liferay Sample Editor Config Contributor
    type: editorConfigContributor
    url: index.js

The client extension has the ID liferay-sample-editor-config-contributor and contains the key configurations for an Editor Config Contributor client extension, including the type, the editorConfigKeys, and the url property that defines the JavaScript resource file’s location. See the Editor Config Contributor YAML configuration reference for more information on the available properties.

It also contains the assemble block:

assemble:
    - from: build
      into: static

This specifies that everything in the build/ folder should be included as a static resource in the built client extension .zip file. The JavaScript file in an Editor Config Contributor client extension is used as a static resource in Liferay.

The src/index.ts file contains code that adds new components for different editors in Liferay. It includes this code that adds a new button for CKEditor 5, using a custom plugin, helloworld.

// CKEditor 5

class HelloWorld extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add('helloworld', () => {
            const button = new ButtonView();

            button.set({
                label: 'Hello',
                withText: true,
            });

            button.on('execute', () => {
                editor.model.change((writer) => {
                    editor.model.insertContent(
                        writer.createText('Hello World ')
                    );
                });
            });

            return button;
        });
    }
}

Important

You can only add custom plugins like this to CKEditor 5. You must have it enabled first.

It also includes this code that adds a video button to the Alloy Editor Configuration.

// Alloy Editor

const toolbars: any = config.toolbars;

if (typeof toolbars === 'object') {
    interface ISelection {
        buttons: Array<string>;
        name: string;
    }

    const textSelection: ISelection = toolbars.styles?.selections?.find(
        (selection: ISelection) => selection.name === 'text'
    );

    if (textSelection.buttons) {
        textSelection.buttons.push('video');

        return {
            ...config,
            toolbars,
        };
    }
}

Finally, it adds a Create AI Content button to the CKEditor 4 configuration.

// CKEditor

const toolbar: string | [string[]] = config.toolbar;

const buttonName = 'AICreator';
let transformedConfig: any;

if (typeof toolbar === 'string') {
    const activeToolbar = config[`toolbar_${toolbar}`];

    activeToolbar.push([buttonName]);

    transformedConfig = {
        ...config,
        [`toolbar_${toolbar}`]: activeToolbar,
    };
}
else if (Array.isArray(toolbar)) {
    toolbar.push([buttonName]);

    transformedConfig = {
        ...config,
        toolbar,
    };
}

const extraPlugins: string = config.extraPlugins;

return {
    ...transformedConfig,
    extraPlugins: extraPlugins ? `${extraPlugins},aicreator` : 'aicreator',
};

To see the changes with CKEditor 5, you must apply the client extension to another editor type. In client-extension.yaml, add rich_text to the list of editorConfigKeys:

editorConfigKeys:
    - rich_text
    - description
    - sampleAlloyEditor
    - sampleClassicEditor
    - sampleLegacyEditor

This key allows this client extension to apply to rich text fields in Liferay DXP, including the Content field for web content.

Now deploy the client extension.

Deploy the Client Extension to Liferay

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

Sign in to Liferay at http://localhost:8080. Use the email address [e-mail] and the password test. When prompted, change the password to learn.

Once Liferay starts, run this command from the client extension’s folder in the sample workspace:

../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)

This builds your client extension and deploys the zip to Liferay’s deploy/ folder.

Note

To deploy your client extension to Liferay SaaS, use the Liferay Cloud Command-Line Tool to run lcp deploy.

Tip

To deploy all client extensions in the workspace simultaneously, run the command from the client-extensions/ folder.

Confirm the deployment in your Liferay instance’s console:

STARTED liferaysampleeditorconfigcontributor_7.4.3.99

Now that your client extension is deployed, check if it’s running properly.

1. Open the Global Menu (), go to the Applications tab, and click Client Extensions under Custom Apps.

2. If the deployment is successful, the Liferay Sample Editor Config Contributor client extension appears in the client extensions manager.

   

3. Click New and choose any option as they all use a WYSIWYG editor.

On the new page, a new Create AI Content button appears at the end of the toolbar.

![The WYSIWYG editor before and after the client extension's deployment](./using-an-editor-config-contributor-client-extension/images/02.png)

If you have CKEditor 5 enabled, see the new controls added to the web content editor:

1. Navigate back to the Liferay site.

2. In the site menu, click Content & Data → Web Content.

3. Click New, then choose Basic Web Content.

The new Hello button appears at the end of the toolbar.

You have successfully used an Editor Config Contributor client extension in Liferay. Next, try deploying other client extension types.

Related Topics

• Editor Config Contributor YAML Configuration Reference
• Using a CSS Client Extension
• Using a JS Client Extension
• Creating a Basic Custom Element