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.

RTE.tt_content.types.textmedia.bodytext.preset = full 
RTE.config.tx_news_domain_model_news.bodytext.preset = default

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.

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['my_preset'] = 'EXT:my_layout_extension/Configuration/RTE/Default.yaml';

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.

imports:
    - { resource: "EXT:rte_ckeditor/Configuration/RTE/Processing.yaml" }
    - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml" }

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.

editor:
   config:
      format_tags: "p;h1;h2;h3;pre"

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.

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

editor:
   config:
     toolbarGroups:
         - { name: clipboard, groups: [clipboard, undo] }
         - { name: editing,   groups: [find, selection, spellchecker] }
         - { name: links }
         - { name: insert }
         - { name: tools }
         - { name: table }
         - { name: tabletools }
         - { name: document,  groups: [ mode, document, doctools ] }
         - { name: others }
         - "/"
         - { name: basicstyles, groups: [ basicstyles, align, cleanup ] }
         - { name: paragraph,   groups: [ list, indent, blocks, align, bidi ] }
         - "/"
         - { name: styles }  
   removeButtons:

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.

editor:
  config:
     contentsCss: "EXT:rte_ckeditor/Resources/Public/Css/contents.css"
     # can be "default", but a custom stylesSet can be defined here, which fits TYPO3 best
     stylesSet:
      # block level styles
      - { name: "Orange title H2", element: "h2", styles: { color: "orange", background: "blue" } }
      - { name: "Orange title H3", element: "h3", attributes: { class: "my_fancy_css_class"} }
      - { name: "Quote / Citation", element: "blockquote" }
      - { name: "Code block", element: "code" }
      # Inline styles
      - { name: "Yellow marker", element: "span", styles: { background-color: "yellow" } }

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.

editor:
  config: 
    removePlugins:
      - image
    extraPlugins:
      - justify
      - font
      - find
      - bidi 
    justifyClasses:
      - align-left
      - align-center
      - align-right
      - align-justify

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:

editor:
  externalPlugins:
    typo3link: { resource: "EXT:rte_ckeditor/Resources/Public/JavaScript/Plugins/typo3link.js", route: "rteckeditor_wizard_browse_links" }

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