Configuration Concepts¶

YAML¶

TYPO3 is using a custom YAML API for handling YAML in TYPO3 based on the Symfony YAML package. Therefore environment variables can be used.

key1: value
key2: value

key1:
  key1-2: value

- list item 1
- list item 2

key:
  key2:
    - item 1
    - item 2

Configuration Presets¶

Presets are the heart of having custom configuration per record type, or page area. A preset consists of a name and a reference to the location of a YAML file.

TYPO3 ships with three RTE presets, “default”, “minimal” and “full”. The "default" configuration is active by default.

It is possible for extensions to ship their own preset like “news”, or “site_xyz”.

Registration of a preset happens within system/config.php, system/additional.php or within ext_localconf.php of an extension:

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

This way, it is possible to override the default preset, for example by using the configuration defined in a custom extension:

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

TYPO3 uses the “default” preset for all Rich-Text-Element fields. To use a different preset throughout an installation or a branch of the website, see Overriding Configuration via page TSconfig.

Selecting a specific preset for bullet lists can be done via TCA configuration of a field. The following example shows the TCA configuration for the sys_news database table, which can be found in EXT:core/Configuration/TCA/sys_news.php.

'content' => [
   'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.text',
   'config' => [
      'type' => 'text',
      'cols' => 48,
      'rows' => 5,
      'enableRichtext' => true,
      'richtextConfiguration' => 'default',
   ],

Enabling Rich Text Parsing itself is done via enableRichtext, and a specific configuration can be set via richtextConfiguration, setting it to for example “news”.

Overriding Configuration via page TSconfig¶

Instead of overriding all TCA fields to use a custom preset, it is possible to override this information via page TSconfig.

The option RTE.default.preset = news can also be set on a per-field and per-type basis:

# per-field
RTE.config.tt_content.bodytext.preset = minimal

# per-type
RTE.config.tt_content.bodytext.types.bullets.preset = bullets

line #2

This sets the "minimal" preset for all bodytext fields of content elements.

line #4

This sets the "bullets" preset for all bodytext fields of content elements, with Content Type “Bullet list” (CType=bullets).

Of course, any other specific option set via YAML can be overridden via Page TSconfig as well:

Specific options set via YAML can be overridden via page TSconfig as well - but be aware that boolean values can not be set, and arrays are not merged but overridden.

# Restrict format_tags to h2 in bodytext field of content elements
RTE.config.tt_content.bodytext.editor.config.format_tags = h2

The loading order for configuration is:

1. preset defined for a specific field via PageTS
2. richtextConfiguration defined for a specific field via TCA
3. general preset defined via page TSconfig
4. default

For more examples, see RTE in "TSconfig Reference".

A Brief Dive Into History¶

Back in the very old days of TYPO3, there was an RTE which only worked inside Microsoft Internet Explorer 4 (within the system extension “rte”). All other editors of TYPO3 had to write HTML by hand, which was very complicated with all the table-based layouts available. Links were not set with a <a> tag, but with a so-called <typolink 23,13 _blank> tag. Further tags were <typolist> and <typohead>, which were stored in the database 1:1. Since RTEs did not understand these special tags, they had to transform these special tags into valid HTML tags. Additionally, TYPO3 did not store regular <p> or <div> tags but treated every line without a surrounding HTML block element as <p> tag. The frontend rendering then added <p> tags for each line when parsing (see below).

Transformations were later used to allow <em>/<strong> tags instead of <b>/<i> tags, while staying backwards-compatible.

A lot of transformation options have been dropped for TYPO3 v8, and the default configuration for these transformations acts as a solid base. CKEditor itself includes features that work as another security layer for disallowing injecting of certain HTML tags in the database.

For TYPO3 v8, the <typolink> tag was migrated to proper <a> tags with a special <a href="t3://page?id=23"> syntax when linking to pages to ensure HTML valid output. Additionally, all records that are edited and stored to the database now contain proper <p> tags, and transformations for paragraph tags are only applied when not set yet.

Transformations for invalid links and images (still available in HtmlArea) are still in place.

Most logic related to transformations can be found within TYPO3\CMS\Core\Html\RteHtmlParser.

Transformations vs. CKEditor’s Advanced Content Filter¶

TYPO3’s HtmlParser transformations were used to transform readable semi-HTML code to a full-blown HTML rendering ready for the RTE and vice versa. Since TYPO3 v8, magically adding <p> tags or transforming <typolink> tags is not necessary anymore, which leaves transformations almost obsolete.

However, they can act as an extra fallback layer of security to filter out disallowed tags when saving. TYPO3 v8 configuration ships with a generic transformation configuration, which is mainly based on legacy functionality shipped with TYPO3 nowadays.

However, CKEditor comes with a separate strategy of allowing which HTML tags and attributes are allowed, and can be configured on an editor-level. This configuration option is called “allowedContent”, the feature itself is named Advanced Content Filter (ACF).

Activating CKEditor’s table plugin allows to add <table>, <tr> tags etc. Enabling the link picker enables the usage of <a> tags. CKEditor cleans content right away which was e.g. copy-pasted from MS Word and does not match the allowed tags.

TypoScript¶

As with every content that is rendered via TYPO3, this processing for the frontend output of Rich-Text-Editing fields is done via TypoScript, more specifically within the stdWrap property parseFunc. With Fluid Styled Content and CSS Styled Content comes lib.parseFunc and lib.parseFunc_RTE which add support for parsing <a> and <link> tags and dumping them into the typolink functionality. The shipped TypoScript code looks like this:

lib.parseFunc.tags {
   a = TEXT
   a {
      current = 1
      typolink {
         parameter.data = parameters:href
         title.data = parameters:title
         ATagParams.data = parameters:allParams
         target.data = parameters:target
         extTarget = {$styles.content.links.extTarget}
         extTarget.override.data = parameters:target
      }
   }
}

If you already use Fluid Styled Content and CSS Styled Content and you haven’t touched that area of TypoScript yet, you’re good to go by including the TypoScript file.

Fluid¶

Outputting the contents of a RTE-enabled database field within Fluid can be achieved by adding {record.myfield -> f:format.html()} which in turn calls stdWrap.parseFunc with lib.parseFunc_RTE thus applying the same logic. Just ensure that the lib.parseFunc_RTE functionality is available.

You can check if this TypoScript snippet is loaded by using Web > TypoScript and use the TypoScript Tree (Setup) to see if lib.parseFunc_RTE is filled.