Velocity Site Doxia Renderer

This module is an extension for Apache Maven. It allows you to generate Xdoc and Apt pages used for the Maven site using Apache Velocity.

The plugin requires Maven 2.0.5 and works best with Maven 2.0.6 or better. It has not yet been tested with Maven 2.1.

Configuring the Renderer Plugin

The renderer is available as a plugin to maven-2 and must be configured in your POM. It runs as a dependency to the site plugin to be available when rendering the site and must also be configured as a plugin itself to allow configuration.

  <build>
    ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <dependencies>
...
         <dependency>
          <groupId>org.apache.velocity.site</groupId>
          <artifactId>velocity-site-doxia-renderer</artifactId>
          <version>1.2.0-SNAPSHOT</version>
         </dependency>
...
        </dependencies>
      </plugin>

...
      <plugin>
        <groupId>org.apache.velocity.site</groupId>
        <artifactId>velocity-site-doxia-renderer</artifactId>
        <configuration>
          <libraries/>
          <tools/>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>pre-site</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
...
    </plugins>
...

What it does

This module allows you to create pages and documents in your maven site that are not just generated from APT and Xdoc sources but are built from Velocity templates.

Velocity is a powerful templating engine which in turn allows you to build pages dynamically.

This is an example of a Velocity generated APT template:

  -----
  This is the title
  -----

This is the head line.

#foreach ($i in [1..10])

* This is paragraph # $i

 This is the text content for paragraph $i.

#end

When this template is rendered, it generates ten paragraphs with demo text.

Where the templates are located

When the module is configured correctly with your project, you can create a number of new directories:

  ...
   |
   +-- src
       |
       +-- site
           |
           +-- velocity  Directory for all related files.
               |
               +-- apt   Velocity Templates parsed in APT format.
               |
               +-- xdoc  Velocity Templates parsed in XDOC format.
               |
               +-- resources Location for Velocity Macro libraries (see below)

Just as the regular src/site/apt and src/site/xdoc directories, the new directories under src/site/velocity are scanned and the resulting documents are put in the target/site folder.

The example from above would be put into the src/site/velocity/apt folder.

Additional features

Context objects

One of the most powerful features of Velocity are its context objects that can be used on templates by using the $object_name notation. The Velocity Doxia Renderer module defines a number of objects that can be used on your templates:

**Predefined context objects**
Context Object	Function	defining Java class
project	The Maven POM	`org.apache.maven.project.MavenProject`
siteDirectory	Filesystem location of `src/site`	`java.io.File`
localRepository	Local Artifact Repository	`org.apache.maven.artifact.repository.ArtifactRepository`
reactorProjects	List of all reactor projects	`java.util.List`
inputEncoding	Template input encoding	`java.lang.String`
outputEncoding	Template output encoding	`java.lang.String`

The following example renders the name of your current project:

Welcome to the ${project.name} project!

Velocity Macro libraries

You can place Velocity Macro Libraries into the src/site/velocity/resources directory and the configure them through the POM.

Put the following file into src/site/velocity/resources/demo.vm:

#macro (BoldMacro $text)
<<${text}>>
#end

and add the following configuration block to the plugin definition:

  <build>
    ...
    <plugins>
      <plugin>
        <groupId>org.apache.velocity.site</groupId>
        <artifactId>velocity-site-doxia-renderer</artifactId>
        ...
        <configuration>
          <libraries>
            <library>demo.vm</library>
          </libraries>
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>

In an Apt template you can now write

  #BoldMacro("This text is bold")

A Velocity Macro library is available for all renderers (currently only Velocity-Apt and Velocity-Xdoc).

For security reasons, all Macro Libraries must be explicitly configured through the POM and must be located in src/site/velocity/resources. You can not load resources with the Velocity Template language instructions #parse and #include!

User defined Context objects (Velocity Tools)

In addition to the predefined context objects (see above), you can configure additional objects to be available through the Velocity context. These objects are called 'Tools'. Any arbitrary object can be configured as a tool as long as it has a public no-parameter constructor. All public methods and fields are then available through the Velocity context.

The following example configures a date object as context element:

  <build>
    ...
    <plugins>
      <plugin>
        <groupId>org.apache.velocity.site</groupId>
        <artifactId>velocity-site-doxia-renderer</artifactId>
        ...
        <configuration>
          <tools>
            <tool>
              <toolName>date</toolName>
              <toolClass>java.util.Date</toolClass>
            </tool>
          </tools>
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>

This object is now available through the context. The following code fragment renders the current date as part of an Apt template:

  This template was rendered at ${date}.

General

Project Documentation