org.apache.click.service
Class VelocityTemplateService

java.lang.Object
  extended by org.apache.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="org.apache.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.WebappResourceLoader
 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 WebappResourceLoader 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.


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  boolean deployedErrorTemplate
          The /click/error.htm page template has been deployed.
protected  boolean deployedNotFoundTemplate
          The /click/not-found.htm page template has been deployed.
protected static String ERROR_PAGE_PATH
          The click error page template path.
protected static String MACRO_VM_FILE_NAME
          The user supplied macro file name:   "macro.vm".
protected static String NOT_FOUND_PAGE_PATH
          The click not found page template path.
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.
protected  void internalRenderTemplate(String templatePath, Page page, Map<String,?> model, Writer writer)
          Provides the underlying Velocity template rendering.
 void onDestroy()
          Destroy the TemplateService.
 void onInit(ServletContext servletContext)
          Initialize the TemplateService with the given application configuration service instance.
 void renderTemplate(Page page, Map<String,?> model, Writer writer)
          Render the given page to the writer.
 void renderTemplate(String templatePath, Map<String,?> 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

ERROR_PAGE_PATH

protected static final String ERROR_PAGE_PATH
The click error page template path.

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

NOT_FOUND_PAGE_PATH

protected static final String NOT_FOUND_PAGE_PATH
The click not found page template path.

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.


deployedErrorTemplate

protected boolean deployedErrorTemplate
The /click/error.htm page template has been deployed.


deployedNotFoundTemplate

protected boolean deployedNotFoundTemplate
The /click/not-found.htm page template has been deployed.


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<String,?> model,
                           Writer writer)
                    throws IOException,
                           TemplateException
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:
IOException - if an IO error occurs
TemplateException - if template error occurs
See Also:
TemplateService.renderTemplate(Page, Map, Writer)

renderTemplate

public void renderTemplate(String templatePath,
                           Map<String,?> model,
                           Writer writer)
                    throws IOException,
                           TemplateException
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:
IOException - if an IO error occurs
TemplateException - 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

internalRenderTemplate

protected void internalRenderTemplate(String templatePath,
                                      Page page,
                                      Map<String,?> model,
                                      Writer writer)
                               throws IOException,
                                      TemplateException
Provides the underlying Velocity template rendering.

Parameters:
templatePath - the template path to render
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:
IOException - if an IO error occurs
TemplateException - if template error occurs