Module org.omnifaces
Package org.omnifaces.component.output

Class PathParam<T>

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
jakarta.faces.component.UIParameter
org.omnifaces.component.output.Param<T>
org.omnifaces.component.output.PathParam<T>
Type Parameters:
T - The type of the value.
All Implemented Interfaces:
PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener, ParamHolder<T>
public class PathParam<T> extends Param<T>
The <o:pathParam> is a component that extends the OmniFaces Param to support the MultiViews and dynamic route segment features of FacesViews. It is done by rendering the supplied parameters of such components as <h:link> and <h:button> among others as path parameters and not as query parameters as otherwise will be produced by <o:param> and <f:param> tags.

The component has built-in support for a Converter to convert the supplied value to string by usual means via the converter attribute of the tag, or the nested <f:converter> tag, or just automatically if a converter is already registered for the target class via @FacesConverter(forClass).

This component doesn't support returning encoded output of its children as parameter value in case no value is present. This feature is provided by Param component instead.

The name attribute is optional and selects between the two features. Without one the value is appended as the next positional path parameter of a MultiViews view, which requires MultiViews to be enabled. With one the value instead interpolates into the dynamic route segment of that name, which requires no MultiViews at all, only a view in a directory whose name is wrapped in square brackets. Both are described below and can be combined on one view.

MultiViews path parameters

This component is used to create bookmarkable URLs via standard outcome target components that take into account <o:pathParam> tags nested in the components. The unnamed path parameters will be rendered in the order they were declared for a view id that is defined as a multi view and if the view was not defined as a multi view then they won't be rendered at all. Additionally, declaring unnamed path parameters for a non-multi view will be logged as a warning and a faces warning message will be added for any stage different from Production.

In the following example the link to the multi view page will be rendered with two path parameters: 

 <h:link value="Link" outcome="multiview-supported-path">
     <o:pathParam value="first" />
     <o:pathParam value="second" />
 </h:link>
The code above will be rendered as: <a id="..." name="..." href="/context-path/multiview-supported-path/first/second">Link</a>. The path parameters will be available via @Inject @Param(pathIndex=0) private String first; and @Inject @Param(pathIndex=1) private String second; the usual way.

Dynamic route segments

When the name attribute is specified, the value interpolates into the dynamic route segment of that name of the target view, as declared by a directory whose name is wrapped in square brackets. In the following example the link to /organizations/[id]/members.xhtml is rendered with the segment id substituted: 

 <h:link value="Link" outcome="/organizations/[id]/members">
     <o:pathParam name="id" value="123" />
 </h:link>
The code above will be rendered as: <a id="..." name="..." href="/context-path/organizations/123/members">Link</a>. The segment value will be available via @Inject @Param(pathName="id") private String id; the usual way.

Every dynamic route segment of the target view must be supplied, as a rendered URL may never contain the square brackets themselves. An unsupplied segment throws an IllegalArgumentException. The values of the current request are deliberately not inherited, so that a link means the same thing regardless of the page it is rendered on.

Since:
3.6
Author:
Sergey Kuntsel
See Also: