# WebSVN Templating System

## Content

- Introduction
- Variables
- Commands
- Template Files
  - Header / Footer
  - index.tmpl
  - directory.tmpl
  - log.tmpl
  - revision.tmpl
  - file.tmpl
  - blame.tmpl
  - diff.tmpl
  - compare.tmpl
- Suggestions

## 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

version | The version of WebSVN
currentyear | The current year
template | The base name of the invoked template file (excluding ".tmpl")
locwebsvnhttp | Root of the WebSVN directory
indexurl | URL for the WebSVN index page
repname | Name of the repository
clientrooturl | The root URL for SVN clients to use (only if provided in `config.php`)
peg | The peg revision passed to the page (can use with `clientrooturl`)
charset | The charset requested by the user
language_code | The RFC 2616 language code of the selected language
language_form | Language selection menu <form> element
language_select | Language selection menu <select>...</select> element
language_submit | Language selection menu submit button
language_endform | Language selection menu </form> element
projects_form | Project selection menu <form> element, plus any hidden inputs
projects_select | Project selection menu <select>...</select> element
projects_submit | Project selection menu submit button
projects_endform | Project selection menu </form> element
error | A string representing an error condition, or empty if there is none.
warning | A 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

treeview | true if the index should be displayed as a tree of grouped projects
flatview | true if the index should be displayed as a simple list of projects
opentree | true if the tree viewed should be open by default
groupcount | The number of project groups (0 or more)

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

projectlink | HTML link to a project (not set for group headers)
clientrooturl | The root URL for SVN clients to use for a repository (only if provided in `config.php`)
rowparity | Parity of the row (0 or 1), used to generate striped tables. Group headers do no have a row parity, only projects
groupparity | Similar to row parity, but the first entry in each group restarts at 0
groupid | Only set if the current entry is a group header
groupname | Set for group headers and each member of a group
notfirstgroup | true if the entry is a second or subsequent group

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

restricted | True if the users has restricted access to this directory (to allow access to a readable directory lower down only)
path | Path of the directory being listed
rev | Revision being viewed
date | Commit date of the current revision
author | Author of the current revision
log | Log message of the current revision
youngestrev | The most recent revision affecting the current directory
goyoungestlink | Link to most recent revision of the current directory (only if a newer revision exists)
pathlinks | List of links to each directory in the current path
logurl | URL to the log view of current directory
revurl | URL to details of the current revision being viewed
rssurl | URL to the RSS feed for the current directory
downloadurl | URL to download an archive for the current directory
compareurl | URL to comparison with previously changed revision
allowdownload | True if downloading has been configured
compare_form | Comparison selection <form> element
compare_submit | Comparison selection submit button
compare_endform | Comparison selection </form> element

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

compare_box | Comparison selection checkbox for the current resource
rowparity | Parity of the row (0 or 1), used to generate striped tables
filename | Name of the current file/directory
fileurl | URL to the current file/directory
filelink | Link to the current file/directory (includes filename)
filetype | Type of the current entry (file, dir, opendir, etc.)
isDir | true if the current file is a directory (use with [websvn-test:isDir] to display icons)
openDir | true if the current file is a directory on the current path
logurl | URL to the log page for the current file/directory
rssurl | URL to the RSS feed for the current file/directory
downloadurl | URL to download the current entry (only for files)
downloadplainurl | URL to download the current entry (only for directories)

