WebSVN Templating System

Content

Introduction

WebSVN's templating system makes it possible to customize the look and feel of WebSVN. Templates can be applied for all repositories or per-repository by specifying the path to the template, like so:

$config->setTemplatePath($locwebsvnreal.'/templates/BlueGrey/');
$config->setTemplatePath($locwebsvnreal.'/templates/calm/', 'My Repository');

WebSVN already includes a few templates, but you can also create your own. This document describes how.

A WebSVN template consists of a set of HTML template files that WebSVN processes by filling in placeholders. There are two placeholder types: variables and commands. This document will cover variables first, then commands, then individual template files and the variables and commands which may be used in each template file.

NOTE: This documentation is not fully up-to-date with recent major changes to the trunk. Consequently, templates that work with previous versions of WebSVN may not work completely (or even at all) with the current development version.

Variables

Variables are written in the form [websvn:varname] where varname is the name of a variable whose value should replace the placeholder.

You may also access the language translations using [lang:varname] to make your templates language-agnostic.

Take special note of the locwebsvnhttp variable. It should be used to locate other files and graphics that your template files need. You may imagine that simply using . should work, but relative paths break when MultiViews are turned on, whereas this variable works in all cases. For example:

<link rel="stylesheet" type="text/css" href="[websvn:locwebsvnhttp]/templates/tmptname/styles.css"/>

The specific variables defined for individual template files (and those defined for all templates) are described under Template Files.

NOTE: When there are two similarly-named variables of the form someurl and somelink, the former is the bare URL while the latter is an HTML anchor tag with the URL in the href attribute and with a localized string as the link title. It is generally cleaner to use the latter, but the former is useful for creating a linked image, etc.

Commands

WebSVN defines a handful of commands which allow templates to create rudimentary control flow and invoke special behaviors.

NOTE: If a command placeholder appears on the same line with any non-whitespace text, WebSVN will not recognize it.

Below are a few examples of commands and how they may be used.

If-Else Constructs

The placeholders [websvn-test:varname], [websvn-else], and [websvn-endtest] provide control flow based on whether a variable exists and is non-zero. The else block is optional, and either block may be empty.

[websvn-test:varname]
...
[websvn-endtest]
[websvn-test:varname]
...
[websvn-else]
...
[websvn-endtest]

Looping Construct

Used in pages that contain listings of files, logs, etc. Everything between the controls is repeated for each item in the list.

[websvn-startlisting]
...
[websvn-endlisting]

Other Behaviors

A few template files — including directory.tmpl and file.tmpl — use additional commands, which are described in those sections below.

Template Files

WebSVN expects a template to provide to provide a number of .tmpl files, each of which is explained in detail below. If any of these files are missing, errors will occur when trying to view the associated WebSVN page.

Variables defined for all template files

versionThe version of WebSVN
currentyearThe current year
templateThe base name of the invoked template file (excluding ".tmpl")
locwebsvnhttpRoot of the WebSVN directory
indexurlURL for the WebSVN index page
repnameName of the repository
clientrooturlThe root URL for SVN clients to use (only if provided in config.php)
pegThe peg revision passed to the page (can use with clientrooturl)
charsetThe charset requested by the user
language_codeThe RFC 2616 language code of the selected language
language_formLanguage selection menu <form> element
language_selectLanguage selection menu <select>...</select> element
language_submitLanguage selection menu submit button
language_endformLanguage selection menu </form> element
projects_formProject selection menu <form> element, plus any hidden inputs
projects_selectProject selection menu <select>...</select> element
projects_submitProject selection menu submit button
projects_endformProject selection menu </form> element
showageinsteadofdateWhether to display the relative age of a commit rather than the absolute date.
errorA string representing an error condition, or empty if there is none.
warningA string representing a warning condition, or empty if there is none.

Note: It is good practice to distinguish between these last two variables, since [websvn:error] is intended to represent a unrecoverable condition (such as a non-existent repository or no access) while [websvn:warning] is intended to represent less serious problems, such as SVN-related failures, non-existent revisions, etc. Check the included templates for suggested approaches for handling errors and warnings.

header.tmpl & footer.tmpl

These files are included by WebSVN before and after the main template file, respectively. They obviously have access to all the variables defined above, but they can also test for the presence of variables defined for a specific template file, detailed below.

