Template Service

Configuration

# -------------------------------------------------------------------
#
#  S E R V I C E S
#
# -------------------------------------------------------------------
# Classes for Turbine Services should be defined here.
# Format: services.[name].classname=[implementing class]
#
# To specify properties of a service use the following syntax:
# service.[name].[property]=[value]

services.TemplateService.classname=org.apache.turbine.services.template.TurbineTemplateService
.
.
.
# -------------------------------------------------------------------
#
#  T E M P L A T E  S E R V I C E
#
# -------------------------------------------------------------------

# Roughly, the number of templates in each category.
#
# Defaults: layout=2, navigation=10, screen=50

services.TemplateService.layout.cache.size=2
services.TemplateService.navigation.cache.size=10
services.TemplateService.screen.cache.size=50

#
# These are the mapper classes responsible for the lookup of Page, Screen, Layout and Navigation classes according
# to the supplied template Name. They also map template names on the Layout and Screen file names to be used.
#
services.TemplateService.mapper.page.class                = org.apache.turbine.services.template.mapper.DirectMapper
services.TemplateService.mapper.screen.class              = org.apache.turbine.services.template.mapper.ClassMapper
services.TemplateService.mapper.layout.class              = org.apache.turbine.services.template.mapper.ClassMapper
services.TemplateService.mapper.navigation.class          = org.apache.turbine.services.template.mapper.ClassMapper
services.TemplateService.mapper.layout.template.class     = org.apache.turbine.services.template.mapper.LayoutTemplateMapper
services.TemplateService.mapper.screen.template.class     = org.apache.turbine.services.template.mapper.ScreenTemplateMapper
services.TemplateService.mapper.navigation.template.class = org.apache.turbine.services.template.mapper.DirectTemplateMapper

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