Doxia Sitetools - Site Renderer
The Site Renderer handles the rendering of sites, assembling a common site template (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 template is included (see default-site.vm), but other templates can be used at will, either as a standalone template or packaged in a skin artifact.
Maven team provides a collection of skins for projects use.
Some documentation is available on how to create a new skin.
Velocity processing
Site 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 |
SiteModel |
Deprecated}: use site. |
currentFileName |
String |
The file name of the (HTML) document being rendered, relative to the site root. |
doxiaSiteRendererVersion |
String |
The version of the Doxia Site Renderer in use. |
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. |
site |
SiteModel |
This is a model that represents the data in your site.xml. |
supportedLocales |
List<Locale> |
The list of locales that the site will contain. |
There are also some tools for general use:
| Variable | Type | Description |
|---|---|---|
PathTool |
PathTool |
|
StringUtils |
StringUtils |
|
plexus |
PlexusContainer |
Additionally, there are Velocity Generic Tools populated with the site locale, the site model's date format, and site renderer's resource bundle:
| Variable | Type | Description |
|---|---|---|
alternator |
AlternatorTool | Deprecated: use CSS3 nth-child(even/odd) selectors or #if($foreach.index % 2). 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 | Deprecated: use NumberTool for numbers formatting/parsing, DateTool for date/time formatting/parsing, or CollectionTool for toStrings(). 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 | Deprecated: use CollectionTool sort methods. 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. |
If you intend to use custom Velocity tools, add them to the Maven Site Plugin's dependency list and make sure that they have a bundled configuration file in /META-INF/maven/site-tools.xml.
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. |
documentDate |
String |
The date specified in the source document: semantics has to be chosen by document writer (document creation date, or document last modification date, or ...), and format is not enforced. |
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. |
docRenderingContext |
RenderingContext |
(since 1.8) The document rendering context. |
See DefaultSiteRenderer.createSiteTemplateVelocityContext(...) source for more details.