Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.turbine.services.template
Class TurbineTemplateService

    java.lang.Object
      org.apache.turbine.services.BaseInitable
          org.apache.turbine.services.BaseService
              org.apache.turbine.services.TurbineBaseService
                  org.apache.turbine.services.template.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: TurbineTemplateService.java 1078552 2011-03-06 19:58:46Z tv $
Author:
  John D. McNally, Dave Bryson, Jason van Zyl, Daniel Rall, Ilkka Priha, Henning P. Schmiedehausen

Field Summary
`static int` | `LAYOUT_KEY` Represents Layout Objects
`static int` | `LAYOUT_TEMPLATE_KEY` Represents Layout Template Objects
`static String` | `LAYOUT_TEMPLATE_NAME` Represents Layout Template Objects
`static int` | `NAVIGATION_KEY` Represents Navigation Objects
`static int` | `NAVIGATION_TEMPLATE_KEY` Represents Navigation Template Objects
`static String` | `NAVIGATION_TEMPLATE_NAME` Represents Navigation Template Objects
`protected static String` | `NO_FILE_EXT` The default file extension used as a registry key when a template's file extension cannot be determined.
`static int` | `PAGE_KEY` Represents Page Objects
`static int` | `SCREEN_KEY` Represents Screen Objects
`static int` | `SCREEN_TEMPLATE_KEY` Represents Screen Template Objects
`static String` | `SCREEN_TEMPLATE_NAME` Represents Screen Template Objects
`static int` | `TEMPLATE_TYPES` Number of different Template Types that we know of

Fields inherited from class org.apache.turbine.services.BaseService
`configuration, name, serviceBroker`

Fields inherited from class org.apache.turbine.services.BaseInitable
`initableBroker, isInitialized`

Fields inherited from interface org.apache.turbine.services.template.TemplateService
`DEFAULT_EXTENSION_KEY, DEFAULT_EXTENSION_VALUE, DEFAULT_NAME, DEFAULT_TEMPLATE_KEY, DEFAULT_TEMPLATE_VALUE, EXTENSION_SEPARATOR, SERVICE_NAME, TEMPLATE_PARTS_SEPARATOR`

Constructor Summary
`TurbineTemplateService()` C'tor

Method Summary
`String` | `getDefaultExtension()` Get the default template name extension specified in the template service properties.
`String` | `getDefaultLayout()` Get the default layout module name of the template engine service corresponding to the default template name extension.
`String` | `getDefaultLayoutName(RunData data)` Find the default layout module name for the given request.
`String` | `getDefaultLayoutName(String template)` Get the default layout module name of the template engine service corresponding to the template name extension of the named template.
`String` | `getDefaultLayoutTemplate()` Get the default layout template name of the template engine service corresponding to the default template name extension.
`String` | `getDefaultLayoutTemplateName(String template)` Get the default layout template name of the template engine service corresponding to the template name extension of the named template.
`String` | `getDefaultNavigation()` Get the default navigation module name of the template engine service corresponding to the default template name extension.
`String` | `getDefaultNavigationName(String template)` Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.
`String` | `getDefaultPage()` Get the default page module name of the template engine service corresponding to the default template name extension.
`String` | `getDefaultPageName(RunData data)` Find the default page module name for the given request.
`String` | `getDefaultPageName(String template)` Get the default page module name of the template engine service corresponding to the template name extension of the named template.
`String` | `getDefaultScreen()` Get the default screen module name of the template engine service corresponding to the default template name extension.
`String` | `getDefaultScreenName(String template)` Get the default screen module name of the template engine service corresponding to the template name extension of the named template.
`String` | `getDefaultTemplate()` Returns the Default Template Name with the Default Extension.
`String` | `getExtension(String template)` Return Extension for a supplied template
`String` | `getLayoutName(String template)` Locate and return the name of the layout module to be used with the named layout template.
`String` | `getLayoutTemplateName(String template)` Locate and return the name of the layout template corresponding to the given screen template name parameter.
`String` | `getNavigationName(String template)` Locate and return the name of the navigation module to be used with the named navigation template.
`String` | `getNavigationTemplateName(String template)` Locate and return the name of the navigation template corresponding to the given template name parameter.
`String` | `getScreenName(String template)` Locate and return the name of the screen module to be used with the named screen template.
`String` | `getScreenTemplateName(String template)` Locate and return the name of the screen template corresponding to the given template name parameter.
`TemplateEngineService` | `getTemplateEngineService(String template)` The `TemplateEngineService` associated with the specified template's file extension.
`void` | `init()` Called the first time the Service is used.
`boolean` | `isCaching()` Returns true if the Template Service has caching activated
`void` | `registerTemplateEngineService(TemplateEngineService service)` Registers the provided template engine for use by the `TemplateService`.
`boolean` | `templateExists(String template, String[] templatePaths)` Deprecated. Use templateExists from the various Templating Engines
`String[]` | `translateTemplatePaths(String[] templatePaths)` Deprecated. Each template engine service should know how to translate a request onto a file.

