58.2. Overriding Images and Programs
In addition to changing the default colors, 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 web server. 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 web server 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 contains a file called useradmin/images/icon.gif, it will 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 overridden 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. This ability, however, should be used carefully as changes to the real CGI may break your custom script if its behaviour is different from the one it replaces. It should also be noted 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 will require ./web-lib.pl instead of ../web-lib.pl, just as the real index.cgi does.
If your theme does replace an existing script, be sure to read it carefully so that your replacement implements all of the same functionality. Some of the things to keep in mind when replacing the top-level index.cgi program are:
If $gconfig{'nohostname'} is set, no hostname or operating system information should be displayed. This can also be set on the Index Page Options page.
When the global variable $gconfig{'nofeedbackcc'} is set to 2, no feedback link should appear. This is configured on the User Interface page of the Webmin Configuration module.
If your menu program normally categorizes modules, categorization should be turned off when the $gconfig{'notabs'} variable is set so that all modules appear on a single page. Again, this is set on the Index Page Options page.
If your program arranges module icons in a table and the variable $gconfig{'nocols'} is set, it should be used as the number of columns to display.
The entries in $config_directory/webmin.catnames should be used to get user-defined categories and different names set for standard categories. This can be done on the Edit Categories page of the Webmin Configuration module.
If your program displays a logout link, it should only appear if neither of the following environment variables are defined. They both indicate that a form of authentication has been used that makes logging out impossible or irrelevant.
$ENV{'SSL_USER'} Indicates that the current user has logged in with SSL client authentication.
$ENV{'LOCAL_USER'} Indicates that the user is connecting from localhost and that his UNIX username matches his Webmin login.
If the variable $main::session_id is set, Webmin is in session (or cookie) authentication mode. You should generate a link to /session_login.cgi?logout=1 labeled Logout or something similar.
If that variable is not set, however, then Webmin is using HTTP authentication. Instead, your code should create a link to /switch_user.cgi labeled Switch User, as the normal logout link above will not work.
It is not mandatory to implement all of the suggestions above. However, it will make your theme behave more like those included as standard with Webmin.