f

Tag Library Information 
InfoValue
ID (tag prefix)f
URIjakarta.faces.core
Tag Summary 
TagDescription
actionListener

Register an ActionListener instance on the UIComponent associated with the closest parent UIComponent tag.

ajax

Register an AjaxBehavior instance on one or more UIComponents implementing the ClientBehaviorHolder interface. This tag may be nested witin a single component (enabling Ajax for a single component), or it may be "wrapped" around multiple components (enabling Ajax for many components).

The String value for ids specified for execute and render may be specified as a search expression as outlined in the JavaDocs for UIComponent.findComponent(). The implementation must resolve these ids as specified for UIComponent.findComponent(). For example, consider the following Facelets code.

  1. <h:form id="form_1">
  2.   <h:panelGrid id="panel_1" rows="2">
  3.     <!-- content irrelevant -->
  4.   </h:panelGrid>
  5. </h:form>
  6.  
  7. <h:form id="form_2">
  8.   <h:commandButton id="button">
  9.     <f:ajax render=":form1:panel_1 panel_2" />
  10.   </h:commandButton>
  11.   <h:panelGrid id="panel_2">
  12.     <!-- content irrelevant -->
  13.   </h:panelGrid>
  14. </h:form>

When the button is pressed, panel_1, in form_1 will be re-rendered, along with panel_2 in form_2.

attribute

Add an attribute to the UIComponent associated with the closest parent UIComponent tag.

attributes

Add attributes to the UIComponent associated with the closest parent UIComponent tag. For each Map.Entry in the Map<String, Object> referenced by the value attribute of this tag, take the following action. If parent.getAttributes().containsKey(entry.getKey()) returns true, take no action for this entry. Otherwise, if entry.getValue() is a ValueExpression call parent.setValueExpression(entry.getKey(), entry.getValue()). Otherwise, call parent.getAttributes.put(entry.getKey(), entry.getValue()).

convertDateTime

Register a DateTimeConverter instance on the UIComponent associated with the closest parent UIComponent tag.

convertNumber Register a NumberConverter instance on the UIComponent associated with the closest parent UIComponent tag.
converter

Register a named Converter instance on the UIComponent associated with the closest parent UIComponent tag.

event

Allow Jakarta Faces page authors to install ComponentSystemEventListener instances on a component in a page.

facet

Register a named facet on the UIComponent associated with the closest parent UIComponent tag.

When the facet contains more than one child the children will be automatically put in a container UIPanel.

importConstants

Used inside of the metadata facet of a view, this tag will import a mapping of all constant field values of the given type in the current view. Constant field values are all public static final fields of the given type. The map key represents the constant field name as String. The map value represents the actual constant field value. This works for classes, interfaces and enums.

loadBundle

Load a resource bundle localized for the Locale of the current view, and expose it as a java.util.Map in the request attributes of the current request under the key specified by the value of the "var" attribute of this tag. The Map must behave such that if a get() call is made for a key that does not exist in the Map, the literal string ???KEY??? is returned from the Map, where KEY is the key being looked up in the Map, instead of a MissingResourceException being thrown. If the ResourceBundle does not exist, a TagAttributeException must be thrown.

metadata

Declare the metadata facet for this view. This must be a child of the <f:view>. This tag must reside within the top level XHTML file for the given viewId, or in a template client, but not in a template. The implementation must insure that the direct child of the facet is a UIPanel, even if there is only one child of the facet. The implementation must set the id of the UIPanel to be the value of the UIViewRoot.METADATA_FACET_NAME symbolic constant.

The implementation must allow templating for this element according to the following pattern.

template client XHTML view, view01.xhtml

  1. <ui:composition template="template.xhtml">
  2.     <ui:define name="metadata">
  3.       <f:metadata>
  4.         <f:viewParam name="id"/>
  5.       </f:metadata>
  6.     </ui:define>
  7.     <ui:define name="content">
  8.         <h1>The big news stories of the day</h1>
  9.     </ui:define>
  10. </ui:composition>

Note line 4. The page author must ensure that the <f:metadata> element does not appear on a template or included page. It must reside on the root page that corresponds to the viewId.

