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.
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.
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>
.
Faces.getHashParameters()
,
Faces.getHashParameterMap()
,
Faces.getHashQueryString()
,
HashChangeEvent
UIViewParameter.Reference
Modifier and Type | Field and Description |
---|---|
static String |
COMPONENT_TYPE
The component type, which is "org.omnifaces.component.input.HashParam".
|
COMPONENT_FAMILY
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
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 and Description |
---|
HashParam()
The constructor instructs JSF to register all scripts during the render response phase if necessary.
|
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.
|
decode, encodeAll, getConvertedValue, getFamily, getName, getStringValue, getStringValueFromModel, getSubmittedValue, isImmediate, setName, setSubmittedValue
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
getConverter, getLocalValue, setConverter
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
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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getConverter, getLocalValue, setConverter
public static final String COMPONENT_TYPE
public HashParam()
public void processDecodes(FacesContext context)
processDecodes
in class UIInput
public void processValidators(FacesContext context)
processValidators
in class UIViewParameter
public void updateModel(FacesContext context)
updateModel
in class UIViewParameter
public String getRenderedValue(FacesContext context)
public String getDefault()
null
or empty.null
or empty.public void setDefault(String defaultValue)
null
or empty.defaultValue
- The default value in case the actual hash parameter is null
or empty.public String getRender()
public void setRender(String render)
render
- A space separated string of client IDs to update on ajax response.public static boolean isHashParamRequest(FacesContext context)
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.context
- The involved faces context.true
if the current request is triggered by a hash param request.Copyright © 2012–2019 OmniFaces. All rights reserved.