Creating Overlay Themes

From Webmin Documentation
Jump to: navigation, search
Webmin development

Creating Overlay Themes
Creating Webmin Themes
MSC Theme
The Webmin API

Module Development
Advanced Module Development
Job Scheduling
Translating Webmin
Development Ideas

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 the default Blue Framed Theme (in the =blue-theme directory), or the Virtualmin Framed Theme. 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 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 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 file might look like :

desc=My Overlay Theme overlay=1 overlays=blue-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 blue-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
  • ui_table_body The inner table of inputs, also created by ui_table_start
  • ui_table_row The table row containing an input, generated by ui_table_row
  • ui_label The label next to an input, generated by ui_table_row
  • ui_value The table element containing the input, generated by ui_table_row
  • ui_table_span An input table row that spans its whole width
  • ui_columns A multi-column table, generated by ui_columns_start
  • 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
  • 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
  • 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
  • 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
  • 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:

  1. Login to Webmin and go to Webmin -> Webmin Configuration -> Webmin Themes
  2. Click on Install theme, and enter the URL
  3. After installation, go back to the Webmin Themes page and on the Change overlay tab select the newly installed CSS Overlay Demo Theme
  4. 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 be /usr/libexec/webmin/overlay-theme, or /usr/share/webmin/overlay-theme .