The template page, template.xhtml

  1. <html xmlns="http://www.w3.org/1999/xhtml"
  2.       xmlns:ui="jakarta.faces.facelets"
  3.       xmlns:f="jakarta.faces.core"
  4.       xml:lang="en" lang="en">
  5.  
  6. <body>
  7. <f:view>
  8.    
  9.         <ui:insert name="metadata"/>
  10.    
  11.     <div id="container">
  12.         <ui:insert name="content"/>
  13.     </div>
  14. </f:view>
  15. </body>
  16. </html>

The page author is not required to use templating, but if they do, it must be done as shown above, (or with <ui:include> in a similar manner).

param

Add a child UIParameter component to the UIComponent associated with the closest parent UIComponent tag.

passThroughAttribute

Add an attribute to the passThroughAttributes Map of the UIComponent associated with the closest parent UIComponent tag.

passThroughAttributes

Add attributes to the passThroughAttributes Map of the UIComponent associated with the closest parent UIComponent tag. For each Map.Entry in the Map<String, Object> referenced by the value attribute of this tag, take the following action. Call component.getPassThroughAttributes().put(entry.getKey(), entry.getValue()).

phaseListener

Register a PhaseListener instance on the UIViewRoot in which this tag is nested.

selectItem

Add a child UISelectItem component to the UIComponent associated with the closest parent UIComponent tag.

selectItems

Add a child UISelectItems component to the UIComponent associated with the closed parent UIComponent tag.

When iterating over the select items, toString() must be called on the string rendered attribute values.

Version 2 of the specification introduces several new attributes, described below. These are: var, itemValue, itemLabel, itemDescription, itemDisabled, and itemLabelEscaped.

selectItemGroup

UISelectItemGroup is a component that may be nested inside a UISelectMany or UISelectOne component, and causes the addition of one SelectItemGroup of one or more SelectItem instances to the list of available options in the parent component. This component accepts only children of type UISelectItems or UISelectItem.

selectItemGroups

UISelectItemGroups is a component that may be nested inside a UISelectMany or UISelectOne component, and causes the addition of one or more SelectItemGroup of one or more SelectItem instances to the list of available options in the parent component. This component accepts only children of type UISelectItems or UISelectItem.

setPropertyActionListener

Register an ActionListener instance on the UIComponent associated with the closest parent UIComponent tag. This actionListener will cause the value given by the "value" attribute to be set into the ValueExpression given by the "target" attribute.

The implementation of this tag creates a special ActionListener instance and registers it on the ActionSource associated with our most immediate surrounding instance of a tag whose implementation class is a subclass of UIComponentTag. This tag creates no output to the page currently being created.

The ActionListener instance created and installed by this tag has the following behavior and contract.

  • Only create and register the ActionListener instance the first time the component for this tag is created
  • The "target" and "value" tag attributes are ValueExpression instances and are stored unevaluated as instance variables of the listener.
  • When the listener executes, perform the following:
      Call getValue() on the "value" ValueExpression.
      If value of the "value" expression is null, call setValue() on the "target" ValueExpression with the null value.
      If the value of the "value" expression is not null, call getType() on the "value" and "target" ValueExpressions to determine their property types.
      Coerce the value of the "value" expression to the "target" expression value type following the Expression Language coercion rules. Call setValue() on the "target" ValueExpression with the resulting value.
      If either coercion or the execution of setValue() fails throw an AbortProcessingException.
subview

Naming Container tag for all Jakarta Faces core and component tags. It is particularly useful when a nested section included via <ui:include> or any tag that dynamically includes another page is included more than once, potentially causing duplicate component IDs. Each of those nested sections can then be wrapped in its own <f:subview> with each an unique id.

validateBean

A validator that delegates the validation of the local value to the Bean Validation API. The validationGroups attribute serves as a filter that instructs the Bean Validation API which contraints to enforce. If there are any constraint violations reported by Bean Validation, the value is considered invalid. An instance of this validator can participate in class-level validation provided the preconditions mentioned in <f:validateWholeBean /> are met. Please see the documentation for <f:validateWholeBean /> and jakarta.faces.validator.BeanValidator.validate() for the specification and usage example.

validateDoubleRange

Register a DoubleRangeValidator instance on the UIComponent associated with the closest parent UIComponent tag.

validateLength

Register a LengthValidator instance on the UIComponent associated with the closest parent UIComponent tag.

