10.2. <rich:calendar>

⁠10.2.1. Basic usage

Basic usage of the <rich:calendar> component requires only the value attribute, which holds the currently selected date. Example 10.3, “Basic usage” shows a basic declaration, with the value pointing to a bean property. The bean property holds the selected date.

⁠

Example 10.3. Basic usage

<rich:calendar value="#{bean.dateTest}" />

⁠10.2.2. Behavior and appearance

The <rich:calendar> component is presented as a pop-up by default, appearing as a text field with a button to expand the full pop-up calendar. To render the calendar in-line on the page instead, set popup="false. This displays the full calendar without the text field and display button.

To add keyboard support for manual input, set enableManualInput="true". To disable the calendar from any user input, set disabled="true".

To change the appearance of the display button from the standard calendar icon, use the buttonIcon and buttonDisabledIcon attributes to replace the icon with a specified file. Alternatively, use the buttonLabel attribute to display text on the button without an icon. If buttonLabel is specified then both the buttonIcon and buttonDisabledIcon attributes are ignored. To hide the text field box, set showInput="false".

The calendar features a Today button for locating today's date on the calendar. This can be set to three different values using the todayControlMode attribute:

hidden, which does not display the button;
select, the default setting, which scrolls the calendar to the current month and selects the date; and
scroll, which scrolls the calendar to the month but does not select the date.
inactive, which displays the date but performs no action when clicked.

To make the entire calendar read-only, set readonly="true". This allows months and years to be browsed through with the arrow controls, but dates and times cannot be selected.

⁠10.2.3. Time of day

The <rich:calendar> component can additionally allow a time of day to be specified with the date. After selecting a date the option to set a time becomes available. The default time can be set with the defaultTime attribute. If the time is altered and a new date is selected, it will not reset unless resetTimeOnDateSelect="true" is specified.

The date selection feature is activated if the time is present in the datePattern attribute for the calendar.

Note

In RichFaces 4, the <rich:calendar> component supports times that include seconds. Previous versions of RichFaces only supported hours and minutes.

⁠10.2.4. Localization and formatting

Date and time strings can be formatted in a set pattern. Use standard locale formatting strings specified by ISO 8601 (for example, d/M/yy HH:mm a) with the datePattern attribute to format date and time strings.

To set the locale of the calendar, use the locale attribute. The calendar will render month and day names in the relevant language. For example, to set the calendar to the US locale, specify locale="en/US".

Use an application resource bundle to localize the calendar control labels. Define the following strings in the resource bundle:

The RICH_CALENDAR_APPLY_LABEL string is the label for the Apply button.
The RICH_CALENDAR_TODAY_LABEL string is the label for the Today button.
The RICH_CALENDAR_CLOSE_LABEL string is the label for the Close button.
The RICH_CALENDAR_OK_LABEL string is the label for the OK button.
The RICH_CALENDAR_CLEAN_LABEL string is the label for the Clean button.
The RICH_CALENDAR_CANCEL_LABEL string is the label for the Cancel button.

Alternatively, use the org.richfaces.calendar resource bundle with Java Archive files (JARs) defining the same properties.

⁠10.2.5. Using a data model

The look and feel of the <rich:calendar> component can be customized through the use of a data model on the server side. The component supports two different ways of loading data from the server side through defining the mode attribute.

When the mode attribute is not specified, the component uses the client mode. The client mode loads an initial portion of data within a set date range. The range can be defined by using the preloadDateRangeBegin and preloadDateRangeEnd attributes. Additional data requests for months outside the range are not sent.

Alternatively, with mode="ajax" the <rich:calendar> requests portions of data from the data model every time the month is switched. The data model can be defined through the dataModel attribute, which points to an object that implements the CalendarDataModel interface. If the dataModel attribute is not defined or has a value of null, the ajax mode functions the same as the client mode.

⁠10.2.6. Client-side customization

Instead of using a data model, the <rich:calendar> component can be customized on the client-side using JavaScript. Use the dayClassFunction attribute to reference the function that determines the CSS style class for each day cell. Use the dayDisableFunction to reference the function that enables or disables a day cell. Example 10.4, “Client-side customization” demonstrates how client-side customization can be used to style different days in a calendar.

⁠

Example 10.4. Client-side customization

<style>
   .everyThirdDay {
      background-color: gray;
   }
   .weekendBold {
      font-weight: bold;
      font-style: italic;
   }
