calendar

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.Calendar
component-class | org.richfaces.component.html.HtmlCalendar
component-family | org.richfaces.Calendar
renderer-type | org.richfaces.CalendarRenderer
tag-class | org.richfaces.taglib.CalendarTag

## Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:

    ...
          <rich:calendar popup="false"/>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlCalendar;
    ...
    HtmlCalendar myCalendar = new HtmlCalendar();
    ...

## Details of Usage

The "popup" attribute defines calendar representation mode on a page. If it's "true" the calendar is represented on a page as an input field and a button. Clicking on the button calls the calendar popup as it's shown on the picture below.

Using the "popup" attribute

Usage "currentDate" attribute isn't available in the popup mode.

The <rich:calendar> component ables to render pages of days in two modes. Switching mode could be defined with the "mode" attribute with two possible parameters: ajax and client. Default value is set to the "client".

- Ajax

Calendar requests portions of data from Data Model for a page rendering. If "dataModel" attribute has "null" value, data requests are not sent. In this case the "ajax" mode is equal to the "client".

- Client

Calendar loads an initial portion of data in a specified range and use this data to render months. Additional data requests are not sent.

Note:

"preloadDateRangeBegin" and "preloadDateRangeEnd" attributes was designed only for the "client" mode to load some data initially.

"ondataselect" attribute is used to define an event that is triggered before date selection.

"ondateselected" attribute is used to define an event that is triggered after date selection.

For example, to fire some event after date selection you should use <a4j:support> . And it should be bound to "ondateselected" event as it's shown in the example below:

    ...
        <rich:calendar id="date" value="#{bean.dateTest}">
            <a4j:support event="ondateselected" reRender="mainTable"/>
        </rich:calendar>
    ...

"ondataselect" could be used for possibility of date selection canceling. See an example below:

    ...
        <rich:calendar id="date" value="#{bean.dateTest}" ondateselect="if (!confirm('Are you sure to change date?')){return false;}"/>
    ...

How to use these attributes see also on the RichFaces Users Forum.

There are three button-related attributes:

- "buttonLabel" defines a label for the button. If the attribute is set "buttonIcon" and "buttonIconDisabled" are ignored

- "buttonIcon" defines an icon for the button

- "buttonIconDisabled" defines an icon for the disabled state of the button

The "direction" and "jointPoint" attributes are used for defining aspects of calendar appearance.

The possible values for the "direction" are:

- top-left - a calendar drops to the top and left
- top-right - a calendar drops to the top and right
- bottom-left - a calendar drops to the bottom and left
- bottom-right - a calendar drops to the bottom and right
- auto - smart positioning activation

By default, the "direction" attribute is set to "bottom-right".

The possible values for the "jointPoint" are:

- top-left - a calendar docked to the top-left point of the button element
- top-right - a calendar docked to the top-right point of the button element
- bottom-left - a calendar docked to the bottom-left point of the button element
- bottom-right - a calendar docked to the bottom-right point of the button element
- auto - smart positioning activation

By default, the "jointPoint" attribute is set to "bottom-left".

The <rich:calendar> component allows to use "header" , "footer" , "optionalHeader" , "optionalFooter" facets. The following elements are available in these facets: {currentMonthControl}, {nextMonthControl}, {nextYearControl}, {previousYearControl}, {previousMonthControl}, {todayControl}, {selectedDateControl}. These elements could be used for labels output.

Also you can use "weekNumber" facet with available {weekNumber}, {elementId} elements and "weekDay" facet with {weekDayLabel}, {weekDayLabelShort}, {weekDayNumber}, {isWeekend}, {elementId} elements. {weekNumber}, {weekDayLabel}, {weekDayLabelShort}, {weekDayNumber} elements could be used for labels output, {isWeekend}, {elementId} - for additional processing in JavaScript code.

These elements are shown on the picture below.

Available elements

Simple example of usage is placed below.

