You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2015/12/19 18:36:18 UTC
svn commit: r1720954 - in
/maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src:
main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
site/apt/index.apt
Author: hboutemy
Date: Sat Dec 19 17:36:18 2015
New Revision: 1720954
URL: http://svn.apache.org/viewvc?rev=1720954&view=rev
Log:
[DOXIASITETOOLS-131] better management of Velocity context for the 2 use cases: Doxia source ".vm" and template merging
Modified:
maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/site/apt/index.apt
Modified: maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java?rev=1720954&r1=1720953&r2=1720954&view=diff
==============================================================================
--- maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java (original)
+++ maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java Sat Dec 19 17:36:18 2015
@@ -61,6 +61,7 @@ import org.apache.maven.doxia.parser.Par
import org.apache.maven.doxia.parser.Parser;
import org.apache.maven.doxia.parser.manager.ParserNotFoundException;
import org.apache.maven.doxia.site.decoration.DecorationModel;
+import org.apache.maven.doxia.site.decoration.PublishDate;
import org.apache.maven.doxia.parser.module.ParserModule;
import org.apache.maven.doxia.parser.module.ParserModuleManager;
import org.apache.maven.doxia.parser.module.ParserModuleNotFoundException;
@@ -78,6 +79,7 @@ import org.codehaus.plexus.util.FileUtil
import org.codehaus.plexus.util.IOUtil;
import org.codehaus.plexus.util.Os;
import org.codehaus.plexus.util.PathTool;
+import org.codehaus.plexus.util.PropertyUtils;
import org.codehaus.plexus.util.ReaderFactory;
import org.codehaus.plexus.util.StringUtils;
import org.codehaus.plexus.util.WriterFactory;
@@ -331,11 +333,12 @@ public class DefaultSiteRenderer
// TODO: DOXIA-111: the filter used here must be checked generally.
if ( renderingContext.getAttribute( "velocity" ) != null )
{
+ getLogger().debug( "Processing Velocity for " + renderingContext.getInputName() );
try
{
SiteResourceLoader.setResource( resource );
- Context vc = createVelocityContext( sink, siteContext );
+ Context vc = createDocumentVelocityContext( sink, siteContext );
StringWriter sw = new StringWriter();
@@ -410,7 +413,14 @@ public class DefaultSiteRenderer
generateDocument( writer, sink, siteContext );
}
- private Context createVelocityContext( SiteRendererSink sink, SiteRenderingContext siteRenderingContext )
+ /**
+ * Create a Velocity Context for a Doxia document, containing every information about rendered document.
+ *
+ * @param sink the site renderer sink for the document
+ * @param siteRenderingContext the site rendering context
+ * @return
+ */
+ protected Context createDocumentVelocityContext( SiteRendererSink sink, SiteRenderingContext siteRenderingContext )
{
ToolManager toolManager = new ToolManager( true );
Context context = toolManager.createContext();
@@ -422,106 +432,47 @@ public class DefaultSiteRenderer
RenderingContext renderingContext = sink.getRenderingContext();
context.put( "relativePath", renderingContext.getRelativePath() );
- // Add infos from document
- context.put( "authors", sink.getAuthors() );
-
- context.put( "shortTitle", sink.getTitle() );
-
- // DOXIASITETOOLS-70: Prepend the project name to the title, if any
- String title = "";
- if ( siteRenderingContext.getDecoration() != null
- && siteRenderingContext.getDecoration().getName() != null )
- {
- title = siteRenderingContext.getDecoration().getName();
- }
- else if ( siteRenderingContext.getDefaultWindowTitle() != null )
- {
- title = siteRenderingContext.getDefaultWindowTitle();
- }
-
- if ( title.length() > 0 )
- {
- title += " – ";
- }
- title += sink.getTitle();
-
- context.put( "title", title );
-
- context.put( "headContent", sink.getHead() );
+ String currentFileName = renderingContext.getOutputName().replace( '\\', '/' );
+ context.put( "currentFileName", currentFileName );
- context.put( "bodyContent", sink.getBody() );
+ context.put( "alignedFileName", PathTool.calculateLink( currentFileName, renderingContext.getRelativePath() ) );
context.put( "decoration", siteRenderingContext.getDecoration() );
- SimpleDateFormat sdf = new SimpleDateFormat( "yyyyMMdd" );
- if ( StringUtils.isNotEmpty( sink.getDate() ) )
- {
- try
- {
- // we support only ISO-8601 date
- context.put( "dateCreation",
- sdf.format( new SimpleDateFormat( "yyyy-MM-dd" ).parse( sink.getDate() ) ) );
- }
- catch ( java.text.ParseException e )
- {
- getLogger().debug( "Could not parse date: " + sink.getDate() + ", ignoring!", e );
- }
- }
- context.put( "dateRevision", sdf.format( new Date() ) );
+ Locale locale = siteRenderingContext.getLocale();
+ context.put( "locale", locale );
+ context.put( "supportedLocales", Collections.unmodifiableList( siteRenderingContext.getSiteLocales() ) );
context.put( "currentDate", new Date() );
+ SimpleDateFormat sdf = new SimpleDateFormat( "yyyyMMdd" );
+ context.put( "dateRevision", sdf.format( new Date() ) );
context.put( "publishDate", siteRenderingContext.getPublishDate() );
- Locale locale = siteRenderingContext.getLocale();
-
DateFormat dateFormat = DateFormat.getDateInstance( DateFormat.DEFAULT, locale );
-
- if ( siteRenderingContext.getDecoration().getPublishDate() != null )
+ PublishDate publishDate = siteRenderingContext.getDecoration().getPublishDate();
+ if ( publishDate != null && StringUtils.isNotBlank( publishDate.getFormat() ) )
{
- if ( StringUtils.isNotBlank( siteRenderingContext.getDecoration().getPublishDate().getFormat() ) )
- {
- dateFormat =
- new SimpleDateFormat( siteRenderingContext.getDecoration().getPublishDate().getFormat(), locale );
- }
+ dateFormat = new SimpleDateFormat( publishDate.getFormat(), locale );
}
-
context.put( "dateFormat", dateFormat );
- String currentFileName = renderingContext.getOutputName().replace( '\\', '/' );
- context.put( "currentFileName", currentFileName );
-
- context.put( "alignedFileName", PathTool.calculateLink( currentFileName, renderingContext.getRelativePath() ) );
-
- context.put( "locale", locale );
- context.put( "supportedLocales", Collections.unmodifiableList( siteRenderingContext.getSiteLocales() ) );
-
// doxiaSiteRendererVersion
- InputStream inputStream = null;
- try
+ InputStream inputStream = this.getClass().getResourceAsStream( "/META-INF/"
+ + "maven/org.apache.maven.doxia/doxia-site-renderer/pom.properties" );
+ Properties properties = PropertyUtils.loadProperties( inputStream );
+ if ( inputStream == null )
{
- inputStream =
- this.getClass().getClassLoader().getResourceAsStream( "META-INF/maven/org.apache.maven.doxia"
- + "/doxia-site-renderer/pom.properties" );
- if ( inputStream == null )
- {
- getLogger().debug( "pom.properties for doxia-site-renderer could not be found." );
- }
- else
- {
- Properties properties = new Properties();
- properties.load( inputStream );
- context.put( "doxiaSiteRendererVersion", properties.getProperty( "version" ) );
- }
+ getLogger().debug( "pom.properties for doxia-site-renderer could not be found." );
}
- catch ( IOException e )
+ else if ( properties == null )
{
getLogger().debug( "Failed to load pom.properties, so doxiaVersion is not available"
- + " in the velocityContext." );
+ + " in the Velocity context." );
}
- finally
+ else
{
- IOUtil.close( inputStream );
+ context.put( "doxiaSiteRendererVersion", properties.getProperty( "version" ) );
}
// Add user properties
@@ -550,21 +501,83 @@ public class DefaultSiteRenderer
return context;
}
- /** {@inheritDoc} */
- public void generateDocument( Writer writer, SiteRendererSink sink, SiteRenderingContext siteRenderingContext )
- throws RendererException
+ /**
+ * Create a Velocity Context for the site template decorating the document. In addition to all the informations
+ * from the document, this context contains data gathered in {@link SiteRendererSink} during document rendering.
+ *
+ * @param sink the site renderer sink for the document
+ * @param siteRenderingContext the site rendering context
+ * @return
+ */
+ protected Context createSiteTemplateVelocityContext( SiteRendererSink sink,
+ SiteRenderingContext siteRenderingContext )
{
- Context context = createVelocityContext( sink, siteRenderingContext );
+ // first get the context from Doxia source
+ Context context = createDocumentVelocityContext( sink, siteRenderingContext );
+
+ // then add data objects from rendered document
- writeTemplate( writer, context, siteRenderingContext );
+ // Add infos from document
+ context.put( "authors", sink.getAuthors() );
+
+ context.put( "shortTitle", sink.getTitle() );
+
+ // DOXIASITETOOLS-70: Prepend the project name to the title, if any
+ String title = "";
+ if ( siteRenderingContext.getDecoration() != null
+ && siteRenderingContext.getDecoration().getName() != null )
+ {
+ title = siteRenderingContext.getDecoration().getName();
+ }
+ else if ( siteRenderingContext.getDefaultWindowTitle() != null )
+ {
+ title = siteRenderingContext.getDefaultWindowTitle();
+ }
+
+ if ( title.length() > 0 )
+ {
+ title += " – ";
+ }
+ title += sink.getTitle();
+
+ context.put( "title", title );
+
+ context.put( "headContent", sink.getHead() );
+
+ context.put( "bodyContent", sink.getBody() );
+
+ SimpleDateFormat sdf = new SimpleDateFormat( "yyyyMMdd" );
+ if ( StringUtils.isNotEmpty( sink.getDate() ) )
+ {
+ try
+ {
+ // we support only ISO-8601 date
+ context.put( "dateCreation",
+ sdf.format( new SimpleDateFormat( "yyyy-MM-dd" ).parse( sink.getDate() ) ) );
+ }
+ catch ( java.text.ParseException e )
+ {
+ getLogger().debug( "Could not parse date: " + sink.getDate() + ", ignoring!", e );
+ }
+ }
+
+ return context;
}
- private void writeTemplate( Writer writer, Context context, SiteRenderingContext siteContext )
+ /** {@inheritDoc} */
+ public void generateDocument( Writer writer, SiteRendererSink sink, SiteRenderingContext siteRenderingContext )
throws RendererException
{
+ String templateName = siteRenderingContext.getTemplateName();
+
+ getLogger().debug( "Processing Velocity for template " + templateName + " on "
+ + sink.getRenderingContext().getInputName() );
+
+ Context context = createSiteTemplateVelocityContext( sink, siteRenderingContext );
+
ClassLoader old = null;
- if ( siteContext.getTemplateClassLoader() != null )
+ if ( siteRenderingContext.getTemplateClassLoader() != null )
{
// -------------------------------------------------------------------------
// If no template classloader was set we'll just use the context classloader
@@ -572,12 +585,30 @@ public class DefaultSiteRenderer
old = Thread.currentThread().getContextClassLoader();
- Thread.currentThread().setContextClassLoader( siteContext.getTemplateClassLoader() );
+ Thread.currentThread().setContextClassLoader( siteRenderingContext.getTemplateClassLoader() );
}
try
{
- processTemplate( siteContext.getTemplateName(), context, writer );
+ Template template;
+
+ try
+ {
+ template = velocity.getEngine().getTemplate( templateName );
+ }
+ catch ( Exception e )
+ {
+ throw new RendererException( "Could not find the site decoration template '" + templateName + "'", e );
+ }
+
+ try
+ {
+ template.merge( context, writer );
+ }
+ catch ( Exception e )
+ {
+ throw new RendererException( "Error while merging site decoration template.", e );
+ }
}
finally
{
@@ -590,33 +621,6 @@ public class DefaultSiteRenderer
}
}
- /**
- * @noinspection OverlyBroadCatchBlock,UnusedCatchParameter
- */
- private void processTemplate( String templateName, Context context, Writer writer )
- throws RendererException
- {
- Template template;
-
- try
- {
- template = velocity.getEngine().getTemplate( templateName );
- }
- catch ( Exception e )
- {
- throw new RendererException( "Could not find the template '" + templateName, e );
- }
-
- try
- {
- template.merge( context, writer );
- }
- catch ( Exception e )
- {
- throw new RendererException( "Error while generating code.", e );
- }
- }
-
/** {@inheritDoc} */
public SiteRenderingContext createContextForSkin( File skinFile, Map<String, ?> attributes,
DecorationModel decoration, String defaultWindowTitle,
Modified: maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/site/apt/index.apt?rev=1720954&r1=1720953&r2=1720954&view=diff
==============================================================================
--- maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/site/apt/index.apt (original)
+++ maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/site/apt/index.apt Sat Dec 19 17:36:18 2015
@@ -34,7 +34,8 @@ Doxia Site Tools - Site Renderer
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 (containing a <<<META-INF/maven/site.vm>>> template).
- Documents can be dynamically generated with Doxia Sink API, like Maven reports, or simply read from static files,
+ 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 Parser}},
eventually processed by Velocity if their file names end in <<<.vm>>>.
* Doxia Site Skins
@@ -56,23 +57,17 @@ Doxia Site Tools - Site Renderer
*---------------------------------+----------------------+-------------------------------+
| <<<alignedFileName>>> | <<<String>>> | The file name of the (html) document being rendered, relative to the document being rendered |
*---------------------------------+----------------------+-------------------------------+
-| <<<authors>>> | <<<List\<String\>>>> | A list of authors from the source document |
-*---------------------------------+----------------------+-------------------------------+
-| <<<bodyContent>>> | <<<String>>> | |
-*---------------------------------+----------------------+-------------------------------+
| <<<decoration>>> | {{{../doxia-decoration-model/apidocs/org/apache/maven/doxia/site/decoration/DecorationModel.html}<<<DecorationModel>>>}} | This is a model that represents the data in your <<<site.xml>>> |
*---------------------------------+----------------------+-------------------------------+
| <<<currentDate>>> | <<<Date>>> | The date when the site is rendered |
*---------------------------------+----------------------+-------------------------------+
| <<<currentFileName>>> | <<<String>>> | The file name of the (html) document being rendered, relative to the site root |
*---------------------------------+----------------------+-------------------------------+
-| <<<dateCreation>>> | <<<String>>> | The date specified in the source document, in the format "yyyyMMdd" |
-*---------------------------------+----------------------+-------------------------------+
-| <<<dateFormat>>> | <<<DateFormat>>> | 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 |
+| <<<dateFormat>>> | <<<DateFormat>>> | An instance of the date format as defined in <<<...@format>>> (default: An instance of the default date format for the locale of the document being rendered |
*---------------------------------+----------------------+-------------------------------+
| <<<dateRevision>>> | <<<String>>> | The date when the site is rendered, in the format "yyyyMMdd" |
*---------------------------------+----------------------+-------------------------------+
-| <<<headContent>>> | <<<String>>> | |
+| <<<doxiaSiteRendererVersion>>> | <<<String>>> | The version of Doxia Site Renderer in use |
*---------------------------------+----------------------+-------------------------------+
| <<<locale>>> | <<<Locale>>> | The locale for the document being rendered |
*---------------------------------+----------------------+-------------------------------+
@@ -80,17 +75,13 @@ Doxia Site Tools - Site Renderer
*---------------------------------+----------------------+-------------------------------+
| <<<relativePath>>> | <<<String>>> | The path to the site root from the document being rendered |
*---------------------------------+----------------------+-------------------------------+
-| <<<shortTitle>>> | <<<String>>> | The title of the document, excluding the project or site name |
-*---------------------------------+----------------------+-------------------------------+
-| <<<supportedLocales>>> | <<<List\<Locale\>>>> | |
-*---------------------------------+----------------------+-------------------------------+
-| <<<title>>> | <<<String>>> | The title of the document, including the project or site name |
+| <<<supportedLocales>>> | <<<List\<Locale\>>>> | The list of locales that the site will contain |
*---------------------------------+----------------------+-------------------------------+
There are also some tools for general use:
*---------------------------------+----------------------+-------------------------------+
-|| property || type || description ||
+|| variable || type || description ||
*---------------------------------+----------------------+-------------------------------+
| <<<FileUtils>>> | {{{http://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/FileUtils.html}<<<FileUtils>>>}} | |
*---------------------------------+----------------------+-------------------------------+
@@ -101,9 +92,11 @@ Doxia Site Tools - Site Renderer
| <<<StringUtils>>> | {{{http://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/StringUtils.html}<<<StringUtils>>>}} | |
*---------------------------------+----------------------+-------------------------------+
- See <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html#L428}DefaultSiteRenderer.createVelocityContext(...)}}>>>
+ See <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html#L416}DefaultSiteRenderer.createDocumentVelocityContext(...)}}>>>
source for more details.
+** Maven Site Plugin
+
When <<<doxia-site-renderer>>> is used by <<<maven-site-plugin>>>, the following template properties are defined:
*---------------------------------+----------------------+-------------------------------+
@@ -113,10 +106,34 @@ Doxia Site Tools - Site Renderer
*---------------------------------+----------------------+-------------------------------+
| <<<outputEncoding>>> | <<<String>>> | |
*---------------------------------+----------------------+-------------------------------+
-| <<<project>>> | {{{/ref/current/maven-core/apidocs/org/apache/maven/project/MavenProject.html}<<<MavenProject>>>}} | |
+| <<<project>>> | {{{/ref/current/maven-core/apidocs/org/apache/maven/project/MavenProject.html}<<<MavenProject>>>}} | The current project |
*---------------------------------+----------------------+-------------------------------+
| <project properties> | <<<String>>> | Properties defined in POM are directly available. |
*---------------------------------+----------------------+-------------------------------+
- See <<<{{{/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.html#createSiteRenderingContext(java.util.Locale)}AbstractSiteRenderingMojo.createSiteRenderingContext(...)}}>>>
+ See <<<{{{/plugins/maven-site-plugin/apidocs/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.html#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 ||
+*---------------------------------+----------------------+-------------------------------+
+| <<<authors>>> | <<<List\<String\>>>> | A list of authors from the source document |
+*---------------------------------+----------------------+-------------------------------+
+| <<<bodyContent>>> | <<<String>>> | HTML body content of the Doxia generated output |
+*---------------------------------+----------------------+-------------------------------+
+| <<<dateCreation>>> | <<<String>>> | The date specified in the source document, in the format "yyyyMMdd" |
+*---------------------------------+----------------------+-------------------------------+
+| <<<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 <<<{{{./xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html#L504}DefaultSiteRenderer.createSiteTemplateVelocityContext(...)}}>>>
source for more details.