How to enable custom tags in TYPO3 RTE

November 5th, 2010 • typo3, typoscript, custom tags, tags, rte, page tsconfig • comments

How to enable custom tags in TYPO3 RTE

I think it's time for a new article and I done this research a long time ago. It's very tricky to enable custom tags for your TYPO3 instance because you have to do some magic things in the page TSconfig and also via TypoScript.

I've done this because I saw a need for it in a clients old website where someone enables the RTE image plugin which allows to insert some star graphics for the hotel's category. Because I thought that enabling the image plugin for the RTE is a bad idea I've done a little research and try-and-error how to achieve this with mighty mighty TypoScript'ing.

Overview

Tooo be able to use custom tags in the default rtehtmlarea RTE of TYPO3, you have to follow this 3 simple steps:

  1. Extend default parseFunc configuration
  2. Extend css_styled_content and stdheader Setup
  3. Extend RTE with page TSconfig to enable custom tag plugin and processing instructions

Extend default parseFunc configuration

At first, you must extend the default parseFunc configuration in order to be able to allow custom tags at all. Only with this configuration you will be able to enable it for certain fields.

I suggest to insert this one in the "setup" field of an extension TypoScript template ext:css_styled_content in your GRSP (General Record Storage Page).

// common parsed elements (e.g.header fields)
lib.parseFunc.allowTags := addToList(star)
lib.parseFunc.tags.star = < plugin.tx_mycustomtagextension_pi1
lib.parseFunc.nonTypoTagStdWrap.HTMLparser.tags.star = < plugin.tx_mycustomtagextension_pi1

// add custom tag to parse function of the RTE
lib.parseFunc_RTE.allowTags := addToList(star)
lib.parseFunc_RTE.tags.star = < plugin.tx_mycustomtagextension_pi1
// this line enables the "passthrough" of non-typo-tags to the HTML parser
// you can also specify an cObject directly, without the need of a plugin call
lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.star = < plugin.tx_mycustomtagextension_pi1

Explanation

The lib.parseFunc setup path is meant to be recognized by fields which do not make usage of the RTE. So, lines 2-4 will pave the way for the usage of custom tags in header fields.

Line 7, 8 & 11 enables the functionality for all fields which uses the RTE and includes the default lib.parseFunc_RTE setup (this is not always the case in some extensions).

Note, that in this setup I decided to create an extension which handles the tag processing, but you're also able to use any TypoScript cObject.

Extend css_styled_content and stdheader Setup

After this, you must enable the custom tag parsing for the desired fields.

In this example, we'll only enable the tt_content.bodytext (text field of most of the default content elements) and header fields (also valid for all default content elemtents).

Note: you're encouraged to also insert this in the above mentioned ext:css_styled_content TypoScript template record.

// here you also can use your TypoScript cObject
tt_content.text.20.parseFunc.tags.star = < plugin.tx_myextkey_pi1

// header fields don't have any parseFunc setup, enable it!
lib.stdheader.10.setCurrent.parseFunc =< lib.parseFunc
// by default all input is parsed with stdWrap.htmlSpecialChars
lib.stdheader.10.setCurrent.htmlSpecialChars = 0

Extend RTE with page TSconfig to enable custom tag plugin and processing instructions

The last part handles the (more or less) tricky configuration of the RTE in the page TSConfig. Nothing will happen at all if the RTE parsing processor don't know about the new tag.

Note: This setup must be added to the page TSConfig field of your root page (or any other page in the tree if you're planning to enable the feature for specific branches).

// add custom tag plugin to RTE buttons
RTE.default.showButtons := addToList(user)
RTE.default.hideButtons := removeFromList(user)

// allowed/denied tags
RTE.default.proc.allowTags := addToList(star)
RTE.default.proc.denyTags := removeFromList(star)

// HTMLparser_rte settings
RTE.default.proc.HTMLparser_rte = 1
// don't mask special html characters like < or >
RTE.default.proc.HTMLparser_rte.htmlSpecialChars = 0
// protect specific, user defined tags
RTE.default.proc.HTMLparser_rte.tags.star.protect = 1

// entryHTMLparser_db settings
// special html characters like < or > will be stored unmasked (get masked by re-display in RTE)
RTE.default.proc.entryHTMLparser_db.htmlSpecialChars = -1
// protect specific tag
RTE.default.proc.entryHTMLparser_db.tags.star.protect = 1
// protect non matching tags
RTE.default.proc.entryHTMLparser_db.keepNonMatchedTags = protect

// exitHTMLparser_db settings
RTE.default.proc.exitHTMLparser_db = 1
// protected non matched tags during fetching from database
RTE.default.proc.exitHTMLparser_db.keepNonMatchedTags = 1
// don't mask html characters like < or >
RTE.default.proc.exitHTMLparser_db.htmlSpecialChars = 0

// RTE plugin "user" settings
// define group tag name
RTE.default.userElements.10 = Own Tags
// tag configuration
RTE.default.userElements.10.1 = Stars
RTE.default.userElements.10.1.description = The selected text will be wrapped with <star></star>
RTE.default.userElements.10.1.mode = wrap
RTE.default.userElements.10.1.content = <star>|</star>

Explanation

The RTE has 3 "processing hooks" in total:

  • HTMLparser_rte: database to RTE
  • entryHTMLparser_db: RTE to database
  • exitHTMLparser_db: database to frontend

Each hook needs its own configuration. Nevertheless, you can also make usage of TypoScripts inherting capabilties, but I thought it would be better to write down the configuration very detailed. Also, the configuration is a little bit contradictory (note the different htmlSpecialChars values).

I came to this solution with a lot try-and-error. So I excuse the lack of detailed explanation for each configuration line.

Comments

comments powered by Disqus