org.apache.velocity.tools.view
Class LinkTool

java.lang.Object
  extended by org.apache.velocity.tools.view.LinkTool
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
LinkTool, SecureLinkTool, StrutsLinkTool

@DefaultKey(value="link")
@ValidScope(value="request")
public class LinkTool
extends java.lang.Object
implements java.lang.Cloneable

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

This VelocityView version of LinkTool is not currently a subclass of the newer, GenericTools' version. This is likely, however, to happen in the future. To best future proof your use of this tool against deprecations, try not to rely upon differences between the two versions, except of course where this tool provides additional servlet-related functions.

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.relative('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"
              selfAbsolute="true" selfIncludeParameters="true"/>
   </toolbox>
 </tools>
 

This tool may only be used in the request scope.

Since:
VelocityTools 2.0
Version:
$Id: LinkTool.java 663715 2008-06-05 19:36:05Z nbubna $
Author:
Gabe Sidler, Nathan Bubna, Chris Schultz

Nested Class Summary
protected  class LinkTool.QueryPair
          Internal util class to handle representation and encoding of key/value pairs in the query string
 
Field Summary
private  java.lang.String anchor
          The anchor set for this link.
protected  javax.servlet.ServletContext application
          A reference to the ServletContext
private  boolean autoIgnoreParams
          The autoIgnoreParameters status
static java.lang.String HTML_QUERY_DELIMITER
          Standard HTML delimiter for query data ('&')
protected  org.apache.velocity.runtime.log.Log LOG
          A reference to the Velocity runtime's Log.
private  java.util.HashSet<java.lang.String> parametersToIgnore
          List of parameters that should be ignored when the current request's parameters are copied.
private  java.util.ArrayList queryData
          A list of query string parameters.
private  java.lang.String queryDataDelim
          The current delimiter for query data
protected  javax.servlet.http.HttpServletRequest request
          A reference to the HttpServletRequest.
protected  javax.servlet.http.HttpServletResponse response
          A reference to the HttpServletResponse.
private  boolean selfAbsolute
          The selfAbsolute status
private  boolean selfParams
          The selfIncludeParameters status
private  java.lang.String uri
          The URI reference set for this link.
static java.lang.String XHTML_QUERY_DELIMITER
          XHTML delimiter for query data ('&amp;')
 
Constructor Summary
LinkTool()
          Default constructor.
 
Method Summary
 LinkTool absolute(java.lang.String uri)
          Convenience method equivalent to setAbsolute(java.lang.String).
 LinkTool addAllParameters()
          Adds all of the current request's parameters to this link's "query data".
 LinkTool addIgnore(java.lang.String parameterName)
          Instructs this LinkTool to ignore the specified parameter when copying the current request's parameters.
 LinkTool addQueryData(java.util.Map parameters)
          Adds multiple key=value pairs to the query data.
 LinkTool addQueryData(java.lang.String key, java.lang.Object value)
          Adds a key=value pair to the query data.
 LinkTool anchor(java.lang.String anchor)
          Convenience method equivalent to setAnchor(java.lang.String).
protected  LinkTool copyWith(LinkTool.QueryPair pair)
          For internal use.
protected  LinkTool copyWith(java.util.Map<java.lang.Object,java.lang.Object> newQueryData)
          For internal use.
protected  LinkTool copyWith(java.lang.String uri)
          For internal use.
protected  LinkTool copyWithAnchor(java.lang.String anchor)
          For internal use.
protected  LinkTool copyWithIgnore(java.lang.String parameterName)
          For internal use.
protected  LinkTool duplicate()
          This is just to avoid duplicating this code for both copyWith() methods
 java.lang.String encodeURL(java.lang.String url)
          Delegates encoding of the specified url to URLEncoder.encode(java.lang.String) using the character encoding for the current HttpServletResponse.
 java.lang.String getAnchor()
          Returns the anchor (internal document reference) set for this link.
 java.lang.String getBaseRef()
          Returns the full URI of this template without any query data.
 java.lang.String getContextPath()
          Returns the context path that addresses this web application, e.g.
 java.lang.String getContextURL()
          Returns the URI that addresses this web application.
 java.lang.String getParams()
          Convenience method equivalent to getQueryData().
 java.lang.String getQueryData()
          Returns this link's query data as a url-encoded string e.g.
 java.lang.String getRequestPath()
          Retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher.
 LinkTool getSelf()
          This method returns a new "self-referencing" LinkTool for the current request.
 java.lang.String getUri()
          Convenience method equivalent to getURI() to enable all lowercase $link.uri syntax.
 java.lang.String getURI()
          Returns the current URI of this link as set by the setURI(String), setAbsolute(String) or setRelative(String) methods.
 LinkTool ignore(java.lang.String paramName)
          Convenience method equivalent to addIgnore(String parameterName).
 LinkTool param(java.lang.Object key, java.lang.Object value)
          Convenience method equivalent to addQueryData(java.lang.String, java.lang.Object).
 LinkTool params(java.util.Map parameters)
          Convenience method equivalent to addQueryData(Map parameters).
 LinkTool relative(java.lang.String uri)
          Convenience method equivalent to setRelative(java.lang.String).
 LinkTool selfParams()
          Convenience method equivalent to addAllParameters().
 LinkTool setAbsolute(java.lang.String uri)
          Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference.
 LinkTool setAnchor(java.lang.String anchor)
          Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink.
 void setAutoIgnoreParameters(boolean autoIgnore)
          Controls whether or not the addQueryData(String,Object) and addQueryData(Map) methods will automatically add the specified parameter(s) to the ignore list for addAllParameters()
 void setLog(org.apache.velocity.runtime.log.Log log)
           
 LinkTool setRelative(java.lang.String uri)
          Returns a copy of the link with the specified context-relative URI reference converted to a server-relative URI reference.
 void setRequest(javax.servlet.http.HttpServletRequest request)
          Sets the current HttpServletRequest.
 void setResponse(javax.servlet.http.HttpServletResponse response)
          Sets the current HttpServletResponse.
 void setSelfAbsolute(boolean selfAbsolute)
          Controls whether or not the getSelf() method will return a duplicate with a URI in absolute or relative form.
 void setSelfIncludeParameters(boolean selfParams)
          Controls whether or not the getSelf() method will return a duplicate that includes current request parameters.
 void setServletContext(javax.servlet.ServletContext application)
           
 LinkTool setURI(java.lang.String uri)
          Returns a copy of the link with the given URI reference set.
 void setXHTML(boolean useXhtml)
          Controls the delimiter used for separating query data pairs.
 java.lang.String toString()
          Returns the full URI reference that's been built with this tool, including the query string and anchor, e.g.
 LinkTool uri(java.lang.String uri)
          Convenience method equivalent to setURI(java.lang.String).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

HTML_QUERY_DELIMITER

public static final java.lang.String HTML_QUERY_DELIMITER
Standard HTML delimiter for query data ('&')

See Also:
Constant Field Values

XHTML_QUERY_DELIMITER

public static final java.lang.String XHTML_QUERY_DELIMITER
XHTML delimiter for query data ('&amp;')

See Also:
Constant Field Values

application

protected javax.servlet.ServletContext application
A reference to the ServletContext


request

protected javax.servlet.http.HttpServletRequest request
A reference to the HttpServletRequest.


response

protected javax.servlet.http.HttpServletResponse response
A reference to the HttpServletResponse.


LOG

protected org.apache.velocity.runtime.log.Log LOG
A reference to the Velocity runtime's Log.


uri

private java.lang.String uri
The URI reference set for this link.


anchor

private java.lang.String anchor
The anchor set for this link.


queryData

private java.util.ArrayList queryData
A list of query string parameters.


queryDataDelim

private java.lang.String queryDataDelim
The current delimiter for query data


selfAbsolute

private boolean selfAbsolute
The selfAbsolute status


selfParams

private boolean selfParams
The selfIncludeParameters status


autoIgnoreParams

private boolean autoIgnoreParams
The autoIgnoreParameters status


parametersToIgnore

private java.util.HashSet<java.lang.String> parametersToIgnore
List of parameters that should be ignored when the current request's parameters are copied.

See Also:
addIgnore(String), addAllParameters()
Constructor Detail

LinkTool

public LinkTool()
Default constructor. Tool must be initialized before use.

Method Detail

setRequest

public void setRequest(javax.servlet.http.HttpServletRequest request)
Sets the current HttpServletRequest. This is required for this tool to operate and will throw a NullPointerException if this is not set or is set to null.


setResponse

public void setResponse(javax.servlet.http.HttpServletResponse response)
Sets the current HttpServletResponse. This is required for this tool to operate and will throw a NullPointerException if this is not set or is set to null.


setServletContext

public void setServletContext(javax.servlet.ServletContext application)

setLog

public void setLog(org.apache.velocity.runtime.log.Log log)

setXHTML

public void setXHTML(boolean useXhtml)

Controls the delimiter used for separating query data pairs. By default, the standard '&' character is used.

This is not exposed to templates as this decision is best not made at that level.

Subclasses may easily override the init() method to set this appropriately and then call super.init()

Parameters:
useXhtml - if true, the XHTML query data delimiter ('&amp;') will be used. if false, then '&' will be used.
See Also:
Using Ampersands in Attribute Values (and Elsewhere)

setSelfAbsolute

public void setSelfAbsolute(boolean selfAbsolute)

Controls whether or not the getSelf() method will return a duplicate with a URI in absolute or relative form.

Parameters:
selfAbsolute - if true, the getSelf() method will return a duplicate of this tool with an absolute self-referencing URI; if false, a duplicate with a relative self-referencing URI will be returned
Since:
VelocityTools 1.3
See Also:
getSelf()

setSelfIncludeParameters

public void setSelfIncludeParameters(boolean selfParams)

Controls whether or not the getSelf() method will return a duplicate that includes current request parameters.

Parameters:
selfParams - if true, the getSelf() method will return a duplicate of this tool that includes current request parameters
Since:
VelocityTools 1.3
See Also:
getSelf()

setAutoIgnoreParameters

public void setAutoIgnoreParameters(boolean autoIgnore)

Controls whether or not the addQueryData(String,Object) and addQueryData(Map) methods will automatically add the specified parameter(s) to the ignore list for addAllParameters()

The default for this setting is true.

Parameters:
autoIgnore - if true, the addQueryData(String,Object) and addQueryData(Map) methods will automatically add the specified parameter(s) to the ignore list for addAllParameters(); otherwise, addIgnore(String) must be called explicitly for each parameter to ignore.

Since:
VelocityTools 1.4
See Also:
addIgnore(String), addAllParameters()

copyWith

protected LinkTool copyWith(LinkTool.QueryPair pair)
For internal use. Copies 'that' LinkTool into this one and adds the new query data.

Parameters:
pair - the query parameter to add

copyWith

protected LinkTool copyWith(java.util.Map<java.lang.Object,java.lang.Object> newQueryData)
For internal use. Copies 'that' LinkTool into this one and adds the new query data.

Parameters:
newQueryData - the query parameters to add
Since:
VelocityTools 1.3

copyWith

protected LinkTool copyWith(java.lang.String uri)
For internal use. Copies 'that' LinkTool into this one and sets the new URI.

Parameters:
uri - uri string

copyWithAnchor

protected LinkTool copyWithAnchor(java.lang.String anchor)
For internal use. Copies 'that' LinkTool into this one and sets the new anchor for the link.

Parameters:
anchor - URI string

copyWithIgnore

protected LinkTool copyWithIgnore(java.lang.String parameterName)
For internal use. Copies this LinkTool and adds the specified parameter name to the ignore set in the copy.

Parameters:
parameterName - The name of the parameter to ignore when copying all parameters from the current request.
Returns:
A new LinkTool with the specified parameterName added to the ignore set.
See Also:
addAllParameters(), addIgnore(java.lang.String)

duplicate

protected LinkTool duplicate()
This is just to avoid duplicating this code for both copyWith() methods


setAnchor

public LinkTool setAnchor(java.lang.String anchor)

Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink.

Example:
<a href='$link.setAnchor("foo")'>Foo</a>
produces something like
<a href="#foo">Foo</a>

Parameters:
anchor - an internal document reference
Returns:
a new instance of LinkTool with the set anchor

anchor

public LinkTool anchor(java.lang.String anchor)
Convenience method equivalent to setAnchor(java.lang.String).

Since:
VelocityTools 1.3

getAnchor

public java.lang.String getAnchor()
Returns the anchor (internal document reference) set for this link.


setRelative

public LinkTool setRelative(java.lang.String uri)

Returns a copy of the link with the specified context-relative URI reference converted to a server-relative URI reference. This method will overwrite any previous URI reference settings but will copy the query string.

Example:
<a href='$link.setRelative("/templates/login/index.vm")'>Login Page</a>
produces something like
<a href="/myapp/templates/login/index.vm">Login Page</a>

Parameters:
uri - A context-relative URI reference. A context-relative URI is a URI that is relative to the root of this web application.
Returns:
a new instance of LinkTool with the specified URI

relative

public LinkTool relative(java.lang.String uri)
Convenience method equivalent to setRelative(java.lang.String).

Since:
VelocityTools 1.3

setAbsolute

public LinkTool setAbsolute(java.lang.String uri)

Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference. This method will overwrite any previous URI reference settings but will copy the query string.

Example:
<a href='$link.setAbsolute("/templates/login/index.vm")'>Login Page</a>
produces something like
<a href="http://myserver.net/myapp/templates/login/index.vm">Login Page</a>
and
<a href='$link.setAbsolute("http://theirserver.com/index.jsp")'>Their, Inc.</a>
produces something like
<a href="http://theirserver.net/index.jsp">Their, Inc.</a>

Parameters:
uri - A context-relative URI reference or absolute URL.
Returns:
a new instance of LinkTool with the specified URI
Since:
VelocityTools 1.3

absolute

public LinkTool absolute(java.lang.String uri)
Convenience method equivalent to setAbsolute(java.lang.String).

Since:
VelocityTools 1.3

setURI

public LinkTool setURI(java.lang.String uri)

Returns a copy of the link with the given URI reference set. No conversions are applied to the given URI reference. The URI reference can be absolute, server-relative, relative and may contain query parameters. This method will overwrite any previous URI reference settings but will copy the query string.

Parameters:
uri - URI reference to set
Returns:
a new instance of LinkTool

uri

public LinkTool uri(java.lang.String uri)
Convenience method equivalent to setURI(java.lang.String).

Since:
VelocityTools 1.3

getURI

public java.lang.String getURI()

Returns the current URI of this link as set by the setURI(String), setAbsolute(String) or setRelative(String) methods. Any conversions have been applied. The returned URI reference does not include query data that was added with method addQueryData().


getUri

public java.lang.String getUri()
Convenience method equivalent to getURI() to enable all lowercase $link.uri syntax.

Since:
VelocityTools 1.3

addQueryData

public LinkTool addQueryData(java.lang.String key,
                             java.lang.Object value)

Adds a key=value pair to the query data. This returns a new LinkTool containing both a copy of this LinkTool's query data and the new data. Query data is URL encoded before it is appended.

Parameters:
key - key of new query parameter
value - value of new query parameter
Returns:
a new instance of LinkTool

addQueryData

public LinkTool addQueryData(java.util.Map parameters)

Adds multiple key=value pairs to the query data. This returns a new LinkTool containing both a copy of this LinkTool's query data and the new data. Query data is URL encoded before it is appended.

Parameters:
parameters - map of new query data keys to values
Returns:
a new instance of LinkTool
Since:
VelocityTools 1.3

param

public LinkTool param(java.lang.Object key,
                      java.lang.Object value)
Convenience method equivalent to addQueryData(java.lang.String, java.lang.Object).

Since:
VelocityTools 1.3

params

public LinkTool params(java.util.Map parameters)
Convenience method equivalent to addQueryData(Map parameters).

Since:
VelocityTools 1.3

getQueryData

public java.lang.String getQueryData()

Returns this link's query data as a url-encoded string e.g. key=value&foo=this+is+encoded.


getParams

public java.lang.String getParams()
Convenience method equivalent to getQueryData().

Since:
VelocityTools 1.3

ignore

public LinkTool ignore(java.lang.String paramName)
Convenience method equivalent to addIgnore(String parameterName).

Since:
VelocityTools 2.0

addIgnore

public LinkTool addIgnore(java.lang.String parameterName)
Instructs this LinkTool to ignore the specified parameter when copying the current request's parameters.

Parameters:
parameterName - The name of the parameter to ignore.
See Also:
addAllParameters()

selfParams

public LinkTool selfParams()
Convenience method equivalent to addAllParameters().

Since:
VelocityTools 2.0

addAllParameters

public LinkTool addAllParameters()
Adds all of the current request's parameters to this link's "query data". Any parameters that have been set to be ignored will be ignored.

Returns:
A LinkTool object with all of the current request's parameters added to it.
See Also:
addIgnore(String)

getContextURL

public java.lang.String getContextURL()

Returns the URI that addresses this web application. E.g. http://myserver.net/myapp. This string does not end with a "/". Note! This will not represent any URI reference or query data set for this LinkTool.


getContextPath

public java.lang.String getContextPath()

Returns the context path that addresses this web application, e.g. /myapp. This string starts with a "/" but does not end with a "/" Note! This will not represent any URI reference or query data set for this LinkTool.


getRequestPath

public java.lang.String getRequestPath()

Retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher. Note! This will not represent any URI reference or query data set for this LinkTool.

Since:
VelocityTools 1.3

getBaseRef

public java.lang.String getBaseRef()
Returns the full URI of this template without any query data. e.g. http://myserver.net/myapp/stuff/View.vm Note! The returned String will not represent any URI reference or query data set for this LinkTool. A typical application of this method is with the HTML base tag. For example: <base href="$link.baseRef">


getSelf

public LinkTool getSelf()
This method returns a new "self-referencing" LinkTool for the current request. By default, this is merely a shortcut for calling relative(String uri) using the result of getRequestPath(). However, this tool can be configured to return an absolute URI and/or to include the parameters of the current request (in addition to any others set so far).

Since:
VelocityTools 1.3
See Also:
uri(String uri), setSelfAbsolute(boolean selfAbsolute), setSelfIncludeParameters(boolean selfParams), addAllParameters()

toString

public java.lang.String toString()
Returns the full URI reference that's been built with this tool, including the query string and anchor, e.g. http://myserver.net/myapp/stuff/View.vm?id=42&type=blue#foo. Typically, it is not necessary to call this method explicitely. Velocity will call the toString() method automatically to obtain a representable version of an object.

Overrides:
toString in class java.lang.Object

encodeURL

public java.lang.String encodeURL(java.lang.String url)
Delegates encoding of the specified url to URLEncoder.encode(java.lang.String) using the character encoding for the current HttpServletResponse.

Returns:
String - the encoded url.


Copyright (c) 2003-2007 Apache Software Foundation