Custom transformations API¶

Instead of using the built-in transformations of TYPO3 you can program your own. This is done by creating a PHP class with two methods for transformation. Additionally you have to define a key (like "css_transform") for your transformation so you can refer to it in the configuration of Rich Text Editors.

Custom transformation key¶

You should pick a custom transformation key prefixed by tx_, something like tx_[extension key]_[suffix]. The key must not contain dashes (see Custom transformations API).

Note

If you pick one of the default transformation keys (except the meta-transformations) you will actually override it and your transformation will be called instead!

Registering the transformation key in the system¶

In ext_localconf.php, simply set a $GLOBALS['TYPO3_CONF_VARS'] variable to point to the class which contains the transformation methods:

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_parsehtml_proc.php']['transformation']['tx_examples_transformation']
   = 'Documentation\Examples\Service\RteTransformation';

Here the transformation key is defined to be tx_examples_transformation and the value is the fully qualified class name.

This class must contain two public methods, transform_db() and transform_rte().

It must also contain two public variables called by TYPO3 Core (this is an old part, which doesn't use a proper API):

$pObj which will contain an instance of \TYPO3\CMS\Core\Html\RteHtmlParser.
$transformationKey which should contain your transformation's key (in this case tx_examples_transformation).

Code listing¶

This code listing shows a simple transformation. When content is delivered to the RTE it will add a <hr/> tag to the end of the content. When the content is stored in the database any <hr/> tag at the end of the content will be removed and substituted with whitespace.

class RteTransformation {
   /**
    * NOTE: must be public as it is accessed by \TYPO3\CMS\Core\Html\RteHtmlParser without API
    *
    * @var \TYPO3\CMS\Core\Html\RteHtmlParser
    */
   public $pObj;

   /**
    * NOTE: must be public as it is accessed by \TYPO3\CMS\Core\Html\RteHtmlParser without API
    *
    * @var string
    */
   public $transformationKey = 'tx_examples_transformation';

   /**
    * @var array
    */
   protected $configuration;

   /**
    * Loads the transformation's configuration
    *
    * @return void
    */
   protected function loadConfiguration() {
      $this->configuration = $this->pObj->procOptions['usertrans.'][$this->transformationKey . '.'];
   }

   /**
    * Transforms RTE content prior to database storage
    *
    * @param string $value RTE HTML to clean for database storage
    * @return string
    */
   public function transform_db($value) {
      $this->loadConfiguration();

      if ($this->configuration['addHrulerInRTE'])    {
         $value = preg_replace('/<hr[[:space:]]*[\/]>[[:space:]]*$/i', '', $value);
      }

      return $value;
   }

   /**
    * Transforms database content for RTE display
    *
    * @param string $value Database content to transform into RTE-ready HTML
    * @return string
    */
   public function transform_rte($value) {
      $this->loadConfiguration();

      if ($this->configuration['addHrulerInRTE'])    {
         $value .= '<hr/>';
      }

      return $value;
   }
}

The transformation methods transform_rte and transform_db take a single argument which is the value to transform. They have to return that value again, modified as needed.
Notice that both transformation functions call initConfig() which uses the reference to the parser object to retrieve configuration related to the custom transformation.