Calendar


The Calendar component enables the user to select a date from a one-month calendar and navigate between months and years. The Calendar component consists of three sections: header, body, and footer. The body displays the days of the month in a table. Each column has a title displaying a weekday name. Each row represents one week.

The current month, year and week number are displayed in the header. The user can navigate between previous and next months or years using << and >> navigation links located in the header. It is also possible to select a needed month or year from a drop-down list that appears when the user clicks on the text displaying the current month or year.

The Calendar's footer contains two buttons: Today and None. Clicking Today selects the current day and clicking None clears any current date selection.

Key Features

Creating the Calendar

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

The following example shows a definition of the Calendar with the value attribute.

<q:calendar value="#{CalendarBean.selectedDate}" />

Like the JSF UIInput component, the Calendar supports the validator, required and immediate attributes. For more details about these attributes, see JavaServer Faces version 1.1 specification (section 3.2.5 EditableValueHolder).

Customizing the Appearance

The first day of the week, which is used by the Calendar component to arrange days by weeks, is specified by the firstDayOfWeek attribute. It can take the values from "1" (Sunday) to "7" (Saturday). By default, the first day of the week is Sunday.

If you want to display the week number of a selected date in the calendar header, set the showWeekNumber attribute to "true" (by default, it is "false"). If there is no date selected, the number of the first week of the displayed month is shown. By default, the label "Wk" is displayed before the week number. To set different text, for example for internalization purposes, use the weekText string attribute, which can also be specified as a value-binding expression.

The labels for the Today and None buttons can be customized with the todayText and noneText string attributes. In addition, you can specify whether to show the Calendar's footer by using a boolean showFooter attribute. By default, it is set to "true".

The following example shows the use of the above attributes:

<q:calendar locale="#{CalendarBean.selectedLocale}"
            todayText="#{CalendarBean.currentTodayText}"
            noneText="#{CalendarBean.currentNoneText}"
            showWeekNumber="#{CalendarBean.showWk}"
            weekText="#{CalendarBean.currentWkText}"/>


To mark out a specific group of dates, you can include them into a date range. Dates within such ranges can be specifically styled. There can be multiple date ranges within the Calendar component.

The date ranges are defined within the <q:dateRanges> tag. You can specify the actual ranges using:

  • The value attribute of the <q:dateRanges> tag. For example, when it is unknown or database-dependent what date ranges will be created.

In this case, you must specify the value attribute as a value-binding expression that references a collection of teamdev.jsf.component.calendar.daterange.SimpleDateRange instances. Using the properties of this class (see the table below), you can set the start and end dates of the range and define the look of date ranges in the normal and rollover states.

  • A set of nested <q:simpleDateRange> tags within the <q:dateRanges> tag. For example, when you already know what date ranges will be used.

In this case, to delimit date ranges and specify their styles, use the attributes of the <q:simpleDateRange> tag, which correspond exactly to the properties of the SimpleDateRange class:

Properties Type Description
fromDate Date Required. The start date of the range.
toDate Date Required. The end date of the range.
dayStyle   A style used for each date cell in the range.
rolloverDayStyle   A style used for each date cell in the range when the mouse is over this cell.

Note that you can combine the value attribute and <q:simpleDateRange> tag(s) of the <q:dateRanges> tag to create date ranges.

If you want to apply one and the same style to all the date ranges (in the normal and rollover states) in the Calendar component, use the dayStyle and rolloverDayStyle attributes of the <q:dateRanges> tag.

You can customize a style for a selected date, both in the normal and rollover states, using the following attributes of the <q:dateRanges> and <q:simpleDateRange> tags:

Attributes Description
selectedDayStyle and selectedDayClass A style used for a selected date.
rolloverSelectedDayStyle and rolloverSelectedDayClass A style used for a selected date in the rollover state.

Additionally, the <q:dateRanges> tag provides attributes to define disabled days within and outside date ranges. Disabled dates cannot be selected by the user.

Attribute Type Description
disableIncludes boolean Determines whether dates in the ranges are disabled or not. By default, it is "false".
disableExcludes boolean Determines whether dates outside the ranges are disabled or not. By default, it is "true".

In the example below, date ranges are defined by the value attribute. The ranges are styled and days outside them are enabled:

<q:calendar>
  <q:dateRanges value="#{DateManager.myRanges}"
                dayStyle="background: green; color: yellow;"
                rolloverDayStyle="background: yellow; color: green;"
                disableExcludes="false"/>
</q:calendar>

The following example shows date ranges defined by the <q:simpleDateRange> tag. The ranges have different styles applied.

<q:calendar value="#{DateManager.introductionFromDate}"
            selectedDayStyle="color: #0033CC; background: #00CCFF;">
  <q:dateRanges>
    <q:simpleDateRange fromDate="#{CalendarBean.introductionFromDate}"
                       toDate="#{CalendarBean.introductionToDate}"
                       dayStyle="color: #0033CC; background: #00CCFF;"/>
    <q:simpleDateRange fromDate="#{CalendarBean.lecturesFromDate}"
                       toDate="#{CalendarBean.lecturesToDate}"
                       dayStyle="color: #006600; background: #ADE9CB;"/>
    <q:simpleDateRange fromDate="#{CalendarBean.practiceFromDate}"
                       toDate="#{CalendarBean.practiceToDate}"
                       dayStyle="color: #FF9900; background: #FFFFCC;"/>
    <q:simpleDateRange fromDate="#{CalendarBean.examinationFromDate}"
                       toDate="#{CalendarBean.examinationToDate}"
                       dayStyle="color: #CC0000; background: #FFB9B9;"/>
  </q:dateRanges>
</q:calendar>

Implementing I18n Support

The Calendar component uses the weekday and month names obtained from the java.util.Locale specified by its locale attribute. By default, the client's locale is used, so the names of the month and weekdays are displayed in the language specified as a local language on the client.

You can specify the locale attribute 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).

In the following example, French is used as a local language and France is used as a local country.

<q:calendar value="#{DateManager.selectedDate}"
    firstDayOfWeek="1"
    locale="fr_FR"/>

Specifying Styles

Different parts of the Calendar component as well as individual date cells can be styled. Use the following style attributes to define how a particular part of the Calendar component will look in the normal and rollover states.

Part of component Style attributes Rollover style attributes
Entire component style and styleClass -
Calendar header (with the drop-down list) headerStyle and headerClass -
Calendar body bodyStyle and bodyClass -
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 (today) date todayStyle and todayClass rolloverTodayStyle and rolloverTodayClass
Disabled dates disabledDayStyle and disabledDayClass rolloverDisabledDayStyle and rolloverDisabledDayClass
Weekend dates weekendDayStyle and weekendDayClass rolloverWeekendDayStyle and rolloverWeekendDayClass

Client-Side Events

The Calendar component supports following client-side events:

Event name Description
onchange Occurs when the user changes a selected date.
onperiodchange Component-specific event that occurs on first load of the Calendar component and then when the user changes months or years.

Server-Side Event Listeners

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

Client-Side API

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

Calendar methods Public methods Description
getSelectedDate() q_getSelectedDate(calendarId) Gets a selected date from the Calendar component with the id specified in the calendarId parameter.
setSelectedDate(date) q_setSelectedDate(calendarId, date) Sets a date for the Calendar component with the id specified in the calendarId parameter. The date parameter is a JavaScript object of Date type.
QuipuKit