Class IncludeTool

java.lang.Object

org.apache.velocity.tools.generic.SafeConfig

org.apache.velocity.tools.view.IncludeTool

All Implemented Interfaces:

Serializable

@DefaultKey("include")
@InvalidScope("application")
public class IncludeTool
extends org.apache.velocity.tools.generic.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

Modifier and Type	Field	Description
protected static final 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	Description
IncludeTool()

Method Summary

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(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, 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.
String	find(String name, 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 Object

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

Field Details

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 Details

IncludeTool

public IncludeTool()

Method Details

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:

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(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)