[OmniFaces utilities (2.1)] Get the concrete domain-relative URL (ParamHolder)

---

[OmniFaces utilities] The getBookmarkableURL() methods returns the concrete domain-relative URL to the current/given view with the given params URL-encoded in the query string and optionally include view parameters as well. This URL can ultimately be used as redirect URL, or in <form action>, or in <a href>. Starting with OmniFaces 2.1, any parameter with an empty name or value will be skipped. To skip empty view parameters as well, use <o:viewParam> instead.

This utility method exist in OmniFaces 2.0, but it was improved in OmniFaces 2.1.

In OmniFaces 2.0, you can use only Collection<ParamHolder>, while in OmniFaces 2.1, you can use Collection<? extends ParamHolder>.

---

Method - get the concrete domain-relative URL to the current view:

See also: Faces#getContext()

Method  - get the concrete domain-relative URL to the given view:

See also: Faces#getContext() | Utils#isAnyEmpty()

Usage:

For those who are familiar with OmniFaces, ParamHolder interface, and just want to see some examples of Faces#getBookmarkableURL() that uses ParamHolder, please skip the next paragraphs and follow the Examples section below. But, if you have no idea what ParamHolder is, then you don't know what to pass instead of the Collection<? extends ParamHolder> params argument. So, here it is a quick story of it provided by steps:

·         An UIComponent is aware of a converter if it implements the JSF built-in ValueHolder interface.

·         OmniFaces comes with an extension of ValueHolder, named ParamHolder. "This interface represents a (request) parameter holder which extends ValueHolder with getName() method to obtain the parameter name associated with the parameter value and changes the getLocalValue() method to return the original, unconverted value and changes the getValue() method to return the converted value."

·         So, whenever you need such a (request) parameter, you can implement OmniFaces, ParamHolder interface, or simply extend the OmniFaces, SimpleParam, which provides a simple and default implementation of it.

·         OmniFaces uses ParamHolder to boost the JSF default <f:param> to support a converter. See the OmniFaces, <o:param> component, which implements ParamHolder.

Examples:

Now, that you know what the Collection<? extends ParamHolder> represents, let's see two examples. In the first example, I'm using SimpleParam as a simple key-value pair holder (parameter name-value), no converter. After I defined two such parameters, I'll use the Faces#getBookmarkableURL() to obtain a the concrete domain-relative URL to the current view with the following characteristics:

·         the returned URL is a concrete domain-relative URL to the current view, index.xhtml

·         it will contain two request parameters provided via SimpleParam:  usernr, usertype

·         it will contain the view parameters (suppose we have two view parameters: name (whose value is evaluated to Rafael text and surname (whose value is evaluated to Nadal text))

import org.omnifaces.component.SimpleParam;

import org.omnifaces.util.Faces;

...

SimpleParam usernr = new SimpleParam("usernr", "one");

SimpleParam usertype = new SimpleParam("usertype", "master");

Collection<SimpleParam> params = new ArrayList();

params.add(usernr);

params.add(usertype);

String url = Faces.getBookmarkableURL(params, true);

The url will be something like (the important part is the query string):

/app_context-root/.../index.xhtml?usernr=one&usertype=master&name=Rafael&surname=Nadal

The above example uses the folowing SimpleParam constructor:

But, you can also use any of the following constructors (the last two are available since OmniFaces 2.2):

In the second example, let's suppose that you have been used <o:param> to pass some extra parameters into a bean. The main characteristics are:

·         the returned URL is a concrete domain-relative URL to the current view, index.xhtml

·         it will contain two request parameters provided via <o:param>:  usernr, usertype

·         the parameters values will be converted to upper case by a custom converter (this will be reflected in the obtained URL)

·         it will not contain the view parameters

So, let's suppose a form as this:

<h:form>                 

 ...

 <h:commandButton value="Login" action="#{loginBean.loginAction()}">           

  <o:param name="usernr" value="#{playerBean.un}" converter="myConverter"/> <!-- #{playerBean.un} evaluated to 'one' text-->

  <o:param name="usertype" value="#{playerBean.ut}" converter="myConverter"/> <!-- #{playerBean.ut} evaluated to 'master' text-->

 </h:commandButton>

</h:form>

Now, in LoginBean#loginAction() method we can exploit several OmniFaces utilities to obtain the two <o:param> in a concrete domain-relative URL, like this:

import org.omnifaces.component.output.Param;

import org.omnifaces.util.Components;

import org.omnifaces.util.Faces;

...

UIForm cform = Components.getCurrentForm();

Collection<Param> oparams = Components.findComponentsInChildren(cform, Param.class); // see Components#findComponentsInChildren()

String url = Faces.getBookmarkableURL(oparams, false);

The url will be something like (the important part is the query string):

/app_context-root/.../index.xhtml?usernr=ONE&usertype=MASTER

 Note If you need to obtain a concrete domain-relative URL to the given view (not the current view), just use, getBookmarkableURL(String viewId, Collection<? extends ParamHolder> params, boolean includeViewParams). The viewId must start with a "/".

We can use Faces#getBookmarkableURL() methods to programmatically obtain an URL that follows to be returned by a custom ViewHandler via getActionURL() method. Of course, you can find many other useful use cases to these methods. OmniFaces documentation specifies: redirect URL, <form action>, or in <a href>. Notice that you can use your own ParamHolder implementations/extensions also!

API 2.1 GH 2.1
API 2.0 GH 2.0