Methods inherited from class org.apache.turbine.services.TurbineBaseService
`init, init, init, shutdown`

Methods inherited from class org.apache.turbine.services.BaseService
`getConfiguration, getName, getProperties, getServiceBroker, setName, setServiceBroker`

Methods inherited from class org.apache.turbine.services.BaseInitable
`getInit, getInitableBroker, setInit, setInitableBroker`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.apache.turbine.services.Service
`getConfiguration, getName, getProperties, setName, setServiceBroker`

Methods inherited from interface org.apache.turbine.services.Initable
`getInit, init, setInitableBroker, shutdown`

Field Detail

### PAGE_KEY

    public static final int PAGE_KEY

  Represents Page Objects

  See Also:
    Constant Field Values

### SCREEN_KEY

    public static final int SCREEN_KEY

  Represents Screen Objects

  See Also:
    Constant Field Values

### LAYOUT_KEY

    public static final int LAYOUT_KEY

  Represents Layout Objects

  See Also:
    Constant Field Values

### NAVIGATION_KEY

    public static final int NAVIGATION_KEY

  Represents Navigation Objects

  See Also:
    Constant Field Values

### LAYOUT_TEMPLATE_KEY

    public static final int LAYOUT_TEMPLATE_KEY

  Represents Layout Template Objects

  See Also:
    Constant Field Values

### LAYOUT_TEMPLATE_NAME

    public static final String LAYOUT_TEMPLATE_NAME

  Represents Layout Template Objects

  See Also:
    Constant Field Values

### SCREEN_TEMPLATE_KEY

    public static final int SCREEN_TEMPLATE_KEY

  Represents Screen Template Objects

  See Also:
    Constant Field Values

### SCREEN_TEMPLATE_NAME

    public static final String SCREEN_TEMPLATE_NAME

  Represents Screen Template Objects

  See Also:
    Constant Field Values

### NAVIGATION_TEMPLATE_KEY

    public static final int NAVIGATION_TEMPLATE_KEY

  Represents Navigation Template Objects

  See Also:
    Constant Field Values

### NAVIGATION_TEMPLATE_NAME

    public static final String NAVIGATION_TEMPLATE_NAME

  Represents Navigation Template Objects

  See Also:
    Constant Field Values

### TEMPLATE_TYPES

    public static final int TEMPLATE_TYPES

  Number of different Template Types that we know of

  See Also:
    Constant Field Values

### NO_FILE_EXT

    protected static final String NO_FILE_EXT

  The default file extension used as a registry key when a template's file extension cannot be determined.

  See Also:
    Constant Field Values

Constructor Detail

### TurbineTemplateService

    public TurbineTemplateService()

  C'tor

Method Detail

### init

    public void init()
              throws InitializationException

  Called the first time the Service is used.

  Specified by:
    `init` in interface `Initable`
  Overrides:
    `init` in class `TurbineBaseService`
  Throws:
    `InitializationException` - Something went wrong when setting up the Template Service.

### isCaching

    public boolean isCaching()

  Returns true if the Template Service has caching activated

  Specified by:
    `isCaching` in interface `TemplateService`
  Returns:
    true if Caching is active.

