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 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.
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.
The placeholder
[websvn-include:user_greeting.tmpl] can be used to include external templates into the current one at the position the command is placed. A path relative
to the template directory needs to be given and the file needs to exist, but doesn't necessary needs to contain any
content. The template is processed recursivly with all commands, variables etc. in it processed as well.
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]
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]
A few template files — including directory.tmpl and file.tmpl — use additional commands, which are described in those sections below.
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.
| 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 |
| showageinsteadofdate | Whether to display the relative age of a commit rather than the absolute date. |
| 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.
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.
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.
| 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) |
| showlastmod | Whether "last modification" info should be displayed for each project |
| projectlink | HTML link to a project (not set for group headers) |
|---|---|
| projectname | Name of the project (not set for group headers) |
| projecturl | URL of the 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 |
| revision | Number of the latest revision affecting the current project |
| 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 |
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.
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.
| 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 |
| age | Age of the latest revision in days, hours, etc. |
| 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 the current revision for this directory |
| revlink | Link to the current revision for this directory |
| 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 |
| showlastmod | Whether "last modification" info should be displayed for each path |
| 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 path |
| 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 |
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]
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.
| 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 |
| age | Age of the latest revision in days, hours, etc. |
| 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 |
| revurl | URL to the newest matching revision for this file/directory |
| 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 |
| compare_box | Comparison selection checkbox for the current revision |
|---|---|
| compareurl | URL to comparison with previously changed 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) |
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.
| rev | Revision number of the current revision |
|---|---|
| date | Commit date of the current revision |
| age | Age of the latest revision in days, hours, etc. |
| 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 |
| 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) |
| path | Path to the resource |
|---|---|
| notinpath | Set if the resource does not reside within the specified path |
| 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 |
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.
| path | Path of item being viewed |
|---|---|
| rev | Revision being viewed |
| date | Commit date of the current revision |
| age | Age of the latest revision in days, hours, etc. |
| 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 |
| revurl | URL to the current revision for this file |
| revlink | Link to 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.) |
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!
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.
| path | Path of item being viewed |
|---|---|
| rev | Revision being viewed |
| date | Commit date of the current revision |
| age | Age of the latest revision in days, hours, etc. |
| 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 |
| revurl | URL to the current revision for this file |
| revlink | Link to 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) |
| 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 |
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.
| action | Action being performed ("Diff") |
|---|---|
| path | Path of item being viewed |
| rev | Revision being viewed |
| date | Commit date of the current revision |
| age | Age of the latest revision in days, hours, etc. |
| 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 |
| revurl | URL to the current revision for this file |
| revlink | Link to 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 |
| 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 |
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.
| 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 |
| age | Age of the latest revision in days, hours, etc. |
| 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 |
| 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 |
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.
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.
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.
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.