Online Help
Webmin versions 0.63 and above have support for context-sensitive help. The hlink function outputs HTML for a link to a CGI program that processes and displays a given help page. Help pages are stored in the help subdirectory under the module directory, and are named simply page.html for those in English. So a call to hlink like
print &hlink("Enter username:", "name"),
"<input name=username size=20><p>\n";
would output a link to display the help page help/name.html. If the help parameter to the header function is set, a link labeled Help to the specified help page is included in the heading. This can be useful if you have created some documentation that explains what the entire page does in general, instead of or as well as documenting fields individually. The same rules about help HTML file selection apply.
Even though online help is not mandatory (or even common) in Webmin modules, it can useful to provide additional information to users about what a field really means or what the purpose of a page is. In many cases inputs are not self-explanatory and need additional documentation, so why not make it available from the page itself?
As the "Internationalization" section explains, Webmin modules can support multiple languages through the use of alternative translation files in the lang subdirectory. Help pages can exist if more than one language as well, by creating files named like page.language.html in the help subdirectory. If such a file exists, it will be used in preference to page.html, which is assumed to be in English. For example, to add a German version of an existing name.html page you would need to create name.de.html.
Help HTML files can contain several special tags that are interpreted by Webmin before the page is sent to the user's browser. These tags are :
- <include pagename>
- A tag like this is replaced by the contents of the help page
pagename. This can be useful for sharing common information between
multiple pages.
- <if condition>html</if>
- The Perl code in condition is evaluated, and if it returns a non-zero
value the enclosed html is displayed. Because the code is evaluated
outside of the context of the module, it can make use of standard Webmin
functions and variables (like %gconfig), but will not automatically
have access to the module's %config hash.
- <if condition>html<else>elsehtml</if>
- Similar to the <if> tag above, but with support for
alternate elsehtml HTML that will be displayed if the
condition returns a zero value.
- <exec code>
- A tag like this is replaced by the return value from evaluating the
Perl code in the tag. Again, it will have access to standard
Webmin functions and global environment variables.
- <footer>
- This tag should appear the end of the help page, and is typically
replaced with a horizontal line.