### getDefaultExtension

    public String getDefaultExtension()

  Get the default template name extension specified in the template service properties. If no extension is defined, return the empty string.

  Specified by:
    `getDefaultExtension` in interface `TemplateService`
  Returns:
    The default extension.

### getExtension

    public String getExtension(String template)

  Return Extension for a supplied template

  Specified by:
    `getExtension` in interface `TemplateService`
  Parameters:
    `template` - The template name
  Returns:
    extension The extension for the supplied template

### getDefaultTemplate

    public String getDefaultTemplate()

  Returns the Default Template Name with the Default Extension. If the extension is unset, return only the template name

  Specified by:
    `getDefaultTemplate` in interface `TemplateService`
  Returns:
    The default template Name

### getDefaultPage

    public String getDefaultPage()

  Get the default page module name of the template engine service corresponding to the default template name extension.

  Specified by:
    `getDefaultPage` in interface `TemplateService`
  Returns:
    The default page module name.

### getDefaultScreen

    public String getDefaultScreen()

  Get the default screen module name of the template engine service corresponding to the default template name extension.

  Specified by:
    `getDefaultScreen` in interface `TemplateService`
  Returns:
    The default screen module name.

### getDefaultLayout

    public String getDefaultLayout()

  Get the default layout module name of the template engine service corresponding to the default template name extension.

  Specified by:
    `getDefaultLayout` in interface `TemplateService`
  Returns:
    The default layout module name.

### getDefaultNavigation

    public String getDefaultNavigation()

  Get the default navigation module name of the template engine service corresponding to the default template name extension.

  Specified by:
    `getDefaultNavigation` in interface `TemplateService`
  Returns:
    The default navigation module name.

### getDefaultLayoutTemplate

    public String getDefaultLayoutTemplate()

  Get the default layout template name of the template engine service corresponding to the default template name extension.

  Specified by:
    `getDefaultLayoutTemplate` in interface `TemplateService`
  Returns:
    The default layout template name.

### getDefaultPageName

    public String getDefaultPageName(String template)

  Get the default page module name of the template engine service corresponding to the template name extension of the named template.

  Specified by:
    `getDefaultPageName` in interface `TemplateService`
  Parameters:
    `template` - The template name.
  Returns:
    The default page module name.

### getDefaultScreenName

    public String getDefaultScreenName(String template)

  Get the default screen module name of the template engine service corresponding to the template name extension of the named template.

  Specified by:
    `getDefaultScreenName` in interface `TemplateService`
  Parameters:
    `template` - The template name.
  Returns:
    The default screen module name.

### getDefaultLayoutName

    public String getDefaultLayoutName(String template)

  Get the default layout module name of the template engine service corresponding to the template name extension of the named template.

  Specified by:
    `getDefaultLayoutName` in interface `TemplateService`
  Parameters:
    `template` - The template name.
  Returns:
    The default layout module name.

### getDefaultNavigationName

    public String getDefaultNavigationName(String template)

  Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.

  Specified by:
    `getDefaultNavigationName` in interface `TemplateService`
  Parameters:
    `template` - The template name.
  Returns:
    The default navigation module name.

### getDefaultLayoutTemplateName

    public String getDefaultLayoutTemplateName(String template)

  Get the default layout template name of the template engine service corresponding to the template name extension of the named template.

  Specified by:
    `getDefaultLayoutTemplateName` in interface `TemplateService`
  Parameters:
    `template` - The template name.
  Returns:
    The default layout template name.

### getDefaultPageName

    public String getDefaultPageName(RunData data)

  Find the default page module name for the given request.

  Specified by:
    `getDefaultPageName` in interface `TemplateService`
  Parameters:
    `data` - The encapsulation of the request to retrieve the default page for.
  Returns:
    The default page module name.

### getDefaultLayoutName

    public String getDefaultLayoutName(RunData data)

  Find the default layout module name for the given request.

  Specified by:
    `getDefaultLayoutName` in interface `TemplateService`
  Parameters:
    `data` - The encapsulation of the request to retrieve the default layout for.
  Returns:
    The default layout module name.

