[BUGFIX] Update wrong title of rst file
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-69814-ModuleTemplateAPI.rst
1 ====================================
2 Feature: #69814 - ModuleTemplate API
3 ====================================
4
5 Challenge
6 =========
7
8
9 Currently all DocHeaders are implemented on their own.
10
11 This means we have about 80 DocHeaders which are equal but not the same.
12
13 The main challenge is to provide extension developers with all tools they need to build decent backend modules while maintaining control of the docHeader itself.
14
15
16 Solution
17 ========
18
19 We will provide a replacement for DocumentTemplate which provides an easy-to-use API which is on the other hand flexible enough to tackle all tasks we currently think of.
20
21 At the same time we will remove the amount of duplicate marker based templates.
22
23 The API uses the Fluent-API approach and has been built to supply maximum IDE code completion support.
24
25 Parts of a docHeader Currently a typical docHeader is split up into the following sections:
26
27 * Top Bar
28
29   * Context Sensitive Help Icon
30   * Select Menu(s)
31   * Path
32   * RecordInformation incl. Clickmenu
33
34 * Bottom Bar
35
36   * Left Button Bar
37   * Right Button Bar
38
39
40 API Components
41 ==============
42
43 Buttons
44 -------
45
46 **InputButton**
47     Used to generate a <button> element.
48
49 **LinkButton**
50     Used to generate links
51
52 **SplitButton**
53     A mixed component accepting multiple button objects and renders them into a condensed form.
54
55 **FullyRenderedButton**
56     Displays arbitrary HTML code and we highly recommend to use these.
57
58 Menus
59 -----
60
61 Creating menus is pretty simple.
62 Ask the ``DocHeaderComponent`` for the ``MenuRegistry`` and ask the ``MenuRegistry`` to create a ``Menu`` for you.
63
64 The ``Menu`` in return can create ``MenuItems`` for you.
65
66 A ``Menu`` can have several **Types** which are represented by their respective Fluid Partials in EXT:backend/Resources/Private/Partials/Menu/.
67
68
69 Examples of usages
70 ==================
71
72 **Adding a button**
73
74 .. code-block:: php
75
76     $openInNewWindowButton = $this->moduleTemplate->getDocHeaderComponent()->getButtonBar()
77         ->makeLinkButton()
78         ->setHref('#')
79         ->setTitle($this->getLanguageService()->sL('LLL:EXT:lang/locallang_core.xlf:labels.openInNewWindow', TRUE))
80         ->setIcon($this->iconFactory->getIcon('actions-window-open', Icon::SIZE_SMALL))
81         ->setOnClick($aOnClick);
82
83     $this->moduleTemplate->getDocHeaderComponent()->getButtonBar()
84         ->addButton($openInNewWindowButton, ButtonBar::BUTTON_POSITION_RIGHT);
85
86 **Adding a menu with menu items**
87
88 .. code-block:: php
89
90     $languageMenu = $this->moduleTemplate->getDocHeaderComponent()->getModuleMenuRegistry()->makeMenu()
91         ->setIdentifier('_langSelector')
92         ->setLabel($this->getLanguageService()->sL('LLL:EXT:lang/locallang_general.xlf:LGL.language', TRUE));
93     $menuItem = $languageMenu->makeMenuItem()
94         ->setTitle($lang['title'] . $newTranslation)
95         ->setHref($href);
96     if((int)$lang['uid'] === $currentLanguage) {
97         $menuItem->setActive(TRUE);
98     }
99     $languageMenu->addMenuItem($menuItem);
100     $this->moduleTemplate->getDocHeaderComponent()->getModuleMenuRegistry()->addMenu($languageMenu);
101
102
103 ButtonBar Hook
104 ==============
105
106 The old module rendering knew a ``$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['typo3/template.php']['docHeaderButtonsHook']`` hook
107 to manipulate buttons. A similar hook is available in ModuleTemplate API as ``$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['Backend\Template\Components\ButtonBar']['getButtonsHook']``.
108
109 **Registering your own hook**
110
111 .. code-block:: php
112
113     $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['Backend\Template\Components\ButtonBar']['getButtonsHook']['MyExt'] =
114         \MyVendor\MyExt\Hooks\ButtonBarHook::class . '->getButtons';
115
116 **Example usage of the hook**
117
118 .. code-block:: php
119
120     class ButtonBarHook {
121
122         /**
123          * Get buttons
124          *
125          * @param array $params
126          * @param ButtonBar $buttonBar
127          * @return array
128          */
129         public function getButtons(array $params, ButtonBar $buttonBar) {
130             $buttons = $params['buttons'];
131
132             $iconFactory = GeneralUtility::makeInstance(IconFactory::class);
133             $button = $buttonBar->makeLinkButton();
134             $button->setIcon($iconFactory->getIcon('my-custom-icon', Icon::SIZE_SMALL));
135             $button->setTitle('My custom docHeader button');
136             $button->setOnClick('alert("Hook works");return false;');
137
138             $buttons[ButtonBar::BUTTON_POSITION_LEFT][1][] = $button;
139
140             return $buttons;
141         }
142     }