From fc65f055f7b7c5926afe45d707ad1fde1381ec1d Mon Sep 17 00:00:00 2001
From: Markus Klein <markus.klein@typo3.org>
Date: Mon, 9 Nov 2015 19:11:38 +0100
Subject: [PATCH] [DOC] Add documentation for element and link browser API
Resolves: #71448
Releases: master
Change-Id: I7fc5c352d8339c4d5af6f6377fb5f96719c0fd4e
Reviewed-on: https://review.typo3.org/44647
Reviewed-by: Wouter Wolters <typo3@wouterwolters.nl>
Tested-by: Wouter Wolters <typo3@wouterwolters.nl>
Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch>
Tested-by: Christian Kuhn <lolli@schwarzbu.ch>
---
...69-RemovedElementBrowserRelatedClasses.rst | 32 +++++++
.../Feature-66369-AddedLinkBrowserAPIs.rst | 91 ++++++++++++++++---
...eature-66369-AddedNewElementBrowserAPI.rst | 21 +++++
3 files changed, 131 insertions(+), 13 deletions(-)
create mode 100644 typo3/sysext/core/Documentation/Changelog/master/Breaking-66369-RemovedElementBrowserRelatedClasses.rst
create mode 100644 typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedNewElementBrowserAPI.rst
diff --git a/typo3/sysext/core/Documentation/Changelog/master/Breaking-66369-RemovedElementBrowserRelatedClasses.rst b/typo3/sysext/core/Documentation/Changelog/master/Breaking-66369-RemovedElementBrowserRelatedClasses.rst
new file mode 100644
index 000000000000..ff2d933a32f4
--- /dev/null
+++ b/typo3/sysext/core/Documentation/Changelog/master/Breaking-66369-RemovedElementBrowserRelatedClasses.rst
@@ -0,0 +1,32 @@
+=========================================================
+Breaking: #66369 - Removed ElementBrowser related classes
+=========================================================
+
+Description
+===========
+
+The following classes have been removed without replacement
+
+ * TYPO3\CMS\Core\ElementBrowser\ElementBrowserHookInterface
+ * TYPO3\CMS\Recordlist\Browser\ElementBrowser
+ * TYPO3\CMS\Rtehtmlarea\BrowseLinks
+ * TYPO3\CMS\Rtehtmlarea\FolderTree
+ * TYPO3\CMS\Rtehtmlarea\PageTree
+
+
+Impact
+======
+
+Any code still using the aforementioned classes will die with a fatal error.
+
+
+Affected Installations
+======================
+
+Any code still using the aforementioned classes.
+
+
+Migration
+=========
+
+Use the new API for adding element browsers or link handlers.
diff --git a/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedLinkBrowserAPIs.rst b/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedLinkBrowserAPIs.rst
index 1b55d7264de8..7fe8fdd85fbd 100644
--- a/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedLinkBrowserAPIs.rst
+++ b/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedLinkBrowserAPIs.rst
@@ -5,15 +5,23 @@ Feature: #66369 - Added LinkBrowser APIs
Description
===========
-This new feature allows to extend the LinkBrowser with new tabs.
+This new feature allows to extend the link browser with new tabs, which allow to implement custom link functionality
+in a generic way in a so called LinkHandler.
+Since the LinkBrowser is used by FormEngine and RTE, the new API ensures that your custom LinkHandler works with those
+two, and possible future, usages flawlessly.
-Each tab is handled by a so called LinkHandler, which has to implement the ``\TYPO3\CMS\Recordlist\LinkHandler\LinkHandlerInterface``.
+Each tab rendered in the link browser has an associated link handler, responsible for rendering the tab and for creating
+and editing of links belonging to this tab.
-The LinkHandlers are registered in page TSconfig like:
+
+Tab registration
+----------------
+
+Link browser tabs are registered in page TSconfig like this:
.. code:: typoscript
- file {
+ TCEMAIN.linkHandlers.<tabIdentifier> {
handler = TYPO3\\CMS\\Recordlist\\LinkHandler\\FileLinkHandler
label = LLL:EXT:lang/locallang_browse_links.xlf:file
displayAfter = page
@@ -23,17 +31,74 @@ The LinkHandlers are registered in page TSconfig like:
}
}
-The handlers are displayed as tabs in the link browser.
-The options ``displayBefore`` and ``displayAfter`` define the order of the displayed tabs.
+The options ``displayBefore`` and ``displayAfter`` define the order how the various tabs are displayed in the link browser.
-The options ``scanBefore`` and ``scanAfter`` define the order in which handlers are executed when scanning existing links.
-For instance, your links might start with a specific prefix to identify them. Therefore you should register at least before
+The options ``scanBefore`` and ``scanAfter`` define the order in which handlers are queried when determining the responsible
+tab for an existing link.
+Most likey your links will start with a specific prefix to identify them. Therefore you should register your tab at least before
the 'url' handler, so your handler can advertise itself as responsible for the given link.
+The 'url' handler should be treated as last resort as it will work with any link.
+
+
+Handler implementation
+----------------------
+
+A link handler has to implement the ``\TYPO3\CMS\Recordlist\LinkHandler\LinkHandlerInterface`` interface, which defines
+all necessary methods for communication with the link browser.
+
+Additionally, each link handler should also provide a Javascript module (requireJS), which takes care of passing a link
+to the link browser.
+A minimal implementation of such a module looks like this:
+
+.. code:: javascript
+
+ define(['jquery', 'TYPO3/CMS/Recordlist/LinkBrowser'], function($, LinkBrowser) {
+
+ var myModule = {};
+
+ myModule.createMyLink = function() {
+ var val = $('.myElmeent').val();
+
+ // optional: If your link points to some external resource you should set this attribute
+ LinkBrowser.setAdditionalLinkAttribute('data-htmlarea-external', '1');
+
+ LinkBrowser.finalizeFunction('mylink:' + val);
+ };
+
+ myModule.initialize = function() {
+ // todo add necessary event handlers, which will propably call myModule.createMyLink
+ };
+
+ $(myModule.initialize);
+
+ return myModule;
+ }
+
+Notice the call to ``LinkBrowser.finalizeFunction``, which is the point where the link is handed over to the link browser
+for further processing and storage.
+
+
+Hooks
+-----
+
+You may have the need to modify the list of available link handlers based on some dynamic value.
+For this purpose you can register hooks.
+
+The registration of a link browser hook generally happens in your ``ext_tables.php`` and looks like:
.. code:: php
- $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['LinkBrowser']['hooks'][1444048118] = [
- 'handler' => \Vendor\Ext\MyClass::class,
- 'before' => [], // optional
- 'after' => [] // optional
- ];
+ if (TYPO3_MODE === 'BE') {
+ $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['LinkBrowser']['hooks'][1444048118] = [
+ 'handler' => \Vendor\Ext\MyClass::class,
+ 'before' => [], // optional
+ 'after' => [] // optional
+ ];
+ }
+
+The ``before`` and ``after`` elements allow to control the execution order of all registered hooks.
+
+Currently the following list of hooks is implemented:
+
+ - modifyLinkHandlers(linkHandlers, currentLinkParts): May modify the list of available link handlers and has to return the final list.
+ - modifyAllowedItems(allowedTabs, currentLinkParts): May modify the list of available tabs and has to return the final list.
diff --git a/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedNewElementBrowserAPI.rst b/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedNewElementBrowserAPI.rst
new file mode 100644
index 000000000000..ea5d96cb94e5
--- /dev/null
+++ b/typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedNewElementBrowserAPI.rst
@@ -0,0 +1,21 @@
+===============================================
+Feature: #66369 - Added new element browser API
+===============================================
+
+Description
+===========
+
+The former code monster class ``ElementBrowser`` has been split into dedicated parts of functionality.
+Specifically the functionality of selecting elements for the FormEngine and the code parts for creating
+links, used in FormEngine and RTE, have been moved into separate APIs.
+
+Each type of element, which can be selected in FormEngine, has its own element browser class.
+You may add your own special type by registering your own element browser in your ``ext_tables.php`` as follows:
+
+.. code:: php
+
+ if (TYPO3_MODE === 'BE') {
+ $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ElementBrowsers'][<identifier>] = \Vendor\Ext\TheClass::class;
+ }
+
+The registered class is expected to implement the ``\TYPO3\CMS\Recordlist\Browser\ElementBrowserInterface`` interface.
--
GitLab