org.apache.turbine.services.template
Class TurbineTemplateService

java.lang.Object
  org.apache.turbine.services.BaseInitable
      org.apache.turbine.services.BaseService
          org.apache.turbine.services.TurbineBaseService
              org.apache.turbine.services.template.TurbineTemplateService

All Implemented Interfaces:

Initable, Service, TemplateService

public class TurbineTemplateService

extends TurbineBaseService

implements TemplateService

This service provides a method for mapping templates to their appropriate Screens or Navigations. It also allows templates to define a layout/navigations/screen modularization within the template structure. It also performs caching if turned on in the properties file. This service is not bound to a specific templating engine but we will use the Velocity templating engine for the examples. It is available by using the VelocityService. This assumes the following properties in the Turbine configuration:

 # Register the VelocityService for the "vm" extension.
 services.VelocityService.template.extension=vm

 # Default Java class for rendering a Page in this service
 # (must be found on the class path (org.apache.turbine.modules.page.VelocityPage))
 services.VelocityService.default.page = VelocityPage

 # Default Java class for rendering a Screen in this service
 # (must be found on the class path (org.apache.turbine.modules.screen.VelocityScreen))
 services.VelocityService.default.screen=VelocityScreen

 # Default Java class for rendering a Layout in this service
 # (must be found on the class path (org.apache.turbine.modules.layout.VelocityOnlyLayout))
 services.VelocityService.default.layout = VelocityOnlyLayout

 # Default Java class for rendering a Navigation in this service
 # (must be found on the class path (org.apache.turbine.modules.navigation.VelocityNavigation))
 services.VelocityService.default.navigation=VelocityNavigation

 # Default Template Name to be used as Layout. If nothing else is
 # found, return this as the default name for a layout
 services.VelocityService.default.layout.template = Default.vm
 

If you want to render a template, a search path is used to find a Java class which might provide information for the context of this template. If you request e.g. the template screen about,directions,Driving.vm then the following class names are searched (on the module search path): 1. about.directions.Driving <- direct matching the template to the class name 2. about.directions.Default <- matching the package, class name is Default 3. about.Default <- stepping up in the package hierarchy, looking for Default 4. Default <- Class called "Default" without package 5. VelocityScreen <- The class configured by the Service (VelocityService) to And if you have the following module packages configured: module.packages = org.apache.turbine.modules, com.mycorp.modules then the class loader will look for org.apache.turbine.modules.screens.about.directions.Driving com.mycorp.modules.screens.about.directions.Driving org.apache.turbine.modules.screens.about.directions.Default com.mycorp.modules.screens.about.directions.Default org.apache.turbine.modules.screens.about.Default com.mycorp.modules.screens.about.Default org.apache.turbine.modules.screens.Default com.mycorp.modules.screens.Default org.apache.turbine.modules.screens.VelocityScreen com.mycorp.modules.screens.VelocityScreen Most of the times, you don't have any backing Java class for a template screen, so the first match will be org.apache.turbine.modules.screens.VelocityScreen which then renders your screen. Please note, that your Screen Template (Driving.vm) must exist! If it does not exist, the Template Service will report an error. Once the screen is found, the template service will look for the Layout and Navigation templates of your Screen. Here, the template service looks for matching template names! Consider our example: about,directions,Driving.vm (Screen Name) Now the template service will look for the following Navigation and Layout templates: 1. about,directions,Driving.vm <- exact match 2. about,directions,Default.vm <- package match, Default name 3. about,Default.vm <- stepping up in the hierarchy 4. Default.vm <- The name configured as default.layout.template in the Velocity service. And now Hennings' two golden rules for using templates: Many examples and docs from older Turbine code show template pathes with a slashes. Repeat after me: "TEMPLATE NAMES NEVER CONTAIN SLASHES!" Many examples and docs from older Turbine code show templates that start with "/". This is not only a violation of the rule above but actively breaks things like loading templates from a jar with the velocity jar loader. Repeat after me: "TEMPLATE NAMES ARE NOT PATHES. THEY'RE NOT ABSOLUTE AND HAVE NO LEADING /". If you now wonder how a template name is mapped to a file name: This is scope of the templating engine. Velocity e.g. has this wonderful option to load templates from jar archives. There is no single file but you tell velocity "get about,directions,Driving.vm" and it returns the rendered template. This is not the job of the Templating Service but of the Template rendering services like VelocityService.

