7950c2749fe49726877af294e80aff17a36a431e
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-69814-ModuleTemplateAPI.rst
1 ==================
2 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 Solution
16 ========
17
18 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.
19
20 At the same time we will remove the amount of duplicate marker based templates.
21
22 The API uses the Fluent-API approach and has been built to supply maximum IDE code completion support.
23
24 Parts of a docHeader Currently a typical docHeader is split up into the following sections:
25
26 * Top Bar
27
28 * Context Sensitive Help Icon
29 * Select Menu(s)
30 * Path
31 * RecordInformation incl. Clickmenu
32
33 * Bottom Bar
34
35 * Left Button Bar
36 * Right Button Bar
37
38 API Components
39 ==============
40
41 Buttons
42 -------
43
44 **InputButton**
45 Used to generate a <button> element.
46
47 **LinkButton**
48 Used to generate links
49
50 **SplitButton**
51 A mixed component accepting multiple button objects and renders them into a condensed form.
52
53 **FullyRenderedButton**
54 Displays arbitrary HTML code and we highly recommend to use these.
55
56 Menus
57 -----
58
59 Creating menus is pretty simple.
60 Ask the ``DocHeaderComponent`` for the ``MenuRegistry`` and ask the ``MenuRegistry`` to create a ``Menu`` for you.
61
62 The ``Menu`` in return can create ``MenuItems`` for you.
63
64 A ``Menu`` can have several **Types** which are represented by their respective Fluid Partials in EXT:backend/Resources/Private/Partials/Menu/.
65
66
67 Examples of usages
68 ==================
69
70 **Adding a button**
71
72 .. code-block:: php
73
74 $openInNewWindowButton = $this->moduleTemplate->getDocHeaderComponent()->getButtonBar()
75 ->makeLinkButton()
76 ->setHref('#')
77 ->setTitle($this->getLanguageService()->sL('LLL:EXT:lang/locallang_core.xlf:labels.openInNewWindow', TRUE))
78 ->setIcon($this->iconFactory->getIcon('actions-window-open', Icon::SIZE_SMALL))
79 ->setOnClick($aOnClick);
80
81 $this->moduleTemplate->getDocHeaderComponent()->getButtonBar()
82 ->addButton($openInNewWindowButton, ButtonBar::BUTTON_POSITION_RIGHT);
83
84 **Adding a menu with menu items**
85
86 .. code-block:: php
87
88 $languageMenu = $this->moduleTemplate->getDocHeaderComponent()->getModuleMenuRegistry()->makeMenu()
89 ->setIdentifier('_langSelector')
90 ->setLabel($this->getLanguageService()->sL('LLL:EXT:lang/locallang_general.xlf:LGL.language', TRUE));
91 $menuItem = $languageMenu->makeMenuItem()
92 ->setTitle($lang['title'] . $newTranslation)
93 ->setHref($href);
94 if((int)$lang['uid'] === $currentLanguage) {
95 $menuItem->setActive(TRUE);
96 }
97 $languageMenu->addMenuItem($menuItem);
98 $this->moduleTemplate->getDocHeaderComponent()->getModuleMenuRegistry()->addMenu($languageMenu);