Usage

The Template Service itself can't render View pages. It is responsible for
matching actual Template Files and Java classes to passed template names. Template
names are "," separated entities which describe a template screen to be displayed.

Note: In all of the following examples, it is assumed that you use
the VelocityService as
your preferred view service. So if you read "Velocity" in the
following paragraphs, this means "default configured view
class". Currently, Turbine includes two supported view services,
Velocity and
Java Server Pages (JSP).

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.

The two golden rules when using Templates with Turbine

1) Many examples and docs from older Turbine code show template
paths with a slashes.
Repeat after me: TEMPLATE NAMES NEVER CONTAIN SLASHES!
Template names are separated by "," (the colon).

2) 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 PATHS. THEY'RE NOT ABSOLUTE AND HAVE NO LEADING /.

If you keep these rules in mind when writing template names, you will never have
trouble loading a 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 use

And if you have the following module packages configured in your TurbineResources.properties:
"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.

If you now wonder how a template name is mapped to an actual 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 file but if you tell velocity "get about,directions,Driving.vm" and it
returns the rendered template. So getting the actual template is not the job of the
Templating Service but of the Template rendering services.

Properties

The mapping of classes and template paths to template names is configured in
mapper classes. These are pluggable and can be exchanged to configure other mapping
policies. This is an option for seasoned Turbine developers and the default policy
shouldn't be changed lightly.

services.TemplateService.mapper.page.class configures the mapper
used for finding a page class suitable for the supplied template
name. Default is org.apache.turbine.services.template.mapper.DirectMapper

services.TemplateService.mapper.screen.class configures the mapper
used for finding a screen class suitable for the supplied template
name. Default is org.apache.turbine.services.template.mapper.ClassMapper

services.TemplateService.mapper.layout.class configures the mapper
used for finding a layout class suitable for the supplied template
name. Default is org.apache.turbine.services.template.mapper.ClassMapper

services.TemplateService.mapper.navigation.class configures the
mapper used for finding navigation classes suitable for the
supplied template name. This mapper is not used directly but from
various navigation helpers like TemplateNavigation. Default is
org.apache.turbine.services.template.mapper.ClassMapper

services.TemplateService.mapper.layout.template.class configures
the mapper used for finding a layout template to render your
screen. This template is used by your Layout class (see above) to
position the various visual elements like content and navigation
on the Page. Default is org.apache.turbine.services.template.mapper.LayoutTemplateMapper

services.TemplateService.mapper.screen.template.class configures
the mapper used for finding your screen template. This is used
whenever a screen class is requesting a template to
render. Default is org.apache.turbine.services.template.mapper.ScreenTemplateMapper

services.TemplateService.mapper.navigation.template.class configures
the mapper used for finding your navigation template. This is used
whenever a navigation class is requesting a template to
render. Default is org.apache.turbine.services.template.mapper.DirectTemplateMapper