In general, the header and footer templates should be generic and "just work" with any template. It is common to create the language and project selection drop-down menus in this context, as well as any ubiquitous content or branding. (For example, you may want the same masthead to appear on each page, and the same footer that contains the version of WebSVN and/or Subversion.) For ideas about what makes sense to include here, consult the included templates.

index.tmpl

This template file is used by index.php. It is the main project page that lists available repositories. Repositories may be displayed in a flat view (which ignores any groups) or tree view (open or closed by default) as controlled by one of the following config lines:

$config->useFlatView();
$config->useTreeView();
$config->useTreeIndex(true);

For examples of how to create an index with either a flat or tree view, consult index.tmpl in any of the included templates. Unlike previous versions of WebSVN, index.php now passes the same variable structure to index.tmpl regardless of whether flat view or tree view is selected. This makes the variable names more uniform, but does require templates to actively skip over group names in flat view (by testing for groupid) if they don't want to display them.

Variables defined for the entire scope of the template

treeviewtrue if the index should be displayed as a tree of grouped projects
flatviewtrue if the index should be displayed as a simple list of projects
opentreetrue if the tree viewed should be open by default
groupcountThe number of project groups (0 or more)
showlastmodWhether "last modification" info should be displayed for each project

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

projectlinkHTML link to a project (not set for group headers)
clientrooturlThe root URL for SVN clients to use for a repository (only if provided in config.php)
rowparityParity of the row (0 or 1), used to generate striped tables. Group headers do no have a row parity, only projects
groupparitySimilar to row parity, but the first entry in each group restarts at 0
groupidOnly set if the current entry is a group header
groupnameSet for group headers and each member of a group
notfirstgrouptrue if the entry is a second or subsequent group
revisionNumber of the latest revision affecting the current project
dateDate of the latest revision (yyyy-mm-dd)
ageAge of the latest revision in days, hours, etc.
authorAuthor of the latest revision

The last variable in each of these lists are useful for determining if an element surrounding a group needs to be closed. For example, you may wish to create a <div> or <ul> tag to open a group, and a closing tag at the end of the group, either between groups or after the last group.

directory.tmpl

This template file is used by listing.php. It displays the contents of the current path, as well as any parent and top-level directories. Directory hierarchies are indented to provide a hierarchical view, and icons can be defined for directories and specific file extensions. Each displayed resource cab be displayed with the revision in which it was last modified, a link to view its history, and (optionally) RSS and download links. Additionally, each row has a checkbox that allows for quickly comparing files and directories.

Variables defined for the entire scope of the template

restrictedTrue if the users has restricted access to this directory (to allow access to a readable directory lower down only)
pathPath of the directory being listed
revRevision being viewed
dateCommit date of the current revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the current revision
logLog message of the current revision
youngestrevThe most recent revision affecting the current directory
goyoungestlinkLink to most recent revision of the current directory (only if a newer revision exists)
pathlinksList of links to each directory in the current path
logurlURL to the log view of current directory
revurlURL to the current revision for this directory
revlinkLink to the current revision for this directory
rssurlURL to the RSS feed for the current directory
downloadurlURL to download an archive for the current directory
compareurlURL to comparison with previously changed revision
allowdownloadTrue if downloading has been configured
compare_formComparison selection <form> element
compare_submitComparison selection submit button
compare_endformComparison selection </form> element
showlastmodWhether "last modification" info should be displayed for each path

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

compare_boxComparison selection checkbox for the current resource
rowparityParity of the row (0 or 1), used to generate striped tables
filenameName of the current file/directory
fileurlURL to the current file/directory
filelinkLink to the current file/directory (includes filename)
filetypeType of the current entry (file, dir, opendir, etc.)
isDirtrue if the current file is a directory (use with [websvn-test:isDir] to display icons)
openDirtrue if the current file is a directory on the current path
logurlURL to the log page for the current file/directory
rssurlURL to the RSS feed for the current file/directory
downloadurlURL to download the current entry (only for files)
downloadplainurlURL to download the current entry (only for directories)
revurlURL for examining the latest revision in detail
revisionNumber of the latest revision affecting the current path
committimeTimestamp of latest revision
dateDate of the latest revision (yyyy-mm-dd)
ageAge of the latest revision in days, hours, etc.
authorAuthor of the latest revision

Special Commands

Note: Remember to put these commands each on their own line!

These commands are used to display certain icons next to certain file types in the directory view.

[websvn-defineicons]
...
[websvn-enddefineicons]
[websvn-treenode]
[websvn-icon]

