The core JavaServer Faces custom actions that are independent of any particular RenderKit. 1.2 f http://java.sun.com/jsf/core This tag library validator verifies certain semantic restrictions on the use of JavaServer Faces component actions, including the requirement that component tags nested inside a JSTL conditional tag must have a value specified for the "id" attribute. com.sun.faces.taglib.jsf_core.CoreValidator com.sun.faces.config.ConfigureListener Register an ActionListener instance on the UIComponent associated with the closest parent UIComponent custom action.

]]> actionListener com.sun.faces.taglib.jsf_core.ActionListenerTag empty Fully qualified Java class name of an ActionListener to be created and registered. type false java.lang.String Value binding expression that evaluates to an object that implements javax.faces.event.ActionListener. binding false javax.faces.event.ActionListener If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Add an attribute to the UIComponent associated with the closest parent UIComponent custom action. attribute com.sun.faces.taglib.jsf_core.AttributeTag empty The name of the component attribute to be set. name java.lang.String The value of the component attribute to be set. value java.lang.Object Register a DateTimeConverter instance on the UIComponent associated with the closest parent UIComponent custom action. convertDateTime com.sun.faces.taglib.jsf_core.ConvertDateTimeTag empty Predefined formatting style which determines how the date component of a date string is to be formatted and parsed. Applied only if type is "date" or "both". Valid values are "default", "short", "medium", "long", and "full". Default value is "default". dateStyle java.lang.String Locale whose predefined styles for dates and times are used during formatting or parsing. If not specified, the Locale returned by FacesContext.getViewRoot().getLocale() will be used. Value must be either a VB expression that evaluates to a java.util.Locale instance, or a String that is valid to pass as the first argument to the constructor java.util.Locale(String language, String country). The empty string is passed as the second argument. locale false java.lang.Object Custom formatting pattern which determines how the date/time string should be formatted and parsed. pattern java.lang.String Predefined formatting style which determines how the time component of a date string is to be formatted and parsed. Applied only if type is "time" or "both". Valid values are "default", "short", "medium", "long", and "full". Default value is "default". timeStyle java.lang.String Time zone in which to interpret any time information in the date String. Value must be either a VB expression that evaluates to a java.util.TimeZone instance, or a String that is a timezone ID as described in the javadocs for java.util.TimeZone.getTimeZone(). timeZone java.lang.Object Specifies what contents the string value will be formatted to include, or parsed expecting. Valid values are "date", "time", and "both". Default value is "date". type java.lang.String A ValueExpression that evaluates to an instance of javax.faces.convert.DateTimeConverter. binding javax.faces.convert.DateTimeConverter If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a NumberConverter instance on the UIComponent associated with the closest parent UIComponent custom action. convertNumber com.sun.faces.taglib.jsf_core.ConvertNumberTag empty ISO 4217 currency code, applied only when formatting currencies. currencyCode java.lang.String Currency symbol, applied only when formatting currencies. currencySymbol java.lang.String Flag specifying whether formatted output will contain grouping separators. Expressions must evaluate to a boolean. Default value is true. groupingUsed java.lang.Boolean Flag specifying whether only the integer part of the value will be formatted and parsed. Expressions must evaluate to a boolean. Default value is false. integerOnly java.lang.Boolean Locale whose predefined styles for numbers are used during formatting and parsing. If not specified, the Locale returned by FacesContext.getViewRoot().getLocale() will be used. Expressions must evaluate to a java.util.Locale or a String that is valid to pass as the first argument to the constructor java.util.Locale(String language, String country). The empty string is passed as the second argument.

]]> locale java.lang.Object Maximum number of digits that will be formatted in the fractional portion of the output. Expressions must evaluate to an int. maxFractionDigits java.lang.Integer Maximum number of digits that will be formatted in the integer portion of the output. Expressions must evaluate to an int. maxIntegerDigits java.lang.Integer Minimum number of digits that will be formatted in the fractional portion of the output. Expressions must evaluate to an int. minFractionDigits java.lang.Integer Minimum number of digits that will be formatted in the integer portion of the output. Expressions must evaluate to an int. minIntegerDigits java.lang.Integer Custom formatting pattern which determins how the number string should be formatted and parsed. pattern java.lang.String Specifies how the number string will be formatted and parsed. Valid values are "number", "currency", and "percent". Default value is "number". type java.lang.String A ValueExpression that evaluates to an instance of javax.faces.convert.NumberConverter. binding javax.faces.convert.NumberConverter If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a named Converter instance on the UIComponent associated with the closest parent UIComponent custom action. converter com.sun.faces.taglib.jsf_core.ConverterTag empty Converter identifier of the Converter instance to be created and registered. converterId java.lang.String A ValueExpression that evaluates to an object that implements javax.faces.convert.Converter. binding javax.faces.convert.Converter If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String 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).

]]> ajax empty A value of "true" indicates the AjaxBehavior should not be rendered. A value of "false" indicates the AjaxBehavior should be rendered. "false" is the default.

]]> disabled false java.lang.Boolean A String identifying the type of event the Ajax action will apply to. If specified, it must be one of the events supported by the component the Ajax behavior is being applied to. For HTML components this would be the set of supported DOM events for the component, plus "action" for Faces ActionSource components and "valueChange" for Faces EditableValueHolder components. If not specified, the default event is determined for the component. The DOM event name is the actual DOM event name (for example: "click") as opposed to (for example: "onclick").

]]> event false java.lang.String Evaluates to Collection. Identifiers of components that will participate in the "execute" portion of the Request Processing Lifecycle. If a literal is specified the identifiers must be space delimited. Any of the keywords "@this", "@form", "@all", "@none" may be specified in the identifier list.

]]> execute false java.lang.Object If "true" behavior events generated from this behavior are broadcast during Apply Request Values phase. Otherwise, the events will be broadcast during Invoke Aplications phase

]]> immediate false java.lang.Boolean Method expression referencing a method that will be called when an AjaxBehaviorEvent has been broadcast for the listener.

]]> listener false false public void processAjaxBehavior(javax.faces.event.AjaxBehaviorEvent event) throws javax.faces.event.AbortProcessingException The name of the JavaScript function that will handle UI events.

]]> onevent false java.lang.String The name of the JavaScript function that will handle errors.

]]> oneerror false java.lang.String Evaluates to Collection. Identifiers of components that will participate in the "render" portion of the Request Processing Lifecycle. If a literal is specified the identifiers must be space delimited. Any of the keywords "@this", "@form", "@all", "@none" may be specified in the identifier list.

]]> render false java.lang.Object Allow JSF page authors to install ComponentSystemEventListener instances on a component in a page.

]]> event JSP Name of the event for which to install a listener. The following table lists the valid values for this attribute, and the corresponding event type for which the listener action is registered.

