# ViewVC 1.0 Template Authoring Guide

## Introduction

This document represents an (unfinished) attempt at providing documentation for how to customize ViewVC 1.0-dev's HTML output via modification of its templates.

## Table of Contents

## Using EZT

### TODO ###

## Variables Available to ViewVC Templates

### Common Template Variable Set (COMMON)

Variable | Type | Description
--- | --- | ---
cfg | Object | Representation of the object used by ViewVC for runtime configuration parameters such as those parsed from `viewvc.conf`. Dot-qualified children of this object map to configuration sections and option keys. For example, cfg.options.show_logs contains the value of the show_logs variable in the options section of the configuration file.
change_root_action | String | Form action URL for the root selection form.
change_root_hidden_values | String | Hidden value HTML markup for the root selection form.
docroot | String | URL of the static documents directory, generally used for referencing stylesheets and images stored in and under that directory (which is typically relative to the template location).
graph_href | String | URL of the ViewVC revision graph view for the current resource.
kv | Object | Representation of the object used by ViewVC for user-defined key/value mappings. Dot-qualified children of this object map to named key/value files and the sections and keys within them. For example, kv.l10n.labels.directory maps to the value of the directory key under the labels section of the key/value file whose configured abstract name is l10n.
log_href | String | URL of the ViewVC revision log view for the current resource.
log_rev_href | String | Revision number of the file-revision currently being viewed, or None.
nav_path | List | Ordered list of path components from the repository root to the current resource.
nav_path.href | String | URL of the default ViewVC view for the path component.
nav_path.name | String | Name of the path component.
pathtype | String | Path kind of the current resource. Valid values: `file` (file), `dir` (directory); may be empty.
rootname | String | Name of the current repository (root).
roots | List | Set of configured viewable repositories.
roots.name | String | Name of a configured repository.
roots.type | String | Version control type of a configured repository. Valid values: `cvs`, `svn`.
roots.href | String | URL of root directory view for a configured repository.
roottype | String | Version control type of the current repository (root). Valid values: `cvs` (CVS), `svn` (Subversion).
up_href | String | Link to the current object's parent directory view.
view | String | Name of the current view. Valid values: `annotate` (annotation view), `diff` (file difference view), `roots` (root listing view), `dir` (directory listing view), `graph` (revision graph view), `log` (revision log view), `markup` (file contents view), `query` (revision history query results view), `queryform` (revision history query form view), `rev` (revision/changeset view).
vsn | String | ViewVC version identifier.
where | String | Path (relative to the current repository root) of the current resource.

### File Navigation Variable Set (NAVDATA)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set
annotate_href | String | URL of the ViewVC annotation view for the current resource.
download_href | String | ViewVC file contents download URL for the current resource.
download_text_href | String | ViewVC file contents as-text download URL for the current resource.
orig_path | String | When viewing an old file revision through a copy of the file, this is the old file revision's original path.
orig_href | String | URL of a ViewVC log view for `orig_path`.
prefer_markup | Boolean | Indicates whether to make the default file link a link to the markup page instead of the checkout page.
rev | String | Revision of the current resource.
revision_href | String | URL of the Subversion revision view for the current revision.
rss_href | String | URL of RSS feed for current location.
view_href | String | URL of the ViewVC file contents view for the current resource.

### Path Revision Form Variable Set (PATHREV)

Variable | Type | Description
--- | --- | ---
lastrev | String | If the current path is deleted in a future revision, last revision where the path is available. (Subversion only)
pathrev | String | Current sticky revision (Subversion) or sticky tag (CVS)
pathrev_action | String | Form action URL for the sticky revision/tag selection form.
pathrev_hidden_values | String | Hidden value HTML markup for the revision/tag selection form.
pathrev_clear_action | String | Form action URL for the path revision clear button.
pathrev_clear_hidden_values | String | Hidden value HTML markup for the path revision clear button.

### Paging Form Variable Set (PAGING)

Variable | Type | Description
--- | --- | ---
picklist | List | List of pages that make up the current directory or log view.
picklist.start | String | Name of first item on the page
picklist.end | String | Name of last item on the page
picklist.page | String | Page number (indexed from 1)
picklist.count | String | Number of the first item on the page (indexed from 0)
picklist_len | String | Number of pages in picklist

