Module org.omnifaces

Package org.omnifaces.component.output

Class Url

java.lang.Object

jakarta.faces.component.UIComponent

jakarta.faces.component.UIComponentBase

org.omnifaces.component.output.OutputFamily

org.omnifaces.component.output.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 Summary

Fields

Modifier and Type	Field	Description
static final String	COMPONENT_TYPE	The component type, which is "org.omnifaces.component.output.Url".

Fields inherited from class org.omnifaces.component.output.OutputFamily

COMPONENT_FAMILY

Fields inherited from class jakarta.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY

Constructor Summary

Constructors

Constructor	Description
Url()

Method Summary

Modifier and Type	Method	Description
void	encodeEnd(FacesContext context)
String	getDomain()	Returns the domain of the URL.
boolean	getRendersChildren()	Returns false.
String	getValue()	Returns the target URL.
String	getVar()	Returns the variable name which exposes the URL into the request scope.
String	getViewId()	Returns the view ID to create URL for.
boolean	isIncludeRequestParams()	Returns whether or not the request query string parameters should be encoded into the URL.
boolean	isIncludeViewParams()	Returns whether or not the view parameters should be encoded into the URL.
void	setDomain(String domain)	Sets the domain of the URL.
void	setIncludeRequestParams(boolean includeRequestParams)	Sets whether or not the request query string parameters should be encoded into the URL.
void	setIncludeViewParams(boolean includeViewParams)	Sets whether or not the view parameters should be encoded into the URL.
void	setValue(String value)	Sets the target URL.
void	setValueExpression(String name, ValueExpression binding)	An override which checks if this isn't been invoked on var attribute.
void	setVar(String varName)	Sets the variable name which exposes the URL into the request scope.
void	setViewId(String viewId)	Sets the view ID to create URL for.

Methods inherited from class org.omnifaces.component.output.OutputFamily

getFamily

Methods inherited from class jakarta.faces.component.UIComponentBase

addClientBehavior, addFacesListener, broadcast, clearInitialState, decode, encodeAll, encodeBegin, encodeChildren, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getPassThroughAttributes, getRenderer, getRendererType, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, visitTree

Methods inherited from class jakarta.faces.component.UIComponent

getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getListenersForEventClass, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The component type, which is "org.omnifaces.component.output.Url".

See Also:

• Constant Field Values

Constructor Details

Url

public Url()

Method Details

setValueExpression

public void setValueExpression(String name,
 ValueExpression binding)

An override which checks if this isn't been invoked on var attribute. Finally it delegates to the super method.

Overrides:

setValueExpression in class UIComponent

Throws:

IllegalArgumentException - When this value expression is been set on var attribute.

getRendersChildren

public boolean getRendersChildren()

Returns false.

Overrides:

getRendersChildren in class OutputFamily

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException

Overrides:

encodeEnd in class UIComponentBase

Throws:

IOException

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 varName)

Sets the variable name which exposes the URL into the request scope.

Parameters:

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