org.apache.velocity.tools.view
Class LinkTool

java.lang.Object
  org.apache.velocity.tools.generic.SafeConfig
      org.apache.velocity.tools.generic.LinkTool
          org.apache.velocity.tools.view.LinkTool

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

LinkTool, SecureLinkTool, StrutsLinkTool

public class LinkTool
extends LinkTool

The LinkTool provides many methods to work with URIs and can help you:

• construct full URIs (absolute or relative)
• encode session ID into a URI
• retrieve server, port and path info for the current request
• reconstruct or alter the current request URI
• and more..

The LinkTool is somewhat special in that nearly all public methods return a new instance of LinkTool. This facilitates greatly the repeated use of the LinkTool in Velocity and leads to an elegant syntax.

 Template example(s):
   #set( $base = $link.path('MyPage.vm').anchor('view') )
   <a href="$base.param('select','this')">this</a>
   <a href="$base.param('select','that')">that</a>

 Toolbox configuration:
 <tools>
   <toolbox scope="request">
     <tool class="org.apache.velocity.tools.view.LinkTool"
              forceRelative="true" includeRequestParams="true"/>
   </toolbox>
 </tools>
 

This tool may only be used in the request scope.

Since:

VelocityTools 2.0

Version:

$Id: LinkTool.java 749726 2009-03-03 20:19:15Z nbubna $

Author:

Gabe Sidler, Nathan Bubna, Chris Schultz

Field Summary

static java.lang.String	INCLUDE_REQUEST_PARAMS_KEY
protected boolean	includeRequestParams
protected javax.servlet.http.HttpServletRequest	request
protected javax.servlet.http.HttpServletResponse	response

Fields inherited from class org.apache.velocity.tools.generic.LinkTool

APPEND_PARAMS_KEY, appendParams, charset, CHARSET_KEY, DEFAULT_CHARSET, DEFAULT_SCHEME, FORCE_RELATIVE_KEY, forceRelative, fragment, FRAGMENT_KEY, host, HOST_KEY, HTML_QUERY_DELIMITER, LOG, opaque, path, PATH_KEY, port, PORT_KEY, query, QUERY_KEY, queryDelim, scheme, SCHEME_KEY, SECURE_SCHEME, self, URI_KEY, user, USER_KEY, XHTML_MODE_KEY, XHTML_QUERY_DELIMITER

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

LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

LinkTool()

Method Summary

LinkTool	addMissingRequestParams(java.lang.String... ignoreThese) Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings or already have a value set for them in the current instance.
private LinkTool	addRequestParams(boolean ignore, java.lang.String... special)
LinkTool	addRequestParams(java.lang.String... butOnlyThese) Adds the specified parameters (if they exist) from the current request to the query data of a copy of this instance.
LinkTool	addRequestParamsExcept(java.lang.String... ignoreThese) Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings.
protected void	configure(ValueParser props) Does the actual configuration.
private boolean	contains(java.lang.String[] set, java.lang.String name)
java.lang.String	getContextPath() Initially, this returns the context path that addresses this web application, e.g.
java.lang.String	getContextURL() Returns a URL that addresses the web application.
java.lang.String	getRequestPath() Initially, this retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher.
protected boolean	isPathChanged()
protected void	setFromRequest(javax.servlet.http.HttpServletRequest request)
void	setIncludeRequestParams(boolean includeRequestParams) Controls whether or not this tool starts off with all parameters from the last request automatically.
java.lang.String	toString() Overrides to use response.encodeURL to get session id into URL if sessions are used but cookies are not supported.

Methods inherited from class org.apache.velocity.tools.generic.LinkTool

absolute, absolute, anchor, append, append, appendAsArray, appendPath, appendQuery, combinePath, combineQuery, createURI, debug, debug, decode, decodeQueryPercents, directory, duplicate, duplicate, encode, equals, getAnchor, getAppendParams, getBaseRef, getCharacterEncoding, getDirectory, getFile, getHost, getParams, getPath, getPort, getQuery, getRoot, getScheme, getSelf, getUri, getUser, handleParamsBoolean, hashCode, host, insecure, isAbsolute, isOpaque, isRelative, isSecure, isXHTML, normalizeQuery, param, params, parseQuery, parseQuery, path, port, query, relative, relative, remove, removeParam, root, scheme, secure, set, setAppendParams, setCharacterEncoding, setForceRelative, setFragment, setFromURI, setHost, setParam, setParams, setPath, setPort, setQuery, setScheme, setUserInfo, setXHTML, toQuery, toQuery, toURI, uri, user

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

configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INCLUDE_REQUEST_PARAMS_KEY

public static final java.lang.String INCLUDE_REQUEST_PARAMS_KEY

See Also:

Constant Field Values

request

protected javax.servlet.http.HttpServletRequest request

response

protected javax.servlet.http.HttpServletResponse response

includeRequestParams

protected boolean includeRequestParams

Constructor Detail

LinkTool

public LinkTool()

Method Detail

configure

protected void configure(ValueParser props)

Description copied from class: SafeConfig

Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.

Overrides:

configure in class LinkTool

setFromRequest

protected void setFromRequest(javax.servlet.http.HttpServletRequest request)

setIncludeRequestParams

public void setIncludeRequestParams(boolean includeRequestParams)

Controls whether or not this tool starts off with all parameters from the last request automatically. Default is false.

addRequestParams

public LinkTool addRequestParams(java.lang.String... butOnlyThese)

Adds the specified parameters (if they exist) from the current request to the query data of a copy of this instance. If no parameters are specified, then all of the current request's parameters will be added.

Returns:

A LinkTool object with the specified parameters from the current request added to it or all the params if none specified.

addRequestParamsExcept

public LinkTool addRequestParamsExcept(java.lang.String... ignoreThese)

Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings.

Returns:

A LinkTool object with all of the current request's parameters added to it, except those specified.

addMissingRequestParams

public LinkTool addMissingRequestParams(java.lang.String... ignoreThese)

Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings or already have a value set for them in the current instance.

Returns:

A LinkTool object with all of the current request's parameters added to it, except those specified or those that already have values.

addRequestParams

private LinkTool addRequestParams(boolean ignore,
                                  java.lang.String... special)

contains

private boolean contains(java.lang.String[] set,
                         java.lang.String name)

isPathChanged

protected boolean isPathChanged()

getContextPath

public java.lang.String getContextPath()

Initially, this returns the context path that addresses this web application, e.g. /myapp. This string starts with a "/" but does not end with a "/". If the path has been changed (e.g. via a call to LinkTool.path(Object)), then this will simply be the first "directory" in the path (i.e. everything from the start up to the second backslash).

Overrides:

getContextPath in class LinkTool

See Also:

LinkTool.relative(Object)

getRequestPath

public java.lang.String getRequestPath()

Initially, this retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher. This string should always start with a "/". If the path has been changed (e.g. via a call to LinkTool.path(Object)), then this will simply be everything in the path after the getContextPath() (i.e. the second "/" in the path and everything after).

getContextURL

public java.lang.String getContextURL()

Returns a URL that addresses the web application. (e.g. http://myserver.net/myapp/. This essentially just replaces the full path with the getContextPath() and removes the anchor and query data.

toString

public java.lang.String toString()

Overrides to use response.encodeURL to get session id into URL if sessions are used but cookies are not supported.

Overrides:

toString in class LinkTool