[Example] Adjust ckeditor configuration

[niklasnatter]

What's in this PR?

This PR demonstrates how to configure the ckeditor instance which is used for text_editor properties. It utilizes the ckeditorPluginRegistry and ckeditorConfigRegistry of Sulu to add and configure the CKEditor 5 font feature.

// assets/admin/app.js
import {ckeditorPluginRegistry, ckeditorConfigRegistry} from 'sulu-admin-bundle/containers';
import Font from '@ckeditor/ckeditor5-font/src/font';

ckeditorPluginRegistry.add(Font);
ckeditorConfigRegistry.add((config) => ({
    toolbar: [...config.toolbar, 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'],
}));

additional plugins need to be added to the package.json e.g.: @ckeditor/ckeditor5-font, the correct version is important:

Sulu Version	CKEditor Version
2.1	^18.0
2.2	^23.0
2.3	^27.1.0
2.4	^31.0.0
2.5	^34.2.0
2.6	^41.2.1

A hint that you installed a wrong version of your plugin is the following error message:

Uncaught CKEditorError: ckeditor-duplicated-modules Read more: https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html#error-ckeditor-duplicated-modules

To apply the changes, the administration frontend application needs to be rebuilt by executing bin/console sulu:admin:update-build.

[niklasnatter]

It is important that the plugin version is compatible with the ckeditor version used in the project. The ckeditor version of the project can be outputted by executing npm list @ckeditor/ckeditor5-core.

[alexander-schranz]

Sulu Version	CKEditor Version
2.1	^18.0
2.2	^23.0
2.3	^27.1.0
2.4	^31.0.0
2.5	^34.2.0
2.6	^41.2.1

[TheCadien]

Maybe important hint.
If your using the command. Read careful the output of it.

It asks you
"Do you want to overwrite your local version of "index.js"? [y]:"
and
"Do you want to overwrite your local version of "package.json"? [y]:"

here you have to say "N".

[alexander-schranz]

@TheCadien We changed this now by adding a new app.js so custom plugins are not longer part of index.js so there now Y should be answered. The package.json should be N but it is in this case required to say Y for merging package.json together.

[ampaze]

I tried this example with

// Implement custom extensions here

import {ckeditorPluginRegistry, ckeditorConfigRegistry} from 'sulu-admin-bundle/containers';

import HorizontalLine from '@ckeditor/ckeditor5-horizontal-line/src/horizontalline';

ckeditorPluginRegistry.add(HorizontalLine);
ckeditorConfigRegistry.add((config) => ({
    toolbar: [...config.toolbar, 'horizontalLine'],
}));

(that is the only code I added to index.js, besides adding "@ckeditor/ckeditor5-horizontal-line" to package.json)

But all I get is

Uncaught CKEditorError: ckeditor-duplicated-modules

What am I missing?

---

Edit:

The answer is hidden in the code review comment

The plugin needs to match the CKeditor version.

[alexander-schranz]

@ampaze Thx for the response we will try to readd the comment after the 2.4.0 release with the new version. I did also had in mind to validate this things saldy not all ckeditor packages are following this type of versioning.

[benjaminrobinet]

Hello, tried many Node version, but can't build the assets.

ERROR in ./node_modules/sulu-admin-bundle/components/Checkbox/Checkbox.js 7:22
Module parse failed: Unexpected token (7:22)
File was processed with these loaders:
 * ./node_modules/babel-loader/lib/index.js
You may need an additional loader to handle the result of these loaders.
| const CHECKED_ICON = 'su-check';
| export default class Checkbox extends React.PureComponent {
>   static defaultProps = {
|     checked: false,
|     disabled: false,

Tried using docker, & manual build; same issue. Maybe a package-lock is missing in the assets ?

[alexander-schranz]

@benjaminrobinet Please make sure you did update sulu to the latest version which adds a new plugin for transpiling or add the plugin manually: sulu/skeleton#155. Background: babel/babel#14059

[spackmat]

Hey, what about manipulating the CKEditor itself (i.e. not the config or plugins)? The answer to this question https://stackoverflow.com/questions/57906914/adding-classes-to-links-in-ckeditor suggests accessing editor.conversion to add a class-selector to links. The registries mentioned here do not allow access to the editor-object and therefor this solution does not work as documented here.

Or maybe the base question: How can I allow my editors to select/manipulate the classes of a link in a text field? Sulu uses its own link properties UI, so maybe the solution differs at all.

Greets

[alexander-schranz]

@spackmat Personally I would say a content manager should not get into contact with CSS classes or even how its content look like. Separating content from presentation is a big topic inside sulu and is not followed by all template developers but really recommended by us to create future proof website which will survive redesigns without having to migrate content. Still I know that it is sometimes requested and so devs need todo things which are not recommended, and so content manager have impact on presentation / design of website.

But if possible a developer should take care of it via .text-editor a to change the styling of a link via css. For usages of a button we normally recommend to use an own field type and not putting this into the text editor see the link content / field type: https://docs.sulu.io/en/2.4/reference/content-types/link.html

Still if you want to add classes to some files you would need to create an own plugin or you can use exist options like the headings: https://ckeditor.com/docs/ckeditor5/latest/features/headings.html and configure them via the above config registries.

[spackmat]

Hey, thanks for the verbose answer. In that case, the link classes are more of a semantic type, not of a presentational. I wrote about link classes, not CSS classes for a reason. That in mind I strongly disapprove your suspicion that giving editors access to some predefined link types is not primarily a content related decision, although I too saw many of those primarily presentational implementations, which I also never found smart.

But think of (inline!) primary and secondary buttons or a marking for different types of links: Internal for the organization, but not inside Sulu vs. really external. Or links with some kind of spoiler or trigger warning icon. Or links that should show a Wikipedia-like preview tooltip. Or whatever marking editors want to give a link from a content perspective and where the presentation is not their business. Or think of other semantic attributes, if you see the class attribute as a mostly presentational feature for some reason.

Saying all those do not separate content from presentation and thus are restrained in Sulu IMHO flushes the baby with the bath (is this a valid translation from that german phrase?).

For some of my usecases, I can build an own content element (e.g. for the call to action button), but not for others. Primarily because those are inline links, so also abusing the headings feature doesn't help here neither.

That brings me back to the basic question in other words: Is there a way to implement such semantic typing of links in Sulu? As The CKEditor originally has that feature, but Sulu replaces it with its own link-property-form. Maybe there is a way to extend that link-property-form, where I already can change a link's target and such?

[Pascal-Meinecke]

Hello, I had a similar issue and we solved it in a way. Maybe this helps for future attempts. Here is an example structure you can use in your app.js within your assets for the admin build for your SULU CMS to add your own colors to the font color pallet.

Provided that you installed via npm the needed ckeditor5 plugins (if not already present). My problem at this point was, I got confused by the "fontColor" and "colors" structure and didn't realized I needed both encapsulated.

Hope it helps.

import Font from "@ckeditor/ckeditor5-font/src/font";
import FontColor from "@ckeditor/ckeditor5-font/src/fontcolor";
import FontColorEditing from "@ckeditor/ckeditor5-font/src/fontcolor/fontcolorediting";
import FontColorUI from "@ckeditor/ckeditor5-font/src/fontcolor/fontcolorui";

ckeditorPluginRegistry.add(Font);
ckeditorPluginRegistry.add(FontColor);
ckeditorPluginRegistry.add(FontColorEditing);
ckeditorPluginRegistry.add(FontColorUI);

ckeditorConfigRegistry.add((config) => ({
    toolbar: [...config.toolbar, 'fontcolor'],
    fontColor: {
        colors: [
            {
                color: '#AAA',
                label: 'my-color-1'
            },
            {
                color: '#FFF',
                label: 'my-color-2'
            },
            // add more colors here like above if you want
        ]
    }
}));

[DanielRuf]

Stumbled on this by doing a search in my preferred search engine.
Would be very great to have this linked in the documentation or directly documented there.

Unfortunately the current documentation does not cover ckeditor in any page: https://docs.sulu.io/en/2.5/search.html?q=ckeditor&check_keywords=yes&area=default

[lubomirfiala]

If you want to define custom text classes, don't forget to add converterPriority, to your definition, even that you don't have element definition without classes.
For example:

ckeditorConfigRegistry.add((config) => ({
  heading: {
    options: [
      {
          model: 'paragraphSmall', 
          view: { name: 'p', classes: 'small' }, 
          class: 'ck-heading_paragraph_small', 
          title: 'Paragraph default 14px', 
          converterPriority: 'high'
      },
      {model: 'paragraphMedium', view: { name: 'p', classes: 'medium'}, class: 'ck-heading_paragraph_medium', title: 'Paragraph medium 18px', converterPriority: 'high'},
      {model: 'paragraphLarge', view: { name: 'p', classes: 'large'}, class: 'ck-heading_paragraph_large', title: 'Paragraph large 22px', converterPriority: 'high'},
      {model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2'},
      {model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3'},
      {model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4'},
    ]
  }
}));

[DanielRuf]

We are getting the following error, when we try to open the admin area: Uncaught CKEditorError: ckeditor-duplicated-modules

New line in package.json:

"@ckeditor/ckeditor5-font": "^38.1.1",

Code in app.js:

// Add project specific javascript code and import of additional bundles here:
import {ckeditorPluginRegistry, ckeditorConfigRegistry} from 'sulu-admin-bundle/containers';


// pkg.dependencies:         "@ckeditor/ckeditor5-font": "^27.1.0",
// see https://github.com/sulu/sulu-demo/pull/77


import Font from "@ckeditor/ckeditor5-font/src/font";
// import FontColor from "@ckeditor/ckeditor5-font/src/fontcolor";
// import FontColorEditing from "@ckeditor/ckeditor5-font/src/fontcolor/fontcolorediting";
// import FontColorUI from "@ckeditor/ckeditor5-font/src/fontcolor/fontcolorui";

ckeditorPluginRegistry.add(Font);
// ckeditorPluginRegistry.add(FontColor);
// ckeditorPluginRegistry.add(FontColorEditing);
// ckeditorPluginRegistry.add(FontColorUI);

ckeditorConfigRegistry.add((config) => ({
    toolbar: [...config.toolbar, 'fontcolor'],
    fontColor: {
        colors: [
            {
                color: 'hsl(186, 95%, 32%)',
                label: 'Primary blue (dark blue)'
            },
            {
                color: '',
                label: 'default (reset)'
            },
            // add more colors here like above if you want
        ]
    }
}));

[DanielRuf]

Ok, seems to work with "@ckeditor/ckeditor5-font": "^34.2.0",.
I still think the table and the example should be part of the documentation @alexander-schranz.

[alexander-schranz]

@DanielRuf you did install a incompatible version. See comment. #77 (comment)

[DanielRuf]

@alexander-schranz I know, that's why I had posted an update afterwards =)

#77 (comment)

How and where can we add this crucial information to the documentation?
So far no relevant results there: https://docs.sulu.io/en/2.5/search.html?q=ckeditor&check_keywords=yes&area=default

[alexander-schranz]

@DanielRuf I personally recommend normally go with the prebuild admin JS build aslong as possible and avoid custom builds. We don't want that its normal to have your own Admin Build for simpliest website because fighting down bc breaks in JS dependencies are hard and sadly very common aslong as you go with the prebuild of Sulu you don't need to fight the JS world there :).

To your questions, all JavaScript components and frontend of the Admin UI has its own documentation, the ckeditor documentation you will find here: https://jsdocs.sulu.io/2.5/#ckeditor5

[DanielRuf]

Unfortunately our design and marketing team needs a single specific addition in the ckeditor. So in our case we have to extend the configuration of ckeditor (and it works so far)

To your questions, all JavaScript components and frontend of the Admin UI has its own documentation, the ckeditor documentation you will find here: https://jsdocs.sulu.io/2.5/#ckeditor5

Ah, perfect. I was not aware of that. I had to search in more detail and I guess I found the link to this at https://docs.sulu.io/en/2.5/book/extend-admin.html?highlight=javascript#extend-admin-ui in these big paragraphs. Much to read.

But still no mention of ckeditor (which was the word I was searching for) at https://docs.sulu.io/en/2.5/book/extend-admin.html.

[alexander-schranz]

@DanielRuf are you able to share a screenshot of the website or design where you require special CKEditor plugins? I'm very curious about your usages and requirements for it, specially how we maybe can make this work maybe out of the box in future without the need of.

[DanielRuf]

@alexander-schranz I don't think another abstraction as solution makes sense (and personally as developer I prefer the possibility to freely extend the ckeditor configuration). We add the font plugin (see #77 (comment)) for this:

Our design team wants to make single words / text in a specific color without us developers to hardcode this in the React code. The website itself is not yet public.

I found the PR here just by accident after searching also in all repos for ckeditor in the text.

[alexander-schranz]

I advocate always Separating Content from Presentation for longevity and flexibility across design changes. I like to ask the question what does the highlighted text mean in point of for blind and color blind people.

Explore the meanings of <strong> (https://html.spec.whatwg.org/#the-strong-element) and <em> (https://html.spec.whatwg.org/#the-em-element) with screen readers can help here. For color highlighting, consider the <mark> (https://html.spec.whatwg.org/#the-mark-element) tag with the CKEditor plugin (https://ckeditor.com/docs/ckeditor5/latest/features/highlight.html). In most cases avoid span with classes and as that connect your markup to a design which you should avoid. Content normally stays longer then a design and migration should be as easy as possible with such specific tags instead of span classes you provide accessibility and future proof markup.

While designers may prefer direct design control, we seek balance here to avoid design decision for the content managers aslong as possible and try to make content management a nobrainer of putting text and media in it.

Still things such new tags could be interesting, but educating content managers on these tags is the hard part when we maybe in future want to add beside <b>, <i> also <strong>, <em> and <mark> while maybe the <mark> is maybe the easist thing aslong as there exist only one <mark> tag (don't like the ckeditor example with multiple different highlightings).

---

I personally like that its a little bit hidden the CKEditor docs as mostly people would try to extend it without thinking what is the Sulu way / our recommended way of doing this things are. Why people sure completely free how they build their templates. Not in your special case but Blocks replaces in Sulu what in other CMS systems are put directly all into the TextEditor and there is the dangerous things that they try to add the image, embed, ... to the Text Editor which should in Sulu way be own Fields and Block Types and not part of Text editor. That is the most dangerous thing we have mostly to fight with "bad" template architecture in some projects we see.

[DanielRuf]

I advocate always Separating Content from Presentation for longevity and flexibility across design changes. I like to ask the question what does the highlighted text mean in point of for blind and color blind people.

I can not really follow. That is what a WYSIWYG editor like ckeditor is meant to be used like. The color setting is wanted by the design team to color single words in the wysiwyg text.

[DanielRuf]

For color highlighting, consider the <mark>

This is just the "yellow" native mark (backkground color, not text color as defined by me via the ckeditor configuration, text color is not comparable to mark[er]), this is not what is needed by the design team and not our goal. I think the reasoning behind the configuration is not really relevant and was not my initial question.

specially how we maybe can make this work maybe out of the box in future without the need of.

I don't think this is needed. Too many abstraction layers will break in the near future, especially when you deal with third-party APIs like ckeditor.

My only problem from the start of our discussion is: the example PRs are not discoverable from the docs and nowhere mentioned, that's all =)

I can understand your point of view, but when you have a CMS and a WYSIWYG editor, the separation between presentation (ckeditor configuration is meant to add WYSIWYG features, the example PR does exactly that) and content always fades. That's by nature. Coloring a single word in a sentence is not possible without this approach.

I'm ok to disagree here. The native mark element is not what we want to use here.

[alexander-schranz]

@DanielRuf Just to make sure, I dont suggest to use the "yellow" marker but style the <mark> tag that it matches your highlighted words design.

[alexander-schranz]

It is required to use the correct version of a plugin which matche Sulu CKEditor version: #77 (comment)