Module org.omnifaces
Package org.omnifaces.component.input

Class HashParam

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
jakarta.faces.component.UIOutput
jakarta.faces.component.UIInput
jakarta.faces.component.UIViewParameter
org.omnifaces.component.input.OnloadParam
org.omnifaces.component.input.HashParam
All Implemented Interfaces:
EditableValueHolder, PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
public class HashParam extends OnloadParam

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: 

 https://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 Faces model gets updated, and on every Faces ajax request update the hash query string in client side when the Faces 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>

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 https://example.com/page.xhtml#foo=baz. If #{bean.bar} is any other value, then it will appear in the hash query string.

Note that as it extends from the standard <f:viewParam>, its built-in conversion and validation functionality is also supported on this component.

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

Since:
3.2
Author:
Bauke Scholtz
See Also:

  • Field Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE
      The component type, which is "org.omnifaces.component.input.HashParam".
      See Also:

    • EVENT_VALUE

      public static final String EVENT_VALUE
      The omnifaces event value, which is "setHashParamValues".
      See Also:

  • Constructor Details

    • HashParam

      public HashParam()

  • Method Details

    • getInitScript

      protected String getInitScript(FacesContext context)
      Description copied from class: OnloadParam
      Returns script which should be executed upon initialization of a new view.
      Overrides:
      getInitScript in class OnloadParam
      Parameters:
      context - The involved faces context.
      Returns:
      Script which should be executed upon initialization of a new view.

    • getUpdateScript

      protected String getUpdateScript(FacesContext context)
      Description copied from class: OnloadParam
      Returns script which should be exeucted upon ajax update of the current view.
      Overrides:
      getUpdateScript in class OnloadParam
      Parameters:
      context - The involved faces context.
      Returns:
      Script which should be exeucted upon ajax update of the current view.

    • getEventValue

      protected String getEventValue(FacesContext context)
      Description copied from class: OnloadParam
      Returns the value of the OmniFaces.OMNIFACES_EVENT_PARAM_NAME associated with the current component.
      Specified by:
      getEventValue in class OnloadParam
      Parameters:
      context - The involved faces context.
      Returns:
      The value of the OmniFaces.OMNIFACES_EVENT_PARAM_NAME associated with the current component.

    • decodeAll

      protected void decodeAll(FacesContext context)
      Description copied from class: OnloadParam
      Decode all relevant OnloadParam components at once.
      Specified by:
      decodeAll in class OnloadParam
      Parameters:
      context - The involved faces context.

    • 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.
      Parameters:
      context - The involved faces context.
      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.

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