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.
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.