org.omnifaces.component.input

Class HashParam

java.lang.Object

javax.faces.component.UIComponent

javax.faces.component.UIComponentBase

javax.faces.component.UIOutput

javax.faces.component.UIInput

javax.faces.component.UIViewParameter

org.omnifaces.component.input.HashParam

All Implemented Interfaces:

EventListener, EditableValueHolder, PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

public class HashParam
extends UIViewParameter

The <o:hashParam> is a component that extends the standard <f:viewParam> with support for setting hash query parameter values in bean and automatically reflecting updated model values in hash query string.

The "hash query string" is the part in URL after the # which could be formatted in the same format as a regular request query string (the part in URL after the ?). An example:

 http://example.com/page.xhtml#foo=baz&bar=kaz
 

This specific part of the URL (also called hash fragment identifier) is by default not sent to the server. This component will on page load and on every window.onhashchange event send it anyway so that the JSF model gets updated, and on every JSF ajax request update the hash query string in client side when the JSF model value has changed.

Usage

It's very similar to the <o:viewParam>.

 <f:metadata>
     <o:hashParam name="foo" value="#{bean.foo}" />
     <o:hashParam name="bar" value="#{bean.bar}" />
 </f:metadata>
 

This only requires that the JSF page has at least one UIForm component, such as <h:form> or <o:form>, otherwise the <o:hashParam> won't be able to fire the ajax request which sets the with hash query parameter values in bean. In such case an error will be printed to JS console when the project stage is Development.

You can use the render attribute to declare which components should be updated when a hash parameter value is present.

 <f:metadata>
     <o:hashParam name="foo" value="#{bean.foo}" render="fooResult" />
     <o:hashParam name="bar" value="#{bean.bar}" />
 </f:metadata>
 ...
 <h:body>
     ...
     <h:panelGroup id="fooResult">
         ...
     </h:panelGroup>
     ...
 </h:body>
 

In case you need to invoke a bean method before rendering, e.g. to preload the rendered contents based on new hash param values, then you can observe the HashChangeEvent. See the "Events" section for an usage example.

You can use the default attribute to declare a non-null value which should be interpreted as the default value. In other words, when the current model value matches the default value, then the hash parameter will be removed.

 <f:metadata>
     <o:hashParam name="foo" value="#{bean.foo}" />
     <o:hashParam name="bar" value="#{bean.bar}" default="kaz" />
 </f:metadata>
 

When #{bean.foo} is "baz" and #{bean.bar} is "kaz" or empty, then the reflected hash query string will become http://example.com/page.xhtml#foo=baz. If #{bean.bar} is any other value, then it will appear in the hash query string.

Events

When the hash query string is changed by the client side, e.g. by following a #foo=baz&bar=kaz link, or by manually manipulating the URL, then a CDI HashChangeEvent will be fired which can be observed in any CDI managed bean as below:

 public void onHashChange(@Observes HashChangeEvent event) {
     String oldHashString = event.getOldValue();
     String newHashString = event.getNewValue();
     // ...
 }
 

This is useful in case you want to preload the model for whatever is rendered by <o:hashParam rendered>.

Since:

3.2

Author:

Bauke Scholtz

See Also:

Faces.getHashParameters(), Faces.getHashParameterMap(), Faces.getHashQueryString(), HashChangeEvent

Nested Class Summary

Nested classes/interfaces inherited from class javax.faces.component.UIViewParameter

UIViewParameter.Reference

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_TYPE The component type, which is "org.omnifaces.component.input.HashParam".

Fields inherited from class javax.faces.component.UIViewParameter

COMPONENT_FAMILY

Fields inherited from class javax.faces.component.UIInput

ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE, CONVERSION_MESSAGE_ID, EMPTY_STRING_AS_NULL_PARAM_NAME, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID, VALIDATE_EMPTY_FIELDS_PARAM_NAME

Fields inherited from class javax.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY

Constructor Summary

Constructors

Constructor and Description
HashParam() The constructor instructs JSF to register all scripts during the render response phase if necessary.

Method Summary

