Custom interface theme

Creating and maintaining a custom theme requires an understanding of the interface generation architecture. This article is intended for developers who create or modify interface themes. It covers:

• theme structure;
• the mechanism for transforming data into HTML;
• debugging techniques;
• working with graphical assets.

Theme structure

Theme files are placed in a subdirectory of the /usr/local/mgr5/skins/ directory. A theme includes the following components:

• XSL templates — for transforming XML data into HTML;
• CSS files — for styling the interface;
• JavaScript code — for client-side logic (optional);
• graphical assets — images, logos, favicon.

Creating a new theme

To create a new theme:

1. Create a directory with a unique name in /usr/local/mgr5/skins/. The directory name must not match existing theme names or the reserved name common.
2. Restart the COREmanager service:
   

   systemctl restart coremanager

   or

   killall core

3. After the restart, the theme will appear in the list of available themes in the web interface. When the theme is selected for the first time without XSL templates, a blank (white) page will be displayed.

Interface generation mechanism

The platform renders the interface as follows:

1. For each request, the platform server generates an XML document containing the response.
2. The response is transformed into the required format (e.g., HTML) using XSL templates.
3. Each function uses a separate XSL template.

Debugging with XML

To include an XML file with debug information in request responses, add the out=devel parameter to the request.

To view XML in log files, enable logging for the output and xml modules at the maximum level:

1. In the platform interface, go to Settings → Logging settings.
2. Select the following modules:
   • output — Manages output in various formats (core.output);
   • xml — Handles XML processing (core.xml).
3. Increase the logging level using one of the options:
   • Click Edit → select User role: "9 — debugging information";
   • Click Maximum.
4. Click Ok.

By default, logs are stored in /usr/local/mgr5/var/.

General XML overview

Each XML file generated by the platform includes information about the current theme and interface language. This data is stored in the attributes of the root doc tag:

<doc lang="en" func="desktop" binary="/core" host="https://127.0.0.1:1500" stylesheet="desktop" theme="/manimg/orion/" css="main.css" logo="logo.png" logolink="" favicon="favicon.ico" localdir="default/">
...
</doc>

Using icons

Icons shared across multiple themes are located in /usr/local/mgr5/skins/common/img/. For example, main menu, property, toolbar button, and module icons. Icons are combined into CSS sprites grouped by size.

To start using icons:

1. Include the sprite CSS file /usr/local/mgr5/skins/common/sprite.css in your theme's XSL template:
   
   Example of including the sprite CSS file

   <link rel="stylesheet" href="/mainimg/common/sprite.css">

2. In the XSL template, create an HTML
   element with the following CSS classes:

   • size class, for example, s16x16;
   • icon name class, for example, mb-sysstat.

   Example HTML element

   <div class="s16x16 mb-sysstat"></div>

Available sprites:

• sprite-16x16.png — contains 16x16 px icons used in the main menu and properties;
• sprite-16x17.png — contains 16x17 px icons used in forms in the sirius theme;
• sprite-24x24.png — contains 24x24 px icons used for toolbar buttons;
• sprite-48x48.png — contains 48x48 px icons used in module headers.