README.md
1# UIComponent Service
2
3The UI Component Service provides wrappers for several UI Components to be re-used. Note that many of those components
4have been deprecated, since we are migrating much of the content of this service to src/UI. If you feel that you need
5to use one of those components nevertheless for new developments, maybe think about providing a PR to src/UI to add the
6missing feature. This would be highly appreciated.
7
8## UserInterfaceHook Pluginslot
9This plugin slot has been published as stable with ILIAS 4.2. The goal of the user interface plugin slot is to allow simple
10 modifications of standard components of the ILIAS user interface. The slot is defined by the UIComponent Service of ILIAS
11 and named "UserInterfaceHook". This means all plugins have to be installed into directories at:
12
13`Customizing/global/plugins/Services/UIComponent/UserInterfaceHook/<Plugin_Name>`
14
15The ID of the UIComponent Service is "ui", the ID of the slot is "uihk". These are used as prefixes together with your
16plugin id for database tables and for language variable identifiers:
17
18DB Table / Language VariablePrefixes: `ui_uihk_<Plugin_ID>_`
19
20## Plugin Directory Structure
21A user interface plugin has the following minimum file/directory structure:
22```
23<PluginName> (Directory)
24 classes (Directory)
25 class.il<PluginName>Plugin.php
26 class.il<PluginName>UIHookGUI.php
27 plugin.php
28```
29
30### ilPluginNamePlugin.php
31Default Structure:
32
33```
34<?php
35
36require_once __DIR__ . "/../vendor/autoload.php";
37
38/**
39 * Previously there was not that much to do here except defining the Plugins name.
40 *
41 * Since the introduction of the Global Screen, this can be also used however, to manipulate the Main Menu of ILIAS.
42 * Note that this does not only work for ilUserInterfaceHookPlugin plugins, but for all plugins descending ilPlugin.
43 *
44 * Class ilPluginNamePlugin
45 */
46class ilPluginNamePlugin extends ilUserInterfaceHookPlugin {
47 /**
48 * @inheritdoc
49 */
50 function getPluginName() {
51 return 'UIHookDemo';
52 }
53
54 /**
55 * This method is used to promote a plugins own GlobalScreen provider. With such a provider, one can easily
56 * extend parts of the Global Screen such as the Main Menu. Note that this method is available for all types
57 * of plugins.
58 *
59 * @return AbstractStaticPluginMainMenuProvider
60 */
61 public function promoteGlobalScreenProvider(): AbstractStaticPluginMainMenuProvider {
62 return new ilPluginGlobalScreenNullProvider();
63 }
64
65 /**
66 * This methods allows to replace the UI Renderer (see src/UI) of ILIAS after initialization
67 * by returning a closure returning a custom renderer. E.g:
68 *
69 * return function(\ILIAS\DI\Container $c){
70 * return new CustomRenderer();
71 * };
72 *
73 * Note: Note that plugins might conflict by replacing the renderer, so only use if you
74 * are sure, that no other plugin will do this for a given context.
75 *
76 * @param \ILIAS\DI\Container $dic
77 * @return Closure
78 */
79 public function exchangeUIRendererAfterInitialization(\ILIAS\DI\Container $dic):Closure{
80 //This returns the callable of $c['ui.renderer'] without executing it.
81 return $dic->raw('ui.renderer');
82 }
83
84 /**
85 * This methods allows to replace some factory for UI Components (see src/UI) of ILIAS
86 * after initialization by returning a closure returning a custom factory. E.g:
87 *
88 * if($key == "ui.factory.nameOfFactory"){
89 * return function(\ILIAS\DI\Container $c){
90 * return new CustomFactory($c['ui.signal_generator'],$c['ui.factory.maincontrols.slate']);
91 * };
92 * }
93 *
94 * Note: Note that plugins might conflict by replacing the same factory, so only use if you
95 * are sure, that no other plugin will do this for a given context.
96 *
97 * @param string $dic_key
98 * @param \ILIAS\DI\Container $dic
99 * @return Closure
100 */
101 public function exchangeUIFactoryAfterInitialization(string $dic_key, \ILIAS\DI\Container $dic):Closure{
102 //This returns the callable of $c[$key] without executing it.
103 return $dic->raw($dic_key);
104 }
105}
106```
107
108### class.ilPluginNameUIHookGUI.php
109Note that the methods of this class are depricated since ILIAS 6.0. Only use if absolutely necessary. Note that
110many scenarios might be better served by using the Global Screen Service or the UI Components (See above method).
111
112```
113<?php
114require_once __DIR__ . "/../vendor/autoload.php";
115
116/**
117 * This is where the actual magic of the GUI modifications take place.
118 *
119 * Class ilPluginNameUIHookGUI
120 */
121class ilPluginNameUIHookGUI extends ilUIHookPluginGUI
122{
123
124 /**
125 * @deprecated Note this method is deprecated. There are several issues with hacking into already rendered html
126 * as provided here:
127 * - The generation of html might be performed twice (especially if REPLACE is used).
128 * - There is limited access to data used to generate the original html. If needed this data needs to be gathered again.
129 * - User Interface components are migrated towards the UIComponents and Global Screen which do not make use of the
130 * mechanism provided here.
131 *
132 *
133 * Modify HTML output of GUI elements. Modifications modes are:
134 * - ilUIHookPluginGUI::KEEP (No modification)
135 * - ilUIHookPluginGUI::REPLACE (Replace default HTML with your HTML)
136 * - ilUIHookPluginGUI::APPEND (Append your HTML to the default HTML)
137 * - ilUIHookPluginGUI::PREPEND (Prepend your HTML to the default HTML)
138 *
139 * @param string $a_comp component
140 * @param string $a_part string that identifies the part of the UI that is handled
141 * @param array $a_par array of parameters (depend on $a_comp and $a_part), e.g. name of the used tpl.
142 *
143 * @return array array with entries "mode" => modification mode, "html" => your html
144 */
145 function getHTML($a_comp, $a_part, $a_par = array())
146 {
147 //...
148 return array("mode" => ilUIHookPluginGUI::KEEP, "html" => "");
149 }
150
151
152 /**
153 * @deprecated Note this method is deprecated. User Interface components are migrated towards the UIComponents and
154 * Global Screen which do not make use of the mechanism provided here. Make use of the extension possibilities provided
155 * by Global Screen and UI Components instead.
156 *
157 * In ILIAS 6.0 still working for working for:
158 * - $a_comp="Services/Ini" ; $a_part="init_style"
159 * - $a_comp="" ; $a_part="tabs"
160 * - $a_comp="" ; $a_part="sub_tabs"
161 *
162 * Allows to modify user interface objects before they generate their output.
163 *
164 * @param string $a_comp component
165 * @param string $a_part string that identifies the part of the UI that is handled
166 * @param array $a_par array of parameters (depend on $a_comp and $a_part)
167 */
168 function modifyGUI($a_comp, $a_part, $a_par = array())
169 {
170 /**
171 * Tabs are not migrated to the UI Components/Global Screen, so they still might be manipulated here.
172 *
173 * Note that you currently do not get information in $a_comp
174 * here. So you need to use general GET/POST information
175 * like $_GET["baseClass"], $ilCtrl->getCmdClass/getCmd
176 * to determine the context.
177 */
178 if ($a_part == "tabs" && $_GET["UIDemo"] == "addTab")
179 {
180 /**
181 * @var $tabs ilTabsGUI
182 */
183 $tabs = $a_par["tabs"];
184 $tabs->addTab("NewTabId","New Tab","#");
185 }
186 }
187
188}
189```
190
191### Example Plugin
192A working example for ILIAS 6.0 can be found at: https://github.com/Amstutz/UIHookDemo
193
194The example show how to:
195* Add Tabs by modify GUI
196* Replace the Metabar of ILIAS by Using getHTML
197* Render parts of the page as json
198* Add a new Item the the Main Bar of ILIAS (aka Main Menu)
199
200There is also an advanced demo of how the Main Menu can be extended by using the new Global Screen service. The
201extension adds top items that can be shown if a set of global roles is attached to the current user. You can see this
202additional type in the Administration > Main Menu by adding a new Top Item.
203