validateLongRange

Register a LongRangeValidator instance on the UIComponent associated with the closest parent UIComponent tag.

validateRegex

A validator that uses the pattern attribute to validate the wrapping component. The entire pattern is matched against the String value of the component. If it matches, it's valid.

validateRequired

A validator that enforces the presence of a value. It has the same affect as setting the required attribute on a UIInput to true.

validateWholeBean

Support multi-field validation by enabling class-level bean validation on CDI based backing beans. This feature causes a temporary copy of the bean referenced by the value attribute, for the sole purpose of populating the bean with field values already validated by <f:validateBean /> and then performing class-level validation on the copy. Regardless of the result of the class-level validation, the copy is discarded. This feature must explicitly be enabled by setting the application parameter specified in the javadoc for the symbolic constant jakarta.faces.validator.BeanValidator.ENABLE_VALIDATE_WHOLE_BEAN_PARAM_NAME. If this parameter is not set, or is set to false, this tag must be a no-op. A non-normative example follows the specification of the feature.

At a high level, the feature provides for a UIInput subclass that maintains its own special private Validator that uses information from one or more <f:validateBean />s to perform class-level bean validation. For discussion, this special Validator is called the wholeBeanValidator.

This tag must be backed by a UIInput component with the following specializations.

  • Override getSubmittedValue() to return a non-null non empty String. This allows UIInput.validate() to call wholeBeanValidator.validate().

  • Override setConverter() to be a no-op. It does not make sense to allow a converter to be installed.

  • Override addValidator() to be a no-op unless the argument is an instance of wholeBeanValidator. It does not make sense to allow additional validators to be installed.

  • Override validate() to take the following actions.

    • If the feature is not enabled, return immediately.

    • If the wholeBeanValidator has not yet been installed, instantiate and pass it to this.addValidator().

    • Call super.validate().

The wholeBeanValidator must have a validate() method that performs the following actions. Due to the above specification, this method will only ever be passed the special UIInput component.

    Resolve the value of the component to its Object. Assume that this value is the bean whose properties are intended to be populated by components whose values are each validated by <f:validateBean /> tags. For discussion, this bean is called the candidate bean and the properties and their respective values are called the candidate values. If the candidate bean cannot be referenced, return immediately from validate(). Use the information recorded by each of those <f:validateBean /> tags to ensure that none of the candidate values are invalid. If any of them are invalid, return immediately from validate(). This ensures class-level validation is only performed on an instance whose fields are all individually valid.

    Otherwise it can be assumed that all field-level validations for this class-level validation have passed.

    Class-level bean validation must operate on a sufficiently populated bean instance. This differs from Faces field-level validation, which prevents beans from being populated with invalid values. To accomodate this difference, the candidate bean must be copied, populated with the already-validated candidate values, and then subjected to class-level validation. The copying must proceed in the following order.

    1. Invoke the newInstance() method on the bean's Class. If this throws any Exception, swallow it and continue.

    2. If the bean implements Serializable, use that to copy the bean instance.

    3. Otherwise, if the bean implements Cloneable, clone the bean instance.

    4. Otherwise, if the bean has a copy constructor, use that to copy the bean instance.

    5. If none of these techniques yields a copy, throw FacesException.

    Populate the copied bean with the candidate values.

    Obtain a reference to a jakarta.validation.Validator instance using the same steps described in the javadoc for jakarta.faces.validator.BeanValidator.validate(). Let the instance be called beanValidator for discussion.

    Obtain the value of the validationGroups attribute using the same steps described in the javadoc for jakarta.faces.validator.BeanValidator.validate(). If this value is not present or not valid, throw FacesException.

    Call the validate method on beanValidator, passing the populated copied bean and the validation groups as arguments. The copied bean can be discarded at this point.

    If the returned Set<ConstraintViolation> is non-empty, for each element in the Set, create a FacesMessage where the summary and detail are the return from calling ConstraintViolation.getMessage(). Capture all such FacesMessage instances into a Collection and pass them to ValidatorException. Using information recorded by the <f:validateBean /> tag(s), call setValid(false) on all of the components whose values contributed to this class-level validation. This is essential to prevent the invalid value from being set into the model during the update model values phase. Finally, throw the exception.

