A.3 Core Library Actions

The core library contains action elements that represent JSF artifacts that are independent of the page markup language, such as converters and validators.

This action creates an instance of the class defined by the type attribute, which must implement the javax.faces.event.ActionListener interface, and adds it to the component represented by the closest JSF component parent action element.

For an alternative, see the action and actionListener attributes for the HTML library <h:commandButton> and <h:commandLink> actions.

Syntax

<f:actionListener type="className" />

Attributes

Attribute name	Java type	EL expression type	Description
type	String	Any	The fully qualified class name for a class implementing the ActionListener interface.

Example

<h:form>

  <h:commandButton value="Save">

    <f:actionListener type="com.mycompany.SaveListener" />

  </h:commandButton>

</h:form>

This action sets a generic attribute for the component represented by the closest JSF component parent action element.

Syntax

<f:attribute name="name" value="value" />

Attributes

Attribute name	Java type	EL expression type	Description
name	String	Any	The attribute name.
value	Object	Any	The attribute value.

Example

<h:form>

  <h:inputText id="from" value="#{filter.from}" />

  <h:inputText value="#{filter.to}">

    <f:validator validatorId="com.mycompany.laterThanValidator" />

    <f:attribute name="compareToComp" value="from" />

  </h:inputText>

</h:form>

This action creates an instance of the converter registered with the ID javax.faces.DateTime, configures it based on the action attributes and associates the converter instance with the component represented by the closest JSF component parent action element.

Syntax

<f:convertDateTime 

  [dateStyle="default |short|medium|long|full"] 

  [timeStyle="default |short|medium|long|full"]

  [pattern="pattern "]

  [type="time|date|both"]

  [locale="locale "]

  [timeZone="timeZone "]

/>

Attributes

Attribute name	Java type	EL expression type	Description
dateStyle	String	Any	One of the predefined locale-dependent date patterns.
locale	String or java.util.Locale	Any	A locale to be used instead of the default.
pattern	String	Any	A custom pattern in the form accepted by java.text.SimpleDateFormat (see the next table).
timeStyle	String	Any	One of the predefined locale-dependent time patterns.
timeZone	String or java.util. TimeZone	Any	The time zone to use instead of the default.
type	String	Any	Which portions to format or parse. Defaults to time if timeStyle is set, to date if dateStyle is set, or to both if both style attributes are set.

The symbols that can be used in a custom pattern, set by the pattern attribute, are the same as those supported by the java.text.SimpleDateFormat:

