# ------------------------------------------------------------------- # # 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
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
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):
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
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:
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.
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.