1User Experience Service (Working-Title) 2====================================== 3 4# Purpose 5The GlobalScreen service offers ILIAS components and plugins the possibility to 6contribute elements to the layout of the page. The service should not be 7confused with the UI service that controls the actual display of elements. The 8GlobalScreen service offers abstractions of specific and unique page elements, 9such as entries in the main menu. 10 11A component or a plugin can offer such elements via so-called providers. 12Collectors collect these elements at a point in time x and have them rendered 13with UI elements of the UI service. More about the collectors below. 14 15GlobalScreen elements therefore do not contain HTML or other forms of 16visualization at any time, but merely mediate between a component and the point 17that renders and places these elements in the correct place using the UI 18service. 19 20# How to use it 21 22## Providers 23Suppose one of the badges component wants to provide an entry for the main 24menu. It implements an `ILIAS\GlobalScreen\Provider\StaticProvider` with the 25methods `getStaticSlates()` and `getStaticEntries()`. 26 27Since the component does not return its own slates, an empty array can be 28returned in `getStaticSlates()`. `getStaticEntries()`, however, returns a new 29entry in the form: 30 31 32```php 33 34return 35[$this->gs->mainmenu()->link($this->gs->identification()->internal('mm_pd_badges')) 36->withTitle($lng->txt("obj_bdga")) 37->withAction("ilias.php?baseClass=ilPersonalDesktopGUI&cmd=jumpToBadges") 38->withParent(...[get the identification of the PD-TopParentItem]...) 39->withAvailableCallable( 40function () { 41return (bool)(ilBadgeHandler::getInstance()->isActive()); 42} 43)]; 44``` 45`->withParent()` defines the default parent (e.g. a slate). However, depending 46on the configuration in the installation, this will be overwritten later by the 47configured parent. 48 49### Static vs. Dynamic 50For the StaticMainMenuProvider - but probably also for other GlobalScreen 51components - there are two different types of providers. Most components will 52use StaticProviders. These provide elements for the GlobalScreen (e.g. slates 53and menu entries), which are collected once during installation or an update of 54ILIAS and are stored "statically" in the database with their identifiers. These 55GlobalScreen elements are thus always statically available to ILIAS, whether 56they are displayed depends on various other properties (see 57withAvailableCallable, withVisibilityCallable). The static elements can also be 58adapted via a configuration in the ILIAS Administration, e.g. by renaming or 59changing the order. 60 61DynamicProviders, on the other hand, will in future provide GlobalScreen 62elements that are only available at a certain point in time, such as the tools 63that are displayed context-dependently. The documentation for tools is only 64added when the tools are implemented. 65 66### How to implement your provider 67Whether a component has GlobalScreen providers is determined by entries in 68`service.xml` or `module.xml`. The following entry is added, e.g.: 69```xml 70<gsproviders> 71<mainmenu class_name="ilBadgeGlobalScreenProvider"/> 72</gsproviders> 73``` 74As many providers as desired can be registered. These can implement one or more 75of the available provider interfaces, e.g..: 76```php 77use ILIAS\GlobalScreen\Provider\DynamicProvider\DynamicMainMenuProvider; 78use ILIAS\GlobalScreen\Provider\StaticProvider\StaticMainMenuProvider; 79 80class ilBadgeGlobalScreenProvider implements StaticMainMenuProvider, 81DynamicMainMenuProvider { 82... 83} 84``` 85 86## Identification 87### Core 88All elements in the GlobalScreen service must be identifiable for the supplying 89components mentioned above. The GlobalScreen service uses this identification, 90for example, for parent/child relationships. The identification is also 91forwarded to the UI service or to the instance that then renders the 92GlobalScreen elements. This means that the identification can be used there 93again, for example, to generate unique IDs for the online help. 94 95Identifications can be retrieved in a provider as follows, for example: 96```php 97// assuming $this is a provider 98$id = $this->gs->identification()->core($this)->identifier('my_internal_id'); 99``` 100### Plugins 101There is a special Identification for Plugins which can be get as follows: 102```php 103// assuming $this is a provider and $pl is a ilPlugin-child 104$id = $this->gs->identification()->plugin($pl, 105$this)->identifier('my_internal_id'); 106``` 107 108## Collectors 109In most cases, you won't need to implement a collector. For the 110StaticMainMenuProvider, for example, the necessary collectors (MainMenuMainCollector-Collector, 111which combines all necessary elements from the collectors "Plugins" and "Core") 112are already implemented in GlobalScreen\Collector\MainMenu. 113 114# Usage in Plugins 115All Plugin-types in ILIAS are capable of using the GlobalScreen-Service 116(currently Mainmenu-Items). All activated Plugins are asked for their providers, 117an empty provider is returned per default. If you want to provide items and even 118types, just override the method promoteGlobalScreenProvider() in your 119Plugin-Class, e.g.: 120```php 121public function promoteGlobalScreenProvider(): AbstractStaticPluginMainMenuProvider { 122 global $DIC; 123 124 return new ilGSDProvider($DIC, $this); 125 } 126``` 127A working sample can be found at https://github.com/studer-raimann/GlobalScreenDemo.git 128This is not a new Plugin-Slot, this is just an addition to all existing Plugin-Slots.