Doxia Site Tools - Site Renderer

The Site Renderer handles the rendering of sites, assembling a common site decoration (also called a skin) with a collection of documents.

Documents can be dynamically generated with Doxia Sink API, like Maven reports, or simply read from static files written in markup supported by Doxia Parsers, eventually processed by Velocity if their file names end in .vm.

Doxia Site Skins

A default site decoration is included (see default-site.vm), but other decorations can be used at will, either as a standalone template or packaged in a skin artifact (containing a META-INF/maven/site.vm template).

Maven team provides a collection of skins for projects use.

Some documentation is available on how to create a new skin.

Velocity processing

Site decoration and documents with file names ending in .vm are processed by Velocity.

The Velocity context contains some variables related to rendering context that you can use:

variable type description
alignedFileName String The file name of the (html) document being rendered, relative to the document being rendered
decoration DecorationModel This is a model that represents the data in your site.xml
currentDate Date The date when the site is rendered
currentFileName String The file name of the (html) document being rendered, relative to the site root
dateFormat DateFormat An instance of the date format as defined in site.xml/publishDate/@format (default: An instance of the default date format for the locale of the document being rendered
dateRevision String The date when the site is rendered, in the format "yyyyMMdd"
doxiaSiteRendererVersion String The version of Doxia Site Renderer in use
isoDateFormat DateFormat An instance of the ISO-8601 date format, ie "yyyy-MM-dd"
locale Locale The locale for the document being rendered
publishDate Date An optional hardcoded publish date that has been set programmatically
relativePath String The path to the site root from the document being rendered
supportedLocales List<Locale> The list of locales that the site will contain

There are also some tools for general use:

variable type description
FileUtils FileUtils
i18n I18N
PathTool PathTool
StringUtils StringUtils
plexus PlexusContainer

Additionally, there are Velocity Generic Tools populated with the site locale, the decoration model's date format, and site renderer's resource bundle:

variable type description
alternator AlternatorTool For creating alternators to easily alternate over a set of values.
class ClassTool For simplifying reflective lookup of information about classes and their fields, methods and constructors.
context ContextTool For convenient access to context data and metadata.
convert ConversionTool For converting String values to richer object types.
date ComparisonDateTool For manipulating, formatting, and comparing dates.
display DisplayTool For controlling display of references (e.g., truncating values, "pretty printing" lists, and displaying alternates when a reference is null).
esc EscapeTool For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.).
field FieldTool For (easy) access to static fields in a class, such as string constants.
link LinkTool For creating and manipulating URIs and URLs. The API for this tool is designed to closely resemble that of the VelocityView tool of the same name.
loop LoopTool A convenience tool to use with #foreach loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more.
math MathTool For performing math functions.
number NumberTool For formatting and converting numbers.
render RenderTool To evaluate and render arbitrary strings of VTL, including recursive rendering.
text ResourceTool For simplified access to resource bundles for internationalization or other dynamic content needs.
sorter SortTool Used to sort collections (or arrays, iterators, etc) on any arbitary set of properties exposed by the objects contained within the collection.
xml XmlTool For reading/navigating XML files. This uses dom4j under the covers and provides complete XPath support.

See DefaultSiteRenderer.createToolManagedVelocityContext(...) source for more details and the tools usage summary.

Maven Site Plugin

When doxia-site-renderer is used by maven-site-plugin, the following template properties are defined:

variable type description
inputEncoding String
outputEncoding String
project MavenProject The current project
project properties String Properties defined in POM are directly available.

See AbstractSiteRenderingMojo.createSiteRenderingContext(...) source for more details.

Site Template

When Velocity is processing the site template (be it from skin or local template), there are a few complementary variables available that give access to information taken from document being merged into the template:

variable type description
authors List<String> A list of authors from the source document
bodyContent String HTML body content of the Doxia generated output
dateCreation String The date specified in the source document, in the format "yyyyMMdd"
headContent String HTML head content of the Doxia generated output
shortTitle String The title of the document, excluding the project or site name
title String The title of the document, including the project or site name

See DefaultSiteRenderer.createSiteTemplateVelocityContext(...) source for more details.