Feature Wiki

Information about planned and released features

Tabs

Customizable Online Help Packages

Page Overview

[Hide]

1 Requirements

The ILIAS Online Help should be customizable to the configuration and wording in a given productive platform.  Administrators should be able to change the online help package. To do so administrators will 

  1. customize the original package for the first time
  2. maintain customizations while updating ILIAS
  3. maintain customizations while updating the help package.

1.1 Administrators customize the original help package for the first time

Administrators can customize their original online help package doing one or more of the following 

  • Search and replace specific terms throughout the package 
  • Add, delete or edit the content of pages in the package
  • Changing titles of pages or chapters
  • Deactivating pages and chapters
  • Assign or de-assign screen-IDs  to chapters 
It is NOT required to change the original structure of the learning module by doing one or more of the following 
  • delete pages or chapters
  • move pages or chapters 
  • add  pages or chapters (Antonia wants it though)

To meet the maintenance requirements we suggest to ID all pages and chapters of the honline help package starting with 5.2. 

1.1.1 Search and replace specific terms throughout the package (Must have)

The online help package corresponds with the language file of the official ILIAS major release. If a local language file is employed at the given installation, the help and the interface will not match. The help has to be edited to match the local language file or small patches.

  1. Administrators open the online help learning module in their ILIAS installation's administration for editing. 
  2. Administrators enter a search term i.e. "Repository" / "im Magazin".
  3. ILIAS lists of all those chapter titles or pages comprising the search term. 
  4. Administrators enter a replacement term for the search term, i.e., "Learning Content" / "in 'Lerninhalte'".
  5. Administrators can replace the search term by the replacement term
    • Administrators can bulk replace all instances of the search term at once [Replace all]
    • Administrators can replace every instance of the search term individually [Replace and move on to next]
  6. ILIAS saves the customized help package.
  7. Administrators activate customized help package. 

1.1.2 Other Customizations  (Must have)

Administrators have more requirements: 

  • Change titles of chapters or pages: If a page is completely re-purposed to include highly relevant information on legal requirements, campusmanagesment Interfaces or authentifaction matters. This is needed, when ILIAs is integrated with other tools and information about this connection is to be imparted to users. 
  • Add, edit or delete the content of a page: Changing pages to reflect the workflows of patched functionality i.e. My Workspace at the University of Cologne. 
  • Deactivate pages and chapters: Hiding texts about functionality that is switched of or patched away at the platform i.e. copying at the University of Cologne. 
  • Assign or de-assign screen-IDs: To re-purpose chapters they are sometimes needed to be displayed in new places. 
  1. Administrators open the online help learning module in their ILIAS installation's administration for editing. 
  2. Administrators open a page and add, edit or delete the content of a page. 
  3. Administrators change titles of chapters or pages.  
  4. Administrators deactivate pages and chapters.
  5. Administrators assign screen-IDs to a chapter.
  6. Administrators save the customized help package.
  7. Administrators activate customized help package. 

1.1.3 Logging Customizations

Administrators need a log about the changes they made. The changes should be logged and the log should be stored

  • ID: ID of edited page or chapter
  • Date: date stamp when edit was made
  • User: Name of person who made the edit
  • Nature of edit: title edit, content edit, screen-ID edit
  • Content of edit: before and after 
  • reason for edit: to be filled in by editor 

1.2 Maintaining Customizations 

Please take from the counts below that from major release to major release the editorial team adds roughly 200 pages. The numer of pages changed is much higher than that: We guess that roughly a third to a half of all pages are edited. 

Release 3.0

Release 4.0

Release 4.1

Release 5.0

Kapitel zum Persönlichen Schreibtisch

12

13

13

13

Kapitel zum Magazin

27

29

32

33

Kapitel zum Querschnittsfunktionen

13

14

15

15

Kapitel zur Administration

37

43

43

43

Seiten im Lernmodul

1257

1464

1538

1679

Unterkapitel im Kurs

15

15

14

15

Unterkapitel im Test

68

75

76

79

Neue Features

nein

nein

links

nein

We have learned from people that customized their help, that they have changed 30 to 50 pages. 

1.2.1 Maintain customizations while updating ILIAS