### Annotation View (annotate.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the NAVDATA variable set
lines | List | Set of objects containing information about the most recent modification of a single line of file content in the current resource, naturally ordered by the line numbers they represent. Every line in the resource is represented in the set.
lines.author | String | Username of the most recent modifier of the line.
lines.date | String | Date (in UTC if not otherwise configured) of the modification of the line.
lines.diff_url | String | URL of the ViewVC file difference view which displays the modification of the line.
lines.line_number | String | Line number (1-based) of the line.
lines.prev_rev | String | Youngest revision of the resource prior to the line's modification.
lines.rev | String | Revision in which the modification of the line occured.
lines.text | String | Textual contents of the line.

### Revision Graph View (graph.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set
imagemap | String | HTML markup containing the image map associated with the revision graph.
imagesrc | String | URL of the ViewVC revision graph image for the current resource.

### File Difference View (diff.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set
annotate_href | String | URL for the annotate view of the right-side file revision.
changes | List | Set of objects which contain information about a single line of file difference data. Valid only when diff_format is `h` or `l`.
changes.have_left | Boolean | Specifies whether the left file has a line of content relevant to the difference data line. Valid only when changes.type is `change`.
changes.have_right | Boolean | Specifies whether the right file has a line of content relevant to the difference data line. Valid only when changes.type is `change`.
changes.left | String | Textual contents of the relevant line in the left file. Valid only when changes.type is `change`, `context`, or `remove`. When changes.type is `change`, valid only when changes.have_left is set (in order to delineate between missing lines and empty lines, which EZT does not support).
changes.right | String | Textual contents of the relevant line in the right file. Valid only when changes.type is `add`, `change`, or `context`. When changes.type is `change`, valid only when changes.have_left is set (in order to delineate between missing lines and empty lines, which EZT does not support).
changes.line_info_extra | String | Additional line information for the current difference hunk. Valid only when changes.type is `header`.
changes.line_info_left | String | First line number represented by the current hunk in the left file. Valid only when changes.type is `header`.
changes.line_info_right | String | First line number represented by the current hunk in the right file. Valid only when changes.type is `header`.
changes.line_number | String | Line number (1-based) of the line.
changes.type | String | The type of change. Value values: `add`, `change`, `context`, `header`, `no-changes`, `remove`.
date_left | String | Date (in UTC if not otherwise configured) in which the left file revision was created.
date_right | String | Date (in UTC if not otherwise configured) in which the right file revision was created.
diff_format | String | Difference dislay format: Valid values are `c` (context), `h` (human-readable, or colored), `l` (long human-readable), `s` (side-by-side), `u` (unified).
diff_format_action | String | Form action URL for the diff format selection form.
diff_format_hidden_values | String | Hidden value HTML markup for the diff format selection form.
raw_diff | String | Raw difference text. Valid only when diff_format is `c`, `s`, or `u`.
rev_left | String | Revision of the left file.
rev_right | String | Revision of the right file.
tag_left | String | Tag of the left file.
tag_right | String | Tag of the right file.

### Directory Listing View (directory.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON, PATHREV, and PAGING variable sets
attic_showing | Boolean | Indicates whether or not the directory list include "dead" files (files not available in, perhaps deleted from, the current tag). CVS only.
branch_tags | List | Set of branch tag names in use by files in the current directory. CVS only.
dir_pagestart | String | Item number (zero-based) of the first directory entry requested to be shown on the page. Corresponds to the dir_pagestart CGI parameter.
dir_paging_action | String | Form action URL for the page selection form.
dir_paging_hidden_values | String | Hidden value HTML markup for the page selection form.
entries | List | Set of objects which represent the entries of this directory.
entries.ago | String | Textual description of the time since entries.date.
entries.annotate_href |  |
entries.author | String | Username of the last modifier of the directory entry.
entries.date | String | Date (in UTC if not otherwise configured) of the last modification of the directory entry.
entries.download_href |  |
entries.download_text_href |  |
entries.errors |  |
entries.graph_href | String | URL of the ViewVC revision graph view for the directory entry.
entries.log |  |
entries.log_file |  |
entries.log_href | String | URL of the ViewVC revision log view for the directory entry.
entries.log_rev |  |
entries.mime_type |  |
entries.name | String | Name of the directory entry.
entries.rev | String | Revision of the directory entry. For CVS repositories, this is a revision at the tip of the selected tag or branch; for Subversion, this is the youngest revision as of the revision of the directory being viewed.
entries.revision_href | String | URL of the Subversion revision view for the directory entries current revision. Valid only when roottype is `svn`.
entries.size | String | Size (in bytes) of the directory entry. Valid only when roottype is `svn` and entries.pathtype is `file`.
entries.state |  |
entries.pathtype | String | Path kind of the directory entry. Valid values: `file` (file), `dir` (directory); may be empty.
entries.prefer_markup | Boolean | Indicates whether to make the default file link a link to the markup page instead of the checkout page. Valid only when entries.pathtype is `file`.
entries.view_href |  | This is a URL for the markup view if the entry is a file, and a URL for a directory listing if the entry is a directory.
files_shown | String | Number of files displayed.
hide_attic_href | String | URL for the current view, but with "dead" files hidden. CVS only.
num_dead | String | Number of dead files in the current directory.
plain_tags | List | List of tag names in use by files in the current directory. CVS only.
queryform_href | String | URL for a query form returning results from this directory.
search_re | String | Current search expression, if any.
search_re_form | Boolean | Indicates whether or not to display the regular expression search form. Value depends on the whether searching is enabled in the configuration and whether or not the current directory is empty.
search_re_action | String | Form action URL for the regular expression search form.
search_re_hidden_values | String | Hidden value HTML markup for the regular expression search form.
show_attic_href | String | URL for the current view, but with "dead" files shown. CVS only.
sortby | String | Current sorting mode. Valid values: `file`, `rev`, `date`, `author`, and `log`.
sortby_author_href | String | URL for the current view, but sorted by author.
sortby_date_href | String | URL for the current view, but sorted by date.
sortby_file_href | String | URL for the current view, but sorted by filename.
sortby_log_href | String | URL for the current view, but sorted by log message.
sortby_rev_href | String | URL for the current view, but sorted by revision number.
sortdir | String | Current sorting mode. Valid values: `up` (ascending) and `down` (descending)
tarball_href | String | URL to download tarball of the current directory.
tree_rev | String | Last revision number where the current directory (or any path underneath it) was modified. Subversion only.
tree_rev_href | String | URL for revision view showing information about the tree_rev revision. Subversion only.
youngest_rev | String | Last revision number in the repository. Subversion only
youngest_rev_href | String | URL for revision view showing information about the youngest_rev revision. Subversion only.

