DateChooser


The DateChooser component allows the user to enter a date either by typing it in the text field or select it from the calendar that appears when the user clicks a button next to text field. The selected date is displayed in the text field in the specified format.

Key Features

Creating the DateChooser

To add the DateChooser component to the page, use the <q: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 and immediate attributes. However, it does not support converter attribute. For more details about these attributes, see JavaServer Faces version 1.1 specification (section 3.2.5 EditableValueHolder).

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.

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.):

<q: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".

<q: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 QuipuKit-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.

The timeZone attribute defines a time zone used for date conversion. Its default value is GMT. The time zone can be specified as a value-binding expression or as a String: either an abbreviation ("PST"), a full name ("America/Los_Angeles"), or a custom ID ("GMT-8:00").

You can use the teamdev.jsf.DateChooserConverter.CONVERSION property from Messages.properties to localize a convertion 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. To specify whether or not to display the week number, use the showWeekNumber attribute.

Also, you can change the default Wk, Today and None labels by using the weekText, 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.

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

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 and styleClass attributes. To customize a style for the drop-down button in the normal and rollover states, use the buttonStyle and rolloverButtonStyle 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, styles for date ranges, inactiveMonthDayStyle, weekendDayStyle, and dayStyle having the lowest priority.

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.

QuipuKit