| <?xml version="1.0"?> |
| <!-- |
| /* |
| * Copyright 2001-2004 The Apache Software Foundation. |
| * |
| * Licensed 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 <- direct matching the template to the class name</li> |
| <li>2. about.directions.Default <- matching the package, class name is Default</li> |
| <li>3. about.Default <- stepping up in the package hierarchy, looking for Default</li> |
| <li>4. Default <- Class called "Default" without package</li> |
| <li>5. VelocityScreen <- 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 <- exact match</li> |
| <li>2. about,directions,Default.vm <- package match, Default name</li> |
| <li>3. about,Default.vm <- stepping up in the hierarchy</li> |
| <li>4. Default.vm <- 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> |
