Icon Wiki

Feature Wiki

Information about planned and released features


KS: Integration in Layout and Styles

1 Requirements

1.1 Background

The Guidelines generated by the UI Kitchen Sink Project need to find a home.  In the last Jour Fixe Meeting we agreed, that this home could be the ILIAS core Special Jour Fixe for Kitchensink. This FR is the result of the feedback that gathered during this last meeting.

1.2 Goals

With the KS integration into the ILIAS Core we seek for:
  • Developers to have easy access to needed documentation.
  • Designers to have an much simplified way of customizing ILIAS.
  • Admins to have a possiblity to create ILIAS skins without touching any files.

1.3 Concept


1.3.1 Short Version

System Styles should be changable through the administration in the same way content styles are. The KS entries serve as documentation of this. 

1.3.2 System Styles

The Page System Style (Administration -> Layout and Styles) would look as follows with this new feature:
Note the following changes:
  • New Default Button: Add Style to create a new System Style in the toolbar
  • New Link (evtl. link in Dropdown) in action column of table: Edit to edit an existing style
  • By clicking Add Style a new System Style will be created (see pattern adding a new "Content Style")
  • By clicking on the title or edit button of the freshly created style we enter a submenu with the tabs: Settings, Less, Icons, Documentation
  • If the Delos style is selected, we will be in a read only mode, since this style can not be changed. 
  • If the webserver does not have write access to the /Customizing/global/skin/ Folder, we display a system feedback to inform the user about this and to not display the 'Add Style' button. If a style is opened, the user will be in a read only mode.
