You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by he...@apache.org on 2006/12/27 22:20:33 UTC
svn commit: r490568 - in /velocity/site/doxia-velocity-renderer: pom.xml
src/site/apt/index.apt
Author: henning
Date: Wed Dec 27 13:20:32 2006
New Revision: 490568
URL: http://svn.apache.org/viewvc?view=rev&rev=490568
Log:
Add minimal documentation.
Modified:
velocity/site/doxia-velocity-renderer/pom.xml
velocity/site/doxia-velocity-renderer/src/site/apt/index.apt
Modified: velocity/site/doxia-velocity-renderer/pom.xml
URL: http://svn.apache.org/viewvc/velocity/site/doxia-velocity-renderer/pom.xml?view=diff&rev=490568&r1=490567&r2=490568
==============================================================================
--- velocity/site/doxia-velocity-renderer/pom.xml (original)
+++ velocity/site/doxia-velocity-renderer/pom.xml Wed Dec 27 13:20:32 2006
@@ -108,10 +108,6 @@
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-plugin-plugin</artifactId>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<configuration>
<configLocation>config/checkstyle.xml</configLocation>
Modified: velocity/site/doxia-velocity-renderer/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/velocity/site/doxia-velocity-renderer/src/site/apt/index.apt?view=diff&rev=490568&r1=490567&r2=490568
==============================================================================
--- velocity/site/doxia-velocity-renderer/src/site/apt/index.apt (original)
+++ velocity/site/doxia-velocity-renderer/src/site/apt/index.apt Wed Dec 27 13:20:32 2006
@@ -8,5 +8,240 @@
Maven. It allows you to generate Xdoc and Apt pages used for the Maven
site using Apache Velocity.
+* Configuring the Renderer Module
+
The module is available as a combined plugin/extension and must be
configured in your POM.
+
++--
+ <build>
+ ...
+ <plugins>
+ <plugin>
+ <groupId>org.apache.velocity</groupId>
+ <artifactId>doxia-velocity-renderer</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>pre-site</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+...
+ <extensions>
+ <extension>
+ <artifactId>doxia-velocity-renderer</artifactId>
+ <groupId>org.apache.velocity</groupId>
+ <version>0.0.1</version>
+ </extension>
+ </extensions>
+ </build>
++--
+
+ Depending on your maven version, the version of some of the plugins,
+ the weather and the phase of the moon, it might also be necessary that
+ you configure the following module as extension (at least for maven
+ 2.0.4 you *must* do this):
+
++--
+ <build>
+ ...
+ <extensions>
+ ...
+ <extension>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.0-SNAPSHOT</version>
+ </extension>
+ </extensions>
+ </build>
++--
+
+* 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 through the Doxia Velocity Renderer, 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 Doxia Velocity Renderer 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.
+
+ Our 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 Doxia Velocity
+ Renderer module defines a number of objects that can be used on your templates:
+
+*--------------------+----------------------------------------+---------------------------------------------------------------+
+| <<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>>> |
+*--------------------+----------------------------------------+---------------------------------------------------------------+
+<<Predefined context objects>>
+
+ 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</groupId>
+ <artifactId>doxia-velocity-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</groupId>
+ <artifactId>doxia-velocity-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}.
+
++--
+
+
+