This tag must be placed in the component tree after all of the fields that are to be included in the multi-field validation. If this precondition is not met, the results of applying this tag are unspecified.

This tag must be used in concert with <f:validateBean /> and Bean Validation. Here is a brief example of the common case of ensuring two password fields are individually valid and also both the same. The feature requires the use of the validationGroups attribute on all of the <f:validateBean /> tags and the <f:validateWholeBean /> tag.

First, the ConstraintValidator implementation.


public class PasswordValidator implements ConstraintValidator<Password, PasswordHolder> {

  @Override
  public void initialize(Password constraintAnnotation) { }

  @Override
  public boolean isValid(PasswordHolder value, ConstraintValidatorContext context) {
    boolean result;
    
    result = value.getPassword1().equals(value.getPassword2());

    return result;
  }

}

Note that a PasswordHolder instance is passed to the isValid() method. This method will only be called if the individual properties of the PasswordHolder are valid. This fact allows the isValid() method to inspect the properties and perform effective class-level validtion.

Next, the Constraint.


@Constraint(validatedBy=PasswordValidator.class)
@Target(TYPE)
@Retention(RUNTIME)
@interface Password {

    String message() default "Password fields must match";
    Class[] groups() default {};
    Class[] payload() default {};
}

Now the backing bean constrained by this Constraint. Note the use of groups. Note the fact that the bean implements Cloneable.


@Named
@RequestScoped
@Password(groups = PasswordValidationGroup.class)
public class BackingBean implements PasswordHolder, Cloneable {
    
    private String password1;
    
    private String password2;

    public BackingBean() {
        password1="";
        password2="";
    }

    @Override
    protected Object clone() throws CloneNotSupportedException {
        BackingBean other = (BackingBean) super.clone();
        other.setPassword1(this.getPassword1());
        other.setPassword2(this.getPassword2());
        return other;
    }
    
    @NotNull(groups=PasswordValidationGroup.class)
    @Size(max=16, min=8, message="Password must be between 8 and 16 characters long",
            groups = PasswordValidationGroup.class)
    @Override
    public String getPassword1() {
        return password1;
    }

    public void setPassword1(String password1) {
        this.password1 = password1;
    }

    @NotNull(groups=PasswordValidationGroup.class)
    @Size(max=16, min=8, message="Password must be between 8 and 16 characters long",
            groups = PasswordValidationGroup.class)
    @Override
    public String getPassword2() {
        return password2;
    }

    public void setPassword2(String password2) {
        this.password2 = password2;
    }
    
}

Finally, the Facelets view.


<h:panelGrid columns="2">

    <h:outputText value="Password" />  
    <h:inputSecret id="password1" value='#{backingBean.password1}'>
        <f:validateBean validationGroups="PasswordValidationGroup" />
    </h:inputSecret>
    
    <h:outputText value="Password again" /> 
    <h:inputSecret id="password2" value='#{backingBean.password2}'>
        <f:validateBean validationGroups="PasswordValidationGroup" />
    </h:inputSecret>
    
</h:panelGrid>

<f:validateWholeBean value='#{backingBean}' 
   validationGroups="PasswordValidationGroup" />
validator

Register a named Validator instance on the UIComponent associated with the closest parent UIComponent tag.

Usage outside of an EditableValueHolder parent

If this element is nested within a UIComponent tag that has other UIComponent children, the validator will be automatically added to all the child components as well as this one. The implementation must ensure this occurs even if the parent of this element is not an instance of EditableValueHolder.

valueChangeListener

Register a ValueChangeListener instance on the UIComponent associated with the closest parent UIComponent tag.

view

Container for all Jakarta Faces core and component tags used on a page.

viewAction

This action component specifies an application-specific command (or action), using an EL method expression, to be invoked during one of the Faces lifecycle phases, by default Invoke Application.

viewParam

Used inside of the metadata facet of a view, this tag causes a UIViewParameter to be attached as metadata for the current view. Because UIViewParameter extends UIInput all of the attributes and nested child content for any UIInput tags are valid on this tag as well.

websocket

Registers a websocket push connection in client side by rendering the necessary scripts. Push messages can be sent from server side via jakarta.faces.push.PushContext interface. See also jakarta.faces.push.Push API documentation for an elaborate instruction on how to use <f:websocket>.