DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: htmlArea RTE API

Author:Stanislas Rolland
Created:2008-11-21T00:49:27
Changed by:Stanislas Rolland
Changed:2012-03-19T14:09:52.390000000
Email:typo3(arobas)sjbr.ca
Info 2:Stanislas Rolland
Info 3:
Info 4:

EXT: htmlArea RTE API

((generated))

Table of Contents

Copyright 2

Extending htmlArea RTE 3

Introduction 3

Extension structure 3

Extension files 3

Plugin naming conventions 3

Skinning conventions for button icons 3

RTE Extension API 4

Class tx_rtehtmlareaapi 4

Protected Variables 4

Public Methods 4

RTE Plugin API 6

Introduction 6

Class HTMLArea.Plugin 6

Plugin Variables 6

Plugin Methods 6

Class HTMLArea 8

Hooks 9

Hooks on link and image insertion dialogues 9

Body tag additions on link insertion dialogue 9

Additional attributes on links 9

Using htmlArea RTE in a frontend plugin 10

Invoking the htmlArea RTE frontend plugin 10

Inserting markers in the HTML template 11

Setting the style attribute of the editing area 11

Extending htmlArea RTE

((generated))

Introduction

This document describes the API that allows TYPO3 extension developers to extend the features of htmlArea RTE.

The last section also describes how extension developers may enable htmlArea RTE to edit textarea fields in TYPO3 frontend plugins.

This document applies to htmlArea RTE version 2.2+ and TYPO3 4.6+.

Extension structure

Extending htmlArea RTE is done by means of a TYPO3 extension that may include one or more htmlArea RTE JavaScript plugins.

Extension files

A TYPO3 extension for extending htmlArea RTE is comprised of the usual extension file components. Additionally, the extension may contain one or more htmlArea RTE plugins and skin components contained in the following file and subdirectory structure:

ext_emconf.php

Filename

ext_emconf.php

Description

This is the usual definition of extension properties. This file is required.

ext_localconf.php

Filename

ext_localconf.php

Description

This is the usual extension configuration file.

The plugins added by the extension should be registered here with the following assignments:

$TYPO3_CONF_VARS['EXTCONF']['rtehtmlarea']['plugins']['PluginName'] = array();
$TYPO3_CONF_VARS['EXTCONF']['rtehtmlarea']['plugins']['PluginName']['objectReference'] =
        'EXT:'.$_EXTKEY.'/PluginName/class.tx_rtehtmlarea_pluginname.php:&tx_rtehtmlarea_pluginname';
$TYPO3_CONF_VARS['EXTCONF']['rtehtmlarea']['plugins']['PluginName']['addIconsToSkin'] = 0;

This variable is used by the default API method getPathToSkin() to determine if any skin component provided by the extension, usually button icons, should be added or not to the RTE skin when the plugin is enabled.

$TYPO3_CONF_VARS['EXTCONF']['rtehtmlarea']['plugins']['PluginName']['disableInFE'] = 0;

This variable may be used by the default API method main($parentObject) to determine if the plugin should be disabled or not when the RTE is used in the TYPO3 frontend.

ext_conf_template.txt

Filename

ext_conf_template.txt

Description

This is the usual extension configuration template. It may be used to provide an interface to edit the values of extension configuration variables addIconsToSkin and disableInFE (see ext_localconf.php above).

PluginName /class.rtehtmlarea_ pluginname .php

Filename

PluginName /class.rtehtmlarea_ pluginname .php

Description

This is the PHP script of each registered plugin. This file contains a PHP class definition extending abstract class tx_rtehtmlareaapi. It should therefore require the file containing the API-defining class:

require_once(t3lib_extMgm::extPath('rtehtmlarea').'class.tx_rtehtmlareaapi.php');

The API provided by class tx_rtehtmlapi is described in the following section.

PluginName /locallang.xml

Filename

PluginName /locallang.xml

Description

Server-side localization file for the labels used by the PHP script of the registered plugin.

PluginName /skin/htmlarea.css

Filename

PluginName /skin/htmlarea.css

Description

Skin component that may be used to add button icons to the RTE skin when the registered plugin is enabled.

PluginName /skin/images/ buttonIcon.gif

Filename

PluginName /skin/images/ buttonIcon.gif

Description

Button icon for any button registered by the JavaScript plugin.

htmlarea/plugins/ PluginName / plugin-name .js

Filename

htmlarea/plugins/ PluginName / plugin-name .js

Description