Symbol	Description	Presentation format	Example
G	Era designator	Text	AD
y	Year	Number	2002
M	Month in year	Text or number	May or 05
d	Day in month	Number	16
h	Hour in AM/PM (1-12)	Number	4
H	Hour in day (0-23)	Number	16
m	Minute in hour	Number	18
s	Second in minute	Number	23
S	Millisecond	Number	678
E	Day in week	Text	Thursday
D	Day in year	Number	144
F	Day of week in month	Number	3
w	Week in year	Number	20
W	Week in month	Number	3
a	AM/PM marker	Text	PM
k	Hour in day (1-24)	Number	17
K	Hour in AM/PM (0-11)	Number	3
z	Time zone	Text	GMT
'	Escape for text	Delimiter
''	Single quote in text	Literal	`

The number of symbols in the pattern determines the presentation format. For Text, four or more symbols means that the full form is used (e.g., "Thursday"), while less than four means that an abbreviation is used (e.g., "Thu"). For Number, the number of symbols sets the minimum number of digits. For Text or Number values, three or more symbols mean that the text format is used, otherwise the number format is used.

Example

<h:form>

  <h:inputText value="#{user.birthDate}">

    <f:convertDateTime dateStyle="short" />

  </h:inputText>

</h:form>

This action creates an instance of the converter registered with the ID javax.faces.Number, configures it based on the action attributes and associates the converter instance with the component represented by the closest JSF component parent action element.

Syntax

<f:convertNumber 

  [pattern="pattern "]

  [minIntegerDigits="min "] [maxIntegerDigits="max "]

  [minFractionDigits="min "] [maxFractionDigits="max "]

  [groupingUsed="true |false"] [integerOnly="true|false "]

  [type="number |currency|percent"]

  [currencyCode="currencyCode "] [currencySymbol="currencySymbol "]

  [locale="locale "]

/>

Attributes

Attribute name	Java type	EL expression type	Description
currencyCode	String	Any	An ISO-4217 currency code.
currencySymbol	String	Any	A Java string to use as the currency symbol.
groupingUsed	boolean	Any	Set to true to include grouping separators in the result.
integerOnly	boolean	Any	Set to true to only parse the integer portion.
locale	String or java.util.Locale	Any	A locale to be used instead of the default.
maxFraction Digits	int	Any	The maximum number of digits in the fractional portion.
maxInteger Digits	int	Any	The maximum number of digits in the integer portion.
minFraction Digits	int	Any	The minimum number of digits in the fractional portion.
minInteger Digits	int	Any	The minimum number of digits in the integer portion.
pattern	String	Any	A custom pattern in the form accepted by java.text.DecimalFormat (see the next table).
type	String	Any	The name of one of the predefined locale-dependent patterns.

The symbols that can be used in a custom pattern, set by the pattern attribute, are the same as those supported by the java.text.DecimalFormat:

Symbol	Description	Location
0	Required digit	Number
#	Digit, zero is not displayed	Number
.	Decimal separator	Number
-	Minus sign	Number
,	Grouping separator	Number
E	Separates mantissa and exponent in scientific notation	Number
%	Multiply by 100 and show as percentage	Prefix or suffix
\u2030	Multiply by 1000 and shows as mille	Prefix or suffix
¤ or \u00A4	Currency sign	Prefix or suffix
'	Escape for text	Prefix or suffix
''	Single quote in text	Prefix or suffix

Example

<h:form>

  <h:inputText value="#{user.salary}">

    <f:convertNumber integerOnly="true" />

  </h:inputText>

</h:form>

This action creates an instance of the class registered with the specified converter ID, which must implement the javax.faces.convert.Converter interface, and associates it with the component represented by the closest JSF component parent action element.

For an alternative, see the converter attribute for HTML library actions that represents JSF components with a value property.

Syntax

<f:converter converterId="converterId" />

Attributes

Attribute name	Java type	EL expression type	Description
converterId	String	Any	The ID used to register a class implementing the Converter interface.

Example

<h:form>

  <h:inputText value="#{user.ssn}">

    <f:converter converterId="ssnConverter" />

  </h:inputText>

</h:form>

This action adds the component represented by the JSF action in its body as a facet with the specified name to the component represented by closest JSF component parent action element. To use a number of components as a facet, create them as children of a simple container component, e.g., by nesting the corresponding HTML library component actions within the body of an <h:panelGroup> action element.

Syntax

<f:facet name="facetName">

  JSF component action elements

</f:facet>

Attributes

Attribute name	Java type	EL expression type	Description
name	String	None	The facet name.

Example

<h:dataTable value="#{reportHandler.reports}" var="report">

  <f:facet name="header">

    <h:outputText value="Reports" />

  </f:facet>

  ...

</h:dataTable>

This action creates an instance of class implementing the java.util.Map interface with a get() method that returns the value of the corresponding resource in the specified resource bundle and saves the instance as a variable in the request scope. Localized resources from the bundle can then be accessed through the Map with regular JSF EL expressions, e.g., as #{mapVar.resourceName}. The resource bundle must be available in the web application's classpath, e.g., as a properties file in the WEB-INF/classes directory. For keys that don't match a resource, the Map returns the key embedded in question marks, e.g., "???myKey???".

Syntax

<f:loadBundle basename="baseName" var="var" />

Attributes

Attribute name	Java type	EL expression type	Description
basename	String	Any	The resource bundle name.
var	String	None	The variable name.

Example

<f:loadBundle basename="messages" var="msgs" />

<h:outputText value="#{msgs.title}" />

This action represents an instance of the component type registered with the type ID javax.faces.Parameter (by default, an instance of the javax.faces.component.UIParameter class). The action creates an instance of the component class, configures it with the name and value from the action attributes and adds it as a child to the component represented by closest JSF component parent action element.

Syntax

<f:param [id="id"] [binding="componentBinding"] [name="name"] value="value" />

Attributes

Attribute name	Java type	EL expression type	Description
binding	String	VB	Must be a value binding expression for a property the component is bound to.
id	String	None	The component ID.
name	String	Any	The parameter name.
value	String	Any	The parameter value.

Example

<f:loadBundle basename="messages" var="msgs" />

<h:outputFormat value="#{msgs.sunRiseAndSetText}">

  <f:param value="#{city.sunRiseTime}" />

  <f:param value="#{city.sunSetTime}" />

</h:outputFormat>

This action represents an instance of the component type registered with the type ID javax.faces.SelectItem (by default, an instance of the javax.faces.component.UISelectItem class). The action creates an instance of the component class, configures it based on the action attributes and adds it as a child to the component represented by closest JSF component parent action element.

Syntax

<f:selectItem [id="id "] [binding="componentBinding "]

  [value="value " | 

    itemValue="itemValue " itemLabel="itemLabel " [itemDisabled="true|false "]

    [itemDescription="itemDescription "]

  ]

/>

Attributes

Attribute name	Java type	EL expression type	Description
binding	String	VB	Must be a value binding expression for a property the component is bound to.
id	String	None	The component ID.
itemDescription	String	Any	The item description.
itemDisabled	boolean	Any	Set to true if the item is disabled.
itemLabel	String	Any	The item label.
itemValue	Object	Any	The item value.
value	javax.faces.model.SelectItem	VB	A SelectItem instance containing all model properties.

Example

<h:form>

  <h:selectManyCheckbox value="#{user.projects}">

    <f:selectItem itemValue="JSF" itemValue="1" />

    <f:selectItem itemValue="JSP" itemValue="2" />

    <f:selectItem itemValue="Servlets" itemValue="3" />

  </h:selectManyCheckbox>

</h:form>

This action represents an instance of the component type registered with the type ID javax.faces.SelectItems (by default, an instance of the javax.faces.component.UISelectItems class). The action creates an instance of the component class, configures it based on the action attributes and adds it as a child to the component represented by closest JSF component parent action element.

If the value is set to an instance of a class implementing the java.util.Map interface, the keys are used as select item labels and the values as select item values.

Syntax

<f:selectItems [id="id"] [binding="componentBinding"] value="value" />

Attributes

Attribute name	Java type	EL expression type	Description
binding	String	VB	Must be a value binding expression for a property the component is bound to.
id	String	None	The component ID.
value	javax.faces.model.SelectItem, an array or Collection with javax.faces.model.SelectItem elements, or a java.util.Map.	VB	One or more SelectItem instances.

Example

<h:form>

  <h:selectManyCheckbox value="#{user.projects}">

    <f:selectItems value="#{allProjects}" />

  </h:selectManyCheckbox>

</h:form>

This action represents an instance of the component type registered with the type ID javax.faces.NamingContainer (by default, an instance of the javax.faces.component.UINamingContainer class).

The action creates an instance of the component class to hold all components defined in an included subview, configures it based on the action attributes and adds it as a child to the component represented by closest JSF component parent action element. For details on how to use this action, see Chapter 12.

Syntax

<f:subView id="id " [binding="componentBinding "] [rendered="true |false"]>

  JSF component action elements 

</f:subView>

Attributes

Attribute name	Java type	EL expression type	Description
binding	String	VB	Must be a value binding expression for a property the component is bound to.
id	String	None	The component ID.
rendered	boolean	Any	If set to false, the component isn't rendered and doesn't participate in any request processing.

Example

<f:view>

  <f:subview id="header">

    <jsp:include page="header.jsp" />

  </f:subview>

  ...

  <f:subview id="footer">

    <jsp:include page="footer.jsp" />

  </f:subview>

</f:view>

This action creates an instance of the validator registered with the ID javax.faces.DoubleRange, configures it based on the action attributes and associates the validator instance with the component represented by the closest JSF component parent action element.

Syntax

<f:validateDoubleRange [maximum="max"] [minimum="min"] />

Attributes

Attribute name	Java type	EL expression type	Description
maximum	double	Any	The maximum allowed value.
minimum	double	Any	The minimum allowed value.

Example

<h:inputText value="#{product.price}">

  <f:convertNumber type="currency" />

  <f:validateDoubleRange minimum="0.0" />

</h:inputText>

This action creates an instance of the validator registered with the ID javax.faces.Length, configures it based on the action attributes and associates the validator instance with the component represented by the closest JSF component parent action element.

Syntax

<f:validateLength [maximum="max"] [minimum="min"] />

Attributes

Attribute name	Java type	EL expression type	Description
maximum	int	Any	The maximum length (number of characters) allowed value.
minimum	int	Any	The minimum length (number of characters) allowed value.

Example

<h:inputText value="#{user.zipCode}">

  <f:validateLength minimum="5" maximum="5" />

</h:inputText>

This action creates an instance of the validator registered with the ID javax.faces.LongRange, configures it based on the action attributes and associates the validator instance with the component represented by the closest JSF component parent action element.

Syntax

<f:validateLongRange [maximum="max"] [minimum="min"] />

Attributes

Attribute name	Java type	EL expression type	Description
maximum	long	Any	The maximum allowed value.
minimum	long	Any	The minimum allowed value.

Example

<h:inputText value="#{employee.salary}">

  <f:convertNumber type="currency" />

  <f:validateLongRange minimum="50000" maximum="150000" />

</h:inputText>

This action creates an instance of the class registered with the specified validator ID, which must implement the javax.faces.validator.Validator interface, and associates it with the component represented by the closest JSF component parent action element.

For an alternative, see the validator attribute for HTML library actions that represents JSF input components.

Syntax

<f:validator validatorId="validatorId" />

Attributes

Attribute name	Java type	EL expression type	Description
validatorId	String	Any	The ID used to register a class implementing the Validator interface.

Example

<h:form>

  <h:inputText value="#{user.ssn}">

    <f:validator validatorId="ssnValidator" />

  </h:inputText>

</h:form>

This action creates an instance of the class defined by the type attribute, which must implement the javax.faces.event.ValueChangeListener interface, and adds it to the component represented by the closest JSF component parent action element.

For an alternative, see the valueChangeListener attributes for the HTML library that represents JSF input components.

Syntax

<f:valueChangeListener type="className" />

Attributes

Attribute name	Java type	EL expression type	Description
type	String	Any	The fully qualified class name for a class implementing the ValueChangeListener interface.

Example

<h:form>

  <h:selectBooleanCheckbox value="Details" immediate="true">

    <f:valueChangeListener type="com.mycompany.DescrLevelListener" />

  </h:selectBooleanCheckbox>

</h:form>

This action represents an instance of the component type registered with the type ID javax.faces.Output (by default, an instance of the javax.faces.component.UIOutput class), combined with a renderer registered with the renderer type ID javax.faces.Text.

The action creates an instance of the component class, sets its value to the evaluation result of the element body, sets the transient property to true and the escape property to the value set by the action attribute with the same name, and adds the component as a child of the component represented by the closest JSF component parent action element.

Syntax

<f:verbatim [escape="true|false ">

  Template text and/or non-JSF action elements 

</f:verbatim>

Attributes

Attribute Name	Java Type	Dynamic Value Accepted	Description
escape	boolean	Any	If true, render special HTML and XML characters as character entity codes, e.g., < as &lt;.

Example

<f:subview id="header">

  <f:verbatim>

    <html>

      <head>

        <title>Welcome to my site!</title>

      </head>

  </f:verbatim>

</f:subview>

This action represents an instance of the component type registered with the type ID javax.faces.ViewRoot (by default, an instance of the javax.faces.component.UIViewRoot class).

The action creates an instance of the component class to hold all components that are part of the view and sets the view's locale to the specified value.

Syntax

<f:view [locale="locale"]>

  JSF component action elements, template text and/or non-JSF action elements

</f:view>

Attributes

Attribute Name	Java Type	Dynamic Value Accepted	Description
locale	String or java.util.Locale	Any	A locale to be used instead of the default.

Example

<f:view locale="#{user.locale}">

  ...

</f:view>