-
Available since OmniFaces 1.4
The <o:param> is a component that extends the standard UIParameter to implement ValueHolder and thus support a Converter to convert the supplied value to string, if necessary.
You can use it the same way as <f:param>, you only need to change f: into o: to get the extra support for a Converter 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).
Also, if no value is specified, but children are present, then the encoded output of children will be returned as param value. This is useful when you want to supply Faces components or HTML as parameter of an unescaped <h:outputFormat>. For example,
<h:outputFormat value="#{bundle.paragraph}" escape="false">
<o:param><h:link outcome="contact" value="#{bundle.contact}" /></o:param>
</h:outputFormat>with this bundle
paragraph = Please {0} for more information.
contact = contact uswill result in the link being actually encoded as output format parameter value.
Using converter
We want to pass this example entity referenced by #{paramBean.exampleEntity} as request parameter:
ExampleEntity[42, The meaning of life]
f:param, check the link URL, it's merely printing the example entity's toString()
o:param with converter, the param in the link URL represents the converted value
We could of course also have used #{paramBean.exampleEntity.id} as param value, but this is not
DRY if you already have a converter for the entity and this is thus potentially maintenance-unfriendly.
Using Faces and HTML as param value
To learn about what's new in OmniFaces, check the What's new in OmniFaces 4.5.1 page.
<h3>Using converter</h3>
<p>
We want to pass this example entity referenced by <code>\#{paramBean.exampleEntity}</code> as request parameter:
<strong>#{paramBean.exampleEntity}</strong>
</p>
<p>
<h:link value="f:param, check the link URL, it's merely printing the example entity's toString()">
<f:param name="exampleEntity" value="#{paramBean.exampleEntity}" />
</h:link>
</p>
<p>
<h:link value="o:param with converter, the param in the link URL represents the converted value">
<o:param name="exampleEntity" value="#{paramBean.exampleEntity}" converter="exampleEntityConverter" />
</h:link>
</p>
<p>
We could of course also have used <code>\#{paramBean.exampleEntity.id}</code> as param value, but this is not
DRY if you already have a converter for the entity and this is thus potentially maintenance-unfriendly.
</p>
<h3>Using Faces and HTML as param value</h3>
<p>
<f:loadBundle basename="org.omnifaces.showcase.i18n.text" var="text" />
<o:outputFormat value="#{text['showcase.components.param.demo.whatsnew.link']}" var="_link">
<f:param value="#{_omniFacesVersionXYZ}" />
</o:outputFormat>
<h:outputFormat value="#{text['showcase.components.param.demo.whatsnew']}" escape="false">
<o:param><h:link outcome="#{text['showcase.whatsnew.outcome']}" value="#{_link}" /></o:param>
</h:outputFormat>
</p>package org.omnifaces.showcase.components;
import jakarta.annotation.PostConstruct;
import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Named;
import org.omnifaces.showcase.model.ExampleEntity;
@Named
@RequestScoped
public class ParamBean {
private ExampleEntity exampleEntity;
@PostConstruct
public void init() {
exampleEntity = new ExampleEntity(42L, "The meaning of life");
}
public ExampleEntity getExampleEntity() {
return exampleEntity;
}
}package org.omnifaces.showcase.model;
import java.io.Serializable;
public class ExampleEntity implements Serializable {
private static final long serialVersionUID = 1L;
private Long id;
private String value;
public ExampleEntity() {
//
}
public ExampleEntity(Long id, String value) {
this.id = id;
this.value = value;
}
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getValue() {
return value;
}
public void setValue(String value) {
this.value = value;
}
@Override
public boolean equals(Object other) {
return (other instanceof ExampleEntity) && (id != null)
? id.equals(((ExampleEntity) other).id)
: (other == this);
}
@Override
public int hashCode() {
return (id != null)
? (this.getClass().hashCode() + id.hashCode())
: super.hashCode();
}
@Override
public String toString() {
return String.format("ExampleEntity[%d, %s]", id, value);
}
}package org.omnifaces.showcase.components;
import jakarta.faces.component.UIComponent;
import jakarta.faces.context.FacesContext;
import jakarta.faces.convert.Converter;
import jakarta.faces.convert.ConverterException;
import jakarta.faces.convert.FacesConverter;
import org.omnifaces.showcase.model.ExampleEntity;
import org.omnifaces.util.Messages;
@FacesConverter("exampleEntityConverter")
public class ExampleEntityConverter implements Converter {
@Override
public String getAsString(FacesContext context, UIComponent component, Object modelValue) {
Long id = (modelValue != null) ? ((ExampleEntity) modelValue).getId() : null;
return (id != null) ? String.valueOf(id) : "";
}
@Override
public Object getAsObject(FacesContext context, UIComponent component, String submittedValue) {
if (submittedValue == null || submittedValue.isEmpty()) {
return null;
}
if (!submittedValue.matches("[0-9]+")) {
throw new ConverterException(Messages.createError("Invalid ID."));
}
Long id = Long.valueOf(submittedValue);
if (id != 42) {
throw new ConverterException(Messages.createError("Unknown ID."));
}
return new ExampleEntity(id, "The meaning of life");
}
}showcase.whatsnew.outcome = /whatsnew
showcase.components.param.demo.whatsnew = To learn about what''s new in OmniFaces, check the {0} page.
showcase.components.param.demo.whatsnew.link = What''s new in OmniFaces {0}