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 screenabout,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 fororg.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$
- Author:
- John D. McNally, Dave Bryson, Jason van Zyl, Daniel Rall, Ilkka Priha, Henning P. Schmiedehausen
-
-
Field Summary
Fields Modifier and Type Field Description static int
LAYOUT_KEY
Represents Layout Objectsstatic int
LAYOUT_TEMPLATE_KEY
Represents Layout Template Objectsstatic String
LAYOUT_TEMPLATE_NAME
Represents Layout Template Objectsstatic int
NAVIGATION_KEY
Represents Navigation Objectsstatic int
NAVIGATION_TEMPLATE_KEY
Represents Navigation Template Objectsstatic String
NAVIGATION_TEMPLATE_NAME
Represents Navigation Template Objectsprotected static String
NO_FILE_EXT
Deprecated.Use TemplateService.DEFAULT_EXTENSION_VALUE.static int
PAGE_KEY
Represents Page Objectsstatic int
SCREEN_KEY
Represents Screen Objectsstatic int
SCREEN_TEMPLATE_KEY
Represents Screen Template Objectsstatic String
SCREEN_TEMPLATE_NAME
Represents Screen Template Objectsstatic 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.Service
SERVICE_NAME
-
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
Constructors Constructor Description TurbineTemplateService()
C'tor
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description String
getDefaultExtension()
Get the default template name extension specified in the template service properties.String
getDefaultLayout()
Get the default layout module name of the template engine service corresponding to the default template name extension.String
getDefaultLayoutName(String template)
Get the default layout module name of the template engine service corresponding to the template name extension of the named template.String
getDefaultLayoutName(PipelineData pipelineData)
Find the default layout module name for the given request.String
getDefaultLayoutTemplate()
Get the default layout template name of the template engine service corresponding to the default template name extension.String
getDefaultLayoutTemplateName(String template)
Get the default layout template name of the template engine service corresponding to the template name extension of the named template.String
getDefaultNavigation()
Get the default navigation module name of the template engine service corresponding to the default template name extension.String
getDefaultNavigationName(String template)
Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.String
getDefaultPage()
Get the default page module name of the template engine service corresponding to the default template name extension.String
getDefaultPageName(String template)
Get the default page module name of the template engine service corresponding to the template name extension of the named template.String
getDefaultPageName(PipelineData pipelineData)
Find the default page module name for the given request.String
getDefaultScreen()
Get the default screen module name of the template engine service corresponding to the default template name extension.String
getDefaultScreenName(String template)
Get the default screen module name of the template engine service corresponding to the template name extension of the named template.String
getDefaultTemplate()
Returns the Default Template Name with the Default Extension.String
getExtension(String template)
Return Extension for a supplied templateString
getLayoutName(String template)
Locate and return the name of the layout module to be used with the named layout template.String
getLayoutTemplateName(String template)
Locate and return the name of the layout template corresponding to the given screen template name parameter.String
getNavigationName(String template)
Locate and return the name of the navigation module to be used with the named navigation template.String
getNavigationTemplateName(String template)
Locate and return the name of the navigation template corresponding to the given template name parameter.String
getScreenName(String template)
Locate and return the name of the screen module to be used with the named screen template.String
getScreenTemplateName(String template)
Locate and return the name of the screen template corresponding to the given template name parameter.TemplateEngineService
getTemplateEngineService(String template)
TheTemplateEngineService
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 activatedvoid
registerTemplateEngineService(TemplateEngineService service)
Registers the provided template engine for use by theTemplateService
.boolean
templateExists(String template, String[] templatePaths)
Deprecated.Use templateExists from the various Templating EnginesString[]
translateTemplatePaths(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, 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.Initable
getInit, init, setInitableBroker, shutdown
-
Methods inherited from interface org.apache.turbine.services.Service
getConfiguration, getName, getProperties, setName, setServiceBroker
-
-
-
-
Field Detail
-
PAGE_KEY
public static final int PAGE_KEY
Represents Page Objects- See Also:
- Constant Field Values
-
SCREEN_KEY
public static final int SCREEN_KEY
Represents Screen Objects- See Also:
- Constant Field Values
-
LAYOUT_KEY
public static final int LAYOUT_KEY
Represents Layout Objects- See Also:
- Constant Field Values
-
NAVIGATION_KEY
public static final int NAVIGATION_KEY
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 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 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 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
@Deprecated protected static final String NO_FILE_EXT
Deprecated.Use TemplateService.DEFAULT_EXTENSION_VALUE.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 interfaceInitable
- Overrides:
init
in classTurbineBaseService
- 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 interfaceTemplateService
- Returns:
- true if Caching is active.
-
getDefaultExtension
public 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 interfaceTemplateService
- Returns:
- The default extension.
-
getExtension
public String getExtension(String template)
Return Extension for a supplied template- Specified by:
getExtension
in interfaceTemplateService
- Parameters:
template
- The template name- Returns:
- extension The extension for the supplied template
-
getDefaultTemplate
public 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 interfaceTemplateService
- Returns:
- The default template Name
-
getDefaultPage
public String getDefaultPage()
Get the default page module name of the template engine service corresponding to the default template name extension.- Specified by:
getDefaultPage
in interfaceTemplateService
- Returns:
- The default page module name.
-
getDefaultScreen
public String getDefaultScreen()
Get the default screen module name of the template engine service corresponding to the default template name extension.- Specified by:
getDefaultScreen
in interfaceTemplateService
- Returns:
- The default screen module name.
-
getDefaultLayout
public String getDefaultLayout()
Get the default layout module name of the template engine service corresponding to the default template name extension.- Specified by:
getDefaultLayout
in interfaceTemplateService
- Returns:
- The default layout module name.
-
getDefaultNavigation
public String getDefaultNavigation()
Get the default navigation module name of the template engine service corresponding to the default template name extension.- Specified by:
getDefaultNavigation
in interfaceTemplateService
- Returns:
- The default navigation module name.
-
getDefaultLayoutTemplate
public String getDefaultLayoutTemplate()
Get the default layout template name of the template engine service corresponding to the default template name extension.- Specified by:
getDefaultLayoutTemplate
in interfaceTemplateService
- Returns:
- The default layout template name.
-
getDefaultPageName
public String getDefaultPageName(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 interfaceTemplateService
- Parameters:
template
- The template name.- Returns:
- The default page module name.
-
getDefaultScreenName
public String getDefaultScreenName(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 interfaceTemplateService
- Parameters:
template
- The template name.- Returns:
- The default screen module name.
-
getDefaultLayoutName
public String getDefaultLayoutName(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 interfaceTemplateService
- Parameters:
template
- The template name.- Returns:
- The default layout module name.
-
getDefaultNavigationName
public String getDefaultNavigationName(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 interfaceTemplateService
- Parameters:
template
- The template name.- Returns:
- The default navigation module name.
-
getDefaultLayoutTemplateName
public String getDefaultLayoutTemplateName(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 interfaceTemplateService
- Parameters:
template
- The template name.- Returns:
- The default layout template name.
-
getDefaultPageName
public String getDefaultPageName(PipelineData pipelineData)
Find the default page module name for the given request.- Specified by:
getDefaultPageName
in interfaceTemplateService
- Parameters:
pipelineData
- The encapsulation of the request to retrieve the default page for.- Returns:
- The default page module name.
-
getDefaultLayoutName
public String getDefaultLayoutName(PipelineData pipelineData)
Find the default layout module name for the given request.- Specified by:
getDefaultLayoutName
in interfaceTemplateService
- Parameters:
pipelineData
- The encapsulation of the request to retrieve the default layout for.- Returns:
- The default layout module name.
-
getScreenName
public String getScreenName(String template) throws Exception
Locate and return the name of the screen module to be used with the named screen template.- Specified by:
getScreenName
in interfaceTemplateService
- Parameters:
template
- The screen template name.- Returns:
- The found screen module name.
- Throws:
Exception
- a generic exception.
-
getLayoutName
public String getLayoutName(String template) throws Exception
Locate and return the name of the layout module to be used with the named layout template.- Specified by:
getLayoutName
in interfaceTemplateService
- Parameters:
template
- The layout template name.- Returns:
- The found layout module name.
- Throws:
Exception
- a generic exception.
-
getNavigationName
public String getNavigationName(String template) throws Exception
Locate and return the name of the navigation module to be used with the named navigation template.- Specified by:
getNavigationName
in interfaceTemplateService
- Parameters:
template
- The navigation template name.- Returns:
- The found navigation module name.
- Throws:
Exception
- a generic exception.
-
getScreenTemplateName
public String getScreenTemplateName(String template) throws 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 interfaceTemplateService
- Parameters:
template
- The template name parameter.- Returns:
- The found screen template name.
- Throws:
Exception
- a generic exception.
-
getLayoutTemplateName
public String getLayoutTemplateName(String template) throws Exception
Locate and return the name of the layout template corresponding to the given screen template name parameter.- Specified by:
getLayoutTemplateName
in interfaceTemplateService
- Parameters:
template
- The template name parameter.- Returns:
- The found screen template name.
- Throws:
Exception
- a generic exception.
-
getNavigationTemplateName
public String getNavigationTemplateName(String template) throws 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 interfaceTemplateService
- Parameters:
template
- The template name parameter.- Returns:
- The found navigation template name.
- Throws:
Exception
- a generic exception.
-
translateTemplatePaths
@Deprecated public String[] translateTemplatePaths(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 interfaceTemplateService
- Parameters:
templatePaths
- An array of template paths.- Returns:
- An array of translated template paths.
-
templateExists
@Deprecated public boolean templateExists(String template, String[] templatePaths)
Deprecated.Use templateExists from the various Templating EnginesDelegates to the appropriateTemplateEngineService
to check the existence of the specified template.- Specified by:
templateExists
in interfaceTemplateService
- Parameters:
template
- The template to check for the existence of.templatePaths
- The paths to check for the template.- Returns:
- true if the given template exists
-
registerTemplateEngineService
public void registerTemplateEngineService(TemplateEngineService service)
Registers the provided template engine for use by theTemplateService
.- Specified by:
registerTemplateEngineService
in interfaceTemplateService
- Parameters:
service
- TheTemplateEngineService
to register.
-
getTemplateEngineService
public TemplateEngineService getTemplateEngineService(String template)
TheTemplateEngineService
associated with the specified template's file extension.- Specified by:
getTemplateEngineService
in interfaceTemplateService
- Parameters:
template
- The template name.- Returns:
- The template engine service.
-
-