This is the main JavaScript script of the plugin. This file contains a JavaScript script extending class HTMLArea.Plugin. The API provided by this class is described in a later section as well as other JavaScript API components.

htmlarea/plugins/ PluginName /locallang.xml

Filename

htmlarea/plugins/ PluginName /locallang.xml

Description

Client-side localization file for the labels used by the JavaScript plugin.

Plugin naming conventions

(to be completed)

Skinning conventions for button icons

(to be completed)

RTE Extension API

Class tx_rtehtmlareaapi

This is the PHP class that should be extended when extending htmlArea RTE.

Protected Variables

The following variables may be used by methods of the class extending class tx_rtehtmlareaapi.

$extensionKey

Variable

$extensionKey

Type

string

Description

Must be set to the key of the extension that is extending htmlArea RTE.

Default: void

$pluginName

Variable

$pluginName

Type

string

Description

Must be set to the name of the plugin registered by the extension.

Default: void

$relativePathToLocallangFile

Variable

$relativePathToLocallangFile

Type

string

Description

The path to the server-side localization file of the registered plugin, relative to the extension directory.

Default: void

$relativePathToSkin

Variable

$relativePathToSkin

Type

string

Description

Path to the skin (css) file to be added to the RTE skin when the registered plugin is enabled, relative to the extension directory.

Default: void

$relativePathToPluginDirectory

Variable

$relativePathToPluginDirectory

Type

string

Description

Path to the directory containing the plugin, relative to the extension dir (should end with slash /).

Default: void

$htmlAreaRTE

Variable

$htmlAreaRTE

Type

object

Description

Reference to the invoking RTE object.

$thisConfig

Variable

$thisConfig

Type

object

Description

Reference to the RTE PageTSConfig.

$toolbar

Variable

$toolbar

Type

array

Description

Reference to the RTE toolbar array. This is the one-dimensional array of configured toolbar elements (buttons, labels, drop-downs).

$LOCAL_LANG

Variable

$LOCAL_LANG

Type

array

Description

Reference to the frontend localization array.

$pluginButtons

Variable

$pluginButtons

Type

string

Description

The comma-separated list of button names that the registered plugin is adding to the htmlArea RTE tollbar.

Default: empty string

$pluginLabels

Variable

$pluginLabels

Type

string

Description

The comma-separated list of label names that the registered plugin is adding to the htmlArea RTE tollbar.

Default: empty string

$convertToolbarForHtmlAreaArray

Variable

$convertToolbarForHtmlAreaArray

Type

array

Description

The name-converting array, converting the button names used in the RTE PageTSConfing to the button id's used by the JavaScripts scripts.

$requiresClassesConfiguration

Variable

$requiresClassesConfiguration

Type

boolean

Description

Should be set to true if the registered plugin requires the PageTSConfig Classes configuration to be parsed and downloaded.

Default: false

$requiresSynchronousLoad

Variable

$requiresSynchronousLoad

Type

boolean

Description

Should be set to true if the plugin must be loaded synchronously

Default: false

$requiredPlugins

Variable

$requiredPlugins

Type

string

Description

The comma-separated list of names of plugins that are prerequisites for the registered plugin.

Default: empty string

Public Methods

The following methods are used by htmlArea RTE main script tx_rtehtmlarea_base. They may be redefined in the class extending the API.

main($parentObject)

Method

main($parentObject)

Description

Initializes some variables and determines if the extension should be enabled.

Returns true if the extension should be enabled.

Default:

Initializes references to parent object variables.

Checks if the etension should be enabled in the frontend based on $TYPO3_CONF_VARS

Initializes the localization arrays.

addButtonsToToolbar()

Method

addButtonsToToolbar()

Description

Adds the buttons to the default tollbar order array, provided that they are not already in the array.

buildJavascriptConfiguration($RTEcounter)

Method

buildJavascriptConfiguration($RTEcounter)

Description

Returns JavaScript code that defines the configuration of the features/buttons of the extension, to be referenced by the JavaScript plugin.

Default:

Initiallizes the Javascript configuration for the buttons, creating one Javascript empty configuration object for each button, if such object does not already exist.

requiresClassesConfiguration()

Method

requiresClassesConfiguration()

Description

Returns true if the extension requires the PageTSConfig Classes configuration to be generated and downloaded.

getExtensionKey()

Method

getExtensionKey()

Description

Returns the extension key.

getPluginButtons()

Method

getPluginButtons()

Description

Returns the list of buttons implemented by the plugin.

getPluginLabels()

Method

getPluginLabels()

Description

Returns the list of toolbar labels implemented by the plugin.

getPathToSkin()

