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.
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.
Maven team provides a collection of skins for projects use.
Some documentation is available on how to create a new skin.
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:
|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||Deprecated: use date or date.systemDate. 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||Deprecated: use date, date.format, or decoration.publishDate.format. 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||Deprecated: same as currentDate. The date when the site is rendered, in the format "yyyyMMdd".|
|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.|
|supportedLocales||List<Locale>||The list of locales that the site will contain.|
There are also some tools for general use:
|i18n||I18N||Deprecated: use text.|
Additionally, there are Velocity Generic Tools populated with the site locale, the decoration model's date format, and site renderer's resource bundle:
|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).|
|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.|
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.
When doxia-site-renderer is used by maven-site-plugin, the following template properties are defined:
|project||MavenProject||The current project.|
|project properties||String||Properties defined in POM are directly available.|
See AbstractSiteRenderingMojo.createSiteRenderingContext(...) source for more details.
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:
|authors||List<String>||A list of authors from the source document.|
|bodyContent||String||HTML body content of the Doxia generated output.|
|dateCreation||String||Deprecated: use documentDate. The date specified in the source document, in the format "yyyyMMdd".|
|creationDate||Date||Deprecated: use documentDate. The date specified in the source document.|
|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.|
See DefaultSiteRenderer.createSiteTemplateVelocityContext(...) source for more details.