Package org.apache.turbine.services.template

Class 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$
    Author:
    John D. McNally, Dave Bryson, Jason van Zyl, Daniel Rall, Ilkka Priha, Henning P. Schmiedehausen