Feature Wiki
Tabs
Persisting Help IDs
Page Overview
[Hide]- 1 Initial Problem
- 2 Conceptual Summary
- 3 User Interface Modifications
- 4 Technical Information
- 4.1 Initial situation and history
- 4.2 The HelpScreenId
- 4.3 The HelpScreenIdObserver
- 4.4 General note
- 4.5 Outlook for UI components
- 4.6 Initial situation
- 4.6.1 Screen IDs
- 4.6.2 Tool-Tip IDs
- 4.7 Identifiability of elements and views
- 4.8 Types of Purposes
- 5 Privacy
- 6 Security
- 7 Contact
- 8 Funding
- 9 Discussion
- 10 Implementation
1 Initial Problem
Many Screen-IDs broke with ILIAS 6. We will have great changes again and this should be prevented in the future.
2 Conceptual Summary
The Help IDs need to stay and not be rattled by functional changes this easily. The IDs should be tied into the Global Screen Service.
3 User Interface Modifications
3.1 List of Affected Views
- none.
3.2 User Interface Details
No visible changes.
3.3 New User Interface Concepts
None.
3.4 Accessibility Implications
There are not accessibility issues forseen with persisting IDs.
4 Technical Information
4.1 Initial situation and history
For the online help, so-called screen IDs are used to make a page identifiable for the help. These screen IDs are currently set via ilHelpGUI using various methods from the called components:
- setDefaultScreenId (2 usages)
- setScreenId (39 usages)
- setSubScreenId (37 usages)
- setScreenIdComponent (104 usages)
For many places in ILIAS, however, no ID can be generated because the called components do not provide any information.
Therefore, a new system for identifying individual screens in ILIAS is to be implemented for ILIAS 9 and later. ilCtrl's call stack comes into play as the most reliable source of information. each view in ILIAS runs through a sequence of (command) classes in order to finally execute a specific command. ilCtrl therefore knows a unique structure for each view.
ilCtrl now allows you to attach yourself as an observer to the called classes as well as to the executed command in order to use this information (see README).
A first prototype has now been created for the online help on how the ID can be built in the future (e.g. for ILIAS 9). In a first step, an attribute HelpScreenId
was proposed. In addition, two further attributes RecurringHelpScreenId
and SilentHelpScreenId
were introduced, although these are intended more as an illustration of the other possibilities. According to feedback from the help maintainer, they would not be used. (See proposed HelpScreenId).
4.2 The HelpScreenId
This attribute has a slim name for the GUI class, e.g. ilPermissionsGUI
becomes 'permissions'
. The heuristics for these names are as follows:
- The GUI class name without il(Obj|Object) prefix and without GUI appendix.
- SnakeCase converted to camel_case
- Lower case
With the help of a Rector, this ID can be introduced once for each GU class, but individual places will certainly have to be adapted in the process. If possible, the rector also retains the values that were previously passed via setScreenIdComponent
. (See proposed Rectors)
All HelpScreenIds
are collected via a BuildArtifactObjective and stored in an artefact with their affiliation to a GUI class, see ilHelpBuildScreenIdMapObjective. The Objective can use the new UsagesOfAttributesFinder.
4.3 The HelpScreenIdObserver
With the help of the ilCtrlObserver, the corresponding screen ID is now built using the call stack together with the artefact of the HelpScreenIds. Finally, the executed command is used as the last element. (See HelpScreenObserver).
4.4 General note
This prototype now aims to ensure that the implementation of this ID takes place entirely in the help service and that it also determines the heuristics, how the IDs are initially built but also as a fallback. in general, this principle could be implemented at a later time or, if desired, already initially as a general screen ID, in which case the implementation would probably be in the GlobalScreen-Service or in UICore.
4.5 Outlook for UI components
With the introduction of HelpTopics in the UI service, new mechanisms are available, such as how the online help can bind information to individual elements (See here, not yet merged) . This principle should also be implemented for the UI\Page, which could then use the help ID.
4.6 Initial situation
Two types of IDs are currently relevant for online help:
4.6.1 Screen IDs
In the current versions of ILIAS, the current screen IDs (for individual views, e.g. rights tab in a wiki) are explicitly set by the maintainers of the respective components. The functions of the ilHelp service are available for this purpose:
1 | ilHelpGUI::setDefaultScreenId($a_part, $a_id) |
These methods must be called manually by the maintainers of a component in order to specify the current view more precisely and thus to be able to offer the online help a screen ID to which the corresponding help texts refer.
If no screen ID is set in a component, there is currently no concrete indication for the online help as to which view the user is on and thus no or only unspecific help texts can be displayed.
4.6.2 Tool-Tip IDs
The tooltips (and in future also other features such as Guided Tour) currently refer to CSS IDs or, since the changeover to UI\Page, to other CSS selectors. Tooltips are always displayed specifically for an element on the current page. Therefore, the HTML elements to which tooltips refer must be clearly identifiable.
With the switch to UI components, more and more specific (self-named) CSS IDs are being dropped. The UI service uses generic CSS IDs and no own CSS IDs assigned by the maintainers are used, e.g. to avoid collisions when assigning CSS IDs and to make JavaScript code not dependent on CSS IDs. The concept and the reasons behind it are generally important and correct, but make the work of the online help or Guided Tour features much more difficult.
4.7 Identifiability of elements and views
4.7.1 Sreen-IDs for all Views
The GlobalScreen service provides an interface between components and the final output and rendering of a page. For example, tools, menu items or other elements of the global page structure can already be supplied by a component, the GS service manages these and passes them on to the rendering of a page.
With the introduction of tools, a so-called ScreenContext was already introduced. This contains information about the current views, but so far only very little and only to give tools the possibility to be displayed context-sensitively.
The ScreenContext should be able to provide much more information to support client-side features such as the online help and Guided Tour, in order to be able to operate the help service with reliable screen IDs that exist on every view. In addition to a unique ID generated for each page, it should also be possible to request further information, such as the RBAC context (does the current user have write or read-only rights?).
For this purpose, the ScreenContext introduces new general pattern called "Purpose". A "Purpose" indicated what an element of a whole view is about. A distinction is made between MainViewPurpose and ViewPurpose.
Some examples:
As long as you are in a Wiki, the MainViewPurpose is the "Wiki". Depending on the view, other ViewPurposes appear below the "Wiki" Purpose, such as "Editor" or "Edit", or "Rights", "Export", ...
A wiki can also be found in the MainViewPurpose "Repository" or within a course. From the point of view of a screen ID, however, MainViewPurposes always represent the first level. A screen ID is therefore composed of
"Last MainViewPurpose (if any)" / "ViewPurpose" / "ViewPurpose" / ...
In principle, this is the same as the previous IDs, although there may be differences due to the implementation.
What mainly changes, however, is that each view must provide such Purposes. This will be taken care of by an interaction of the current routing (ilCtrl) together with the GlobalScreen service.
ilCtrl assigns interfaces for all executing GUI classes (aka CommandClasses and BaseClasses) in ILIAS with ILIAS 9. This interface will not provide any functionality for ilCtrl for the time being, but serves to identify such classes. Using the same mechanism as we implement a PurposeProvider-interface for all GUI classes, we also want to introduce an interface for all these classes in order to be able to request a "Purpose" from them.
In a first step, we will equip each class with a "helper" trait, which already provides a generic Purpose derived from the class name. For example, the ilPermissionsGUI can provide a ViewPurpose('permissions') without further adjustments of the maintainer. In this implementation, we will already take into account that, for example, an ilObjWikiGUI should provide a MainViewPurpose('wiki'), but other classes only a ViewPurpose('xy).
If we already find calls to ilHelpGUI::setScreenIdComponent in a class, we take over this value (in order to get screen IDs that are as consistent as possible).
In a further step, we ensure that the names of the Purposes are unique and that there is no ViewPurpose('permissions') in two different places, for example.
4.7.2 Individual elements such as buttons, MainBar entries, ...
In consultation with Richard Klees in his role as coordinator of the UI component, we would like to be able to implement the possibility of Purposes in the UI service as well. Individual UI components (a list of which is still being worked out, but buttons and slates, for example, must be able to be used) will receive a "withPurpose('specific_purpose_name')".
For example, a MainBar entry can receive the information that it belongs to the Purpose "dashboard_mainbar_item".
In the rendering, this HTML element can then receive an additional attribute data-purpose='dashboard_mainbar_item'. On the one hand, this attribute makes the element identifiable for features such as ToolTips, but on the other hand it can also be used to inform the ScreenContext (see above) that an element with an ElementPurpose('dashboard_mainbar_item') is displayed on the current page. The online help could also refer to this if necessary.
4.8 Types of Purposes
Class of Purpose | Meaning / Descripton | Examples |
---|---|---|
MainViewPurpose | As long as you stay in the same context, you stay in the same main purpose. A MainViewPuposes is always the first element of a help screen ID. A help screen ID always begins with the last MainViewPuposes that appears in the stack of called Purposes. | All modules (Wiki, Course, DataCollection, ...) or services such as the Dashboard, Calendar, etc. represent MainViewPuposes. As long as you move in tabs, "sub-worlds" or other views within a course, for example, the MainViewPurpose remains the same. |
ViewPurpose | All other views are then merely ViewPurposes. ViewPurposes are not stand-alone and are not a context of their own, but function within a context. | For example, settings pages or the rights tab only work within a context such as a module. Therefore they are ViewPurposes. |
ElementPurpose | Important and distinctive individual elements on the page can have a purpose. This makes it possible to reference this purpose on the client side. | Single, important buttons like "Add new Object" or "Edit Page". These have a very specific purpose, which may also need to be described by the online help or other client-side features. Modals can also have a very specific purpose, such as "conrfirm_delete_menu_subitem". |
5 Privacy
This feature does dot store personal data.
6 Security
This feature does not include any special security relevant changes.
7 Contact
- Author of the Request: Tödt, Alexandra [atoedt]
- Maintainer: Schmid, Fabian [fschmid], Killing, Alexander [alex]
- Implementation of the feature is done by: {The maintainer must add the name of the implementing developer.}
8 Funding
If you are interest in funding this feature, please add your name and institution to this list.
- …
9 Discussion
JourFixe, ILIAS [jourfixe], 26 JUN 2023 : We highly appreciate this suggestion and schedule the feature for ILIAS 9 with the following change: we do not implement the Rector in the first step but check first in which cases we need an attribute for the HelpScreenIds.
Schmid, Fabian [fschmid] 2023-06-30: The PR has been opened here: https://github.com/ILIAS-eLearning/ILIAS/pull/6092
Killing, Alexander [alex], 19 Aug 2024: Follow-up PR is here: https://github.com/ILIAS-eLearning/ILIAS/pull/7869
JourFixe, ILIAS [jourfixe], 19 AUG 2024 : We highly appreciate this suggestion and accept the feature for ILIAS 10.
10 Implementation
{ The maintainer has to give a description of the final implementation and add screenshots if possible. }
Test Cases
Test cases completed at {date} by {user}
- {Test case number linked to Testrail} : {test case title}
Approval
Approved at {date} by {user}.
Last edited: 19. Aug 2024, 15:19, Kunkel, Matthias [mkunkel]