|
Size: 3078
Comment:
|
Size: 3858
Comment: mention that simplified examples are from former theme
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 4: | Line 4: |
| <<TableOfContents>> |
|
| Line 6: | 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 14: | Line 16: |
| 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> " |
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> " |
| Line 22: | 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. | 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. |
| Line 26: | Line 30: |
| Each template is simply a file or string with a number of tags of the form #variable# (or {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: | 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 former default theme: |
| Line 29: | Line 33: |
| #header# <title>#repo#: tags</title> |
{header} <title>{repo}: tags</title> |
| Line 35: | Line 39: |
| <a href="?cmd=changelog;rev=#rev#">changelog</a> <a href="?cmd=manifest;manifest=#manifest#;path=/">manifest</a> |
<a href="?cmd=changelog;rev={rev}">changelog</a> <a href="?cmd=manifest;manifest={manifest};path=/">manifest</a> |
| Line 42: | Line 46: |
| #entries%tagentry# | {entries%tagentry} |
| Line 45: | Line 49: |
| #footer# | {footer} |
| Line 50: | Line 54: |
| 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. | 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. |
| Line 57: | Line 61: |
| <title>#repo|escape#: changeset #node|short#</title> | <title>{repo|escape}: changeset {node|short}</title> |
| Line 60: | Line 64: |
| This applies the 'escape' filter to the 'desc' variable and the 'short' filter to the node variable. | This applies the 'escape' filter to the 'repo' variable and the 'short' filter to the node variable. |
| Line 64: | Line 68: |
| <h2>changeset: #desc|escape|firstline#</h2> | <h2>changeset: {repo|escape|firstline}</h2> |
| Line 70: | Line 74: |
| * age: print a date in 'x days ago' format * date: print a date in default format * rfc822data: print a date in rfc822 format |
* 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}}}) |
| Line 87: | Line 94: |
| ---- CategoryWeb |
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 former 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