Version:

$Id: TurbineTemplateService.java 534527 2007-05-02 16:10:59Z tv $

Author:

John D. McNally, Dave Bryson, Jason van Zyl, Daniel Rall, Ilkka Priha, Henning P. Schmiedehausen

Field Summary

static int	LAYOUT_KEY Represents Layout Objects
static java.lang.String	LAYOUT_NAME Represents Layout Objects
static int	LAYOUT_TEMPLATE_KEY Represents Layout Template Objects
static java.lang.String	LAYOUT_TEMPLATE_NAME Represents Layout Template Objects
static int	NAVIGATION_KEY Represents Navigation Objects
static java.lang.String	NAVIGATION_NAME Represents Navigation Objects
static int	NAVIGATION_TEMPLATE_KEY Represents Navigation Template Objects
static java.lang.String	NAVIGATION_TEMPLATE_NAME Represents Navigation Template Objects
protected static java.lang.String	NO_FILE_EXT The default file extension used as a registry key when a template's file extension cannot be determined.
static int	PAGE_KEY Represents Page Objects
static java.lang.String	PAGE_NAME Represents Page Objects
static int	SCREEN_KEY Represents Screen Objects
static java.lang.String	SCREEN_NAME Represents Screen Objects
static int	SCREEN_TEMPLATE_KEY Represents Screen Template Objects
static java.lang.String	SCREEN_TEMPLATE_NAME Represents Screen Template Objects
static int	TEMPLATE_TYPES Number of different Template Types that we know of

Fields inherited from class org.apache.turbine.services.BaseService

configuration, name, serviceBroker

Fields inherited from class org.apache.turbine.services.BaseInitable

initableBroker, isInitialized

Fields inherited from interface org.apache.turbine.services.template.TemplateService

DEFAULT_EXTENSION_KEY, DEFAULT_EXTENSION_VALUE, DEFAULT_NAME, DEFAULT_TEMPLATE_KEY, DEFAULT_TEMPLATE_VALUE, EXTENSION_SEPARATOR, SERVICE_NAME, TEMPLATE_PARTS_SEPARATOR

Constructor Summary

TurbineTemplateService()
C'tor

Method Summary

java.lang.String	getDefaultExtension() Get the default template name extension specified in the template service properties.
java.lang.String	getDefaultLayout() Get the default layout module name of the template engine service corresponding to the default template name extension.
java.lang.String	getDefaultLayoutName(RunData data) Find the default layout module name for the given request.
java.lang.String	getDefaultLayoutName(java.lang.String template) Get the default layout module name of the template engine service corresponding to the template name extension of the named template.
java.lang.String	getDefaultLayoutTemplate() Get the default layout template name of the template engine service corresponding to the default template name extension.
java.lang.String	getDefaultLayoutTemplateName(java.lang.String template) Get the default layout template name of the template engine service corresponding to the template name extension of the named template.
java.lang.String	getDefaultNavigation() Get the default navigation module name of the template engine service corresponding to the default template name extension.
java.lang.String	getDefaultNavigationName(java.lang.String template) Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.
java.lang.String	getDefaultPage() Get the default page module name of the template engine service corresponding to the default template name extension.
java.lang.String	getDefaultPageName(RunData data) Find the default page module name for the given request.
java.lang.String	getDefaultPageName(java.lang.String template) Get the default page module name of the template engine service corresponding to the template name extension of the named template.
java.lang.String	getDefaultScreen() Get the default screen module name of the template engine service corresponding to the default template name extension.
java.lang.String	getDefaultScreenName(java.lang.String template) Get the default screen module name of the template engine service corresponding to the template name extension of the named template.
java.lang.String	getDefaultTemplate() Returns the Default Template Name with the Default Extension.
java.lang.String	getExtension(java.lang.String template) Return Extension for a supplied template
java.lang.String	getLayoutName(java.lang.String template) Locate and return the name of the layout module to be used with the named layout template.
java.lang.String	getLayoutTemplateName(java.lang.String template) Locate and return the name of the layout template corresponding to the given screen template name parameter.
java.lang.String	getNavigationName(java.lang.String template) Locate and return the name of the navigation module to be used with the named navigation template.
java.lang.String	getNavigationTemplateName(java.lang.String template) Locate and return the name of the navigation template corresponding to the given template name parameter.
java.lang.String	getScreenName(java.lang.String template) Locate and return the name of the screen module to be used with the named screen template.
java.lang.String	getScreenTemplateName(java.lang.String template) Locate and return the name of the screen template corresponding to the given template name parameter.
TemplateEngineService	getTemplateEngineService(java.lang.String template) The TemplateEngineService associated with the specified template's file extension.
void	init() Called the first time the Service is used.
boolean	isCaching() Returns true if the Template Service has caching activated
void	registerTemplateEngineService(TemplateEngineService service) Registers the provided template engine for use by the TemplateService.
boolean	templateExists(java.lang.String template, java.lang.String[] templatePaths) Deprecated. Use templateExists from the various Templating Engines
java.lang.String[]	translateTemplatePaths(java.lang.String[] templatePaths) Deprecated. Each template engine service should know how to translate a request onto a file.

