Summary: How to customise the authentication form (login form)
Version: 2006-08-20
Prerequisites: pmwiki 2.1
Categories: Layout Passwords

Questions answered by this recipe

How to customise the authentication form (login form).
How to use a custom AuthForm page.


Site.AuthForm contains the default form displayed when a user tries to access a page with insufficient acces rights. It displays a login prompt and a field to enter a password, and if user authentication is enabled in config.php with


then it displays an input box for the user name as well as for the password. Note that Site.AuthForm is not a login page, but will be used for an access attempt on any page, and if the authentication is successful, the page will be displayed.

Site.AuthForm can be edited directly and custom form elements and text can be added, or the layout and styling changed etc.

Display of the auth form can look strange on some skins, as the form is shown as page content, but some page elements may be hidden, while others may still be visible. To hide any irritating page elements, like remnants of the sidebar, and the margin left for the sidebar, one can try and eliminate sidebar and header and footer etc. by setting the styles for the containing divisions to {display:none}. Check the skin you use for the appropiate div names. For instance for the PmWiki default skin one can add to config.php:

# stripping sidebar, title and footer when not logged in
if (!$AuthId) {
  $HTMLStylesFmt[] = "
    #wikilogo, #wikihead, #wikileft, #wikititle, #wikifoot {display:none}\n";

For Gemini, FixFlow and Triad skins (all three):

if (!$AuthId) {
   $HTMLStylesFmt[] = " 
        #sidebar, #titlebarbox, #footer {display:none} 
        #sidebarbox {width:0} #main {margin:0}
        #left-box, #right-box, #topnavbox {display:none}\n";

Using the condition if(!$AuthId) will apply the style changes only to the page if the user is not authenticated, i.e. just for the purpose of showing the auth form.

An alternative may be to display a blank auth form, without any skin elements or styles, with no headers or footers, by adding to config.php:

$AuthPromptFmt = array(&$HTMLStartFmt,
    'page:$SiteGroup.AuthForm', &$HTMLEndFmt);

This effectively bypasses the skin defaults and produces a bare-bones HTML page, with just the contents of the Site.AuthForm itself.

And to use a different page for the AuthForm, set in config.php:

$AuthPromptFmt = array(&$PageStartFmt, 'page:Site.LocalAuthForm',

In other words, simply change PmWiki's default 'page:$SiteGroup.AuthForm' to refer to whatever page you wish. Or, if you don't want the skin header/footer :

$AuthPromptFmt = array(&$HTMLStartFmt, 'page:Site.LocalAuthForm',

In fact, it's even possible to have per-group AuthForms:

$AuthPromptFmt = array(&$PageStartFmt,
   'page:{$Group}.AuthForm $SiteGroup.AuthForm',

which uses AuthForm of the current group if there is one, and the Site.AuthForm otherwise.


Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See Also




See discussion at CustomAuthForm-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.