|
Size: 3682
Comment: Fix formatting of last change that added an example for the age filter
|
Size: 3851
Comment: update info about styles
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 8: | Line 8: |
| The hgweb engine looks up templates in a file named templates/map (or templates/map-<style> if a style is specified). It looks something like this: | The hgweb engine looks up web styles in templates/ dir. Every style has a its own directory with a file named '''map'''. It looks something like this: |
| Line 24: | Line 24: |
| A style is simply a separate map file and possibly some additional template files. Mercurial comes with a few styles already, including the default HTML style, an XML style for RSS feeds, and a 'raw' style that allows getting patches and source files as plain text, as well as a gitweb-lookalike style | A style is simply a separate map file and possibly some additional template files. Mercurial comes with a few styles already, including the default HTML style (called 'paper'), an XML style for Atom and RSS feeds, and a 'raw' style that allows getting patches and source files as plain text, as well as a gitweb-lookalike style. In version 1.5 there are also `coal`, `monoblue` and `spartan` styles. Styles can be switched by appending `?style=name` URL parameter. |
The hgweb interface is completely themable. All output is generated from templates, nothing is hardcoded. Here's how it works:
The Map File
The hgweb engine looks up web styles in templates/ dir. Every style has a its own directory with a file named map. It looks something like this:
default = "changelog"
header = header.tmpl
footer = footer.tmpl
search = search.tmpl
changelog = changelog.tmpl
naventry = "<a href="?cmd=changelog;rev={rev}">{label}</a> "
filedifflink = "<a href="?cmd=filediff;node={node};file={file}">{file}</a> "
filenodelink = "<a href="?cmd=file;filenode={filenode};file=[file}">{file}</a> "
...This maps a template name to either a file (for example 'header' is found in header.tmpl) or a simple quoted string (eg naventry). The latter is used for small templates where a separate file would be awkward.
A style is simply a separate map file and possibly some additional template files. Mercurial comes with a few styles already, including the default HTML style (called 'paper'), an XML style for Atom and RSS feeds, and a 'raw' style that allows getting patches and source files as plain text, as well as a gitweb-lookalike style. In version 1.5 there are also coal, monoblue and spartan styles.
Styles can be switched by appending ?style=name URL parameter.
Templates
Each template is simply a file or string with a number of tags of the form {variable} that get replaced with the appropriate text when the template gets processed. For example, here's the template for the tags page in the default theme:
{header}
<title>{repo}: tags</title>
</head>
<body>
<div class="buttons">
<a href="?cmd=changelog;rev={rev}">changelog</a>
<a href="?cmd=manifest;manifest={manifest};path=/">manifest</a>
</div>
<h2>tags:</h2>
<ul id="tagEntries">
{entries%tagentry}
</ul>
{footer}
Interpolations
Note the {entries%tagentry} line above. The entries variable is actually a list of variable mappings, and the % syntax instructs the template engine to apply the tagentry format to each of them.
Filters
There is also a set of filters that can be applied to replacements, for example:
<title>{repo|escape}: changeset {node|short}</title>This applies the 'escape' filter to the 'repo' variable and the 'short' filter to the node variable. Multiple filters can be applied to a single variable:
<h2>changeset: {repo|escape|firstline}</h2>The available filters include:
- escape: escape HTML
age: print a date in 'x days ago' format (e.g. {date|age} gives 15 hours ago)
date: print a date in default format (e.g. {date|date} gives Mon Mar 29 15:16:05 2010 -0500)
rfc822date: print a date in rfc822 format (e.g. {date|rfc822date} gives Mon, 29 Mar 2010 15:16:05 -0500)
rfc3339date: print a date in rfc3339 format (e.g. {date|rfc3339date} gives 2010-03-29T15:16:05-05:00)
localdate: print a date in the local timezone (e.g. {date|localdate|rfc822date} gives Mon, 29 Mar 2010 21:16:05 +0100)
shortdate: print a date in short format (e.g. {date|shortdate} gives 2010-03-29)
addbreaks: insert <br> tags for newlines
- obfuscate: disguise email addresses
- short: print node ids in short form
- firstline: print the first line of a multiline string
- permissions: convert a permission code to ls-style formatting
Creating your own theme
Now that you know how the templates work, creating your own theme is simply a matter of copying the stock map file to map-mytheme, modifying it, and copying any template files you modify. Then you can add the following to your .hg/hgrc file:
[web] style = mytheme