----- Introduction ----- Hervé Boutemy Dennis Lundberg ------ 2015-12-20 ------ ~~ Licensed to the Apache Software Foundation (ASF) under one ~~ or more contributor license agreements. See the NOTICE file ~~ distributed with this work for additional information ~~ regarding copyright ownership. The ASF licenses this file ~~ to you under the Apache License, Version 2.0 (the ~~ "License"); you may not use this file except in compliance ~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ ~~ Unless required by applicable law or agreed to in writing, ~~ software distributed under the License is distributed on an ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Doxia Sitetools - Site Renderer The Site Renderer handles the rendering of sites, assembling a common site template (also called ) with a collection of documents. Documents can be dynamically generated with {{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}, like Maven reports, or simply read from static files written in {{{/doxia/references/index.html}markup supported by Doxia Parsers}}, eventually processed by {{{https://velocity.apache.org/engine/${velocityEngineVersion}/}Velocity}} if their file names end in <<<.vm>>>. [doxia-site-renderer.png] * Doxia Site Skins A default site template is included (see <<>>), but other templates can be used at will, either as a standalone template or packaged in a {{{../doxia-skin-model/}<> artifact}}. Maven team provides {{{/skins/}a collection of skins}} for projects use. Some documentation is available on {{{/plugins/maven-site-plugin/examples/creatingskins.html}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 || *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | <>: use <<>>. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The file path of the (HTML) document being rendered, relative to the document being rendered. | *---------------------------------+----------------------+-------------------------------+ | <<>> | {{{../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html}<<>>}} | <>: use <<>>. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | <>: use <<>>. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The file path of the (HTML) document being rendered, relative to the site root. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The version of the Doxia Site Renderer in use. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The locale for the document being rendered. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | An optional hardcoded publish date that has been set programmatically. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The path to the site root from the document being rendered. | *---------------------------------+----------------------+-------------------------------+ | <<>> | {{{../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html}<<>>}} | This is a model that represents the data in your {{{../doxia-site-model/site.html}<<>>}}. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>>> | The list of locales that the site will contain. | *---------------------------------+----------------------+-------------------------------+ There are also some tools for general use: #set( $plexus = "https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util" ) *---------------------------------+------------------------------------------------------+-------------------------------+ || Variable || Type || Description || *---------------------------------+------------------------------------------------------+-------------------------------+ | <<>> | {{{$plexus/PathTool.html}<<>>}} | | *---------------------------------+------------------------------------------------------+-------------------------------+ | <<>> | {{{$plexus/StringUtils.html}<<>>}} | | *---------------------------------+------------------------------------------------------+-------------------------------+ | <<>> | {{{https://github.com/eclipse/sisu.plexus/blob/master/org.eclipse.sisu.plexus/src/main/java/org/codehaus/plexus/PlexusContainer.java}<<>>}} | | *---------------------------------+------------------------------------------------------+-------------------------------+ Additionally, there are {{{https://velocity.apache.org/tools/${velocityToolsVersion}/tools-summary.html} Velocity Generic Tools}} populated with the site locale, the site model's date format, and site renderer's resource bundle: #set( $generic = "https://velocity.apache.org/tools/${velocityToolsVersion}/tools-summary.html" ) *------------------+---------------------------------------------------------------+-------------------------------+ || Variable || Type || Description || *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}deprecated-tools}AlternatorTool}} | {{{$generic${esc.hash}deprecated-tools}<>}}: use CSS3 nth-child(even/odd) selectors or ${esc.hash}if($foreach.index % 2). For creating alternators to easily alternate over a set of values. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}ClassTool}ClassTool}} | For simplifying reflective lookup of information about classes and their fields, methods and constructors. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}ContextTool}ContextTool}} | For convenient access to context data and metadata. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}deprecated-tools}ConversionTool}} | {{{$generic${esc.hash}deprecated-tools}<>}}: use NumberTool for numbers formatting/parsing, DateTool for date/time formatting/parsing, or CollectionTool for toStrings(). For converting String values to richer object Types. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}ComparisonDateTool}ComparisonDateTool}} | For manipulating, formatting, and comparing dates. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}DisplayTool}DisplayTool}} | For controlling display of references (e.g., truncating values, "pretty printing" lists, and displaying alternates when a reference is null). *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}EscapeTool}EscapeTool}} | For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.). *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}FieldTool}FieldTool}} | For (easy) access to static fields in a class, such as string constants. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}LinkTool}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. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}LoopTool}LoopTool}} | A convenience tool to use with <<<${esc.hash}foreach>>> loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}MathTool}MathTool}} | For performing math functions. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}NumberTool}NumberTool}} | For formatting and converting numbers. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}RenderTool}RenderTool}} | To evaluate and render arbitrary strings of VTL, including recursive rendering. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}ResourceTool}ResourceTool}} | For simplified access to resource bundles for internationalization or other dynamic content needs. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}deprecated-tools}SortTool}} | {{{$generic${esc.hash}deprecated-tools}<>}}: 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. *------------------+---------------------------------------------------------------+-------------------------------+ | <<>> | {{{$generic${esc.hash}XmlTool}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 <<>>. See <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html${esc.hash}L483}DefaultSiteRenderer.createToolManagedVelocityContext(...)}}>>> source for more details and the {{{https://velocity.apache.org/tools/devel/tools-summary.html}tools usage summary}}. ** Maven Site Plugin When <<>> is used by <<>>, the following template properties are defined: *---------------------------------+----------------------+-------------------------------+ || Variable || Type || Description || *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | | *---------------------------------+----------------------+-------------------------------+ | <<>> | {{{/ref/current/maven-core/apidocs/org/apache/maven/project/MavenProject.html}<<>>}} | The current project. | *---------------------------------+----------------------+-------------------------------+ | | <<>> | Properties defined in POM are directly available. | *---------------------------------+----------------------+-------------------------------+ See <<<{{{/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.html${esc.hash}createSiteRenderingContext-java.util.Locale-}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 || *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>>> | A list of authors from the source document. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | HTML body content of the Doxia generated output. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | 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. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | HTML head content of the Doxia generated output. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The title of the document, excluding the project or site name. | *---------------------------------+----------------------+-------------------------------+ | <<>> | <<>> | The title of the document, including the project or site name. | *---------------------------------+----------------------+-------------------------------+ | <<>> | {{{./apidocs/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.html}<<>>}} | (since 1.8) The document rendering context. | *---------------------------------+----------------------+-------------------------------+ See <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html${esc.hash}L616}DefaultSiteRenderer.createSiteTemplateVelocityContext(...)}}>>> source for more details.