58.3. Theme Functions
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 that contains 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.
These functions give you a lot of power to create themes that significantly change the Webmin layout. For them to work properly, however, they must handle all the parameters that they are passed in exactly the same way that the standard functions do.
The most complex is the theme_header function due to the large number of parameters that it takes and the other global variables that it can make use of. When writing it, consider the following:
All parameters should be checked and interpreted in the same way as the real header function.
There is no need for your function to call PrintHeader, as this will be done automatically before it is called. It can just go ahead and start producing HTML.
If the variable $gconfig{'sysinfo'} is set to 0, information about the current user, hostname, operating system, and version of Webmin should be displayed in the browser's status bar. This can be done by producing HTML like:
<script> defaultStatus = "fred logged into Webmin 1.060 on www.example.com"; </script>
If $gconfig{'sysinfo'} is set to 1, this information should be appended to the page title in the <title> HTML tag. If $gconfig{'sysinfo'} is set to 2, the information should be displayed in the page itself, somewhere just below the title. If set to 3, the host and login details should not appear anywhere.
In all cases, the function get_webmin_version can be used to get the version of Webmin and get_system_hostname can get the current hostname.
The <body> tag that your code produces may contain bgcolor=, link=, and text= parameters containing the values from the global variables $gconfig{'cs_page'}, $gconfig{'cs_link'}, and $gconfig{'cs_text'}, if they are set. This ensures that color preferences set by the user on the User Interface page of the Webmin Configuration module are used. Feel free, however, to ignore them if your theme only looks good with a certain color scheme.
If every page includes a Logout or Switch User link, it should not appear if any of the following environment variables are set:
$ENV{'SSL_USER'} The current user has logged in with SSL client authentication.
$ENV{'LOCAL_USER'} The user is connecting from localhost and his UNIX username matches his Webmin login.
$ENV{'ANONYMOUS_USER'} This page is being accessed without any authentication at all.
If the variable $ENV{'HTTP_WEBMIN_SERVERS'} is set, your page heading should include a link to the URL in that variable labeled Webmin Servers. This is set when connecting via a tunnel in the Webmin Servers Index module, and the URL refers to that module on the originating system. This gives the user an easy way to return to the list of servers.
If your theme generates titles made up of letter images, plain text should be used instead, if $gconfig{'texttitles'} is set to 1. A setting on the User Interface page of the Webmin Configuration module controls this.
Unless your heading is very similar to the default, the theme_footer function should be defined as well. It must produce closing HTML that matches that produced by theme_header, followed by </body> and </html> tags. Be sure to interpret and display the multiple “return” links that can be supplied to the footer function as well.
Some themes normally put all page content into a table by outputting an unclosed <table> tag in the header function. If the global variable $theme_no_table is set, this should be turned off, as it indicates that the CGI program will be slowly producing some progressive output. Many browsers will not display a table's content until it has been completely output.
Similarly, your theme_footer function should not produce a closing </table> tag when $theme_no_table is set.
The special CGI program, session_login.cgi, that displays Webmin's login form will call theme_header as well. At this point, however, the browser has not logged into Webmin and so will not be able to access any images to which your header refers. For this reason, when called with the first two parameters set to undef (as it will be in this case), your function should not produce any <img> tags. Or they should always refer to the special /unauthenticated URL path, to which access is always allowed even to clients that have not logged in.
Reading the header function in web-lib.pl and the theme_header function in mscstyle3/theme.pl should give you a good idea of how the various parameters and global variables should be handled.