<?xml version="1.0"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>

 <properties>
  <title>Turbine Services - Template Service</title>
 </properties>

<body>

<section name="Template Service">

<p>
</p>

</section>

<section name="Configuration">

<source><![CDATA[
# -------------------------------------------------------------------
#
#  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

]]></source>

</section>

<section name="Usage">
<p>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.
</p>

<p>Note: In all of the following examples, it is assumed that you use
the <a href="velocity-service.html">VelocityService</a> 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,
<a href="velocity-service.html">Velocity</a> and
<a href="jsp-service.html">Java Server Pages (JSP)</a>.
</p>

<p>
  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.
</p>

<p><u>The two golden rules when using Templates with Turbine</u></p>

<ul>
  <li>1) Many examples and docs from older Turbine code show template
         paths with a slashes.<br/>
         Repeat after me: <b>TEMPLATE NAMES NEVER CONTAIN SLASHES!</b><br/>
         Template names are separated by "," (the colon). </li>
  <li>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.<br/>
         Repeat after me: <b>TEMPLATE NAMES ARE NOT PATHS. THEY'RE NOT ABSOLUTE AND HAVE NO LEADING /</b>.</li>
</ul>

<p>
  If you keep these rules in mind when writing template names, you will never have
  trouble loading a template.
</p>

<p>
  If you request e.g. the template screen "about,directions,Driving.vm"
  then the following class names are searched (on the module search
  path):
</p>

<ul>
  <li>1. about.directions.Driving     &lt;- direct matching the template to the class name</li>
  <li>2. about.directions.Default     &lt;- matching the package, class name is Default</li>
  <li>3. about.Default                &lt;- stepping up in the package hierarchy, looking for Default</li>
  <li>4. Default                      &lt;- Class called "Default" without package</li>
  <li>5. VelocityScreen               &lt;- The class configured by the Service (VelocityService) to use</li>
</ul>

<p>
  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
</p>

<ul>
  <li>org.apache.turbine.modules.screens.about.directions.Driving</li>
  <li>com.mycorp.modules.screens.about.directions.Driving</li>
  <li>org.apache.turbine.modules.screens.about.directions.Default</li>
  <li>com.mycorp.modules.screens.about.directions.Default</li>
  <li>org.apache.turbine.modules.screens.about.Default</li>
  <li>com.mycorp.modules.screens.about.Default</li>
  <li>org.apache.turbine.modules.screens.Default</li>
  <li>com.mycorp.modules.screens.Default</li>
  <li>org.apache.turbine.modules.screens.VelocityScreen</li>
  <li>com.mycorp.modules.screens.VelocityScreen</li>
</ul>

<p>
  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.
</p>

<p>
  Please note, that your Screen Template (Driving.vm) must exist!
  If it does not exist, the Template Service will report an error.
</p>

<p>
  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!
</p>

<p>
  Consider our example:  about,directions,Driving.vm (Screen Name)
</p>

<p>
  Now the template service will look for the following Navigation
  and Layout templates:
</p>

<ul>
  <li>1. about,directions,Driving.vm      &lt;- exact match</li>
  <li>2. about,directions,Default.vm      &lt;- package match, Default name</li>
  <li>3. about,Default.vm                 &lt;- stepping up in the hierarchy</li>
  <li>4. Default.vm                       &lt;- The name configured as default.layout.template in the Velocity service.</li>
</ul>

<p>
  If you now wonder how a template name is mapped to an actual file name: This is
  scope of the templating engine. <a href="velocity-service.html">Velocity</a>
  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.
</p>
</section>

<section name="Properties">
<p>
  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.
</p>

<ul>
  <li>
    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
  </li>
  <li>
    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
  </li>
  <li>
    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
  </li>
  <li>
    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
  </li>
  <li>
    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
  </li>
  <li>
    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
  </li>
  <li>
    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
  </li>
</ul>
</section>
</body>
</document>
