Configure CKEditor in TYPO3

The new RTE “CKEditor” hit the TYPO3 core in version 8.5. Since the last release 8.6 it is now possible to configure the rich text editor via yaml files. Read on for a tutorial, how to configure the new rte CKEditor in TYPO3.

The configuration file format

The configuration of the CKEditor within TYPO3 is written in YAML. YAML stands for “YAML Ain’t Markup Language” as it contains really no markup. It is quite new to the TYPO3 universe. The first TYPO3 core project, which used YAML as the configuration file format, was the system extension “form”.

Why not use the default format of CKEditor?

This was one of the first questions I asked myself … My first answer was: “It is clear! As an integrator, I do not want to fiddle around with javascript arrays”. The second advantage of the approach TYPO3 takes is, that it is easy to import and overwrite existing “presets”. The third advantage is to separate code from configuration, as we know it already from TypoScript and Fluid.

YAML basics

A YAML file is just a text file. Its structure is determined by indentations with spaces. “Key value pairs are separated by a colon and sequence item are denoted by a dash”. So far the short introduction by the YAML inventors themselves. Furthermore the syntax is meant to be easily readable by humans.

If you want to learn more about the format and its rules, the specification can be found athttp://www.yaml.org/spec/1.2/spec.html

Editor config presets

A preset is a portion (or all) of a configuration, which can be applied to a certain rte enabled field. The TYPO3 core comes with three presets: full, minimal and default. Each name indicates already a scope of a configuration. They show very how a configuration can look like and can be taken as a basis for your own configurations.

The examples are located under typo3/sysext/rte_ckeditor/Configuration/RTE and give a good overview over many configuration options. But before you dig through the files yourself, I will show you what is happening there.

Applying config to rte enabled fields

The default preset for the RTE is (as you can guess) the “default” preset. It can be overridden in the pageTS config field, using the assignment RTE.default.preset = minimal This preset will then be applied to each rte below the page where it was set and for all fields, to which no other preset was applied.

This means, that it is possible to apply an own preset on each rte enabled field. Here are two examples:

  • for the field bodytext in the context of the content element textmedia and
  • for the bodytext field of the news extension.

 

If other presets than these three are necessary, they must be provided by an extension. The extension must register the yaml files via ext_localconf.php.

The array key of the preset must be unique, so I would recommend to prefix it with a “vendor name” or the extension key.

Structure of a rte preset file

As already written above, the configuration format for the CKEditor in TYPO3 is yaml. The file consists of three sections. At the start of a file other yaml files can be imported. So it is easily possible to reuse portions of configuration.

 

The Processing.yaml contains the instructions for the code processing, when it is written to the database. The options are the same as in the RTE.default.proc. section of the pageTS config.

The Base.yaml contains some basic settings like the width and height of the rte, buttons, which should be removed by default and so on.

After loading the imports, new options can be added. I split a typical config file up into several pieces and explain a little bit.

Option “format_tags”

The format_tagsoption enables the block level elements which can be selected in the format dropdown.

DropDown for Tags

Option “toolbarGroups”

The option toolbarGroups defines the layout of the toolbars at the top of the editor. A "/" starts a new button bar in the editor. All elements and buttons, contained in a name:section, will stay grouped together when the editor windows is too small to display the name:sections in one row. Maybe it gets more clear with two screenshots.

Display in wide editor area

Display in narrow editor area

They show the second row of buttons of the following configuration:

I will not go into more details of the button configuration, because there is a comprehensive documentation. Furthermore ckeditor provides a button configurator, with which you can configure the button configuration with drag and drop, and export it afterwards. The last thing, you have to do with the export, is to convert it to the yaml configuration format.

Providing styles

Besides the basic styles this is one of the main goals of an RTE: To provide editors the possibility to format the text in an attractive manner (without going crazy 😉 ).

Custom stylesheets are provided with the option contentsCss. These styles are used in the RTE and should (must?) also be available in the frontend.

 

The section stylesSet defines the labels and formatting in the “Styles” drop down. The string behind name: is a human readable label, which should make it easy for the editor to select the style. element: defines on which html element the selected style can be applied. If selected, the block level element is also set to this element.

In the last part of a style definition the visual representation is defined, either with styles or attibutes. The styles option adds the attribute styleto the markup and applies the css definition in that way. IMHO the better way it to use the attributes option and add just a css class.

Configuring plugins

Another strength of CKEditor is the extensibility with plugins. Currently over 200 are available in the plugin directory. The system extension of TYPO3 already provides seventy of them. They can be included via the extraPlugins:option.

 

The last block justifyClasses contains the necessary options for the justify plugin, included earlier.

If non default plugins should be included in the editor, they must be provided by a layout extension. The code for including them to the ckeditor looks like the following lines:

Conclusion

With the new RTE CKEditor, we have now a really great and also stable alternative to the good old htmlareaRTE. The yaml configuration format should be only a small hurdle to take, as it is just plain text and quite easy to read.

