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 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 can be used to override some of the settings in the global Webmin config file /etc/webmin/config. 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.

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 CGIs 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. For example, 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.

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