Updating ILIAS should not temper the customizatons made to help package locally.  What might come with a new ILIAS release?

Change relevant to customized help package

Maintenance requirement 

Pre-existing screen-IDs changed to a new name (example: Page Editor Screen-ID was the same for all Page Editors, then we made a special one for the wiki and one for all others)

Administrators could be notified about this rather rare event. (nice to have) Administrators could assign the re-named screen-IDs to chapters.

New features come with new screen-IDs  

None: New screen-IDs would not change the availability of the existing help texts. There is no new text available before the release of a new help package. 

New screen-IDs are added to existing features because they lacked screen-IDs before

 None: New screen-IDs would not change the availability of the existing help texts. There is no new text available before the release of a new help package. 

1.2.2 Maintain customizations while updating the help package

Administrators would install a new help package along with their customized one. Administrators open their log and check whether the edits they made last time are still required / vaild.

  1. Administrators open their log and click on the ID of the first edit.
  2. ILIAS opens a comparison page contrasting the page ID x of the customized help and the page of the ID x of the new help package next to each other. Changes, omissions and additions are highlighted. 
  3. Administrators can choose to overwrite the page in the new package with the customized one. A fresh log is started. Administrators can choose to keep the new page and not make any changes. Administrators can edit the new page. 
  4. ILIAS somehow gets back to the log that the administrator worked from. 
  5. Administrator click on the next ID.....

Administrators can view additions lists: 

  • List of new pages: Pages with IDs that are not contained in the customized version are listet. 
  • List of Screen-IDs: List of new Screen-IDs, Screen-IDs that died, diferences in assignments 

2 Additional Information

  • Idea / concept: Alexandra Tödt toedt (at) leifos.com
  • Funding: Required
  • Maintainer: Alexander Killing
  • Development: Feature is to be developed by
  • Testcases:
  • Tested by:

3 Discussion

JF 7 Jan 2013: We agree that a customization of the help packages is needed in the long run. As the online help has just been released with 4.3 we need to collect user experiences in the next months first. It may be necessary to make some fundamental changes to the concepts and this should be done before we add customization features in the core. So we keep this discussion open for now but the implemenation of it may be more a 4.5 feature than a 4.4 feature.
 
Please collect cases of your customization needs on this page (similar to the "repository" renaming case).

Fred Neumann, January, 6th, 2013:
I propose to support the editing of online help packages in all installations. Forcing people to use a central installation for this seems rather restrictive to me. If new features are implemented for that, why shouldn’t they be available to all?
In fact, with a few step it is already possible to edit an imported help package in your own installation:

  • Create a reference for the online help learning module in the repository tree
  • Add this ref_id as setting OH_REF_ID under [system]  in the client.ini.php
  • Change the module_id  of this module in the tables help_module, help_map and help_tooltip to 0.
We will customize the online help of StudOn this way and I can provide a patch for that. But I think this should be possible without a patch and I see the challenge to keep track of the customizations and to re-apply them when a new help package is installed. Therefore I propose the following features:
  • The help packages should be editable directly in the online help administration.
  • It should be possible to export/import the tooltips as CSV file. This way they can be easily edited and compared with other versions, using external tools.
  • It should be possible to compare local modifications of help pages with those in the original. The learning module history can be used to identify the pages with local customizations. Comparing their page content with the corresponding pages of a newly imported official package would identify those, which are changed there, too. An overview should list those pages. Perhaps it’s possible to create an automated “merged” page. Conflicting page blocks would be included both, one of them as disabled. This merging could be a useful general feature of learning modules.

JF 7 Jan 2013: We agree that a customization of the help packages is needed in the long run. As the online help has just been released with 4.3 we need to collect user experiences in the next months first. It may be necessary to make some fundamental changes to the concepts and this should be done before we add customization features in the core. So we keep this discussion open for now but the implemenation of it may be more a 4.5 feature than a 4.4 feature.
 
Please collect cases of your customization needs on this page (similar to the "repository" renaming case).

AT May 2014: I have thought about Florians suggestion and I do like it.

4 Implementation

...

Last edited: 3. Feb 2016, 17:47, Tödt, Alexandra [atoedt]