customize login page?

I would would like to change the appearance of the login page on a foswiki site (change logo, provide a link to new user registration) - can anyone provide some information on how to do this?

Thanks, dave r.

---

If you are using the Template Login Manager, then you can customize the page using SkinTemplates. The trick is understanding how the templates are layered and where you need to inject your customizations. You should be familiar with Skins (especially how customization is done) and how SkinTemplates are used and found. It's also helpful to look at the login templates in the templates directory in the Foswiki distribution.

In the following example I'm assuming that

• the template path hasn't been changed from the Foswiki default;
• the system is using PatternSkin; and
• you haven't created any topics to override the default templates for login

I've duplicated the default template path here for reference:

1. templates/$web/$name.$skin.tmpl
2. templates/$name.$skin.tmpl
3. $web.$skinSkin$nameTemplate
4. System.$skinSkin$nameTemplate
5. templates/$web/$name.tmpl
6. templates/$name.tmpl
7. $web.$nameTemplate
8. System.$nameTemplate

By default the Template Login uses the login template. With the above assumptions It will find it in the file templates/login.pattern.tmpl. That file (on Foswiki 1.1.3) is pretty simple; it

1. loads the login template (again!)
2. defines some template blocks

Step 1 is the important one. It directs Foswiki to load the login template. Foswiki recognizes that it has already loaded a login template using rule 2 in the template path so it starts looking for another login template using the next rule in the template path. With the default setup it will find this in the file templates/login.tmpl using rule 6. That file contains the real content which is expanded into the login page. The templates/login.pattern.tmpl loads this first and then redefines a few template blocks.

Where and how you customize depends upon how much you need to change the default layout and the search order defined in the template path.

If you do not change the default template path, templates/login.pattern.tmpl will always be loaded first (via rule 2). But, since the first thing it does is load another template, you can inject a new login template at that point using rule 4. (Rule 3 doesn't make sense -- there's no point in having web specific login templates -- and rule 5 is deprecated, so don't depend upon it). So, you could put your template in a new topic called System.PatternSkinLoginTemplate, and templates/login.pattern.tmpl will load it first and then apply the few customizations it does.

At this point you have complete control over the login page template, modulo the few changes made by templates/login.pattern.tmpl. This is great, but rather than recreate everything, you may just need to modify a few of the template blocks defined in templates/login.tmpl (recall that this file is what contains the bulk of the login page blocks). The best way to do this is to load that file and then redefine those blocks. Since your template topic was found via rule 4, when your template loads the login template Foswiki starts searching for it using the next rule, and finds the templates/login.tmpl file using rule 6.

What if you don't like the skin specific template loaded via rule 2? You have several options:

1. reorder the template path so your topic gets loaded first
2. create a new skin (e.g. mylogin) and add it to the beginning of your skin path. Then, either
   • create a System.MyloginSkinLoginTemplate topic; or
   • create the file templates/login.mylogin.tmpl

As an example, here's how I've modified the default PatternSkin login template for my site. My site uses an external database for authentication and user mapping, so it doesn't allow registering or changing of passwords. I wanted to modify the templates as little as possible, so I just removed those bits which weren't pertinent to my site. I created a System.PatternSkinLoginTemplate topic which looks like this:

%TMPL:INCLUDE{"login"}%

%TMPL:DEF{"usernamenote"}%%TMPL:END%

%TMPL:DEF{"title"}%<h2>Log on with your HEAD username and password</h2>%TMPL:END%

%TMPL:DEF{"usernamefieldhelplink"}%%TMPL:END%

%TMPL:DEF{"usernamefieldhelpcontents"}%%TMPL:END%

%TMPL:DEF{"passwordnote"}%%TMPL:END%

%TMPL:DEF{"UNRECOGNISED_USER"}%Oops: we could not recognize you. Try again.%TMPL:END%

-- DiabJerius - 29 Oct 2011