DateChooser

The DateChooser component enables the user to enter a date either by typing it in the text field or selecting it from the drop-down calendar. With internationalization support, a selected date can be displayed in different date formats and languages. The appearance of virtually every element of the DateChooser component can be customized.


API Reference | Tag Reference
Online Demo

Key Features

Creating the DateChooser

To add the DateChooser component to the page, use the <o:dateChooser> tag. This tag has the value attribute that controls a currently selected date. The attribute must be a value-binding expression that references a java.util.Date instance.

Like the JSF UIInput component, the DateChooser supports the validator, required, immediate and disabled attributes. However, it does not support converter attribute. For more details about these attributes, see JavaServer Faces specification (section "EditableValueHolder").

It's possible to implement a scenario, when a date can be selected only from drop-down calendar using typingAllowed attribute. By default it has a value of "true". To disable the possibility of manual date entering directly into DateChooser's input field just set typingAllowed attribute to "false".

DateChooser component supports the timeZone attribute that can be used to specify the time zone in which to interpret the time information in the date.
The timeZone attribute can be specified as value binding:

<o:dateChooser value="#{DateManager.toDate}"  timeZone="#{DateManager.timeZone}"/>

You can also specify the timeZone attribute as a String that is a timezone ID as described in the javadocs for java.util.TimeZone.getTimeZone().

<o:dateChooser value="#{DateManager.toDate}" timeZone="GMT"/>

Please note that when the DateChooser's value is saved on the server, the selected date is used and time is set to 00:00:00 in the time zone specified with the timeZone attribute(the server time zone is used by default).

Specifying the Date Format

The DateChooser component uses a specific date format to display dates. It is also assumed that the same date format is used by the user when typing a date. The date format can either be specified by the pattern attribute or be derived from the locale and dateFormat attributes.

The pattern string attribute specifies the date format with the pattern similar to that in the java.text.SimpleDateFormat class. Note that the DateChooser component supports only "d", "M", "y" and "E" pattern letters, which represent the components of the date. Please also note that in order for the DateChooser component to work correctly you should specify day, month and year parameters in the pattern attribute.

The following example shows a pattern according to which a date, for example, 11 June 2005 will be formatted to "6/11/05, Sat" (if the default locale is U.S.):

<o:dateChooser value="#{DateManager.toDate}"
    pattern="M/d/yy, EEE"/>

If no pattern is specified, the date format is derived from the locale used by the DateChooser based on the dateFormat attribute. By default, the DateChooser uses the client's locale, but it can also be explicitly specified by the locale attribute. You must specify it as a value-binding expression that references a java.util.Locale instance or as a String in "ll_CC_vv" format, where:

  • ll specify the language - lowercase two-letter ISO-639 code
  • CC specify the country - uppercase two-letter ISO-3166 code (optional)
  • vv specify the variant - vendor and browser specific code (optional)

The dateFormat attribute defines which of the predefined date formats for a given locale should be used. It can take the following values: "short", "medium", "long", "full". The default value is "medium".

In this example, the date format for the DateChooser is set to "full", which means that if the locale is U.S., the date format is "dddd, MMMM dd, yyyy".

<o:dateChooser value="#{DateManager.toDate}"
    dateFormat="full"/>

If the user enters an invalid value, the DateChooser component shows a validation error message. Conversion is triggered on the onchange event and failed conversion does not block page submission. The error message is shown with the FloatingIconMessage component by default. You can add your own component, for example a OpenFaces-supplied Message component. For more information about validation messages, see Validation Framework documentation). At the moment, convertion errors are shown only if the client-side validation is turned on.

You can use the javax.faces.convert.DateTimeConverter.CONVERSION property from Messages.properties to localize a conversion error message. For more details about message bundles, see Validation Framework documentation.

Customizing the Appearance

You can customize the appearance of any part of the DateChooser component. For example, to change the image of the button that opens the drop-down calendar, use the buttonImageUrl attribute. If you want to change the appearance of the calendar, use the attributes that are passed to the inner Calendar component. The firstDayOfWeek attribute lets you define the first day of the week within the calendar.

