Package org.apache.velocity.tools.view

Class LinkTool

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class LinkTool
extends org.apache.velocity.tools.generic.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$
    Author:
    Gabe Sidler, Nathan Bubna, Chris Schultz
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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, 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, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

    • Constructor Summary

      Constructors 
      Constructor Description
      LinkTool()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      LinkTool addMissingRequestParams​(java.lang.Object... 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.
      LinkTool addRequestParams​(java.lang.Object... 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.Object... 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​(org.apache.velocity.tools.generic.ValueParser props)  
      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, 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, getLog, initLogger, 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​(org.apache.velocity.tools.generic.ValueParser props)
        Overrides:
        configure in class org.apache.velocity.tools.generic.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.

        Parameters:
        includeRequestParams - whether or not to keep current request params

      • addRequestParams

        public LinkTool addRequestParams​(java.lang.Object... 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.
        Parameters:
        butOnlyThese - curent request parameters to keep
        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.Object... 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.
        Parameters:
        ignoreThese - curent request parameters to ignore
        Returns:
        A LinkTool object with all of the current request's parameters added to it, except those specified.

      • addMissingRequestParams

        public LinkTool addMissingRequestParams​(java.lang.Object... 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.
        Parameters:
        ignoreThese - curent request parameters to ignore
        Returns:
        A LinkTool object with all of the current request's parameters added to it, except those specified or those that already have values.

      • 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 org.apache.velocity.tools.generic.LinkTool
        Returns:
        context path
        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).

        Returns:
        request path

      • 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.

        Returns:
        context URL

      • 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 org.apache.velocity.tools.generic.LinkTool
        Returns:
        final string representation