Module org.omnifaces
Package org.omnifaces.component.output

Class Url

  • All Implemented Interfaces:
    PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
    public class Url
extends OutputFamily

    The <o:url> is a component which renders the given target URL or Faces view ID as a bookmarkable URL with support for adding additional query string parameters to the URL via nested <f:param> and <o:param>, and for exposing it into the request scope by the variable name as specified by the var attribute instead of rendering it.

    This component fills the gap caused by absence of JSTL <c:url> in Facelets. This component is useful for generating URLs for usage in e.g. plain HTML <link> elements and JavaScript variables.

    Values

    You can supply the target URL via either the value attribute or the viewId attribute. When both are specified, the value attribute takes precedence and the viewId attribute is ignored. When none are specified, then the viewId will default to the current view ID. The support for value attribute was added in OmniFaces 3.0.

    Domain

    When the target URL is specified as viewId, then the domain of the target URL defaults to the current domain. It is possible to provide a full qualified domain name (FQDN) via the domain attribute which the URL is to be prefixed with. This can be useful if a canonical page shall point to a different domain or a specific subdomain.

    Valid formats and values for domain attribute are:

    • <o:url domain="https://example.com" />
    • <o:url domain="//example.com" />
    • <o:url domain="example.com" />
    • <o:url domain="/" />
    • <o:url domain="//" />

    The domain value will be validated by URL and throw an illegal argument exception when invalid. If the domain equals /, then the URL becomes domain-relative. If the domain equals or starts with //, or does not contain any scheme, then the URL becomes scheme-relative. If the value attribute is specified, then the domain attribute is ignored.

    Request and view parameters

    You can add query string parameters to the URL via nested <f:param> and <o:param>. You can optionally include all GET request query string parameters or only Faces view parameters in the resulting URL via includeRequestParams="true" or includeViewParams="true". The includeViewParams is ignored when includeRequestParams="true". The <f|o:param> will override any included request or view parameters on the same name. To conditionally add or override, use the disabled attribute of <f|o:param>.

    Usage

    Some examples: 

     <p>Full URL of current page is: <o:url /></p>
 <p>Full URL of another page is: <o:url viewId="/another.xhtml" /></p>
 <p>Full URL of current page including view params is: <o:url includeViewParams="true" /></p>
 <p>Full URL of current page including query string is: <o:url includeRequestParams="true" /></p>
 <p>Domain-relative URL of current page is: <o:url domain="/" /></p>
 <p>Scheme-relative URL of current page is: <o:url domain="//" /></p>
 <p>Scheme-relative URL of current page on a different domain is: <o:url domain="sub.example.com" /></p>
 <p>Full URL of current page on a different domain is: <o:url domain="https://sub.example.com" /></p>
 <p>External URL with encoded parameters appended: <o:url value="https://google.com/search">
     <o:param name="q" value="#{bean.search}" />
 </url></p>
 
     <o:url var="_linkCanonical">
     <o:param name="foo" value="#{bean.foo}" />
 </o:url>
 <link rel="canonical" href="#{_linkCanonical}" />
 
     <o:url var="_linkNext" includeViewParams="true">
     <f:param name="page" value="#{bean.pageIndex + 1}" />
 </o:url>
 <link rel="next" href="#{_linkNext}" />
    Since:
    2.4
    Author:
    Bauke Scholtz
    See Also:
    OutputFamily

    • Field Detail

      • COMPONENT_TYPE

        public static final String COMPONENT_TYPE
        The component type, which is "org.omnifaces.component.output.Url".
        See Also:
        Constant Field Values

    • Constructor Detail

      • Url

        public Url()

    • Method Detail

      • getVar

        public String getVar()
        Returns the variable name which exposes the URL into the request scope.
        Returns:
        The variable name which exposes the URL into the request scope.

      • setVar

        public void setVar​(String var)
        Sets the variable name which exposes the URL into the request scope.
        Parameters:
        var - The variable name which exposes the URL into the request scope.

      • getValue

        public String getValue()
        Returns the target URL.
        Returns:
        The target URL.

      • setValue

        public void setValue​(String value)
        Sets the target URL.
        Parameters:
        value - The target URL.

      • getViewId

        public String getViewId()
        Returns the view ID to create URL for. Defaults to current view ID.
        Returns:
        The view ID to create URL for.

      • setViewId

        public void setViewId​(String viewId)
        Sets the view ID to create URL for.
        Parameters:
        viewId - The view ID to create URL for.

      • getDomain

        public String getDomain()
        Returns the domain of the URL. Defaults to current domain.
        Returns:
        The domain of the URL.

      • setDomain

        public void setDomain​(String domain)
        Sets the domain of the URL.
        Parameters:
        domain - The domain of the URL.

      • isIncludeViewParams

        public boolean isIncludeViewParams()
        Returns whether or not the view parameters should be encoded into the URL. Defaults to false. This setting is ignored when includeRequestParams is set to true.
        Returns:
        Whether or not the view parameters should be encoded into the URL.

      • setIncludeViewParams

        public void setIncludeViewParams​(boolean includeViewParams)
        Sets whether or not the view parameters should be encoded into the URL. This setting is ignored when includeRequestParams is set to true.
        Parameters:
        includeViewParams - Whether or not the view parameters should be encoded into the URL.

      • isIncludeRequestParams

        public boolean isIncludeRequestParams()
        Returns whether or not the request query string parameters should be encoded into the URL. Defaults to false. When set to true, then this will override the includeViewParams setting.
        Returns:
        Whether or not the request query string parameters should be encoded into the URL.

      • setIncludeRequestParams

        public void setIncludeRequestParams​(boolean includeRequestParams)
        Sets whether or not the request query string parameters should be encoded into the URL. When set to true, then this will override the includeViewParams setting.
        Parameters:
        includeRequestParams - Whether or not the request query string parameters should be encoded into the URL.