org.apache.velocity.tools.view

## Class IncludeTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.view.IncludeTool

All Implemented Interfaces:
  Serializable

    @DefaultKey(value="include")
     @InvalidScope(value="application")
    public class IncludeTool
    extends SafeConfig
    implements 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
`protected static String` `DEFAULT_LANGUAGE_KEY` The key used to search initialization, context, and JVM parameters for the default language to use.
`protected 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 and Description
`IncludeTool()`

### Method Summary

All Methods Instance Methods Concrete Methods
`protected void` `configure(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(String name)` Checks to see whether a #parse-able template or #include-able resource exists under the specified name/path.
`boolean` `exists(String name, String language)` Checks to see whether a localized version of the named template exists for the specified language.
`String` `find(String name)` Calls `find(String, String)` using the default language.
`String` `find(String name, Locale locale)` Calls `find(String, String)` using the language extracted from `locale`.
`String` `find(String name, 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.

### 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 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 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(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 `SafeConfig`
Parameters:
  `params` - the `Map` of configuration parameters
Throws:
  `IllegalArgumentException` - if the param is not a ViewContext

#### configure

    protected void configure(ViewToolContext ctx)

#### find

    public String find(String name,
                       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 String find(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 String find(String name,
                       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(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(String name,
                          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)`