Within the [websvn-startlisting] ... [websvn-endlisting] block, [websvn-treeview] will output the HTML code defined for the appropriate tree view icon. In the same context, [websvn-icon] will output the HTML code defined for the type of the current file.

The [websvn-defineicons] block should contain a line for each file type, defining the HTML to be used for that file type. To define the HTML for a particular extension use the syntax:

.<extension>=<HTML code>

There are also some special filetypes:

dir=<HTML code>Used for directory icons
diropen=<HTML code>Used for open directory icons
*=<HTML code>Used for all filetypes which have no other definition
i-nodeI-shaped node for the tree view
t-nodeT-shaped node for the tree view
l-nodeL-shaped node for the tree view
e-nodeEmpty node for the tree view

Example from the BlueGrey template:

[websvn-defineicons]
dir=<img align="middle" valign="center" src="[websvn:locwebsvnhttp]/templates/BlueGrey/folder.png" alt="[FOLDER]">
diropen=<img align="middle" valign="center" src="[websvn:locwebsvnhttp]/templates/BlueGrey/folder-open.png" alt="[FOLDER]">
*=<img align="middle" src="[websvn:locwebsvnhttp]/templates/BlueGrey/file.png" alt="[FILE]">
.c=<img align="middle" src="[websvn:locwebsvnhttp]/templates/BlueGrey/filec.png" alt="[C-FILE]">
.h=<img align="middle" src="[websvn:locwebsvnhttp]/templates/BlueGrey/fileh.png" alt="[H-FILE]">
.s=<img align="middle" src="[websvn:locwebsvnhttp]/templates/BlueGrey/files.png" alt="[S-FILE]">

i-node=<img align="middle" border="0" width="24" height="26" src="[websvn:locwebsvnhttp]/templates/BlueGrey/i-node.png" alt="[NODE]">
t-node=<img align="middle" border="0" width="24" height="26" src="[websvn:locwebsvnhttp]/templates/BlueGrey/t-node.png" alt="[NODE]">
l-node=<img align="middle" border="0" width="24" height="26" src="[websvn:locwebsvnhttp]/templates/BlueGrey/l-node.png" alt="[NODE]">
e-node=<img align="middle" border="0" width="24" height="26" src="[websvn:locwebsvnhttp]/templates/BlueGrey/e-node.png" alt="[NODE]">
[websvn-enddefineicons]

log.tmpl

This template file is used by log.php. It displays log (history) information for a directory or file. The output is obtained via the svn log command, and is augmented with links to each revision in which the resource was modified and to a detail view of the resource. WebSVN allows users to search and filter logs, and this template should use the appropriate variables to expose this functionality.

Variables defined for the entire scope of the template

actionAction being performed ("Log")
pathPath of item being logged
revThe most recent revision of the current path
dateCommit date of the most recent revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the most recent revision
logLog message of the most recent revision
pathlinksList of links to each directory in the current path
pagelinksList of list to all the pages of the log
showalllinkLink to show the entire log in one go
directorylink(For directories) Link to the directory listing for the current path
filedetaillink(For files) Link to the listing for this file
blamelink(For files) Link to the blame information for this file
difflink(For files) Link to comparison with the previous revision
goyoungestlinkLink to log info for the most recent revision of the resource (only if a newer revision exists)
showchangesWhether changed resources should be shown for each revision
changeslinkLink to show/hide changed resources for each revision
revurlURL to the newest matching revision for this file/directory
logsearch_formLog search box <form> element, plus any hidden inputs
logsearch_inputboxLog search box text field for search text
logsearch_submitLog search box submit button
logsearch_endformLog search box </form> element
logsearch_clearloglinkLink to unfiltered display (remove current search criteria)
logsearch_resultsfoundSet when there are logs to display
logsearch_nomatchesSet when there are no matches for the current request
logsearch_nomorematchesSet when there are no further matches to the current request (but there have been previous pages)
compare_formComparison selection <form> element
compare_submitComparison selection submit button
compare_endformComparison selection </form> element

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

compare_boxComparison selection checkbox for the current revision
compareurlURL to comparison with previously changed revision
revpathlinkLink to revision
revauthorAuthor of this revision
revageAge of revision
revdateDate of revision
revlogLog message of revision
revaddedResources added in this revision (only if showchanges is true)
revdeletedResources deleted in this revision (only if showchanges is true)
revmodifiedResources modified in this revision (only if showchanges is true)