### Error View (error.ezt)

Variable | Type | Description
--- | --- | ---
msg | String | Message describing the current error.
stacktrace | String | Python stack trace showing where the error occurred.
status | String | HTTP status code like "404 Not Found" that was sent to the browser with this error message.

### Revision Log View (log.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON, PATHREV, and PAGING variable sets
annotate_href | String | URL for annotate view of the HEAD revision of the file.
branch_tags | List | Names of branch tags in the file. CVS only.
default_branch | List | Default branch names (CVS only)
diff_format | String | Currently selected diff format in the diff selection form. Valid values are `c` (context), `h` (human-readable, or colored), `l` (long human-readable), `s` (side-by-side), `u` (unified).
diff_select_action | String | Form action URL for the diff selection form.
diff_select_hidden_values | String | Hidden value HTML markup for the diff selection form.
download_href | String | URL to download the HEAD revision of the file.
download_text_href | String | URL to download the HEAD revision of the file as `text/plain`.
entries | List | List of revisions where the file or directory was modified.
entries.ago | String | Text description of the time elapsed since entries.date.
entries.annotate_href | String | URL for the annotate view of the file revision.
entries.author | String | Author of the revision.
entries.branch_names | List | If this last revision on a branch, a list of names for that branch.
entries.branch_point | String | If the revision is on a branch, this is the revision number the branch branched off from. CVS only.
entries.branch_points | String | List of branch tags which branch off of this revision. CVS only.
entries.branch_points.name | String | Name of the branch tag.
entries.branch_points.href | String | URL for the current view, but with this tag set as the sticky tag.
entries.branches | String | List of branch tags that include this file revision. CVS only.
entries.branches.name | String | Name of the branch tag.
entries.branches.href | String | URL for the current view, but with this tag set as the sticky tag.
entries.changed | String | Numbers of lines added and removed since the previous revision. CVS only.
entries.copy_href | String | URL for log view of entries.copy_path.
entries.copy_path | String | If the file revision was copied from somewhere, this is the path it was copied from. Subversion only.
entries.copy_rev | String | If the file revision was copied from somewhere, this is the revision number of the path it was copied from. Subversion only.
entries.date | String | Date (in UTC if not otherwise configured) of the revision.
entries.diff_to_branch_href | String | URL for a diff view of this file revision showing the changes since the branch was created at (entries.branch_point). CVS only.
entries.diff_to_main_href | String | If this revision is at the tip of a branch, URL for a diff view of this file revision showing the differences between it and the latest revision on the parent branch (entries.next_main). CVS only.
entries.diff_to_prev_href | String | URL for a diff view of this file revision showing the changes since the previous revision (entries.prev).
entries.diff_to_sel_href | String | URL for a diff view of this file revision and the currently selected revision (rev_selected).
entries.download_href | String | URL to download the file revision.
entries.download_text_href | String | URL to download the file revision as `text/plain`.
entries.log | String | Revision log message.
entries.next_main | String | If this revision is on the tip of the branch, this is the latest revision of the parent branch, a likely merge candidate.
entries.orig_href | String | URL for log view of entries.orig_path
entries.orig_path | String | If this file revision is located at a different path than the newest file revision (because it precedes a copy or move), this is the path it was originally located at. Subversion only.
entries.prefer_markup | Boolean | Indicates whether to make the default file link a link to the markup page instead of the checkout page.
entries.prev | String | Previous revision number.
entries.rev | String | Revision number.
entries.revision_href | String | URL for revision view showing more information about the revision.
entries.sel_for_diff_href | String | URL for current view, but with this revision selected for diffs.
entries.size | String | Size of the file revision, in bytes. Subversion only.
entries.state | String | State of the file revision. Possible values: `dead`, and the empty string.
entries.tag_names | List | List of tag names which refer to the revision.
entries.tags | List | List of tags which refer to the revision
entries.tags.name | String | Name of the tag.
entries.tags.href | String | URL for the current page, but with this tag set as the sticky tag.
entries.vendor_branch | Boolean | Indicates if this revision is on a vendor branch.
entries.view_href | String | URL for markup view for a file revision, or directory listing view for a directory revision.
human_readable | Boolean | Indicates whether or not currently selected diff format (diff_format) is human readable (colored).
log_pagestart | String | Item number (zero based) of the first directory entry requested to be shown on the page. Corresponds to the log_pagestart query parameter.
log_paging_action | String | Form action URL for the page selection form.
log_paging_hidden_values | String | Hidden value HTML markup for the page selection form.
logsort | String | Current sorting mode. Possible values: `date` and `rev`.
logsort_action | String | Form action URL for log sort drop down box.
logsort_hidden_values | String | Hidden value HTML markup for the log sort drop down box
mime_type | String | MIME type of current file.
plain_tags | List | Names of non-branch in the file. CVS only.
prefer_markup | Boolean | Indicates whether to make the default file link a link to the markup page instead of the checkout page.
rev_selected | String | Revision number currently selected for diffs.
tag_annotate_href | String | URL for annotate view of the file at currently selected sticky tag.
tag_download_href | String | URL to download the file at currently selected sticky tag. CVS only.
tag_download_text_href | String | URL to download the file as `text/plain` at the currently selected sticky tag. CVS only
tag_prefer_markup | Boolean | Indicates whether to make the default file link a link to the markup page instead of the checkout page.
tag_view_href | String | URL for markup view of the file at the currently selected sticky tag. CVS only.
tags | String | List of tags that in the current file. CVS only.
tags.rev | String | Revision number for a non-branch tag, or the latest revision number on the branch for a branch tag.
tags.name | String | Tag name
view_href | String | URL for markup view of the HEAD revision of the file.