Example:

    ...
    <!--Styles for cells -->
    <style>
        .width100{
            width:100%;
        }
        .talign{
            text-align:center;
        }
    </style>

    <rich:calendar id="myCalendar" popup="true" locale="#{calendarBean.locale}" value="#{bean.date}"
                                preloadRangeBegin="#{bean.date}" preloadRangeEnd="#{bean.date}" selectedDate="#{bean.date}" cellWidth="40px" cellHeight="40px">

    <!-- Customization with usage of facets and accessible elements -->
        <f:facet name="header">
            <h:panelGrid columns="2" width="100%" columnClasses="width100, fake">
                <h:outputText value="{selectedDateControl}" />
                <h:outputText value="{todayControl}"  style="font-weight:bold; text-align:left"/>
            </h:panelGrid>
        </f:facet>
        <f:facet name="weekDay">
            <h:panelGroup style="width:60px; overflow:hidden;" layout="block">
                <h:outputText value="{weekDayLabelShort}"/>
            </h:panelGroup>
        </f:facet>
        <f:facet name="weekNumber">
             <h:panelGroup>
                <h:outputText value="{weekNumber}" style="color:red"/>
            </h:panelGroup>
         </f:facet>
         <f:facet name="footer">
            <h:panelGrid columns="3" width="100%" columnClasses="fake, width100 talign">
                <h:outputText value="{previousMonthControl}" style="font-weight:bold;"/>
                <h:outputText value="{currentMonthControl}" style="font-weight:bold;"/>
                <h:outputText value="{nextMonthControl}" style="font-weight:bold;"/>
            </h:panelGrid>
        </f:facet>
        <h:outputText value="{day}"></h:outputText>
    </rich:calendar>
    ...

This is a result:

Facets usage

As it's shown on the picture above {selectedDateControl}, {todayControl} elements are placed in the "header" facet, {previousMonthControl}, {currentMonthControl}, {nextMonthControl} - in the "footer" facet, {weekDayLabelShort} - in the "weekDay" facet, {nextYearControl}, {previousYearControl} are absent. Numbers of weeks are red colored.

The <rich:calendar> component allows to show and manage time. It's necessary to define time in a pattern (for example, it could be defined as "d/M/yy HH:mm"). Then after you choose some data in the calendar, it becomes possible to manage time for this date. For time editing it's necessary to click on its field (see a picture below). To clean the field click on the "Clean".

Timing

It's possible to program events for calendar from JavaScript code. A simplest example of usage JavaScript API is placed below:

Example:

    ...
             <a4j:form id="form">
                            <rich:calendar popup="true" rendered="#{!bean.check}" value="#{bean.date}" id="c"/>
                            <!--The link which is used to call a calendar popup externally-->
                            <a onclick="$('form:c').component.Expand()" href="#">Show</a>
            </a4j:form>
    ...

Also the discussion about this problem can be found on the RichFaces Users Forum.

The <rich:calendar> component provides the possibility to use a special Data Model to define data for element rendering. Data Model includes two major interfaces:

- CalendarDataModel
- CalendarDataModelItem

CalendarDataModel provides the following function:

- CalendarDataModelItem[] getData(Date[]);

This method is called when it's necessary to represent the next block of CalendarDataItems. It happens during navigation to the next (previous) month or in any other case when calendar renders. This method is called in "Ajax" mode when the calendar renders a new page.

CalendarDataModelItem provides the following function:

- Date getDate() - returns date from the item. Default implementation returns date.
- Boolean isEnabled() - returns "true" if date is "selectable" on the calendar. Default implementation returns "true".
- String getStyleClass() - returns string appended to the style class for the date span. For example it could be "relevant holyday". It means that the class could be defined like the "rich-cal-day-relevant-holyday" one. Default implementation returns empty string.
- Object getData() - returns any additional payload that must be JSON-serializable object. It could be used in the custom date representation on the calendar (inside the custom facet).

## JavaScript API

JavaScript API