Also the transformation from the old config format in plain TSconfig to the new presets in yaml should not be too hard.

I am really glad that we have it now and also a great open source community from CKEditor as a partner.

If you found this post helpful or know somebody who could profit from it, I would be happy if you share it in your favorite social network. For convenience, you can use the buttons below.. Thanks in advance for sharing.

Finally here the complete list of links used in the post:

Links

Documentation: http://docs.ckeditor.com/#!/api/CKEDITOR.config

Button Configurator: http://ckeditor.com/latest/samples/toolbarconfigurator/index.html#basic

Plugin Directory: http://ckeditor.com/addons/plugins/all

Credits
I found the blogpost image on unsplash. It was created by Sergey Zolkinand published unter the “Unsplash license“. I modified it using the service of Pablo on Buffer

23 Comments

  1. Was ich nicht ganz verstehe, trotz der versuchten Erklärung: wieso YAML?

    Wenn ich das richtig verstehe, muss ja auch das YAML erst in die native config.js von CKeditor übersetzt werden?
    Und falls das so ist, frag ich mich natürlich, ob wir nicht bereits eine Konfigurationssprache mit ähnlicher Syntax im Angebot gehabt hätten …

    Reply
    • Hi

      Thanks for your comment. For non-german readers, it would be cool, if you comment in english, as this is the main language of this blog.

      And yes, I agree with you. Additionally the GOTS (good old typoscript) provides features, that yaml does not have, like unsetting values and conditions.

      Reply
    • Thanks for the new RTE! Seriously!

      Nevertheless I need to comment on the yaml part. For some reason (I don’t get) yaml seems to be more en vogue today. To be honest I think yaml is just ugly. It depends on formating instead of syntax. My opinion is: Please stop to use more yaml in TYPO3 for no reason.

      Back to the topic. You tried to give arguments why it is a good idea to use yaml. I think none of the arguments provides a reason to use yaml (instead of TSConfig for example).

      Here are some reasons against yaml:

      Yaml is not needed because there’s TypoScript/TSConfig. (the RTE yaml is even converted to a TS array internally 🙂
      I find yaml even more strange than … just everything (and JavaScript arrays).
      More integrators know JavaScript than yaml.
      The CKEditor documentation can’t be used to configure the editor (at least not copy and paste.
      You can do dynamic things in config.js you never can do in yaml. (okay not many people would use that)

      Please consider to make the use of yaml optional.
      It would be nice if one could just use CKEditor JavaScript config files in presets.

      A preset file could be TSConfig (*.ts/*t3s) with one option defining the config.js file.

      Reply
  2. Hi,
    thanks! I created a class “btn” for links, by the following lines:

    In the database the ‘btn’ class is stored, but it won’t be rendered in frontend.

    Do you have a hint for me?

    Reply
  3. I tried (TYPO3 CMS 8.6.1) to extend the processing.yaml with allowedAttribs but this ends up in an exception:

    Reply
  4. How do I load external plugins to ckeditor in Typo3? for example I downloaded from ckeditor’s website the plugin wordcount. how do I enable it since it’s not part of the shipped extraPlugins in Typo3?

     

     

    Reply
    • Have a look at the configuration of the sysext, where the extraPlugins are loaded. Include a similar statement in your yaml file and point the path to where the downloaded plugins reside.

      For better and faster feedback, I recommend to ask such questions on https://typo3.slack.org or on StackOverflow tagged with #TYPO3.

      Reply
  5. Thank you for your Configuration tutorial. I have an issue concerning my configuration. Even when I try to include my configuration like you do I get an JS error:

    TSConfig:

    My ext_localconf:

    My .yaml

    My Error is:

    Uncaught Error: [CKEDITOR.resourceManager.load] Resource name “default” was not found

    VM1041 ckeditor.js?bust=67522e8…:85 GET http://training.local/typo3/sysext/rte_ckeditor/Resources/Public/JavaScript/Contrib/styles.js?t=H0CF 404 (Not Found)

    Maybe you got a hint for me.

    Reply
    • Hi,

      i had the same problem. you need a valid “stylesSet” in you yaml file. Check out sysext/rte_ckeditor/Configuration/RTE/Full.yaml

      best of luck!

      Reply
  6. Thanks for replying to my previous question.

    On the Typo3 8.7, I’m trying to setup custom classesAnchor for the new rte_ckeditor. Currently when linking to pages, files, or external site, the targets and titles are blank. On 6.2 and 7.6 I was able to auto populate with custom values. Can you help me with this? This is my current config under my_extension/Configuration/PageTS/RTE.txt :

    Nothing seems to work for setting up the above custom values.

    Thanks for your help!

    Reply
  7. Leider funktioniert bei mir das codesnippet nur im Backend. Typo3 8.7.1.

    Css und JS Datei ist im Frontend eingebunden aber die Formatierung funktioniert nicht

    Reply

Leave a Comment.