### getScreenName

    public String getScreenName(String template)
                         throws Exception

  Locate and return the name of the screen module to be used with the named screen template.

  Specified by:
    `getScreenName` in interface `TemplateService`
  Parameters:
    `template` - The screen template name.
  Returns:
    The found screen module name.
  Throws:
    `Exception,` - a generic exception.
    `Exception`

### getLayoutName

    public String getLayoutName(String template)
                         throws Exception

  Locate and return the name of the layout module to be used with the named layout template.

  Specified by:
    `getLayoutName` in interface `TemplateService`
  Parameters:
    `template` - The layout template name.
  Returns:
    The found layout module name.
  Throws:
    `Exception,` - a generic exception.
    `Exception`

### getNavigationName

    public String getNavigationName(String template)
                             throws Exception

  Locate and return the name of the navigation module to be used with the named navigation template.

  Specified by:
    `getNavigationName` in interface `TemplateService`
  Parameters:
    `template` - The navigation template name.
  Returns:
    The found navigation module name.
  Throws:
    `Exception,` - a generic exception.
    `Exception`

### getScreenTemplateName

    public String getScreenTemplateName(String template)
                                 throws Exception

  Locate and return the name of the screen template corresponding to the given template name parameter. This might return null if the screen is not found!

  Specified by:
    `getScreenTemplateName` in interface `TemplateService`
  Parameters:
    `template` - The template name parameter.
  Returns:
    The found screen template name.
  Throws:
    `Exception,` - a generic exception.
    `Exception`

### getLayoutTemplateName

    public String getLayoutTemplateName(String template)
                                 throws Exception

  Locate and return the name of the layout template corresponding to the given screen template name parameter.

  Specified by:
    `getLayoutTemplateName` in interface `TemplateService`
  Parameters:
    `template` - The template name parameter.
  Returns:
    The found screen template name.
  Throws:
    `Exception,` - a generic exception.
    `Exception`

### getNavigationTemplateName

    public String getNavigationTemplateName(String template)
                                     throws Exception

  Locate and return the name of the navigation template corresponding to the given template name parameter. This might return null if the navigation is not found!

  Specified by:
    `getNavigationTemplateName` in interface `TemplateService`
  Parameters:
    `template` - The template name parameter.
  Returns:
    The found navigation template name.
  Throws:
    `Exception,` - a generic exception.
    `Exception`

### translateTemplatePaths

    @Deprecated
    public String[] translateTemplatePaths(String[] templatePaths)

  Deprecated. Each template engine service should know how to translate a request onto a file.

  Translates the supplied template paths into their Turbine-canonical equivalent (probably absolute paths). This is used if the templating engine (e.g. JSP) does not provide any means to load a page but the page path is passed to the servlet container.

  Specified by:
    `translateTemplatePaths` in interface `TemplateService`
  Parameters:
    `templatePaths` - An array of template paths.
  Returns:
    An array of translated template paths.

### templateExists

    @Deprecated
    public boolean templateExists(String template,
                                             String[] templatePaths)

  Deprecated. Use templateExists from the various Templating Engines

  Delegates to the appropriate `TemplateEngineService` to check the existance of the specified template.

  Specified by:
    `templateExists` in interface `TemplateService`
  Parameters:
    `template` - The template to check for the existance of.
    `templatePaths` - The paths to check for the template.

### registerTemplateEngineService

    public void registerTemplateEngineService(TemplateEngineService service)

  Registers the provided template engine for use by the `TemplateService`.

  Specified by:
    `registerTemplateEngineService` in interface `TemplateService`
  Parameters:
    `service` - The `TemplateEngineService` to register.

### getTemplateEngineService

    public TemplateEngineService getTemplateEngineService(String template)

  The `TemplateEngineService` associated with the specified template's file extension.

  Specified by:
    `getTemplateEngineService` in interface `TemplateService`
  Parameters:
    `template` - The template name.
  Returns:
    The template engine service.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2011 The Apache Software Foundation. All Rights Reserved.