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
Copyright¶
Extension Key: rtehtmlarea_api
Copyright 2008-2011, Stanislas Rolland, <typo3(arobas)sjbr.ca>
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
a GNU/GPL CMS/Framework available from www.typo3.com
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- dropDownId: the unique id of the dropdown
registerHotKey(hotKeyConfiguration)¶
Method
registerHotKey(hotKeyConfiguration)
Description
Registers a hotkey.
Arguments:
- 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:
- 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:
- key: the hotkey character
getButton(buttonId)¶
Method
getButton(buttonId)
Description
Gets a reference to the toolbar button or combo box ExtJS object.
Arguments:
- 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:
- 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:
- 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:
- 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:
- url: url of the file to load
- 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:
- url: url to post data to
- 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:
- modulePath: the module path
- 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:
- functionName: the name of the plugin method writing to the log
- text: the text of the message
Return:
void
Class HTMLArea¶
(To be completed)
Hooks¶
((generated))¶
Hooks on link and image insertion dialogues¶
Extension developers may define hooks on classes tx_rtehtmlarea_browse_links and tx_rtehtmlarea_select_image in order to add their own tabs to these dialogues or replace any of the tabs provided by htmlArea RTE or other extensions, such as DAM (Digital Assets Management)..
The hooks should be defined in a class implementing interface t3lib_browseLinksHook (see t3lib/interfaces/interface.t3lib_browselinkshook.php).
Configuration of the hooks should be done in the ext_localconf.php file of the extension with the following statements:
$TYPO3_CONF_VARS['SC_OPTIONS']['ext/rtehtmlarea/mod3/class.tx_rteh tmlarea_browse_links.php']['browseLinksHook'][] = 'EXT:myextension/h ooks/class.tx_myextension_browse_links.php:&tx_myextension_browse _links';
$TYPO3_CONF_VARS['SC_OPTIONS']['ext/rtehtmlarea/mod4/class.tx_rteh tmlarea_select_image.php']['browseLinksHook'][] = 'PATH_txdam.'comp at/class.tx_myextension_select_image.php:&tx_myextension_select_ image';
Body tag additions on link insertion dialogue¶
Hooks on 'ext/rtehtmlarea/mod3/class.tx_rtehtmlarea_browse_links.php' may include an additional method for adding attributes to the document's body tag:
/**
* Modifies the body tag additions array and returns it
*
* @param array body tag additions
* @return array modified body tag additions
*/
public function addBodyTagAdditions($bodyTagAdditions) {
return $bodyTagAdditions;
}
Additional attributes on links¶
Hooks on 'ext/rtehtmlarea/mod3/class.tx_rtehtmlarea_browse_links.php' may also add additional, possibly custom, attributes on the link tag. The additional attributes should be configured using:
$TYPO3_CONF_VARS['EXTCONF']['rtehtmlarea']['plugins']['TYPO3Link'][' additionalAttributes'] = 'list-of-string';
Values for the additional attributes must be provided by the hook using JavaScript method browse_links_setAdditionalValue(name, value).
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.
EXT: htmlArea RTE API - 11