JavaServer Faces – Converter Tutorial
This tutorial explains the usage of
converters in JSF. It shows how you can use standard converters step
by step using an example application.
General
Author:
Sascha
Wolski
http://www.laliluna.de/tutorials.html
Date: March, 10 2005
Software:
Eclipse
3.x
MyEclipse
3.8.x
Source
code:
The
sources do not contain any project files of eclipse or libraries.
Create a new project following the tutorial, add the libraries as
explained in the tutorial and then you can copy the sources in your
new project.
http://www.laliluna.de/download/jsf-converter-source-light.zip
PDF
Version
http://www.laliluna.de/download/jsf-converter-en.pdf
What
is a converter
A
converter is used to format an object to a ?nicer? text to be
displayed. For example if you want to display a date in JSP you can
use a converter to format the date in terms the user understand, like
?10/03/2005?.
But
there is another way to use a converter. If you use them in
conjunction with an input control, the user’s input must be in the
format specified by the converter. If the format of the input is not
matching the format you can throw an exception in the converter which
is displayed to the user. The associated object is not updated.
Using converters
Converter can be specified within JSP, or
you can register converters programmatically.
You can register a converter using JSP in
one of the three ways:
Specify the converter identifier with a
component tag’s converter property.
<h:outputText value="#{myBean.date}" <b>converter="myConverter"</b>>
Nest the
<f:converter> tag the converters’s identifier inside the
component tag.
<h:outputText value=“#{myBean.date}”>
<f:converter converterId=“myConverter”/>
</h:outputText>
Nest the converter’s custom tag inside a component tag.
<h:outputText value=“#{myBean.date}”>
<laliluna:myConverter />
</h:outputText>The
following JSF Tags supports converters.
<h:outputText>
<h:outputFormat>
<h:outputLink>
<h:outputLabel>
<h:inputText>
<h:inputTextarea>
<h:inputHidden>
<h:inputSecret>
<h:selectBooleanCheckbox>
<h:selectManyListbox>
<h:selectMaynyMenu>
<h:selectOneRadio>
<h:selectOneListbox>
<h:selectOneMenu>
If
you don’t specify a converter, JSF will pick one for you. The
framework has standard converters for all of the basic types: Long,
Byte, Integer, Short, Character, Double,
Float, BigDecimal, BigInteger and Boolean..
For example, if your component is associated with a property of type
boolean, JSF will choose the Boolean converter.
Primitive types are automatically converted to their object
counterparts.
Using
standard converters
DateTime converter
For all basic Java types JSF will
automatically use converters. But if you want to format a Date
object JSF provides a converter tag <f:convertDateTime>.
This tag must be nested inside a component tag that supports
converters.
<h:outputText value="#{myBean.date}"><br><b><f:convertDateTime type="date" dateStyle="medium"/></b><br></h:outputText>
The
converter DateTime supports attributes, like type or
dateStyle, to configure the converter. The listing below shows
the attributes you can use with the DateTime converter.
Attribute name |
Description |
|---|---|
dateStyle |
Specifies the formatting style for the date |
|
timeStyle |
Specifies the formatting style for the time |
|
timeZone |
Specifed the time zone for the date. If not |
|
locale |
The specifed local to use for displaying this |
|
pattern |
The date format pattern used to convert this |
|
type |
Specifies whether to display the date, time or |
Number converter
The
second converter you can customize by using additional attributes is
the Number converter. It is useful for displaying numbers in
basic formats that works for the user’s locale.
<h:outputText value="#{myBean.date}"><br><b><f:convertNumber type="number" maxIntegerDigits="3"/></b><br></h:outputText>
The
listing below shows the attribute you can use with Number
converter. These attributes allow for precise control how a number is
displayed.
Attribute name |
Description |
|---|---|
currencyCode |
Specifies a three-digit international currency |
|
currencySymbol |
Specifies a specific symbol, like ?$?, to |
|
groupingUsed |
True if a grouping symbol, like ?,? or ? |
|
integerOnly |
True if only the integer portion of the input |
|
locale |
The locale to be used for displaying this |
|
minFractionDigits |
Minimal numbers of fractional digits to |
|
maxFractionDigits |
Maximal numbers of fractional digits to |
|
minIntegerDigits |
Minimal numbers of integer digits to display. |
|
maxIntegerDigits |
Maximal numbers of integer digits to display. |
|
pattern |
The decimal format pattern used to convert |
|
type |
The type of number; either number (default), |
The example Application
Create a new java project named JSFConverter
and add the JSF capabilities.
Backing Bean
Create a new Java class named MyBean
in the package de.laliluna.tutorial.converter.bean.
Add three properties, dateVar of type
Date, integerVar of type Integer and floatVar of type
Float.
Initial the properties with some values.
Provide getter and setter methods for each
properties.
The following source code shows the Java
class MyBean:
public class MyBean {<br><br> private Date dateVar = new Date();<br> private Integer integerVar = new Integer(2023);<br> private Float floatVar = new Float(9.099783);<br><br> public Date getDateVar() {<br> return dateVar;<br> }<br> public void setDateVar(Date dateVar) {<br> this.dateVar = dateVar;<br> }<br> public Float getFloatVar() {<br> return floatVar;<br> }<br> public void setFloatVar(Float floatVar) {<br> this.floatVar = floatVar;<br> }<br> public Integer getIntegerVar() {<br> return integerVar;<br> }<br> public void setIntegerVar(Integer integerVar) {<br> this.integerVar = integerVar;<br> }<br>}
Application configuration file
Open the faces-config.xml and add a
managed bean associated with the backing bean MyBean.
Add a navigation-rule for the JSP file
example.jsp.
The following source code shows the content
of the faces-config.xml:
<faces-config>
<managed-bean>
<managed-bean-name>myBean</managed-bean-name>
<managed-bean-class>de.laliluna.tutorial.converter.bean.MyBean</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
</managed-bean>
<navigation-rule>
<from-view-id>example.jsp</from-view-id>
</navigation-rule>
</faces-config>
The JSP file
Create a new JSP file named example.jsp
in the folder /WebRoot of the project.
Add the following example usages of
converters for the DateTime and Number converter:
<%@ page language=“java” >
<%@ taglib uri=“http://java.sun.com/jsf/html” prefix=“h” %>
<%@ taglib uri=“http://java.sun.com/jsf/core” prefix=“f” %>
<!DOCTYPE HTML PUBLIC “-//W3C//DTD HTML 4.01 Transitional//EN”>
<html>
<head>
<title>JSF Converters</title>
</head>
<body>
<f:view>
<h4>DateTime converter</h4>
<p>Display only the date and the dateStyle is <i>short</i></p>
<h:outputText value=“#{myBean.dateVar}”>
<f:convertDateTime type=“date” dateStyle=“short” />
</h:outputText>
<p>Display only the time and the timeStyle is <i>full</i></p>
<h:outputText value=“#{myBean.dateVar}”>
<f:convertDateTime type=“time” timeStyle=“full” />
</h:outputText>
<p>Display both date and time, the dateStyle is <i>full</i> and the locale is <i>ru</i></p>
<h:outputText value=“#{myBean.dateVar}”>
<f:convertDateTime type=“both” dateStyle=“full” locale=“ru” />
</h:outputText>
<p>Display the both, date and time and the dateStyle is <i>short</i></p>
<h:outputText value=“#{myBean.dateVar}”>
<f:convertDateTime type=“both” dateStyle=“short” />
</h:outputText>
<p>Display a date with the pattern <i>dd.MM.yyyy HH:mm</i></p>
<h:outputText value=“#{myBean.dateVar}”>
<f:convertDateTime pattern=“dd.MM.yyyy HH:mm” />
</h:outputText>
<h:form id=“datetime1”>
<p>Input a date and the dateStyle is <i>short</i></p>
<h:inputText value=“#{myBean.dateVar}”>
<f:convertDateTime type=“date” dateStyle=“short” />
</h:inputText>
<h:commandButton value=“Send” />
</h:form>
<h:form id=“datetime2”>
<p>Input a date matching this pattern <i>dd.MM.yyyy</i></p>
<h:inputText value=“#{myBean.dateVar}”>
<f:convertDateTime pattern=“dd.MM.yyyy” />
</h:inputText>
<h:commandButton value=“Send” />
</h:form>
<h4>Number converter</h4>
<p>Display maximal <i>3 integer digits</i></p>
<h:outputText value=“#{myBean.integerVar}”>
<f:convertNumber maxIntegerDigits=“3” />
</h:outputText>
<p>Display type is <i>currency</i> and the currencySymbol is <i>$</i></p>
<h:outputText value=“#{myBean.integerVar}”>
<f:convertNumber type=“currency” currencySymbol=“$”/>
</h:outputText>
<p>Display type is <i>percent</i></p>
<h:outputText value=“#{myBean.integerVar}”>
<f:convertNumber type=“percent”/>
</h:outputText>
<p>Display maximal 4 fraction digits</p>
<h:outputText value=“#{myBean.floatVar}”>
<f:convertNumber maxFractionDigits=“4”/>
</h:outputText>
<p>Display number matching pattern <i>###0,00</i></p>
<h:outputText value=“#{myBean.floatVar}”>
<f:convertNumber pattern=“###0,00%”/>
</h:outputText>
<h:form id=“number1”>
<p>Input a number but only the integer digits will be processed</p>
<h:inputText value=“#{myBean.integerVar}”>
<f:convertNumber integerOnly=“true”/>
</h:inputText>
<h:commandButton value=“Send” />
</h:form>
<h:form id=“number2”>
<p>Input a number matching the pattern <i>##0,00</i></p>
<h:inputText value=“#{myBean.integerVar}”>
<f:convertNumber pattern=“##0,00”/>
</h:inputText>
<h:commandButton value=“Send” />
</h:form>
</f:view>
</body>
</html>
Thats all. Now you can deploy and test the
example application. We recommends a Jboss and Tomcat installation.
Call the example with the following link:
http://localhost:8080/JSFConverters/example.faces