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 1773378 2016-12-09 13:19:59Z tv $
  Author:
    John D. McNally, Dave Bryson, Jason van Zyl, Daniel Rall, Ilkka Priha, Henning P. Schmiedehausen

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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` Deprecated. Use TemplateService.DEFAULT_EXTENSION_VALUE.
    `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

    Constructors
    Constructor and Description
    `TurbineTemplateService()` C'tor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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(PipelineData pipelineData)` 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(PipelineData pipelineData)` 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, 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

          @Deprecated
          protected static final String NO_FILE_EXT

      Deprecated. Use TemplateService.DEFAULT_EXTENSION_VALUE.
      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(PipelineData pipelineData)

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

    - #### getDefaultLayoutName

          public String getDefaultLayoutName(PipelineData pipelineData)

      Find the default layout module name for the given request.
      Specified by:
        `getDefaultLayoutName` in interface `TemplateService`
      Parameters:
        `pipelineData` - 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.

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

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

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

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

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

    - #### 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 existence of the specified template.
      Specified by:
        `templateExists` in interface `TemplateService`
      Parameters:
        `template` - The template to check for the existence of.
        `templatePaths` - The paths to check for the template.
      Returns:
        true if the given template exists

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

Copyright © 2000–2018 The Apache Software Foundation. All rights reserved.