| TurbineTemplateService |
| public class TurbineTemplateService extends TurbineBaseService implements TemplateService(Code) |
| 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.
author:
John D. McNally
author:
Dave Bryson
author:
Jason van Zyl
author:
Daniel Rall
author:
Ilkka Priha
author:
Henning P. Schmiedehausen
version:
$Id: TurbineTemplateService.java 534527 2007-05-02 16:10:59Z tv $ |
| Method Summary |
|
| public String | getDefaultExtension()
Get the default template name extension specified
in the template service properties. |
| public String | getDefaultLayout()
Get the default layout module name of the template engine
service corresponding to the default template name extension. |
| 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.
Parameters:
template - The template name. |
| public String | getDefaultLayoutName(RunData data)
Find the default layout module name for the given request.
Parameters:
data - The encapsulation of the request to retrieve thedefault layout for. |
| public String | getDefaultLayoutTemplate()
Get the default layout template name of the template engine
service corresponding to the default template name extension. |
| 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.
Parameters:
template - The template name. |
| public String | getDefaultNavigation()
Get the default navigation module name of the template engine
service corresponding to the default template name extension. |
| 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.
Parameters:
template - The template name. |
| public String | getDefaultPage()
Get the default page module name of the template engine
service corresponding to the default template name extension. |
| 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.
Parameters:
template - The template name. |
| public String | getDefaultPageName(RunData data)
Find the default page module name for the given request.
Parameters:
data - The encapsulation of the request to retrieve thedefault page for. |
| public String | getDefaultScreen()
Get the default screen module name of the template engine
service corresponding to the default template name extension. |
| 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.
Parameters:
template - The template name. |
| public String | getDefaultTemplate()
Returns the Default Template Name with the Default Extension. |
| public String | getExtension(String template)
|
| public String | getLayoutName(String template)
Locate and return the name of the layout module to be used
with the named layout template.
Parameters:
template - The layout template name. |
| public String | getLayoutTemplateName(String template)
Locate and return the name of the layout template corresponding
to the given screen template name parameter.
Parameters:
template - The template name parameter. |
| public String | getNavigationName(String template)
Locate and return the name of the navigation module to be used
with the named navigation template.
Parameters:
template - The navigation template name. |
| public String | getNavigationTemplateName(String template)
Locate and return the name of the navigation template corresponding
to the given template name parameter. |
| public String | getScreenName(String template)
Locate and return the name of the screen module to be used
with the named screen template.
Parameters:
template - The screen template name. |
| public String | getScreenTemplateName(String template)
Locate and return the name of the screen template corresponding
to the given template name parameter. |
| public TemplateEngineService | getTemplateEngineService(String template)
The
org.apache.turbine.services.template.TemplateEngineService associated with the specified template's file extension.
Parameters:
template - The template name. |
| public void | init()
Called the first time the Service is used. |
| public boolean | isCaching()
|
| public synchronized void | registerTemplateEngineService(TemplateEngineService service)
Registers the provided template engine for use by the
TemplateService. |
| public boolean | templateExists(String template, String[] templatePaths)
Delegates to the appropriate
org.apache.turbine.services.template.TemplateEngineService to
check the existance of the specified template. |
| public String[] | translateTemplatePaths(String[] templatePaths)
Translates the supplied template paths into their Turbine-canonical
equivalent (probably absolute paths). |
