About

This page explains how to create overlay themes, which are a new feature in Webmin 1.450 and later. These allow you to easily modify the colors, icons and CSS of another theme, without having to create or duplicate its entire layout.

Introduction to overlay themes

Implementing a Webmin theme from scratch is a lot of work, as it involves creating icons, CSS, index CGI scripts and much more. Most theme developers only really want to change the appearance of one of the more common themes, like Framed Theme (in the gray-theme directory). Overlays provide an easy way to do this - in effect, they are meta-themes that are layered on top of an existing theme.

Once an overlay theme is installed, it can be selected globally in the Webmin Configuration module on the Webmin Themes page, or in the Change Language and Theme module. Each overlay theme is typically designed to modify the appearance of one or more core themes, specified in its theme.info file.

Overlay theme files

Like regular themes, an overlay theme is simply a directory under the Webmin root. This is normally /usr/libexec/webmin or /usr/share/webmin , and can be found in the root line of the /etc/webmin/miniserv.conf file. If you want to create your own overlay, just create a sub-directory under the root, named something like my-overlay-theme .

This directory must contain a theme.info file, which uses the same text line by line name=value format seen in other Webmin configuration files. The only required names are:

  • desc

    A description for this theme, such as My Overlay Theme

  • overlay

    This must be set to 1 to indicate that this is an overlay theme.

  • overlays

    The value must be a space-separated list of real theme directories that this can be used with.

An example theme.info file might look like:

desc=My Overlay Theme
overlay=1
overlays=gray-theme
version=1.0

A theme can also contain a config file, also in the same format. It’s entries are used to apply the actual changes in Webmin’s appearance that the theme makes. Some of the entries you may want to set are:

  • headhtml

    HTML that will be included inside the <head> section of each Webmin page.

  • inbody

    Text that will be included inside the <body> tag itself.

  • prebody

    HTML that will be included at the top of the <body> section of each page.

  • postbody

    HTML that will be included at the bottom of the <body> section on each page. The same substitutions as prebody are done.

  • prebodyinclude

    File that will be read and included at the top of the <body> section of each page.

  • postbodyinclude

    File that will be read and included at the bottom of the <body> section on each page.

Because most of the UI changes an overlay theme might want to make can be done using CSS, you could create a config file containing just:

headhtml=<link rel='stylesheet' type='text/css' href='/unauthenticated/overlay.css'>

And then create the file unauthenticated/overlay.css under the theme’s directory. This can be used to modify CSS styling defined in the original theme, such as in the file gray-theme/unauthenticated/style.css . For example, you could make the page background pink with an overlay.css file like:

body { background-color: #ffeeee; }
html { background-color: #ffeeee; }

CSS styling

All Webmin UI elements have CSS classes, which can then be styled by a overlay theme’s .css file. Some of the useful classes are:

  • ui_table

    The table that contains inputs, started by ui_table_start function

  • ui_table_body

    The inner table of inputs, also created by ui_table_start function

  • ui_table_row

    The table row containing an input, generated by ui_table_row function

  • ui_label

    The label next to an input, generated by ui_table_row function

  • ui_value

    The table element containing the input, generated by ui_table_row function

  • ui_table_span

    An input table row that spans its whole width

  • ui_columns

    A multi-column table, generated by ui_columns_start function

  • ui_columns_heads

    The headings row of a multi-column table

  • ui_columns_row

    A single row in a multi-column table

  • ui_checked_columns

    A row in a multi-column table with a checkbox in the first column

  • ui_radio_columns

    A row in a multi-column table with a radio button in the first column

  • ui_columns_header

    An additional headings row in a multi-column table

  • ui_emptymsg

    The text displayed if a multi-column table is empty

  • ui_form

    Start of a form generated by ui_form_start function

  • ui_form_end_buttons

    The table containing buttons at the end of a form=

  • ui_textbox

    A text input box, single line

  • ui_upload

    A file upload input box.

  • ui_password

    A password text box

  • ui_select

    A single or multi-element select input

  • ui_multi_select

    The table surrounding a multi-element left-right select input

  • ui_radio

    A single radio button

  • ui_checkbox

    A single checkbox input

  • ui_textarea

    A multi-line text box

  • ui_opt_textbox

    The text box for an optional input field, as generated by ui_opt_textbox function

  • ui_submit

    A single submit button

  • ui_data

    The span around year / month / day inputs

  • ui_buttons_table

    The table around a set of action buttons, started by the ui_buttons_table function

  • ui_buttons_form

    The form for a single button in a buttons table

  • ui_buttons_row

    The <tr> for a row in a buttons table

  • ui_buttons_label

    The <td> containing the button in a buttons table row

  • ui_buttons_value

    The <td> containing the description text in a buttons table row

  • ui_buttons_hr

    The <tr> for a row in a buttons table that just contains a separator

  • ui_post_header

    The <center> block for a post-page-title message

  • ui_footer

    The <p> block generated by ui_footer function

  • ui_subheading

    The <h3> block containing text generated by the ui_subheading function

  • ui_tabs

    The table surrounding tabs and their contents, generated by ui_tabs_start function

  • ui_tab

    The <td> for a single tab title

  • ui_tabs_box

    The table surrounding all tab contents

  • ui_tabs_start

    The <div> that surrounds the contents of a single tab

  • ui_grid_table

    The table containing all HTML generated by the ui_grid_table function

  • ui_grid_row

    The <tr> for a single row in a grid table

  • ui_grid_cell

    The <td> for a single cell in a grid table

  • ui_radio_table

    The table surrounding all options generated by the ui_radio_table function

  • ui_confirmation

    The <center> surrounding a confirmation form

Overlaying files

An overlay theme can replace icons, CSS or other files in the base theme by simply including them in its directory using the same paths. For example, you could replace the Webmin logo that appears on the main page by creating the file images/webmin-blue.png under your theme’s directory.

Replacing CSS files is not recommended though, as this will break most existing UI elements. Instead, add to the base theme’s CSS by using the headhtml option described above.

Example overlay theme

To see a very simple overlay theme in action, install the example as follows:

  • Login to Webmin and go to Webmin ⇾ Webmin Configuration ⇾ Webmin Themes
  • Click on Install theme, and enter the URL http://download.webmin.com/download/modules/overlay-theme.wbt.gz
  • After installation, go back to the Webmin Themes page and on the Change overlay tab select the newly installed CSS Overlay Demo Theme
  • Click the Change button to activate it

You should now see that your Webmin pages have a pink background. To look at the source for this theme, SSH into your system and cd to the overlay-theme directory under the Webmin root. This will probably located in /usr/libexec/webmin/overlay-theme, or /usr/share/webmin/overlay-theme directory.