revurl | URL for examining the latest revision in detail
revision | Number of the latest revision affecting the current element
committime | Timestamp of latest revision
date | Date of the latest revision (yyyy-mm-dd)
age | Age of the latest revision in days, hours, etc.
author | Author 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-node` | I-shaped node for the tree view
`t-node` | T-shaped node for the tree view
`l-node` | L-shaped node for the tree view
`e-node` | Empty 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

action | Action being performed ("Log")
path | Path of item being logged
rev | The most recent revision of the current path
date | Commit date of the most recent revision
author | Author of the most recent revision
log | Log message of the most recent revision
pathlinks | List of links to each directory in the current path
pagelinks | List of list to all the pages of the log
showalllink | Link 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
goyoungestlink | Link to log info for the most recent revision of the resource (only if a newer revision exists)
showchanges | Whether changed resources should be shown for each revision
changeslink | Link to show/hide changed resources for each revision
logsearch_form | Log search box <form> element, plus any hidden inputs
logsearch_inputbox | Log search box text field for search text
logsearch_submit | Log search box submit button
logsearch_endform | Log search box </form> element
logsearch_clearloglink | Link to unfiltered display (remove current search criteria)
logsearch_resultsfound | Set when there are logs to display
logsearch_nomatches | Set when there are no matches for the current request
logsearch_nomorematches | Set when there are no further matches to the current request (but there have been previous pages)
compare_form | Comparison selection <form> element
compare_submit | Comparison selection submit button
compare_endform | Comparison selection </form> element

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

compare_box | Comparison selection checkbox for the current revision
revpathlink | Link to revision
revauthor | Author of this revision
revage | Age of revision
revdate | Date of revision
revlog | Log message of revision
revadded | Resources added in this revision (only if showchanges is true)
revdeleted | Resources deleted in this revision (only if showchanges is true)
revmodified | Resources 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

rev | Revision number of the current revision
date | Commit date of the current revision
author | Author of the current revision
log | Log message of the current revision
path | Path of the resource passed to this page
pathlinks | List of links to each directory in the current path
directorylink | Link 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
revlink | Link to details of the current revision for this file
loglink | Link to the log page for the current path, from the current revision backward
goyoungestlink | Link to most recent revision of the current path (only if a newer revision exists)
prevrev / prevrevurl | Revision of / link to the previous modification of the current path (only if an older revision exists)
nextrev / nextrevurl | Revision of / link to the next modification of the current path (only if a newer revision exists)

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

path | Path to the resource
oldpath | Previous path of the resource (only for move or copy)
action | A letter (either A, D, or M) representing how the resource was changed at this revision
added | True if the resource was added in this revision
deleted | True if the resource was deleted in this revision
modified | True if the resource was modified in this revision
detailurl | Link to the listing for the resource (previous revision if deleted)
blameurl | Link to the blame information for the resource (only for modified/moved/copied files)
diffurl | Link to the diff information for the resource (only for modified/moved/copied files)
logurl | Link to the log page for the resource
rowparity | Parity 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

path | Path of item being viewed
rev | Revision being viewed
date | Commit date of the current revision
author | Author of the current revision
log | Log message of the current revision
pathlinks | List of links to each directory in the current path
goyoungestlink | Link to most recent revision of the file (only if a newer revision exists)
blamelink | Link to the blame information for this file
difflink | Link to comparison with previous revision
revlink | Link to details of the current revision for this file
loglink | Link to the log page for this file
downloadlink | Link to download this file
mimelink | Link 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

path | Path of item being viewed
rev | Revision being viewed
date | Commit date of the current revision
author | Author of the current revision
log | Log message of the current revision
pathlinks | List of links to each directory in the current path
filedetaillink | Link to the listing for this file
difflink | Link to comparison with previous revision
revlink | Link to details of the current revision for this file
loglink | Link to the log page for this file
goyoungestlink | Link to blame info for the most recent revision of the file (only if a newer revision exists)

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

line | The current line of text to display
lineno | Line number of the current line
revision | Last revision in which the current line was changed
author | Last 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

action | Action being performed ("Diff")
path | Path of item being viewed
rev | Revision being viewed
date | Commit date of the current revision
author | Author of the current revision
log | Log message of the current revision
pathlinks | List of links to each directory in the current path
goyoungestlink | Link to diff for the most recent revision of a resource (only if a newer revision exists)
filedetaillink | Link to the listing for this file
blamelink | Link to the blame information for this file
revlink | Link to details of the current revision for this file
loglink | Link to the log page for this file
rev1 | Revision number of the older file
rev2 | Revision number of the newer file
showcompactlink | Link to compact view
showalllink | Link to full view

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

rev1lineno / rev2lineno | Line number of the next difference block (only defined at the start of a file comparison block)
rev1diffclass / rev2diffclass | Class name of the diff block used for colouring differences. One of: {diff, diffadded, diffchanged, diffdeleted}.
rev1line / rev2line | The 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

action | Action being performed ("Path Comparison")
path1 | Path of 1st resource being compared
path2 | Path of 2nd resource being compared
rev1 | Revision of 1st resource being compared
rev2 | Revision of 2nd resource being compared
rev1url | URL to 1st revision being compared
rev2url | URL to 2nd revision being compared
rev | The more recent of the revisions being compared
date | Commit date of the more recent revision
author | Author of the more recent revision
log | Log message of the more recent revision
success | true if the comparison succeeded
reverselink | Link to reverse the comparison
compare_form | Comparison selection <form> element
compare_path1input | Comparison selection text field for path of 1st resource
compare_path2input | Comparison selection text field for path of 2nd resource
compare_rev1input | Comparison selection text field for revision of 1st resource
compare_rev2input | Comparison selection text field for revision of 2nd resource
compare_submit | Comparison selection submit button
compare_endform | Comparison selection </form> element

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

newpath | Name of new file being compared (only defined at the start of a file comparison block)
difflines | Lines changed information for this file. Start of diff lines. (only defined after newpath)
diffclass | Class name of the diff block used for colouring differences. One of: {diff, diffadded, diffdeleted}
line | The current line
enddifflines | End of diff lines
properties | Property changes
endpath | End 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.