Show Advanced KnowledgeHide Advanced Knowledge

Refactoring ilTemplate

1 Initial Problem

The ilTemplate class plays a central role in the generation of the ILIAS UI. By careful examination one can identify at least seven, quite distinct, responsibilities of that class:

• It is the general templating class that needs to be instantiated whenever there is a template that needs to be rendered.
• It contains a static caching mechanism for all instances of the class.
• It provides functionality to generate the standard ILIAS-look. This responsibility could further be divided into the general page layout as also regarded in the Page Layout Revision and in the layout of the content area, which is not regarded by the Page Layout Revision. The responsibilities could be further subdivided into responsibilities like rendering the main menu, rendering the content header, etc.
• In its form as the global $tpl variable it also is a stash for names of CSS and Javascript files that need to be included in general or for specific views.
• In its form as the global $tpl variable it also is a stash for diverse layout-related settings, like headers, alerts, menues, etc.
• In its global form there are some settings that seem to be specifically designed to render divergent layouts for single components like the learning module or the blog.
• Finally, the show-method of the class defines the means by which the actual output of the application is generated, which is either done via the new HTTPService or the PHP print-statement.

To figure out all responsibilities and use cases of the class is a tedious exercise, as it is very often used as a global. The analysis is further complicated by the fact, that many of its methods aren’t tagged with an access qualifier.

Many of the use cases also seem to involve a call to the method getStandardTemplate, which loads another template that contains HTML for the content area of the standard ILIAS view. Many other methods in turn seem implicitly rely on the fact that getStandardTemplate was called before.

To implement the Page Layout in a clean manner, at least the part responsible for the page layout needs to be extracted and removed. Splitting the class into smaller parts along the different responsibilities will have positive effects for the class itself and for the complete system. The rendering logic of the UI-framework suggests that the class in its current form will need to be abandoned at some point, a refactoring will aloud to keep some parts while removing the others.

2 Conceptual Summary

We suggest to take the following actions:

1. Remove methods of ilTemplate that are not in use anymore.
2. Copy the current ilTemplate-class and introduce a new ilGlobalTemplate-class that is used to initialize the global ilTemplate-instance.
3. Since the remaining ilTemplate-class is used for rendering via instantiation by new only, it should be possible to remove the huge majority of methods. To get better control over the actual output of the application show should be among the removed methods.
4. The ilGlobalTemplate should be subject to a thorough analysis. The analysis done so far suggests, that several parts of the class are exclusively used by a handful of other classes. It might be beneficial to create further copies of ilGlobalTemplate and move these closer to their users. It should be possible to get rid of more methods of the class then.
5. The remaining ilGlobalTemplate should be refactored along the lines of the responsibilities outlined above. A thorough analysis might also reveal even more responsibilities. The existing class should be kept as a facade around new services that take care of the different responsibilities. The stripped down ilTemplate should be one of the classes that is used.
6. By introducing corresponding dicto-rules, users of the global ilTemplate should be encouraged to use the new services directly instead of the global instance of ilGlobalTemplate. The rules will also allow an assessment of the situation before finally the final implementation of the new page layout.

3 User Interface Modifications

3.1 List of Affected Views

{Please list all views (screens) of ILIAS that should be modified, newly introduced or removed.}

3.2 User Interface Details

{For each of these views please list all user interface elements that should be modified, added or removed. Please provide the textual appearance of the UI elements and their interactive behaviour.}

3.3 New User Interface Concepts

{If the proposal introduces any completely new user interface elements, you might consult UI Kitchen Sink in order to find the necessary information to propose new UI-Concepts. Note that any maintainer might gladly assist you with this.}

4 Technical Information

Klees, Richard [rklees], 2018-09-13: During the implemantation of PR 1184 I used this excel to understand the usage of methods from ilGlobalTemplate throughout the system. Please note, that this reflects the state of affairs at a certain point in time and was created only half-automatically. So use at your own risk. A "1" means, that a class uses a method, while a "0" means, that a class used to use a method, but doesn't anymore since the introduction of a specialized version of ilGlobalTemplate.

5 Contact

• Author of the Request: {Please add your name.}
• Maintainer: {Please add your name before applying for an initial workshop or a Jour Fixe meeting.}
• Implementation of the feature is done by: {The maintainer must add the name of the implementing developer.}

6 Funding

If you are interest in funding this feature, please add your name and institution to this list.

• …

7 Discussion

8 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}.