May 13, 2010

Setting up and configuring Mercurial in a Windows/IIS/Active Directory environment - Part 4/4

Part 4: Customizing the theme/skin of your Mercurial web interface.

This blog post is part of a four part series for getting Mercurial up and running in a Windows environment and hosting it on IIS 5.1 (i.e. Windows Server 2003).

  1. Part 1 Getting Mercurial set up in IIS and hosting a repository at
  2. Part 2 Getting IIS to hide hgwebdir.cgi in the URL for your Mercurial repositories.
  3. Part 3 Locking down security using Active Directory so that only authorized users can view, clone, pull and/or push to a repository.
  4. Part 4 Customizing the theme/skin of the web interface of your Mercurial repositories.

Continuing from my previous posts, I will refer to the directory containing my Mercurial Web UI as MercurialWeb and the UI itself as http://MercurialWeb/Repos/. On my test server my MercurialWeb directory is D:\Mercurial\hgWeb

I will start by ripping off one of the other existing themes that comes with Mercurial - monoblue. I don't personally like any of the existing themes very much, but everyone's taste is different. If you choose to modify a different theme as a base, just change monoblue to whatever theme you picked.

The themes are all stored in the templates directory of your \templates folder.

Make a copy of monoblue and rename the copy to something new and catchy. I'll call mine Alabaster, because I can't think of anything more inspiring than me :D The theme name is not displayed anywhere on your site, so it's really irrelevant what you call it unless you're going to distribute it or display it as part of the theme on your web UI. Okay, now we've got a template we can butcher...

Next step, go to the \static directory in your templates folder and make a copy of the monoblue.css renaming it to style-.css. Mine's called style-Alabaster.css.

Last step before we get to modification - open hgweb.config in your directory. If you have a [web] section add or modify the style property to point to your theme:

style = Alabaster

Okay, that's all the configuration done... now for modification of the style sheet and templates to change the look and feel of the site.

First thing I want to change is to display a logo of my own choosing instead of the Mercurial one and hook it to the repository root instead of the Mercurial website. We need to do this in a couple of places because the template isn't completely DRY. But we can come back and address that another day...

The first place is in \templates\Alabaster\index.tmpl


<div id="powered-by">
 <a href="" title="Mercurial"><img src="{staticurl}hglogo.png" width=75 height=90 border=0 alt="mercurial"></a></p>


<div id="powered-by">
 <a href="http://MercurialWeb/" title="Alabaster"><img src="{staticurl}AlabasterLogo.png" width=50 height=80 border=0 alt="mercurial"></a></p>

We also need to do this in \templates\Alabaster\footer.tmpl. The section is identical, you can just copy and paste it from index.tmpl over the same div in footer.tmpl.

To add our own favicon modify header.tmpl and change:

<link rel="icon" href="{staticurl}hgicon.png" type="image/png" />

to point to our own favicon:

<link rel="icon" href="{staticurl}AlabasterIcon.png" type="image/png" />

Add our two logos are in the \templates\static directory.

Now that we've got those changes sorted, it's no more complicated to modify our theme than modifying the style-Alabaster.css file. The first change I made was that I don't like all the lower case text everywhere. I was brought up to capitalize the first letter of a sentence and by god I want them capitalized... but some of the strings are generated on the fly so without the motivation to modify a bunch of hgweb base code, I'm going to add a couple of pseudo elements to my theme file which will do the job far more easily for me: li:first-letter{
 text-transform: capitalize;
 text-transform: capitalize;

There, now my theme looks more... proper. Headings and links now start with capital letters... as they should.

Now it's just a case of buggering around with the CSS and coming up with something I like which is more about taste than technicality so I will leave the rest to you...

I will blog again about this process in more recent versions of IIS once I find the time to upgrade my server ;)

No comments:

Post a Comment