Method

getPathToSkin()

Description

Returns the path to the skin component (button icons) that should be added to linked stylesheets.

getPathToPluginDirectory()

Method

getPathToPluginDirectory()

Description

Returns the path to the plugin directory, if any is set

getConvertToolbarForHtmlAreaArray()

Method

getConvertToolbarForHtmlAreaArray()

Description

Returns the conversion array from TYPO3 button names to htmlArea button names.

requiresSynchronousLoad()

Method

requiresSynchronousLoad()

Description

Returns true if the plugin requires synchronous load

setSynchronousLoad($value =true)

Method

setSynchronousLoad($value =true)

Description

Sets the plugin to require synchronous load or not

Note: This method would presumably be used to require that the plugin of another RTE extension be loaded synchronously, so as to ensure its availabilitywhen the plugin of the requesting extension is loaded.

getRequiredPlugins()

Method

getRequiredPlugins()

Description

Returns the list of plugins that are required by the plugin.

transformContent($value)

Method

transformContent($value)

Description

Returns transformed content. This method is invoked in order to perform some content transformation, in addition to the normal RTE transformation. The transformation is performed on the way from the database to the RTE.

Note: This method is not present in the abtract API class, but may be added when extending it.

applyToolbarConstraints($show)

Method

applyToolbarConstraints($show)

Description

Returns a modfified one-dimentional array of button names to be shown in the toolbar. The method is invoked after all other inclusions and exclusions have been performed on the toolbar array.

Note: This method is not present in the abtract API class, but may be added when extending it.

RTE Plugin API

((generated))

Introduction

This section describes the JavaScript API that should be used when creating a RTE htmlArea plugin.

Class HTMLArea.Plugin

Every htmlArea RTE JavaScript plugin is a subclass of class HTMLArea.Plugin.

This is done with code like the following :