Methods inherited from class org.apache.turbine.services.TurbineBaseService

init, init, init, shutdown

Methods inherited from class org.apache.turbine.services.BaseService

getConfiguration, getName, getProperties, getServiceBroker, setName, setServiceBroker

Methods inherited from class org.apache.turbine.services.BaseInitable

getInit, getInitableBroker, setInit, setInitableBroker

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.turbine.services.Service

getConfiguration, getName, getProperties, setName, setServiceBroker

Methods inherited from interface org.apache.turbine.services.Initable

getInit, init, setInitableBroker, shutdown

Field Detail

PAGE_KEY

public static final int PAGE_KEY

Represents Page Objects

See Also:

Constant Field Values

PAGE_NAME

public static final java.lang.String PAGE_NAME

Represents Page Objects

See Also:

Constant Field Values

SCREEN_KEY

public static final int SCREEN_KEY

Represents Screen Objects

See Also:

Constant Field Values

SCREEN_NAME

public static final java.lang.String SCREEN_NAME

Represents Screen Objects

See Also:

Constant Field Values

LAYOUT_KEY

public static final int LAYOUT_KEY

Represents Layout Objects

See Also:

Constant Field Values

LAYOUT_NAME

public static final java.lang.String LAYOUT_NAME

Represents Layout Objects

See Also:

Constant Field Values

NAVIGATION_KEY

public static final int NAVIGATION_KEY

Represents Navigation Objects

See Also:

Constant Field Values

NAVIGATION_NAME

public static final java.lang.String NAVIGATION_NAME

Represents Navigation Objects

See Also:

Constant Field Values

LAYOUT_TEMPLATE_KEY

public static final int LAYOUT_TEMPLATE_KEY

Represents Layout Template Objects

See Also:

Constant Field Values

LAYOUT_TEMPLATE_NAME

public static final java.lang.String LAYOUT_TEMPLATE_NAME

Represents Layout Template Objects

See Also:

Constant Field Values

SCREEN_TEMPLATE_KEY

public static final int SCREEN_TEMPLATE_KEY

Represents Screen Template Objects

See Also:

Constant Field Values

SCREEN_TEMPLATE_NAME

public static final java.lang.String SCREEN_TEMPLATE_NAME

Represents Screen Template Objects

See Also:

Constant Field Values

NAVIGATION_TEMPLATE_KEY

public static final int NAVIGATION_TEMPLATE_KEY

Represents Navigation Template Objects

See Also:

Constant Field Values

NAVIGATION_TEMPLATE_NAME

public static final java.lang.String NAVIGATION_TEMPLATE_NAME

Represents Navigation Template Objects

See Also:

Constant Field Values

TEMPLATE_TYPES

public static final int TEMPLATE_TYPES

Number of different Template Types that we know of

See Also:

Constant Field Values

NO_FILE_EXT