</style>
<script type="text/javascript">
   var curDt = new Date();
   function disablementFunction(day){
      if (day.isWeekend) return false;
      if (curDt==undefined){
         curDt = day.date.getDate();
      }
      if (curDt.getTime() - day.date.getTime() &lt; 0) return true;
      else return false;  
   }
   function disabledClassesProv(day){
      if (curDt.getTime() - day.date.getTime() &gt;= 0) return 'rf-ca-boundary-dates';
      var res = '';
      if (day.isWeekend) res+='weekendBold ';
      if (day.day%3==0) res+='everyThirdDay';
      return res;
   }
</script>
<rich:calendar dayDisableFunction="disablementFunction" 
               dayClassFunction="disabledClassesProv" 
               boundaryDatesMode="scroll" />

⁠10.2.7. JavaScript API

The <rich:calendar> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

showPopup(): Expand the pop-up calendar element.
hidePopup(): Collapse the pop-up calendar element.
switchPopup(): Invert the state of the pop-up calendar element.
getValue(): Return the selected date value of the calendar.
getValueAsString(): Return the selected date value of the calendar as a formatted string.
setValue(newValue): Set the selected date value to the newValue date passed as a parameter. If the new date is not in the currently displayed month, a request is performed to display the correct month.
resetValue(): Clear the selected date value.
today(): Select today's date.
getCurrentMonth(): Return the number of the month currently being displayed.
getCurrentYear(): Return the number of the year currently being displayed.
showSelectedDate(): Show the calendar month that contains the currently selected date.
showDateEditor(): Show the date editor pop-up.
hideDateEditor(): Hide the date editor pop-up.
showTimeEditor(): Show the time editor pop-up.
hideTimeEditor(): Hide the time editor pop-up.

⁠10.2.8. Reference data

component-type: org.richfaces.Calendar
component-class: org.richfaces.component.UICalendar
component-family: org.richfaces.Calendar
renderer-type: org.richfaces.CalendarRenderer
handler-class: org.richfaces.view.facelets.CalendarHandler

⁠10.2.9. Style classes and skin parameters

⁠

Table 10.2. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-cal-extr` This class defines the styles for a pop-up calendar exterior.	`panelBorderColor`	border-color
`.rf-cal-btn` This class defines styles for a calendar button.	No skin parameters.
`.rf-cal-hdr` This class defines the styles for a calendar header.	`panelBorderColor`	border-bottom-color
	`additionalBackgroundColor`	background-color
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-hdr-optnl` This class defines the styles for an optional header.	`panelBorderColor`	border-bottom-color
	`additionalBackgroundColor`	background-color
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-hdr-month` This class defines the styles for the month header.	`headerBackgroundColor`	background-color
	`headerSizeFont`	font-size
	`headerFamilyFont`	font-family
	`headerWeightFont`	font-weight
	`headerTextColor`	color
`.rf-cal-ftr` This class defines the styles for a calendar footer.	`panelBorderColor`	border-right-color, border-bottom-color
	`additionalBackgroundColor`	background
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-ftr-optnl` This class defines the styles for an optional footer.	`panelBorderColor`	border-right-color, border-bottom-color
	`additionalBackgroundColor`	background
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-tl` This class defines the styles for calendar toolbars.	`headerBackgroundColor`	background-color
	`headerSizeFont`	font-size
	`headerFamilyFont`	font-family
	`headerWeightFont`	font-weight
	`headerTextColor`	color
`.rf-cal-tl-ftr` This class defines the styles for a toolbar item in the calendar footer.	`additionalBackgroundColor`	background
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-tl-btn` This class defines styles for a toolbar button.	No skin parameters.
`.rf-cal-tl-btn-dis` This class defines styles for a disabled toolbar button.	No skin parameters.
`.rf-cal-tl-btn-hov` This class defines the styles for toolbar items when it is hovered over with the mouse cursor.	`calendarWeekBackgroundColor`	background-color
	`generalTextColor`	color
	`tableBackgroundColor`	border-color
	`panelBorderColor`	border-right-color, border-bottom-color
`.rf-cal-tl-btn-press` This class defines the styles for toolbar items when it is pressed.	`panelBorderColor`	border-color
	`panelBorderColor`	border-right-color, border-bottom-color