HTMLArea.PluginName = Ext.extend(HTMLArea.Plugin, ({

    some-method : function() {
        ...
    }
});

Note that, as of TYPO3 4.6, the plugin name must be within the HTMLArea naming space.

Any number of additional methods may also be added.

The same approach may be applied for a plugin to extend another plugin.

Note: Before TYPO3 4.6, invoking this.base() from any method, invoked the corresponding method of the parent class. This will not work in TYPO3 4.6+ . this.base now invokes only the constructor of class HTMLArea.Plugin.

Plugin Variables

The following variables are declared by the constructor method and may be used by methods of the plugin class.

editor

Variable

editor

Type

object

Description

Reference to the RTE object.

editorNumber

Variable

editorNumber

Type

num

Description

The relative number of the editor object within the page.

editorConfiguration

Variable

editorConfiguration

Type

object

Description

Reference to the configuration object of the editor.

name

Variable

name

Type

string

Description

The name of the plugin.

Plugin Methods

The following methods are defined in the HTMLArea.Plugin class. They may be invoked by methods of the plugin class.

constructor(editor, pluginName)

Method

constructor(editor, pluginName)

Description

This method must be included and must declared as fololows:

constructor : function(editor, pluginName) {
    this.base(editor, pluginName);
}
configurePlugin(editor)

Method

configurePlugin(editor)

Description

This method is invoked by the constructor.

This method should be used to register the About information, the buttons and the dropdown lists. It may also be used to declare additional plugin variables.

Arguments:

  1. editor: reference to the RTE object

Return:

boolean: true, if the plugin was correctly initialized and configured.

registerPluginInformation(pluginInformation)

Method

registerPluginInformation(pluginInformation)

Description

This method is used to register the plugin's About information.

Arguments:

  1. pluginInformation: an object with the following components:
  • version: the version
  • developer: the name of the developer
  • developerUrl: the url of the developer
  • copyrightOwner: the name of the copyright owner
  • sponsor: the name of the sponsor
  • sponsorUrl: the url of the sponsor
  • license: the type of license (should be "GPL")

Return:

boolean: true, if registration was successful

getPluginInformation()

Method

getPluginInformation()

Description

Gets the plugin information object that was registered.

isButtonInToolbar(buttonId)

Method

isButtonInToolbar(buttonId)

Description

Determines if the button is configured in the toolbar.

Arguments:

  1. buttonId: string identifying the button

Return:

boolean: true, if the button is present in the toolbar configuration

registerButton(buttonConfiguration)

Method

registerButton(buttonConfiguration)

Description

Registers a button.

Arguments:

  1. buttonConfiguration: an object with the following components:
  • id : unique id for the button; required
  • tooltip: tooltip for the button; required
  • textMode: enable the button in text mode; defaults to false
  • action: name of the method of the plugin class invoked when the button is pressed; required
  • context: disable the button when the cursor is not inside one of listed elements; defaults to null
  • hide: hide the button in the toolbar; defaults to false
  • selection: disable the button when there is no selection; defaults to false
  • hotkey: hotkey character; if present, a hotkey will also be registered
  • dialog: the button opens a dialogue; defaults to false

Return:

boolean: true, if button registration was successful

registerDropDown (dropDownConfiguration)

Method

registerDropDown (dropDownConfiguration)

Description

Registers a dropdown list.

Arguments:

  1. buttonConfiguration: an object with the following components:
  • id : unique id for the dropdown; required
  • tooltip: tooltip for the dropdown; required
  • textMode: enable the dropdown in text mode; defaults to false
  • action: name of the method of the plugin class invoked when an option is selected; required
  • refresh: name of the method of the plugin class invoked in order to refresh the drop-down when the toolbar is updated; required
  • context: disable the button when the cursor is not inside one of listed elements; defaults to null

Return:

boolean: true, if dropdown registration was successful

getDropDownConfiguration(dropDownId)

Method

getDropDownConfiguration(dropDownId)

Description

Gets the dropdown configuration object that was registered.

Arguments:

  1. dropDownId: the unique id of the dropdown
registerHotKey(hotKeyConfiguration)

Method

registerHotKey(hotKeyConfiguration)

Description

Registers a hotkey.

Arguments:

  1. buttonConfiguration: an object with the following components:
  • id : the one-character key; required
  • action: name of the method of the plugin class invoked when the hotkey is pressed; required

Return:

boolean: true, if hotkey registration was successful

translateHotKey(key)

Method

translateHotKey(key)

Description

Gets the button id associated with the key, if any.

Arguments:

  1. key: the hotkey character

Return:

string: the button id or an empty string.

getHotKeyConfiguration(key)

Method

getHotKeyConfiguration(key)

Description

Gets the hotkey configuration object that was registered.

Arguments:

  1. key: the hotkey character
getButton(buttonId)

Method

getButton(buttonId)

Description

Gets a reference to the toolbar button or combo box ExtJS object.

Arguments:

  1. buttonId: the unique id of the button or dropdown
onUpdateToolbar()

Method

onUpdateToolbar()

Description

If defined in the plugin class, this method will be invoked when the toolbar state is refreshed.

Default: null

onMode(mode)

Method

onMode(mode)

Description

This method is invoked when the editor changes mode from text to wysiwyg or vice versa

Arguments:

  1. mode: “textmode” or “wysiwyg”

Default:

The default method will close any dialogue window left opened by the plugin.

onGenerate()

Method

onGenerate()

Description

If defined in the plugin class, this method will be invoked when the editor is being generated.

Default: null

makeFunctionReference(functionName)

Method

makeFunctionReference(functionName)

Description

This method creates a function reference in order to avoid memory leakage in IE.

Arguments:

  1. functionName: the name of the plugin method to be invoked

Return:

function: function definition invoking the specified method of the plugin

localize(label)

Method

localize(label)

Description

Localizes a label.

Arguments:

  1. label: the key of a string to be localized

Return:

string: localized string

getJavascriptFile(url, noEval)

Method

getJavascriptFile(url, noEval)

Description

Loads a Javascript file synchronously.

Arguments:

  1. url: url of the file to load
  2. noEval: if false or null, the loaded file is evaluated

Return:

boolean: true on success

postData(url, data, handler)

Method

postData(url, data, handler)

Description

Posts data to the specified url

Arguments:

  1. url: url to post data to
  2. data: data to be posted

3. handler: function that will handle the response returned by the server

Return:

void

makeUrlFromModulePath(modulePath, parameters)

Method

makeUrlFromModulePath(modulePath, parameters)

Description

Makes an url from a TYPO3 module path adding most commonly used parameters (RTEtsConfigParams, etc.)

Arguments:

  1. modulePath: the module path
  2. parameters: additional parameters to add to the url

Return:

string: the url

appendToLog(functionName, text)

Method

appendToLog(functionName, text)

Description

Appends an entry at the end of the troubleshooting log

Arguments:

  1. functionName: the name of the plugin method writing to the log
  2. text: the text of the message

Return:

void

Class HTMLArea

(To be completed)

Hooks

((generated))

Using htmlArea RTE in a frontend plugin

Extension developers may enable the use of htmlArea RTE to edit textarea fields in TYPO3 frontend plugins. In order to do so, the TYPO3 plugin class must invoke the htmlArea RTE frontend plugin and some markers must be inserted in the HTML template.

((generated))

Invoking the htmlArea RTE frontend plugin

Step 1. Include the htmlArea RTE frontend plugin:

require_once(t3lib_extMgm::extPath('rtehtmlarea').'pi2/class.tx_rtehtmlarea_pi2.php');

Step 2. Declare the following class variables for the RTE API:

var $RTEObj;
     var $docLarge = 0;
     var $RTEcounter = 0;
     var $formName;
         // Initial JavaScript to be printed before the form
         // (should be in head, but cannot due to IE6 timing bug)
     var $additionalJS_initial = '';
         // Additional JavaScript to be printed before the form
         // (works in Mozilla/Firefox when included in head, but not in IE6)
     var $additionalJS_pre = array();
         // Additional JavaScript to be printed after the form
     var $additionalJS_post = array();
         // Additional JavaScript to be executed on submit
     var $additionalJS_submit = array();
     var $PA = array(
             'itemFormElName' =>  '',
             'itemFormElValue' => '',
             );
     var $specConf = array(
             'rte_transform' => array(
                     'parameters' => array('mode' => 'ts_css')
                     )
             );
     var $thisConfig = array();
     var $RTEtypeVal = 'text';
     var $thePidValue;

Step 3. Set the HTML markers for rendering the form:

$this->postvars = t3lib_div::_POST('tx_myextension_pi1');
     if(!$this->RTEObj)  $this->RTEObj = t3lib_div::makeInstance('tx_rtehtmlarea_pi2');
     if($this->RTEObj->isAvailable()) {
         $this->RTEcounter++;
         $this->table = 'my-table-name';
         $this->field = 'my-field-name';
         $this->formName = 'my-form-name';
         $this->PA['itemFormElName'] = 'tx_myextension_pi1[my-field-name]';
         $this->PA['itemFormElValue'] = $this->postvars['my-field-name'];
         $this->thePidValue = $GLOBALS['TSFE']->id;
         $RTEItem = $this->RTEObj->drawRTE(
                     $this,
                     'my-table-name',
                     'my-field-name',
                     $row=array(),
                     $this->PA,
                     $this->specConf,
                     $this->thisConfig,
                     $this->RTEtypeVal,
                     '',
                     $this->thePidValue
                 );
             $markerArray['###ADDITIONALJS_PRE###'] = $this->additionalJS_initial.'
             <script type="text/javascript">'. implode(chr(10), $this->additionalJS_pre).'
             </script>';
             $markerArray['###ADDITIONALJS_POST###'] = '
             <script type="text/javascript">'. implode(chr(10), $this->additionalJS_post).'
             </script>';
             $markerArray['###ADDITIONALJS_SUBMIT###'] = implode(';', $this->additionalJS_submit);
             $markerArray['###FORM_RTE_ENTRY###'] = $RTEItem;
     }

Step 4. Process and save data sent in the textarea:

if($this->RTEObj->isAvailable()) {
         $pageTSConfig = $GLOBALS['TSFE']->getPagesTSconfig();
         $RTEsetup = $pageTSConfig['RTE.'];
         $this->thisConfig = $RTEsetup['default.'];
         $this->thisConfig = $this->thisConfig['FE.'];
         $dataArray['my-field-name'] = $this->RTEObj->transformContent(
                     'db',
                     $dataArray['my-field-name'],
                     'my-table-name',
                     'my-field-name',
                     $dataArray,
                     $this->specConf,
                     $this->thisConfig,
                     '',
                     $this->thePidValue
                 );
     }
     $insert = $GLOBALS['TYPO3_DB']->exec_INSERTquery('my-table-name', $dataArray);

where $dataArray is the array of data used to insert the data into the table.

Inserting markers in the HTML template

Step 1. Insert JavaScript marker before the form:

###ADDITIONALJS_PRE###

Step 2. Insert onSubmit marker on the form tag:

<form name="my-form-name" method="post" action="###ACTION_URL###" onsubmit="###ADDITIONALJS_SUBMIT###" >

Step3. Replace the <textarea> tag and its contents with:

###FORM_RTE_ENTRY###

Step4. Insert JavaScript marker after the form:

###ADDITIONALJS_POST###

Setting the style attribute of the editing area

You may use $this->RTEObj->RTEWrapStyle and $this->RTEObj->RTEdivStyle to set the style attributes of the editing area and of its wrapping div.

img-1 EXT: htmlArea RTE API - 11