org.apache.velocity.tools.view
Class LinkTool

java.lang.Object
  extended by org.apache.velocity.tools.generic.SafeConfig
      extended by org.apache.velocity.tools.generic.LinkTool
          extended by 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:

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


Copyright (c) 2003-2007 Apache Software Foundation