`.rf-cal-tl-close` This class defines styles for a Close button in a toolbar.	No skin parameters.
`.rf-cal-c` This class defines the styles for regular calendar cells.	`panelBorderColor`	border-bottom-color, border-right-color
	`tableBackgroundColor`	background-color
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-c-cnt` This class defines styles for the content of a cell.	No skin parameters.
`.rf-cal-today` This class defines the styles for the cell representing today's date.	`calendarCurrentBackgroundColor`	background-color
	`calendarCurrentTextColor`	color
`.rf-cal-sel` This class defines the styles for the selected day.	`headerBackgroundColor`	background-color
	`headerTextColor`	color
`.rf-cal-hov` This class defines the styles for a cell when it is hovered over with the mouse cursor.	`calendarSpecBackgroundColor`	background-color
	`calendarSpecTextColor`	color
`.rf-cal-week` This class defines the styles for week numbers.	`panelBorderColor`	border-bottom-color, border-right-color
	`calendarWeekBackgroundColor`	background-color
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-holiday` This class defines the styles for weekends and holidays.	`calendarHolidaysBackgroundColor`	background-color
	`calendarHolidaysTextColor`	color
`.rf-cal-boundary-day` This class defines styles for an active boundary button.	No skin parameters.
`.rf-cal-sp-inp` This class defines the styles for a spinner input field in the pop-up element for time selection.	`buttonSizeFont`	font-size
	`buttonFamilyFont`	font-family
`.rf-cal-sp-inp-cntr` This class defines the styles for a wrapper `<td>` element for a spinner input field in the pop-up element for time selection.	`controlBackgroundColor`	background-color
	`panelBorderColor`	border-color
	`subBorderColor`	border-right-color, border-bottom-color
`.rf-cal-sp-btn` This class defines the styles for a wrapper `<td>` element for spinner buttons in the pop-up element for time selection.	`headerBackgroundColor`	background-color, border-color
`.rf-cal-sp-up` This class defines styles for the Up spinner button.	No skin parameters.
`.rf-cal-sp-down` This class defines styles for the Down spinner button.	No skin parameters.
`.rf-cal-sp-press` This class defines styles for a spinner button when it is pressed.	No skin parameters.
`.rf-cal-edtr-shdw` This class defines the styles for the calendar editor shadow.	`tableBackgroundColor`	background
`.rf-cal-edtr-layout-shdw` This class defines the styles for the layout shadow of a calendar editor.	`shadowBackgroundColor`	background-color
`.rf-cal-edtr-btn` This class defines styles for a button in the calendar editor.	No skin parameters.
`.rf-cal-edtr-btn-over` This class defines the styles for the calendar editor button when it is hovered over with the mouse cursor.	`panelBorderColor`	border-color
	`calendarSpecBackgroundColor`	background
`.rf-cal-edtr-btn-sel` This class defines the styles for the calendar editor button when it is selected.	`calendarCurrentBackgroundColor`	background-color
	`calendarCurrentTextColor`	color
`.rf-cal-edtr-tl-over` This class defines the styles for a toolbar item in the calendar editor when it is hovered over with the mouse cursor.	`additionalBackgroundColor`	background
	`tableBackgroundColor`	border-color
	`panelBorderColor`	border-right-color, border-bottom-color
`.rf-cal-edtr-tl-press` This class defines the styles for a toolbar item in the calendar editor when it is pressed.	`additionalBackgroundColor`	background
	`panelBorderColor`	border-color
	`tableBackgroundColor`	border-right-color, border-bottom-color
`.rf-cal-time-inp` This class defines styles for the time input field.	No skin parameters.
`.rf-cal-time-btn` This class defines the styles for a button in the pop-up element for the calendar's time section.	`tableBackgroundColor`	border-color
	`panelBorderColor`	border-right-color, border-bottom-color
`.rf-cal-time-btn-press` This class defines the styles for a pressed button in the pop-up element for the calendar's time section.	`tableBackgroundColor`	border-right-color, border-bottom-color
	`panelBorderColor`	border-color
	`calendarWeekBackgroundColor`	background-color
`.rf-cal-timepicker-cnt` This class defines the styles for the content of the pop-up element during time selection.	`panelBorderColor`	border-color
	`additionalBackgroundColor`	background
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-timepicker-inp` This class defines the styles for an input field in the time picker.	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-timepicker-ok` This class defines styles for the OK button in the time picker.	No skin parameters.
`.rf-cal-timepicker-cancel` This class defines styles for the Cancel button in the time picker.	No skin parameters.
`.rf-cal-monthpicker-cnt` This class defines the styles for the content of the pop-up element during month or year selection.	`panelBorderColor`	border-color
	`tableBackgroundColor`	background
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-cal-monthpicker-ok` This class defines the styles for the OK button for the month picker.	`additionalBackgroundColor`	background
	`panelBorderColor`	border-top-color
`.rf-cal-monthpicker-cancel` This class defines the styles for the Cancel button for the month picker.	`additionalBackgroundColor`	background
	`panelBorderColor`	border-top-color
`.rf-cal-monthpicker-split` This class defines the styles for the splitter in the month picker.	`panelBorderColor`	border-right-color