Modifier and Type	Method and Description
String	getDefault() Returns the default value in case the actual hash parameter is null or empty.
String	getRender() Returns a space separated string of client IDs to update on ajax response.
String	getRenderedValue(FacesContext context) Convert the value to string using any converter and ensure that an empty string is returned when the component is invalid or the resulting string is null or represents the default value.
static boolean	isHashParamRequest(FacesContext context) Returns true if the current request is triggered by a hash param request.
void	processDecodes(FacesContext context) If this is invoked during a hashparam postback, then decode as if immediate=true to save lifecycle overhead.
void	processValidators(FacesContext context) This override which does effectively nothing prevents JSF from performing validation during non-hashparam postbacks.
void	setDefault(String defaultValue) Sets the default value in case the actual hash parameter is null or empty.
void	setRender(String render) Sets a space separated string of client IDs to update on ajax response.
void	updateModel(FacesContext context) This override which does effectively nothing prevents JSF from performing update during non-hashparam postbacks.

Methods inherited from class javax.faces.component.UIViewParameter

decode, encodeAll, getConvertedValue, getFamily, getName, getStringValue, getStringValueFromModel, getSubmittedValue, isImmediate, setName, setSubmittedValue

Methods inherited from class javax.faces.component.UIInput

addValidator, addValueChangeListener, clearInitialState, compareValues, getConverterMessage, getRequiredMessage, getValidator, getValidatorMessage, getValidators, getValue, getValueChangeListener, getValueChangeListeners, isEmpty, isLocalValueSet, isRequired, isValid, markInitialState, processUpdates, removeValidator, removeValueChangeListener, resetValue, restoreState, saveState, setConverterMessage, setImmediate, setLocalValueSet, setRequired, setRequiredMessage, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, validate, validateValue

Methods inherited from class javax.faces.component.UIOutput

getConverter, getLocalValue, setConverter

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class javax.faces.component.UIComponent

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.faces.component.ValueHolder

getConverter, getLocalValue, setConverter

Field Detail

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The component type, which is "org.omnifaces.component.input.HashParam".

See Also:

Constant Field Values

Constructor Detail

HashParam

public HashParam()

The constructor instructs JSF to register all scripts during the render response phase if necessary.

Method Detail

processDecodes

public void processDecodes(FacesContext context)

If this is invoked during a hashparam postback, then decode as if immediate=true to save lifecycle overhead.

Overrides:

processDecodes in class UIInput

processValidators

public void processValidators(FacesContext context)

This override which does effectively nothing prevents JSF from performing validation during non-hashparam postbacks.

Overrides:

processValidators in class UIViewParameter

updateModel

public void updateModel(FacesContext context)

This override which does effectively nothing prevents JSF from performing update during non-hashparam postbacks.

Overrides:

updateModel in class UIViewParameter

getRenderedValue

public String getRenderedValue(FacesContext context)

Convert the value to string using any converter and ensure that an empty string is returned when the component is invalid or the resulting string is null or represents the default value.

Returns:

The rendered value.

getDefault

public String getDefault()

Returns the default value in case the actual hash parameter is null or empty.

Returns:

The default value in case the actual hash parameter is null or empty.

setDefault

public void setDefault(String defaultValue)

Sets the default value in case the actual hash parameter is null or empty.

Parameters:

defaultValue - The default value in case the actual hash parameter is null or empty.

getRender

public String getRender()

Returns a space separated string of client IDs to update on ajax response.

Returns:

A space separated string of client IDs to update on ajax response.

setRender

public void setRender(String render)

Sets a space separated string of client IDs to update on ajax response.

Parameters:

render - A space separated string of client IDs to update on ajax response.

isHashParamRequest

public static boolean isHashParamRequest(FacesContext context)

Returns true if the current request is triggered by a hash param request. I.e. if it is initiated by OmniFaces.HashParam.setHashParamValues() script which runs on page load when the window.location.hash is present, and on every window.onhashchange event.

Parameters:

context - The involved faces context.

Returns:

true if the current request is triggered by a hash param request.