Function | Description
--- | ---
selectDate(date) | Selects the date specified. If the date isn't in current month - performs request to select
isDateEnabled(date) | Checks if given date is selectable
enableDate(date) | Enables date cell control on the calendar
disableDate(date) | Disables date cell control on the calendar
enableDates(date[]) | Enables dates cell controls set on the calendar
disableDates(date[]) | Disables dates cell controls set on the calendar
nextMonth() | Navigates to next month
nextYear() | Navigates to next year
prevMonth() | Navigates to previous month
prevYear() | Navigates to previous year
today() | Selects today date
getSelectedDate() | Returns currently selected date
Object getData() | Returns additional data for the date
enable() | Enables calendar
disable() | Disables calendar
getCurrentMonth() | Returns number of the month currently being viewed
getCurrentYear() | Returns number of the year currently being viewed
Collapse() | Collapses calendar element
Expand() | Expands calendar element

## Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:calendar> components at once:

- Redefine the corresponding skin parameters

- Add to your style sheets style classes used by a <rich:calendar> component

## Skin Parameters Redefinition

Skin parameters redefinition for a popup element

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-color

Skin parameters redefinition for headers (header, optional header)

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-bottom-color
additionalBackgroundColor | background-color
generalSizeFont | font-size
generalFamilyFont | font-family

Skin parameters redefinition for footers (footer, optional footer) and names of working days

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-top-color
panelBorderColor | border-right-color
additionalBackgroundColor | background
generalSizeFont | font-size
generalFamilyFont | font-family

Skin parameters redefinition for weeks numbers

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-bottom-color
panelBorderColor | border-right-color
additionalBackgroundColor | background
calendarWeekBackgroundColor | background-color
generalSizeFont | font-size
generalFamilyFont | font-family

Skin parameters redefinition for a toolbar and names of months

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color
headerSizeFont | font-size
headerFamilyFont | font-family
headerWeightFont | font-weight
headerTextColor | color

Skin parameters redefinition for cells with days

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-bottom-color
panelBorderColor | border-right-color
generalBackgroundColor | background-color
generalSizeFont | font-size
generalFamilyFont | font-family

Skin parameters redefinition for holiday

Skin parameters | CSS properties
--- | ---
calendarHolidaysBackgroundColor | background-color
calendarHolidaysTextColor | color

Skin parameters redefinition for cell with a current date

Skin parameters | CSS properties
--- | ---
calendarCurrentBackgroundColor | background-color
calendarCurrentTextColor | color

Skin parameters redefinition for a selected day

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color
headerTextColor | color
headerWeightFont | font-weight

## Definition of Custom Style Classes

On the screenshot there are classes names that define styles for component elements.

Style classes

Classes names that define an input field and a button appearance

Class name | Description
--- | ---
rich-calendar-input | Defines styles for an input field
rich-calendar-button | Defines styles for a popup button

Classes names that define a days appearance

Class name | Description
--- | ---
rich-calendar-days | Defines styles for names of working days in a header
rich-calendar-weekends | Defines styles for names of weekend in a header
rich-calendar-week | Defines styles for weeks numbers
rich-calendar-today | Defines styles for cell with a current date
rich-calendar-cell | Defines styles for cells with days
rich-calendar-holly | Defines styles for holiday
rich-calendar-select | Defines styles for a selected day
rich-calendar-hover | Defines styles for a hovered day

Classes names that define a popup element

Class name | Description
--- | ---
rich-calendar-popup | Defines styles for a popup element
rich-calendar-exterior | Defines styles for a popup element exterior
rich-calendar-tool | Defines styles for toolbars
rich-calendar-month | Defines styles for names of months
rich-calendar-header-optional | Defines styles for an optional header
rich-calendar-footer-optional | Defines styles for an optional footer
rich-calendar-header | Defines styles for a header
rich-calendar-footer | Defines styles for a footer
rich-calendar-boundary-dates | Defines styles for an active boundary button
rich-calendar-btn | Defines styles for an inactive boundary date
rich-calendar-toolfooter | Defines styles for a today control date

In order to redefine styles for all <rich:calendar> components on a page using CSS, it's enough to create classes with the same names and define necessary properties in them.

To change styles of particular <rich:calendar> components, define your own style classes in the corresponding <rich:calendar> attributes.

## Relevant Resources Links

Here you can see the example of <rich:calendar> usage and sources for the given example.

How to use JavaScript API see on the RichFaces Users Forum.