revision.tmpl

This template file is used by revision.php. It displays information about a selected revision, including the author, date, and the resources that were added, deleted, and modified in the revision.

Variables defined for the entire scope of the template

revRevision number of the current revision
dateCommit date of the current revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the current revision
logLog message of the current revision
pathPath of the resource passed to this page
pathlinksList of links to each directory in the current path
directorylinkLink to the directory listing for the current path at this revision
filedetaillink(For files) Link to the listing for this file
blamelink(For files) Link to the blame information for this file
loglinkLink to the log page for the current path, from the current revision backward
goyoungestlinkLink to most recent revision of the current path (only if a newer revision exists)
prevrev / prevrevurlRevision of / link to the previous modification of the current path (only if an older revision exists)
nextrev / nextrevurlRevision of / link to the next modification of the current path (only if a newer revision exists)

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

pathPath to the resource
notinpathSet if the resource does not reside within the specified path
oldpathPrevious path of the resource (only for move or copy)
actionA letter (either A, D, or M) representing how the resource was changed at this revision
addedTrue if the resource was added in this revision
deletedTrue if the resource was deleted in this revision
modifiedTrue if the resource was modified in this revision
detailurlLink to the listing for the resource (previous revision if deleted)
blameurlLink to the blame information for the resource (only for modified/moved/copied files)
diffurlLink to the diff information for the resource (only for modified/moved/copied files)
logurlLink to the log page for the resource
rowparityParity of the row (0 or 1), used to generate striped tables

file.tmpl

This template file is used by filedetails.php. It displays the contents of a file resource. Binary files are displayed by the browser if possible. Text files are displayed inline as plain text unless they have a svn:mime-type property or WebSVN has been configured to display it with a specific MIME type. (See include/distconfig.php for details.) Text files displayed as inline may also be highlighted using GeSHi or Enscript. (See the WebSVN installation guide for details.) MIME type handling and highlighting are done for you automatically in filedetails.php.

Variables defined for the entire scope of the template

pathPath of item being viewed
revRevision being viewed
dateCommit date of the current revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the current revision
logLog message of the current revision
pathlinksList of links to each directory in the current path
goyoungestlinkLink to most recent revision of the file (only if a newer revision exists)
blamelinkLink to the blame information for this file
difflinkLink to comparison with previous revision
revurlURL to the current revision for this file
revlinkLink to the current revision for this file
loglinkLink to the log page for this file
downloadlinkLink to download this file
mimelinkLink to display a file with its associated MIME type. (Only if the file has a MIME type, but it was set to be ignored.)

Special Commands

The command [websvn-getlisting] is used to display the file listing. If syntax highlighting is enabled, the resulting text is styled appropriately.

Note: Remember to put this command on its own line!

blame.tmpl

This template file is used by blame.php. It displays "blame" information like you would see from svn blame, augmented with line numbers and revision links. The variables define for this template make it easy to display groups of consecutive lines last modified in the same revision as a striped block. It also provides JavaScript definitions for displaying at-a-glance revision information popups when hovering over revision numbers. Check the included templates to see how this is done.

Text files displayed as inline may also be highlighted using GeSHi or Enscript. See the WebSVN installation guide for details.

Variables defined for the entire scope of the template

pathPath of item being viewed
revRevision being viewed
dateCommit date of the current revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the current revision
logLog message of the current revision
pathlinksList of links to each directory in the current path
filedetaillinkLink to the listing for this file
difflinkLink to comparison with previous revision
revurlURL to the current revision for this file
revlinkLink to the current revision for this file
loglinkLink to the log page for this file
goyoungestlinkLink to blame info for the most recent revision of the file (only if a newer revision exists)

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

lineThe current line of text to display
linenoLine number of the current line
revisionLast revision in which the current line was changed
authorLast author to modify the line

diff.tmpl

This template file is used by diff.php. It displays the differences between the selected revision of a file and the previous version of the file. Only text files can be diffed in this way — binary files will cause problems.

Variables defined for the entire scope of the template

