[BUGFIX] Refer to correct naming of link handler TSconfig option
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 7.6 / Feature-66369-AddedLinkBrowserAPIs.rst
1 ========================================
2 Feature: #66369 - Added LinkBrowser APIs
3 ========================================
4
5 Description
6 ===========
7
8 This new feature allows to extend the link browser with new tabs, which allow to implement custom link functionality
9 in a generic way in a so called LinkHandler.
10 Since the LinkBrowser is used by FormEngine and RTE, the new API ensures that your custom LinkHandler works with those
11 two, and possible future, usages flawlessly.
12
13 Each tab rendered in the link browser has an associated link handler, responsible for rendering the tab and for creating
14 and editing of links belonging to this tab.
15
16
17 Tab registration
18 ----------------
19
20 Link browser tabs are registered in page TSconfig like this:
21
22 .. code:: typoscript
23
24 TCEMAIN.linkHandler.<tabIdentifier> {
25 handler = TYPO3\CMS\Recordlist\LinkHandler\FileLinkHandler
26 label = LLL:EXT:lang/locallang_browse_links.xlf:file
27 displayAfter = page
28 scanAfter = page
29 configuration {
30 customConfig = passed to the handler
31 }
32 }
33
34 The options ``displayBefore`` and ``displayAfter`` define the order how the various tabs are displayed in the link browser.
35
36 The options ``scanBefore`` and ``scanAfter`` define the order in which handlers are queried when determining the responsible
37 tab for an existing link.
38 Most likely your links will start with a specific prefix to identify them. Therefore you should register your tab at least before
39 the 'url' handler, so your handler can advertise itself as responsible for the given link.
40 The 'url' handler should be treated as last resort as it will work with any link.
41
42
43 Handler implementation
44 ----------------------
45
46 A link handler has to implement the ``\TYPO3\CMS\Recordlist\LinkHandler\LinkHandlerInterface`` interface, which defines
47 all necessary methods for communication with the link browser.
48
49 Additionally, each link handler should also provide a Javascript module (requireJS), which takes care of passing a link
50 to the link browser.
51 A minimal implementation of such a module looks like this:
52
53 .. code:: javascript
54
55 define(['jquery', 'TYPO3/CMS/Recordlist/LinkBrowser'], function($, LinkBrowser) {
56
57 var myModule = {};
58
59 myModule.createMyLink = function() {
60 var val = $('.myElmeent').val();
61
62 // optional: If your link points to some external resource you should set this attribute
63 LinkBrowser.setAdditionalLinkAttribute('data-htmlarea-external', '1');
64
65 LinkBrowser.finalizeFunction('mylink:' + val);
66 };
67
68 myModule.initialize = function() {
69 // todo add necessary event handlers, which will propably call myModule.createMyLink
70 };
71
72 $(myModule.initialize);
73
74 return myModule;
75 }
76
77 Notice the call to ``LinkBrowser.finalizeFunction``, which is the point where the link is handed over to the link browser
78 for further processing and storage.
79
80
81 Hooks
82 -----
83
84 You may have the need to modify the list of available link handlers based on some dynamic value.
85 For this purpose you can register hooks.
86
87 The registration of a link browser hook generally happens in your ``ext_tables.php`` and looks like:
88
89 .. code:: php
90
91 if (TYPO3_MODE === 'BE') {
92 $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['LinkBrowser']['hooks'][1444048118] = [
93 'handler' => \Vendor\Ext\MyClass::class,
94 'before' => [], // optional
95 'after' => [] // optional
96 ];
97 }
98
99 The ``before`` and ``after`` elements allow to control the execution order of all registered hooks.
100
101 Currently the following list of hooks is implemented:
102
103 - modifyLinkHandlers(linkHandlers, currentLinkParts): May modify the list of available link handlers and has to return the final list.
104 - modifyAllowedItems(allowedTabs, currentLinkParts): May modify the list of available tabs and has to return the final list.