### File Contents View (markup.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the NAVDATA variable set
ago | String | Text description of the time elapsed since date.
author | String | Author of the revision being viewed.
branch_points | String | List of branch tag names which branch off of the revision being viewed (CVS only).
branches | List | If revision currently being viewed is on a branch, list of names for the branch.
changed | String | Numbers of lines added and removed since the previous revision.
date | String | Date (in UTC if not otherwise configured) of the revision currently being viewed.
log | String | Log message of the revision currently being viewed.
markup | File | Marked up contents of the current file revision.
mime_type | String | MIME type of the current file.
prev | String | Previous revision number.
size | String | Size of the file revision, in bytes. Subversion only.
state | String | State of the file revision. Possible values: `dead`, and the empty string.
tags | List | Names of tags that have been applied to the current file revision.
vendor_branch | Boolean | Indicates whether or not the current file revision is on a vendor branch.

### Revision History Query Results View (query_results.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set
backout_href | String | URL for a page that shows a list of commands that can be applied to a working copy to revert all the changes returned by the query.
commits | List | List of commits to files under the current directory that meet the query criteria.
commits.author | String | Author of the commit.
commits.files | List | List of files under the current directory affected by the commit.
commits.files.author | String | Author of the commit.
commits.files.date | String | Date (in UTC if not otherwise configured) the change to the file was committed.
commits.files.dir | String | Path of the directory containing the file.
commits.files.dir_href | String | URL for directory listing of commits.files.dir.
commits.files.file | String | File name.
commits.files.rev | String | Revision number of the file.
commits.files.branch | File | Branch the commit occurred on.
commits.files.diff_href | String | URL to diff page showing changes since previous file revision.
commits.files.log_href | String | URL for file's log page.
commits.files.minus | String | Number of lines removed from the file by the commit.
commits.files.plus | String | Number of lines added to the file by the commit.
commits.files.type | String | Type of change made to the file by the commit. Possible values: `Change`, `Add`, `Remove`
commits.log | String | Commit log message.
commits.limited_files | Boolean | True if files list was cut short due to `limit_changes`.
commits.minus | String | Total number of lines removed from files in this commit.
commits.num_files | String | Total number of files in the commits.files list.
commits.plus | String | Number of lines added to files in this commit.
commits.rev | String | Commit revision number. Subversion only.
commits.rss_date | String | Date of the commit formatted for RSS.
commits.rss_url | String | Absolute URL of the revision page for the commit. Subversion only.
commits.short_log | String | Truncated commit log message.
english_query | String | Text description of the current query criteria.
limit_changes | String | Current `limit_changes` value, maximum number of changed files to show per commit.
limit_changes_href | String | URL for the current view but with `limit_changes` disabled.
minus_count | String | Total number of lines removed from all files across all returned commits.
plus_count | String | Total number of lines added to all files across all returned commits.
queryform_href | String | URL for form to edit query criteria.
querysort | String | Indicates how query results are being sorted. Possible values: `date`, `author`, and `file`.
show_branch | Boolean | Indicates whether or not to list branch names in the results. True when query results can include more than a single branch.
sql | String | SQL string used to query database. Included for debugging purposes.