value for "name" tag attribute Type of event sent to listener method
preRenderComponent javax.faces.event.PreRenderComponentEvent
PostAddToView javax.faces.event.PostAddToViewEvent
preValidate javax.faces.event.PreValidateEvent
postValidate javax.faces.event.PostValidateEvent

In addition to these values, the fully qualified class name of any java class that extends javax.faces.event.ComponentSystemEvent may be used as the value of the "type" attribute.

Also, the @javax.faces.event.NamedEvent annotation may be attached to any java class that extends javax.faces.event.ComponentSystemEvent. This enables that event to be referenced from this attribute, as descibed in the javadocs for @NamedEvent.

]]> name true false java.lang.String Method expression pointing to a method expression of that will be called when the listener's processEvent method would have been called. listener true false public void listener(javax.faces.event.ComponentSystemEvent event) throws javax.faces.event.AbortProcessingException Register a named facet on the UIComponent associated with the closest parent UIComponent custom action.

]]> facet javax.faces.webapp.FacetTag JSP Name of the facet to be created. name true false java.lang.String 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, 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.

viewId XHTML page, page01.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="http://java.sun.com/jsf/facelets"
  3.       xmlns:f="http://java.sun.com/jsf/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).

]]> metadata javax.faces.webapp.FacetTag JSP 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 JspException must be thrown. loadBundle com.sun.faces.taglib.jsf_core.LoadBundleTag empty Base name of the resource bundle to be loaded. basename java.lang.String Name of a request scope attribute under which the resource bundle will be exposed as a Map. var true false Add a child UIParameter component to the UIComponent associated with the closest parent UIComponent custom action. param com.sun.faces.taglib.jsf_core.ParameterTag JSP ValueExpression to a backing bean property bound to the component instance for the UIComponent created by this custom action. binding javax.faces.component.UIComponent Component identifier of the UIParameter component to be created. id false true Name of the parameter to be created. name java.lang.String Value of the parameter to be set. value RELEASE_PENDING - Also update spec for bookmarkable URL (don't forget the two sources for include-view-params). - convey precendence feature using non-normative language vs algorithmic Flag enabling or disabling the inclusion of the parameter disable boolean Used inside of the metada 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.

]]> viewParam com.sun.faces.taglib.jsf_core.ParameterTag JSP converter false javax.faces.convert.Converter converterMessage false java.lang.String id false true required false boolean requiredMessage false java.lang.String validator false void validate(javax.faces.context.FacesContext, javax.faces.component.UIComponent, java.lang.Object) validatorMessage false java.lang.String value false java.lang.Object Name of the parameter to be created. name true java.lang.String MethodExpression representing a value change listener method that will be notified when a new value has been set for this input component. The expression must evaluate to a public method that takes a ValueChangeEvent parameter, with a return type of void, or to a public method that takes no arguments with a return type of void. In the latter case, the method has no way of easily knowing what the new value is, but this can be useful in cases where a notification is needed that "this value changed".

]]> valueChangeListener false void valueChange(javax.faces.event.ValueChangeEvent) maxlength false int The ValueExpression linking this component to a property in a backing bean binding false javax.faces.component.UIComponent If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a PhaseListener instance on the UIViewRoot in which this tag is nested. phaseListener com.sun.faces.taglib.jsf_core.PhaseListenerTag empty Fully qualified Java class name of an PhaseListener to be created and registered. type false java.lang.String Value binding expression that evaluates to an object that implements javax.faces.event.PhaseListener. binding false javax.faces.event.PhaseListener Add a child UISelectItem component to the UIComponent associated with the closest parent UIComponent custom action. selectItem com.sun.faces.taglib.jsf_core.SelectItemTag empty Value binding expression to a backing bean property bound to the component instance for the UIComponent created by this custom action. binding javax.faces.component.UIComponent Component identifier of the UISelectItem component to be created. id false true Description of this option, for use in development tools. itemDescription java.lang.String Flag indicating whether the option created by this component is disabled. Expressions must evaluate to a boolean. Default value is false. itemDisabled java.lang.Boolean Label to be displayed to the user for this option. itemLabel java.lang.String Flag indicating that characters that are sensitive in the value of the itemLabel]]> attribute must be escaped. This flag is set to "true" by default. escape java.lang.String Value to be returned to the server if this option is selected by the user. itemValue Value binding expression pointing at a SelectItem instance containing the information for this option. value javax.faces.model.SelectItem Flag indicating whether the option created by this component represents the special "no selection" option. Expressions must evaluate to a boolean. Default value is false. noSelectionOption java.lang.Boolean Add a child UISelectItems component to the UIComponent associated with the closed parent UIComponent custom action.