actionAction being performed ("Diff")
pathPath of item being viewed
revRevision being viewed
dateCommit date of the current revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the current revision
logLog message of the current revision
pathlinksList of links to each directory in the current path
goyoungestlinkLink to diff for the most recent revision of a resource (only if a newer revision exists)
filedetaillinkLink to the listing for this file
blamelinkLink to the blame information for this file
revurlURL to the current revision for this file
revlinkLink to the current revision for this file
loglinkLink to the log page for this file
rev1Revision number of the older file
rev2Revision number of the newer file
showcompactlinkLink to compact view
showalllinkLink to full view

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

rev1lineno / rev2linenoLine number of the next difference block (only defined at the start of a file comparison block)
rev1diffclass / rev2diffclassClass name of the diff block used for colouring differences. One of: {diff, diffadded, diffchanged, diffdeleted}.
rev1line / rev2lineThe line under comparison

compare.tmpl

This template file is used by comp.php. It displays a comparison of two path-revision pairs. The comparison is colorized to show the lines that would need to be added or deleted to transform the first path and revision into the second. This may be applied to files or directories at arbitrary revisions. (For example, it may be used to compare tags and branches with each other or with the trunk.) This template is passed variables used for constructing an HTML form that allows for selecting the paths and revisions to compare.

Variables defined for the entire scope of the template

actionAction being performed ("Path Comparison")
path1Path of 1st resource being compared
path2Path of 2nd resource being compared
rev1Revision of 1st resource being compared
rev2Revision of 2nd resource being compared
rev1urlURL to 1st revision being compared
rev2urlURL to 2nd revision being compared
revThe more recent of the revisions being compared
dateCommit date of the more recent revision
ageAge of the latest revision in days, hours, etc.
authorAuthor of the more recent revision
logLog message of the more recent revision
successtrue if the comparison succeeded
reverselinkLink to reverse the comparison
compare_formComparison selection <form> element
compare_path1inputComparison selection text field for path of 1st resource
compare_path2inputComparison selection text field for path of 2nd resource
compare_rev1inputComparison selection text field for revision of 1st resource
compare_rev2inputComparison selection text field for revision of 2nd resource
compare_submitComparison selection submit button
compare_endformComparison selection </form> element

Variables defined within [websvn-startlisting] ... [websvn-endlisting]

newpathName of new file being compared (only defined at the start of a file comparison block)
difflinesLines changed information for this file. Start of diff lines. (only defined after newpath)
diffclassClass name of the diff block used for colouring differences. One of: {diff, diffadded, diffdeleted}
lineThe current line
enddifflinesEnd of diff lines
propertiesProperty changes
endpathEnd of current path

Suggestions

Although providing all the .tmpl files detailed above can prevent template-related WebSVN errors, there are several things that can make a bare-bones custom template more attractive, useful, and robust.

Styling

CSS rules should be placed in an external stylesheet wherever possible. The standard approach is to create a styles.css file in your template directory and link to it in header.tmpl as shown above. This makes it easy to make broad changes across the entire template with very little effort. Grouping the CSS rules logically in the stylesheet makes it easier to tell which rules affect which pages.

Poorly-designed templates can be inconvenient (even painful) to use. Use space wisely. Some WebSVN pages can present a lot of data, and endless scrolling can be a pain. On the other hand, packing things too tightly can make it difficult to find what you need. If you use icons, choose ones that match the functionality they represent. Sites like iconfinder.net and iconspedia.com can be good resources. If your colors clash, try using a color set from a site like kuler.adobe.com or colorschemer.com.

If your template doesn't look good when printed, consider creating a print-only stylesheet. For example, it might omit background images or colors that harm readability when printed in grayscale, change font sizes, etc. It could also be worthwhile to make sure your template works on mobile browsers.

Markup

Creating semantically-oriented markup (including judicious use of <div> and <span> tags, as well as id and class attributes) is also a good idea. Well-structured markup makes it much easier to apply CSS rules, and can improve the appearance of your template when viewed by users with older browsers or special accessibility needs.

It should go without saying that valid (X)HTML markup is ideal. Check the output of your template files against validator.w3.org to ensure that browsers can render the pages quickly and correctly. There is no excuse for creating new content using invalid markup — it saves very little development time and can cost you down the road when your template doesn't always look the way it should. Be especially careful about properly closing <div> and <span>tags, or the problem may be compounded by incorrectly-applied CSS rules.

Organization

Although WebSVN only cares how you organize the .tmpl files, good organization scheme makes it easier to understand and maintain your template. For example, it's pretty standard to place images in an images/ subdirectory. If you have a lot of JavaScript or other assets, consider grouping them in a subdirectory as well.