Persistent Store:
  • All persistent information is stored directly on the file system in the skin directory of the Customizing folder (not in the databasee). 
  • Less variables can only be edited if:
    • Lessc (compiler for less) is installed on the server.
    • The style contains a variable.less file that is included in the main less file of the style (named: myStyleName.less).
  • Creating a new style creates the following file structure (if not exists):
    • Customizing/global/skin/mySkinName/
      • template.xml
      • mySkinName.less (includes variable.less and delos.less and indicates some place to include further style specific less files if needed.
      • mySkinName.css (compiled version of mySkinName.less)
      • ./less
        • variables.less (exact copy of default variable.less of ILIAS)
      • ./myImagesFolderName (contains all images from the default skin, ready to be changed)
      • ./fonts (contains all fonts from the default skin)
  • Modifying an existing skin will create the same structure in the existing folder.
    • The name of the images folder is parsed out of the template.xml.
    • Users will be warned, that images will be overritten on modification.
    • Users will be warned, that variables.xml will be overritten on modification
  • mySkinName.less nee
  • One new permissions need to be added for this screen: "Edit System Styles" to change existing system styles. The requires a slight reorganization of the permissions for the layout section in the administration.
  • Current permissions:
    • Visible: Layout and Styles administration is visible
    • Read: User has read access to Layout and Styles administration
    • Edit Settings: User can edit settings in Layout and Styles administration
    • Change Permissions: User can change permission settings of Layout and Styles administration
  • Proposed permissions:
    • Visible: Layout and Styles administration is visible
    • Read: User has read access to Layout and Styles administration
    • Modify System Styles: User can edit/create/delete System Styles
    • Modify Content Styles: User can edit/create/delete Content Styles
    • Modify Page Layouts: User can edit/create/delete Page Layouts
    • Change Permissions: User can change permission settings of Layout and Styles administration

1.3.3 New Subsection

The new subsection has the Tabs "Settings", "Less", "Icons" and "Documentation". It still caries the title of the System Style in focuswith the matching Icon (see behaviour in 'Content Styless').
The content of the individual tabs is explained in the following subsections:
Contains a form to enter the basic settings of the new style needed to create the template.xml file and some additional settigns. Namely:
  • id (Text Input)
  • Title (Text Input)
  • Description (Text Input)
  • image directory (Text Input)
  • default (checkbox)
  • active (checkbox)
  • nr. of users (static information)
A form containing an input element for all less variables in the variables.less file grouped by the categories listed in the variables.less file of ILIAS along with a description (if provided in the variables.less file) and the usages of the variables in KS entries.

The form has the following actions:
  • Update: Recompiles less and creates an new CSS for the style.
  • Reset to Delos: Resets all variables to their default and compiles the less code.
  • Export: Exports the variables of the style to a "variables.less" file to download.
  • Import: Imports a variables.less file and sets the values of the form accordingly.
A form containing a color picker for each occuring color in the icons including an indication which icons use a certain color in the description along with a list of thumbnails displaying all icons.

The form has the following actions:
  • Update: Changes the color of all icons in the images folder of the skin (if it does not exist, the default images folder will be copied)
  • Reset to Delos: resets all colors to their default values
  • Export: Exports the colors of the icons of the style to a "colors.json" file to download 
  • Import: Imports a colors.json file and sets the values of the form accordingly.
This is the page containing all the KS-Content as presented by the KS-Plugin in the Special Jour Fixe for Kitchensink
On the left side, a tree displays the structure of the KS-Entries. Each entry can be selected by clicking on it. 

In the center there is a toolbar on top, allowing to reload the entries (might be needed after an update, all data needs to be parsed again).

Bellow the toolbar the entry is displayed with the aspects listed in the Template and Organisation of KS-Inventory:
Note that the less variables can be clicked upon, which link directly the the corresponding input element in the less form.

2 Additional Information

  • Idea / concept: Amstutz, Timon [amstutz]
  • Interest in funding: Universität Bern
  • Maintainer: (will be set by Jour Fixe / maintainer)
  • Implementation of the feature is done by (will be set by Jour Fixe / maintainer)
  • Testcases by: (please add your name if you want to create the testcases for this feature)

3 Discussion

JourFixe, ILIAS [jourfixe], March 14, 2016: We appreciate Timon's suggestion and decided:
  • Styles should be editable by an Action button instead of clicking on the title.
  • We need a clear description for the data handling of Skins in the Customizing directory. @ Timon: please make a suggestion how and where the files are stored. This is a requirement for a final decision of the feature request.
  • Delete action should be supported for the Customizing » local ... directory but not for Customizing » global.
  • We would like to have dedicated permissions for "Edit System Style" and "Edit Content Style". Please define which actions are possible with write permission on Layout administration node.
Amstutz, Timon [amstutz], April 6, 2016: I tried to make a concept to only edit the styles for the current client (Customizing -> local). As far as Icon see there is currently no concept for local styles (styles available for only one client), is that correct?

If so, we either have to introduce local skins OR deactivate the modification of system styles in the administration by default in the client ini, since this could lead to issues on a system with multiple clienst (admin of client A could delete or modify style of client B). I personally would like to deactivate it by default, since customization of skins over the frontend should anyways only be done in a test environment.

However, the introduction of local styles should also be feasible without to much overhead.

What do the others think?
JourFixe, ILIAS [jourfixe], May 09, 2016: We discussed Timon's last feedback and scheduled the feature for 5.1. We decided:
  • … not to support local styles with this first version.
  • … that the creation of new styles shall be enabled in the Setup (for all clients).
  • We agree with Timon's suggestion to replace the permission "Edit Settings" by adding the three new permissions like described in 1.3.2 - RBAC
  • Feature requires LESSC. Path to LESS needs to be added to Setup » Path input screen.
  • We decided to separate content styles and system styles and to define them as separate components. Timon will take over the maintainership for the system styles.

4 Implementation

Amstutz, Timon [amstutz], 25 Aug 2016: This feature has been implemented as described above. Please note, that the editing of System Styles need to be activated in the setup of ILIAS in "Basic Settings" -> "Manage System Styles".
Test Cases
Test cases completed at 22.08.2016 by Seiler, Yvonne [yvseiler]

These cases are part of testsuite "Administration": S215

Administrationsbereich: Layout
  • C12941: Rollenvorlage "Designer" erstellen
  • C12942: Rolle einem Benutzer zuweisen
  • C12940: Rechte anpassen
System-Styles: Style anlegen
  • C12870: System Style manuell hinzufügen
  • C12871: System Style importieren
  • C12872: System Style kopieren
Einstellungen festlegen
  • C12873: Einstellungen des eigenen System Styles aufrufen
  • C12874: ID und Namen anpassen
  • C12875: System Style aktivieren (Standard)
  • C12876: System Style aktivieren (Persönlich)
LESS anpassen
  • C12877: LESS Variablen aktualisieren
  • C12881: LESS Variablen zurücksetzen
Icons anpassen
  • C12882: Bearbeitung nach Farbe
  • C12973: Bearbeitung nach Symbol
  • C12884: Vorschau der Symbole prüfen
  • C12903: Mehrere Farben zusammenlegen
  • C12883: Alle Farben zurücksetzen
Dokumentation Kitchen Sink aufrufen
  • C12885: Haupteintrag aufrufen
  • C12886: Untereintrag aufrufen
  • C12887: Einträge aktualisieren (nur DevMode Entwickler)
Substyle anlegen
  • C12892: Sub Style manuell hinzufügen
  • C12893: Einstellungen des Sub Styles festlegen
  • C12895: Sub Style einer Kategorie zuordnen
  • C12944: Mehrere Sub Styles derselben Kategorie zuordnen
  • C12897: Sub Style LESS Variablen aktualisieren
  • C12898: Sub Style Icon Symbole aktualisieren
  • C12896: Zuordnung löschen
Styles aktivieren und löschen
  • C12888: System Style der Benutzer ändern
  • C12890: System Style als Standard setzen
  • C12925: Mehrere System Styles (de-)aktivieren
  • C12926: System Styles sortieren
  • C12889: System Styles exportieren
  • C12891: System Styles einzeln löschen
  • C12924: System Styles mehrere löschen
General Feature: Approved at 22.08.2016 by Seiler, Yvonne [yvseiler].
New Permissions: Approved at 22.07.2016 by Timon Amstutz. (Develped by Leifos)

Last edited: 04. Sep 2017, 17:20, Amstutz, Timon [amstutz]