Package org.apache.velocity.tools.view

Class IncludeTool

  • All Implemented Interfaces:
    java.io.Serializable
    @DefaultKey("include")
@InvalidScope("application")
public class IncludeTool
extends org.apache.velocity.tools.generic.SafeConfig
implements java.io.Serializable
    Allows for transparent content negotiation in a manner mimicking Apache httpd's MultiViews.

    Reads the default language out of the ViewToolContext as org.apache.velocity.tools.view.i18n.defaultLanguage. See find(String, String), find(String, Locale) and exists(String) for usage.

    This is the successor to the MultiViewsTool in VelocityTools 1.x. Please note that it does NOT do the actual #include or #parse for you, but is merely to aid in include content negotiation.

    Since:
    VelocityTools 2.0
    Version:
    $Id$
    Author:
    Daniel Rall, Nathan Bubna
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.lang.String DEFAULT_LANGUAGE_KEY
      The key used to search initialization, context, and JVM parameters for the default language to use.
      protected java.lang.String defaultLanguage
      The two character abbreviation for the request's default language.
      protected org.apache.velocity.app.VelocityEngine engine  

      • Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

        LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

    • Constructor Summary

      Constructors 
      Constructor Description
      IncludeTool()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void configure​(org.apache.velocity.tools.generic.ValueParser params)
      Extracts the default language from the specified ViewContext, looking first at the Velocity context, then the servlet context, then lastly at the JVM default.
      protected void configure​(ViewToolContext ctx)  
      boolean exists​(java.lang.String name)
      Checks to see whether a #parse-able template or #include-able resource exists under the specified name/path.
      boolean exists​(java.lang.String name, java.lang.String language)
      Checks to see whether a localized version of the named template exists for the specified language.
      java.lang.String find​(java.lang.String name)
      Calls find(String, String) using the default language.
      java.lang.String find​(java.lang.String name, java.lang.String language)
      Finds the a localized version of the requested Velocity resource (such as a file or template) which is most appropriate for the locale of the current request.
      java.lang.String find​(java.lang.String name, java.util.Locale locale)
      Calls find(String, String) using the language extracted from locale.

      • Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

        configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DEFAULT_LANGUAGE_KEY

        protected static final java.lang.String DEFAULT_LANGUAGE_KEY
        The key used to search initialization, context, and JVM parameters for the default language to use.
        See Also:
        Constant Field Values

      • defaultLanguage

        protected java.lang.String defaultLanguage
        The two character abbreviation for the request's default language.

      • engine

        protected org.apache.velocity.app.VelocityEngine engine

    • Constructor Detail

      • IncludeTool

        public IncludeTool()

    • Method Detail

      • configure

        protected void configure​(org.apache.velocity.tools.generic.ValueParser params)
        Extracts the default language from the specified ViewContext, looking first at the Velocity context, then the servlet context, then lastly at the JVM default. This "narrow scope to wide scope" pattern makes it easy to setup language overrides at different levels within your application.
        Overrides:
        configure in class org.apache.velocity.tools.generic.SafeConfig
        Parameters:
        params - the Map of configuration parameters
        Throws:
        java.lang.IllegalArgumentException - if the param is not a ViewContext

      • find

        public java.lang.String find​(java.lang.String name,
                             java.util.Locale locale)
        Calls find(String, String) using the language extracted from locale.
        Parameters:
        name - resource filename
        locale - locale
        Returns:
        locallized resource filename
        See Also:
        find(String, String)

      • find

        public java.lang.String find​(java.lang.String name)
        Calls find(String, String) using the default language.
        Parameters:
        name - resource filename
        Returns:
        locallized resource filename
        See Also:
        find(String, String)

      • find

        public java.lang.String find​(java.lang.String name,
                             java.lang.String language)

        Finds the a localized version of the requested Velocity resource (such as a file or template) which is most appropriate for the locale of the current request. Use in conjuction with Apache httpd's MultiViews, or by itself.

        Usage from a template would be something like the following:

        
 #parse( $include.find('header.vm', 'en') )
 #include( $include.find('my_page.html', 'en') )
 #parse( $include.find('footer.vm', 'en') )

        You might also wrap this method using another pull/view tool which does internationalization/localization/content negation for a single point of access.

        Parameters:
        name - The unlocalized name of the file to find.
        language - The language to find localized context for.
        Returns:
        The localized file name, or name if it is not localizable.

      • exists

        public boolean exists​(java.lang.String name)

        Checks to see whether a #parse-able template or #include-able resource exists under the specified name/path.

        Usage from a template would be something like the following:

         #if( $include.exists('header.vm') )
   #parse( 'header.vm' )
 #end
        Parameters:
        name - resource filename
        Returns:
        whether resource exists
        See Also:
        VelocityEngine.resourceExists(java.lang.String)

      • exists

        public boolean exists​(java.lang.String name,
                      java.lang.String language)
        Checks to see whether a localized version of the named template exists for the specified language.
        Parameters:
        name - resource filename
        language - asked language
        Returns:
        whether resource exists
        See Also:
        exists(String)