protected static final java.lang.String NO_FILE_EXT

The default file extension used as a registry key when a template's file extension cannot be determined.

See Also:

Constant Field Values

Constructor Detail

TurbineTemplateService

public TurbineTemplateService()

C'tor

Method Detail

init

public void init()
          throws InitializationException

Called the first time the Service is used.

Specified by:

init in interface Initable

Overrides:

init in class TurbineBaseService

Throws:

InitializationException - Something went wrong when setting up the Template Service.

isCaching

public boolean isCaching()

Returns true if the Template Service has caching activated

Specified by:

isCaching in interface TemplateService

Returns:

true if Caching is active.

getDefaultExtension

public java.lang.String getDefaultExtension()

Get the default template name extension specified in the template service properties. If no extension is defined, return the empty string.

Specified by:

getDefaultExtension in interface TemplateService

Returns:

The default extension.

getExtension

public java.lang.String getExtension(java.lang.String template)

Return Extension for a supplied template

Specified by:

getExtension in interface TemplateService

Parameters:

template - The template name

Returns:

extension The extension for the supplied template

getDefaultTemplate

public java.lang.String getDefaultTemplate()

Returns the Default Template Name with the Default Extension. If the extension is unset, return only the template name

Specified by:

getDefaultTemplate in interface TemplateService

Returns:

The default template Name

getDefaultPage

public java.lang.String getDefaultPage()

Get the default page module name of the template engine service corresponding to the default template name extension.

Specified by:

getDefaultPage in interface TemplateService

Returns:

The default page module name.

getDefaultScreen

public java.lang.String getDefaultScreen()

Get the default screen module name of the template engine service corresponding to the default template name extension.

Specified by:

getDefaultScreen in interface TemplateService

Returns:

The default screen module name.

getDefaultLayout

public java.lang.String getDefaultLayout()

Get the default layout module name of the template engine service corresponding to the default template name extension.

Specified by:

getDefaultLayout in interface TemplateService

Returns:

The default layout module name.

getDefaultNavigation

public java.lang.String getDefaultNavigation()

Get the default navigation module name of the template engine service corresponding to the default template name extension.

Specified by:

getDefaultNavigation in interface TemplateService

Returns:

The default navigation module name.

getDefaultLayoutTemplate

public java.lang.String getDefaultLayoutTemplate()

Get the default layout template name of the template engine service corresponding to the default template name extension.

Specified by:

getDefaultLayoutTemplate in interface TemplateService

Returns:

The default layout template name.

getDefaultPageName

public java.lang.String getDefaultPageName(java.lang.String template)

Get the default page module name of the template engine service corresponding to the template name extension of the named template.

Specified by:

getDefaultPageName in interface TemplateService

Parameters:

template - The template name.

Returns:

The default page module name.

getDefaultScreenName

public java.lang.String getDefaultScreenName(java.lang.String template)

Get the default screen module name of the template engine service corresponding to the template name extension of the named template.

Specified by:

getDefaultScreenName in interface TemplateService

Parameters:

template - The template name.

Returns:

The default screen module name.

getDefaultLayoutName

public java.lang.String getDefaultLayoutName(java.lang.String template)

Get the default layout module name of the template engine service corresponding to the template name extension of the named template.

Specified by:

getDefaultLayoutName in interface TemplateService

Parameters:

template - The template name.

Returns:

The default layout module name.

getDefaultNavigationName

public java.lang.String getDefaultNavigationName(java.lang.String template)

Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.

Specified by:

getDefaultNavigationName in interface TemplateService

Parameters:

template - The template name.

Returns:

The default navigation module name.

getDefaultLayoutTemplateName

public java.lang.String getDefaultLayoutTemplateName(java.lang.String template)

Get the default layout template name of the template engine service corresponding to the template name extension of the named template.

Specified by:

getDefaultLayoutTemplateName in interface TemplateService

Parameters:

template - The template name.

Returns:

The default layout template name.

getDefaultPageName

public java.lang.String getDefaultPageName(RunData data)

Find the default page module name for the given request.

Specified by:

getDefaultPageName in interface TemplateService

Parameters:

data - The encapsulation of the request to retrieve the default page for.

Returns:

The default page module name.

getDefaultLayoutName

public java.lang.String getDefaultLayoutName(RunData data)

Find the default layout module name for the given request.

Specified by:

getDefaultLayoutName in interface TemplateService

Parameters:

data - The encapsulation of the request to retrieve the default layout for.

Returns:

The default layout module name.

getScreenName

public java.lang.String getScreenName(java.lang.String template)
                               throws java.lang.Exception

Locate and return the name of the screen module to be used with the named screen template.

Specified by:

getScreenName in interface TemplateService

Parameters:

template - The screen template name.

Returns:

The found screen module name.

Throws:

Exception, - a generic exception.

java.lang.Exception

getLayoutName

public java.lang.String getLayoutName(java.lang.String template)
                               throws java.lang.Exception

Locate and return the name of the layout module to be used with the named layout template.

Specified by:

getLayoutName in interface TemplateService

Parameters:

template - The layout template name.

Returns:

The found layout module name.

Throws:

Exception, - a generic exception.

java.lang.Exception

getNavigationName

public java.lang.String getNavigationName(java.lang.String template)
                                   throws java.lang.Exception

Locate and return the name of the navigation module to be used with the named navigation template.

Specified by:

getNavigationName in interface TemplateService

Parameters:

template - The navigation template name.

Returns:

The found navigation module name.

Throws:

Exception, - a generic exception.

java.lang.Exception

getScreenTemplateName

public java.lang.String getScreenTemplateName(java.lang.String template)
                                       throws java.lang.Exception

Locate and return the name of the screen template corresponding to the given template name parameter. This might return null if the screen is not found!

Specified by:

getScreenTemplateName in interface TemplateService

Parameters:

template - The template name parameter.

Returns:

The found screen template name.

Throws:

Exception, - a generic exception.

java.lang.Exception

getLayoutTemplateName

public java.lang.String getLayoutTemplateName(java.lang.String template)
                                       throws java.lang.Exception

Locate and return the name of the layout template corresponding to the given screen template name parameter.

Specified by:

getLayoutTemplateName in interface TemplateService

Parameters:

template - The template name parameter.

Returns:

The found screen template name.

Throws:

Exception, - a generic exception.

java.lang.Exception

getNavigationTemplateName

public java.lang.String getNavigationTemplateName(java.lang.String template)
                                           throws java.lang.Exception

Locate and return the name of the navigation template corresponding to the given template name parameter. This might return null if the navigation is not found!

Specified by:

getNavigationTemplateName in interface TemplateService

Parameters:

template - The template name parameter.

Returns:

The found navigation template name.

Throws:

Exception, - a generic exception.

java.lang.Exception

translateTemplatePaths

public java.lang.String[] translateTemplatePaths(java.lang.String[] templatePaths)

Deprecated. Each template engine service should know how to translate a request onto a file.

Translates the supplied template paths into their Turbine-canonical equivalent (probably absolute paths). This is used if the templating engine (e.g. JSP) does not provide any means to load a page but the page path is passed to the servlet container.

Specified by:

translateTemplatePaths in interface TemplateService

Parameters:

templatePaths - An array of template paths.

Returns:

An array of translated template paths.

templateExists

public boolean templateExists(java.lang.String template,
                              java.lang.String[] templatePaths)

Deprecated. Use templateExists from the various Templating Engines

Delegates to the appropriate TemplateEngineService to check the existance of the specified template.

Specified by:

templateExists in interface TemplateService

Parameters:

template - The template to check for the existance of.

templatePaths - The paths to check for the template.

registerTemplateEngineService

public void registerTemplateEngineService(TemplateEngineService service)

Registers the provided template engine for use by the TemplateService.

Specified by:

registerTemplateEngineService in interface TemplateService

Parameters:

service - The TemplateEngineService to register.

getTemplateEngineService

public TemplateEngineService getTemplateEngineService(java.lang.String template)

The TemplateEngineService associated with the specified template's file extension.

Specified by:

getTemplateEngineService in interface TemplateService

Parameters:

template - The template name.

Returns:

The template engine service.