[DOC] Add documentation for element and link browser API 47/44647/2
authorMarkus Klein <markus.klein@typo3.org>
Mon, 9 Nov 2015 18:11:38 +0000 (19:11 +0100)
committerChristian Kuhn <lolli@schwarzbu.ch>
Mon, 9 Nov 2015 20:22:51 +0000 (21:22 +0100)
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>
typo3/sysext/core/Documentation/Changelog/master/Breaking-66369-RemovedElementBrowserRelatedClasses.rst [new file with mode: 0644]
typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedLinkBrowserAPIs.rst
typo3/sysext/core/Documentation/Changelog/master/Feature-66369-AddedNewElementBrowserAPI.rst [new file with mode: 0644]

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 (file)
index 0000000..ff2d933
--- /dev/null
@@ -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.
index 1b55d72..7fe8fdd 100644 (file)
@@ -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 (file)
index 0000000..ea5d96c
--- /dev/null
@@ -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.