### Revision History Query Form View (query_form.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set
branch | String | Query string for filtering results by branch.
branch_match | String | Type of match to perform with branch query string. Valid values: `exact`, `like`, `glob`, `regex`, `notregex`.
date | String | Option for filtering results by date. Possible values: `hours`, `day`, `week`, `month`, `all`, `explicit`.
dir | String | Query string for filtering results by subdirectory.
dir_href | String | URL for directory list of current directory.
file | String | Query string for filtering results by file name.
file_match | String | Type of match to perform with file query string. Valid values: `exact`, `like`, `glob`, `regex`, `notregex`.
hours | String | If date is `hours`, number of hours back to include results from.
limit_changes | String | Current `limit_changes` value, maximum number of changed files to show per commit.
maxdate | String | If date is `explicit`, latest date to include results from.
mindate | String | If date is `explicit`, earliest date to include results from.
query_action | String | Form action URL for query form.
query_hidden_values | String | Hidden value HTML markup for query form.
querysort | String | Option for sorting query results. Possible values: `date`, `author`, and `file`.
who | String | Query string for filtering results by author.
who_match | String | Type of match to perform with who query string. Possible values: `exact`, `like`, `glob`, `regex`, `notregex`.

### Revision/ChangeSet View (revision.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set
ago | String | Text description of the time elapsed since date.
author | String | Author of the revision.
changes | List | List of paths changed in this revision.
changes.action | String | Indicates what happened to the path in this revision. Valid values are: `added`, `modified`, `replaced`, and `deleted`.
changes.copy_path | String | Original path if path was copied from somewhere in this revision.
changes.copy_rev | String | Revision number of original path if path was copied from somewhere in this revision
changes.diff_href | String | URL for diff of changed path against previous revision.
changes.is_copy | Boolean | Indicates whether path was copied from another path in this revision.
changes.log_href | String | URL for log view of changed path.
changes.path | String | Changed path.
changes.pathtype | String | Type of changed path. Valid values: `file` or `dir`
changes.prop_mods | Boolean | Indicates whether the path's properties changed in this revision
changes.text_mods | Boolean | Indicates whether the path's file contents changed in this revision.
changes.view_href | String | URL for markup view of changed path.
date | String | Revision date (in UTC if not otherwise configured).
first_changes | String | Configured value for `limit_changes`.
first_changes_href | String | URL for the current view but with `limit_changes` set to the configured value.
jump_rev_action | String | Form action URL for revision jump form.
jump_rev_hidden_values | String | Hidden value HTML markup for revision jump form.
limit_changes | String | Current `limit_changes` value, maximum number of changed files to show per commit.
log | String | Revision log message.
more_changes | String | Number of changes not being shown due to `limit_changes`.
more_changes_href | String | URL for the current view but with `limit_changes` disabled.
next_href | String | URL for revision page of the next revision.
prev_href | String | URL for revision page of the previous revision.
rev | String | Revision number.

### Root Listing View (roots.ezt)

Variable | Type | Description
--- | --- | ---
Includes all variables from the COMMON variable set