When iterating over the select items, toString() mest 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.

]]> selectItems com.sun.faces.taglib.jsf_core.SelectItemsTag empty Value binding expression to a backing bean property bound to the component instance for the UIComponent created by this custom action. binding javax.faces.component.UIComponent Component identifier of the UISelectItems component to be created. id false true Value expression pointing at any Collection or array. The member elements may be instances of SelectItem or any Java Object. In the case where the member elements are plain Java Objects, several additional attributes must be used by the page author to correctly identify the data to the enclosing UISelectOne or UISelectMany component, as shown in the following example.
  1. <h:selectOneListbox size="1" id="escape02" value="#{select05NoSelection.initialCollectionValues}">
  2.   <f:selectItems value="#{select05NoSelection.hobbitList}"
  3.                  var="n"
  4.                  itemValue="#{n}"
  5.                  itemLabel="#{n.bio}"
  6.                  itemDescription="#{n.description}"
  7.                  itemDisabled="#{n.disabled}"
  8.                  itemLabelEscaped="true"
  9.                  noSelectionValue="#{select05NoSelection.hobbitList[0]}"/>
  10. </h:selectOneListbox>

In the preceding example, the value attribute on line 1 points to a Collection<HobbitBean>. HobbitBean is just a regular Java Object (POJO) that conforms to JavaBeans naming conventions for its properties. The value attribute on line 2 points to a List<HobbitBean>, though it could just as well point to a Collection, array, or javax.faces.model.DataModel. The attributes on lines 3 through 9, inclusive, leverage the fact that the value is a collection of POJOs.

]]> value java.lang.Object Expose the value from the value attribute under this request scoped key so that it may be referred to in EL for the value of other attributes.

]]> var false false java.lang.String evaluates to a Collection, array, or Map from which the items to be shown will be rendered.

]]> itemValue java.lang.Object evaluates to a String that will serve as the label to be shown for the item.

]]> itemLabel java.lang.String evaluates to a String that will serve as the description to be shown for the item.

]]> itemDescription java.lang.String evaluates to a boolean that will determine if the item value is selectable or not.

]]> itemDisabled java.lang.Boolean evaluates to a boolean that will determine if the rendered markup for the item receives normal JSF HTML escaping or not.

]]> itemLabelEscaped java.lang.Boolean Is either an EL expression pointing to the element in the value collection whose value should be marked as a “no selection” item, or a literal string that exactly matches the value of the item in the collection that must be marked as the “no selection” item. If the user selects such an item and the field is marked as required, then it will not pass validation.

]]> itemLabelEscaped java.lang.Boolean Register an ActionListener instance on the UIComponent associated with the closest parent UIComponent custom action. 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.
]]> setPropertyActionListener com.sun.faces.taglib.jsf_core.SetPropertyActionListenerTag empty ValueExpression to be stored as the value of the target attribute. value true ValueExpression that is the destination of the value attribute. target true If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Container action for all JavaServer Faces core and custom component actions used on a nested page via "jsp:include" or any custom action that dynamically includes another page from the same web application, such as JSTL's "c:import". subview com.sun.faces.taglib.jsf_core.SubviewTag JSP Value binding expression to a backing bean property bound to the component instance for the UIComponent created by this custom action. binding javax.faces.component.UIComponent Component identifier of the UINamingContainer component to be created. id true true Flag indicating whether this component (and its children) should be rendered. Expressions must evaluate to a boolean. rendered java.lang.Boolean Register a DoubleRangeValidator instance on the UIComponent associated with the closest parent UIComponent custom action. validateDoubleRange com.sun.faces.taglib.jsf_core.ValidateDoubleRangeTag JSP A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean Maximum value allowed for this component. maximum java.lang.Double Minimum value allowed for this component. minimum java.lang.Double A ValueExpression that evaluates to an instance of DoubleRangeValidator. binding javax.faces.validator.DoubleRangeValidator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a LengthValidator instance on the UIComponent associated with the closest parent UIComponent custom action. validateLength com.sun.faces.taglib.jsf_core.ValidateLengthTag JSP A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean Maximum length allowed for this component. maximum java.lang.Integer Minimum length allowed for this component. minimum java.lang.Integer A ValueExpression that evaluates to an instance of LenghtValidator. binding javax.faces.validator.LengthValidator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a LongRangeValidator instance on the UIComponent associated with the closest parent UIComponent custom action. validateLongRange com.sun.faces.taglib.jsf_core.ValidateLongRangeTag JSP A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean Maximum value allowed for this component. maximum java.lang.Long Minimum value allowed for this component. minimum java.lang.Long A ValueExpression that evaluates to an instance of LongRangeValidator. binding javax.faces.validator.LongRangeValidator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String 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.

]]> validateBean com.sun.faces.taglib.jsf_core.BeanValidatorTag empty A comma-separated list of validation groups. A validation group is a fully-qualified class name. validationGroups false java.lang.String A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean A ValueExpression that evaluates to an instance of BeanValidator. binding javax.faces.validator.BeanValidator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String 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.

]]> validateRegex com.sun.faces.taglib.jsf_core.RegexValidatorTag empty A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean A regular expression pattern. Remember that, like in all Java strings, backslash must be escaped with another backslash. pattern true java.lang.String A ValueExpression that evaluates to an instance of RegexpValidator. binding javax.faces.validator.RegexValidator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String A validator that enforces the presence of a value. It has the same affect as setting the required attribute on a UIInput to true.

]]> validateRequired com.sun.faces.taglib.jsf_core.ValidateLengthTag JSP A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean A ValueExpression that evaluates to an instance of RequiredValidator. binding javax.faces.validator.RequiredValidator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a named Validator instance on the UIComponent associated with the closest parent UIComponent custom action.

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.

]]> validator com.sun.faces.taglib.jsf_core.ValidatorTag empty A boolean value enabling page level determination of whether or not this validator is enabled on the enclosing component.

]]> disabled java.lang.Boolean Validator identifier of the Validator to be created and registered. validatorId java.lang.String A ValueExpression that evaluates to an object that implements the javax.faces.validator.Validator interface. binding javax.faces.validator.Validator If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Register a ValueChangeListener instance on the UIComponent associated with the closest parent UIComponent custom action. valueChangeListener com.sun.faces.taglib.jsf_core.ValueChangeListenerTag empty Fully qualified Java class name of a ValueChangeListener to be created and registered. type java.lang.String Value binding expression that evaluates to an object that implements javax.faces.event.ValueChangeListener. binding false javax.faces.event.ValueChangeListener If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.

]]> for false java.lang.String Create and register a child UIOutput component associated with the closest parent UIComponent custom action, which renders nested body content. verbatim com.sun.faces.taglib.jsf_core.VerbatimTag JSP Flag indicating that generated markup must be escaped in a manner that is appropriate for the markup language to be rendered. Expressions must evaluate to a boolean. Default value is false. escape java.lang.Boolean rendered false java.lang.Boolean Container for all JavaServer Faces core and custom component actions used on a page. view com.sun.faces.taglib.jsf_core.ViewTag JSP Locale to use for localizing this page. Expressions must evaluate to a java.util.Locale or to a String that is converted to a Locale. locale java.lang.Object Identifier for the RenderKit to use for rendering this page. renderKitId false java.lang.String MethodBinding pointing to a method that takes a javax.faces.event.PhaseEvent and returns void. This method will be called before every phase except for restore view. beforePhase false void beforePhase(javax.faces.event.PhaseEvent) MethodBinding pointing to a method that takes a javax.faces.event.PhaseEvent and returns void. This method will be called after every phase except for restore view. afterPhase false void afterPhase(javax.faces.event.PhaseEvent)