net.sf.click.service
Class VelocityTemplateService

java.lang.Object
  net.sf.click.service.VelocityTemplateService

All Implemented Interfaces:

TemplateService

public class VelocityTemplateService

extends Object

implements TemplateService

Provides a Velocity TemplateService class.

Velocity provides a simple to use, but powerful and performant templating engine for the Click Framework. The Velocity templating engine is configured and accessed by this VelocityTemplateService class. Velocity is the default templating engine used by Click and the Velocity class dependencies are included in the standard Click JAR file.

You can also instruct Click to use a different template service implementation. Please see TemplateService for more details.

To see how to use the Velocity templating language please see the Velocity Users Guide.

Velocity Configuration

The VelocityTemplateService is the default template service used by Click, so it does not require any specific configuration. However if you wanted to configure this service specifically in your click.xml configuration file you would add the following XML element.

 <template-service classname="net.sf.click.service.VelocityTemplateService"/> 

Velocity Properties

The Velocity runtime engine is configured through a series of properties when the VelocityTemplateService is initialized. The default Velocity properties set are:

 resource.loader=webapp, class

 webapp.resource.loader.class=org.apache.velocity.tools.view.servlet.WebappLoader
 webapp.resource.loader.cache=[true|false]   #depending on application mode
 webapp.resource.loader.modificationCheckInterval=0 #depending on application mode

 class.resource.loader.class=org.apache.velocity.runtime.loader.ClasspathResourceLoader
 class.resource.loader.cache=[true|false]   #depending on application mode
 class.resource.loader.modificationCheckInterval=0 #depending on application mode

 velocimacro.library.autoreload=[true|false] #depending on application mode
 velocimacro.library=click/VM_global_library.vm
 

This service uses the Velocity Tools WebappLoader for loading templates. This avoids issues associate with using the Velocity FileResourceLoader on JEE application servers.

See the Velocity Developer Guide for details about these properties. Note when the application is in trace mode the Velocity properties used will be logged on startup.

If you want to add some of your own Velocity properties, or replace Click's properties, add a velocity.properties file in the WEB-INF directory. Click will automatically pick up this file and load these properties.

As a example say we have our own Velocity macro library called mycorp.vm we can override the default velocimacro.library property by adding a WEB-INF/velocity.properties file to our web application. In this file we would then define the property as:

 velocimacro.library=mycorp.vm 

Note do not place Velocity macros under the WEB-INF directory as the Velocity ResourceManager will not be able to load them.

The simplest way to set your own macro file is to add a file named macro.vm under your web application's root directory. At startup Click will first check to see if this file exists, and if it does it will use it instead of click/VM_global_library.vm.

Application Modes and Caching

Production and Profile Mode

When the Click application is in production or profile mode Velocity caching is enabled. With caching enables page templates and macro files are loaded and parsed once and then are cached for use with later requests. When in production or profile mode the following Velocity runtime properties are set:

 webapp.resource.loader.cache=true
 webapp.resource.loader.modificationCheckInterval=0

 class.resource.loader.cache=true
 class.resource.loader.modificationCheckInterval=0

 velocimacro.library.autoreload=false 

When running in these modes the ConsoleLogService will be configured to use

Development and Debug Modes

When the Click application is in development, debug or trace modes Velocity caching is disabled. When caching is disabled page templates and macro files are reloaded and parsed when ever they changed. With caching disabled the following Velocity runtime properties are set:

 webapp.resource.loader.cache=false

 class.resource.loader.cache=false

 velocimacro.library.autoreload=true 

Disabling caching is useful for application development where you can edit page templates on a running application server and see the changes immediately.

Please Note Velocity caching should be used for production as Velocity template reloading is much much slower and the process of parsing and introspecting templates and macros can use a lot of memory.

Velocity Logging

Velocity logging is very verbose at the best of times, so this service keeps the logging level at ERROR in all modes except trace mode where the Velocity logging level is set to WARN.

If you are having issues with some Velocity page templates or macros please switch the application mode into trace so you can see the warning messages provided.

To support the use of Click LogService classes inside the Velocity runtime a VelocityTemplateService.LogChuteAdapter class is provided. This class wraps the Click LogService with a Velocity LogChute so the Velocity runtime can use it for logging messages to.

If you are using LogServices other than ConsoleLogService you will probably configure that service to filter out Velocity's verbose INFO level messages.

Author:

Malcolm Edgar

Nested Class Summary

static class