Also, you can change the default Today and None labels by using the todayText and noneText attributes. In addition, you can specify whether to show the Calendar's footer by using a boolean showFooter attribute. For more details about the Calendar component, see Calendar documentation.

In this example, the first day of the week is Sunday. French is used as a local language and France is used as a local country for the calendar.

<o:dateChooser value="#{DateManager.toDate}"
    buttonImageUrl="/customButton.gif"
    firstDayOfWeek="1"
    locale="fr_FR"
    todayText="Aujourd'hui"
    noneText="Aucun"/>

Like the HTML <input> tag, <o:dateChooser> supports the title, tabindex and accesskey attributes. These attributes are rendered for a nested input field of the DateChooser component.

Using Styles

You can define styles for the entire DateChooser component and its individual parts. To apply a style for the DateChooser, use the style, styleClass, focusedStyle, focusedClass, rolloverStyle, and rolloverClass attributes. To customize a style for the drop-down button in the normal, rollover, and pressed states, use the buttonStyle, buttonClass, rolloverButtonStyle, rolloverButtonClass, pressedButtonStyle, and pressedButtonClass attributes, respectively. To customize a style for the text field in the normal and rollover states, use the fieldStyle, fieldClass, rolloverFieldStyle, and rolloverFieldClass attributes, respectively. To change the icon of the button, use the buttonImageUrl attribute.

Styles for the calendar within the DateChooser component are defined the same way as for the Calendar component. The table below lists all the style attributes for customizing the appearance of the calendar, selected and current dates, weekends, etc.

Part of calendar Style attributes Rollover style attributes
Entire calendar calendarStyle and calendarClass -
Calendar header (and the drop-down list) headerStyle and headerClass -
Calendar footer footerStyle and footerClass -
Row with weekday names daysHeaderStyle and daysHeaderClass -
All dates dayStyle and dayClass rolloverDayStyle and rolloverDayClass
Dates of the inactive month inactiveMonthDayStyle and inactiveMonthDayClass rolloverInactiveMonthDayStyle and rolloverInactiveMonthDayClass
Selected date selectedDayStyle and selectedDayClass rolloverSelectedDayStyle and rolloverSelectedDayClass
Current date todayStyle and todayClass rolloverTodayStyle and rolloverTodayClass
Weekends weekendDayStyle and weekendDayClass rolloverWeekendDayStyle and rolloverWeekendDayClass

Because of the variety of styles for calendar of the DateChooser component, some style definitions may overlap. To avoid any style conflict, please keep in mind that selectedDayStyle has the highest priority, followed by todayStyle, inactiveMonthDayStyle, weekendDayStyle, and dayStyle having the lowest priority.

Keyboard Support

When using the DateChooser component with keyboard, besides just typing in the desired date, you can open the drop-down calendar by pressing the Down key and selecting the date with the Left/Right/Up/Down keys to move the selection within a month and PgUp/PgDown keys to move the selection between months. When the selection is done, you can press the Enter key to apply the selection into the DateChooser's field, or the Esc key to close the calendar popup without applyng the selected date. The look of DateChooser in the focused state can be customized with the focusedStyle/focusedClass attributes.

Client-Side Events

The DateChoser component supports the following standard client-side events: onkeypress, ondblclick, onmousedown, onmouseover, onmousemove, onmouseout, onmouseup, onfocus, onblur, onkeydown, onkeyup and onchange event which occurs when the user changes a date.

Server-Side Event Listeners

The DateChooser component has the valueChangeListener attribute. This attribute is a method-binding expression that must reference a method that accepts the javax.faces.event.ValueChangeEvent parameter. ValueChangeListener for the DateChooser works the same way as for the standard UIInput components. You can also add a value change listener to the component by using the <f:valueChangeListener> tag.

Client-Side API

All client-side API methods for the DateChooser component are listed in the following table:

Method Description
getSelectedDate() Gets a selected date from the DateChooser component on which this method is invoked. This function returns a JavaScript object of Date type.
setSelectedDate(date) Sets a date for the DateChooser component on which this method is invoked. The date parameter is a JavaScript object of Date type.
OpenFaces