Creating Themes

Webmin versions 0.83 and above support themes, which are sets of alternate user interfaces, graphics and colour schemes. A user can choose which theme he wants by going into Webmin Configuration and clicking on Webmin Themes. Multiple themes can be installed, but only one can be active for a Webmin user at any one time - or if no theme is active, the default colours and layout are used.

Like a module, a theme is a directory under the Webmin root directory that contains certain files. The most important is the theme.info file, which has the same format as the module.info file - name=value entries, one per line. Required names and their values are:

desc
A description for this theme, such as My Webmin Theme. This is the text that will appear in the theme selection menu.

A theme can also contain a config file, also in name=value format. The values defined in this file control the behaviour of the standard header and footer functions. Supported names and their values are:

cs_page
A six-character hex string in RRGGBB format for the background colour of Webmin pages.

cs_link
A six-character hex string in RRGGBB format for the colour of visited and unvisiting links on Webmin pages.

cs_text
A six-character hex string in RRGGBB format for the colour of normal text.

bgimage
A relative URL (like images/background.gif) for a background image to be displayed on all pages.

noindex
If set to 1, the HTML generated by the header function will not include a Webmin Index link. Useful if another frame is used for the main index.

brand
HTML for an image or text to be displayed in the top-right corder of the main index page.

brand_url
A URL to which the brand image is linked. These two options are usually combined to create a company icon that links to its homepage in customised versions of Webmin.

headhtml (Versions 0.86 and above)
HTML that will be included inside the <head> section of each Webmin page.

headinclude (Versions 0.86 and above)
The name of a file in your theme directory whose contents will be included inside the <head> section of each page.

inbody (Versions 0.86 and above)
Text that will be included inside the <body> tag itself.

prebody (Versions 0.86 and above)
HTML that will be included at the top of the <body> section of each page. The following substitutions will be done in the HTML :
  • %HOSTNAME% will be replaced with the system's hostname.
  • %VERSION% will be replaced with the webmin version.
  • %USER% will be replaced with the current user's login.
  • %OS% will be replaced with the OS name and version.

texttitles (Versions 0.86 and above)
If set to 1, the titles on all pages will be displayed as HTML text rather than using letter images.

postbody (Versions 0.86 and above)
HTML that will be included at the bottom of the <body> section on each page. The same substitutions as prebody are done.

tb (Versions 0.86 and above)
Text that will be included inside the <tr> tag in table header rows.

cb (Versions 0.86 and above)
Text that will be included inside the <tr> tag in table rows below the header.

functions (Versions 0.92 and above)
The name of a file in your theme's directory that contains perl functions for overriding the default header, footer and error functions. See below for more details.

noicons
If set to 1, the standard generate_icon and icons_table functions will display only a name instead of an icon. This can be useful if your theme is designed for text-only or low bandwidth use.

In addition to changing the default colours, a theme can be used to selectively override any icon or CGI program used by Webmin. When a theme is chosen, its directory becomes an 'overlay' root directory for the Webmin webserver. Thus, if your theme subdirectory contains a file called images/newlogo.gif, it will replace the logo on the main menu when it is displayed, because the webserver will look in the theme directory first before looking for images/newlogo.gif under the top-level directory.

In this way any of the module icons can be overridden, as can the images used to make up the titles at the top of pages. For example, if your theme directory contained a file called useradmin/images/icon.gif, it would be used as the icon for the Users and Groups module on the main menu. Because this 'replacement' does not actually change the real images, the user can switch between themes or back to the default theme easily.

CGI programs can also be overriden as well, in exactly the same way. This can be used to do things like changing the way the main menu is displayed, by putting a custom index.cgi script in your theme directory. However, this ability should be used carefully as changes to the real CGI may break your custom script if its behaviour is different to the one it replaces. Also, note that when a theme CGI is executed, it will be in the real directory and not the theme subdirectory. This means that a custom top-level index.cgi script would have to require ./web-lib.pl instead of ../web-lib.pl, just as the real index.cgi does.

In Webmin versions 0.92 and above, a theme can override some of the common HTML-generating functions by adding a line like functions=theme.pl to the config file and creating a theme.pl script in the theme's directory containing one or more of the following functions :

  • theme_header
    This function will be called instead of the standard header function, with all the same parameters. It must handle all those parameters properly, and output whatever HTML you want to use for the page titles and so on.

  • theme_footer
    Called instead of the standard footer function, with the same parameters. If your theme_header function opens an HTML table for layout purposes, this function must close it so that the HTML is properly complete.

  • theme_error
    Called instead of the standard error function, with the same parameters.

These functions give you a lot of power to create themes that significantly change the Webmin layout. However, for them to work properly they must handle all the parameters that they are passed in exactly the same way that the standard functions do.

All the code that your theme uses in .cgi and .pl scripts can make use of the $text hash to get messages in the user's current language. Typically a theme will only use standard messages that are part of Webmin, but in some cases you will want to define your own that are specific to the theme. In order to make use of Webmin's internationalisation features, your theme directory should contain a lang subdirectory, containing files for the various languages that you support, like en, de and so on. These should be formatted just like the translation files for a module, explained in the "Internationalisation" section.

To make use of your theme's language files, you need to use code like: 

%mytext = &load_language($current_theme);
print "<b>$mytext{'mytheme_smeg'}</b> <p>\n";
Note that your theme's language files will NOT be automatically loaded into the %text array.

The final part of creating a theme is packaging it. Just like module, themes are packaged as an optionally compressed tar file of the theme directory, usually with a .wbt extension. They can then be installed through the Webmin Themes page.