VelocityTemplateService.LogChuteAdapter Provides a Velocity LogChute adapter class around the application log service to enable the Velocity Runtime to log to the application LogService.

Field Summary

protected ConfigService	configService The application configuration service.
protected static String	DEFAULT_TEMPLATE_PROPS The default velocity properties filename: "/WEB-INF/velocity.properties".
protected static String	MACRO_VM_FILE_NAME The user supplied macro file name: "macro.vm".
protected org.apache.velocity.app.VelocityEngine	velocityEngine The VelocityEngine instance.
protected static String	VM_FILE_PATH The global Velocity macro file path: "/click/VM_global_library.vm".
protected static int	WRITER_BUFFER_SIZE The Velocity writer buffer size.
protected org.apache.velocity.util.SimplePool	writerPool Cache of velocity writers.

Constructor Summary

VelocityTemplateService()

Method Summary

protected Integer	getInitLogLevel() Return the Velocity Engine initialization log level.
protected Properties	getInitProperties() Return the Velocity Engine initialization properties.
void	onDestroy() Destroy the TemplateService.
void	onInit(ServletContext servletContext) Initialize the TemplateService with the given application configuration service instance.
void	renderTemplate(Page page, Map model, Writer writer) Render the given page to the writer.
void	renderTemplate(String templatePath, Map model, Writer writer) Render the given template and model to the writer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TEMPLATE_PROPS

protected static final String DEFAULT_TEMPLATE_PROPS

The default velocity properties filename: "/WEB-INF/velocity.properties".

See Also:

Constant Field Values

MACRO_VM_FILE_NAME

protected static final String MACRO_VM_FILE_NAME

The user supplied macro file name: "macro.vm".

See Also:

Constant Field Values

VM_FILE_PATH

protected static final String VM_FILE_PATH

The global Velocity macro file path: "/click/VM_global_library.vm".

See Also:

Constant Field Values

WRITER_BUFFER_SIZE

protected static final int WRITER_BUFFER_SIZE

The Velocity writer buffer size.

See Also:

Constant Field Values

configService

protected ConfigService configService

The application configuration service.

velocityEngine

protected org.apache.velocity.app.VelocityEngine velocityEngine

The VelocityEngine instance.

writerPool

protected org.apache.velocity.util.SimplePool writerPool

Cache of velocity writers.

Constructor Detail

VelocityTemplateService

public VelocityTemplateService()

Method Detail

onInit

public void onInit(ServletContext servletContext)
            throws Exception

Description copied from interface: TemplateService

Initialize the TemplateService with the given application configuration service instance.

This method is invoked after the TemplateService has been constructed.

Note you can access ConfigService by invoking ClickUtils.getConfigService(javax.servlet.ServletContext)

Specified by:

onInit in interface TemplateService

Parameters:

servletContext - the application servlet velocityContext

Throws:

Exception - if an error occurs initializing the Template Service

See Also:

TemplateService.onInit(ServletContext)

onDestroy

public void onDestroy()

Description copied from interface: TemplateService

Destroy the TemplateService.

Specified by:

onDestroy in interface TemplateService

See Also:

TemplateService.onDestroy()

renderTemplate

public void renderTemplate(Page page,
                           Map model,
                           Writer writer)
                    throws Exception

Description copied from interface: TemplateService

Render the given page to the writer.

Specified by:

renderTemplate in interface TemplateService

Parameters:

page - the page template to render

model - the model to merge with the template and render

writer - the writer to send the merged template and model data to

Throws:

Exception - if an error occurs

See Also:

TemplateService.renderTemplate(Page, Map, Writer)

renderTemplate

public void renderTemplate(String templatePath,
                           Map model,
                           Writer writer)
                    throws Exception

Description copied from interface: TemplateService

Render the given template and model to the writer.

Specified by:

renderTemplate in interface TemplateService

Parameters:

templatePath - the path of the template to render

model - the model to merge with the template and render

writer - the writer to send the merged template and model data to

Throws:

Exception - if an error occurs

See Also:

TemplateService.renderTemplate(String, Map, Writer)

getInitLogLevel

protected Integer getInitLogLevel()

Return the Velocity Engine initialization log level.

Returns:

the Velocity Engine initialization log level

getInitProperties

protected Properties getInitProperties()
                                throws MalformedURLException

Return the Velocity Engine initialization properties.

Returns:

the Velocity Engine initialization properties

Throws:

MalformedURLException - if a resource cannot be loaded