-
Notifications
You must be signed in to change notification settings - Fork 15
Calendar 2.x
TOCSTART
TOCEND
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 and year 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.
<p><span class="image-wrap" style=""><img
src="https://github.com/TeamDev-Ltd/OpenFaces/blob/master/wikiResources/calendar.gif"
style="border: 0px solid black"></span><br>
<br>
<a href="http://www.openfaces.org/demo/calendar/" class="external-link" rel="nofollow">Online Demo</a>
</p>
To add the Calendar component to the page, use the <o: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.
<o:calendar value="#{CalendarBean.selectedDate}" />
Like the JSF UIInput component, the Calendar supports the validator, required, immediate and disabled attributes. For more details about these attributes, see JavaServer Faces specification (section "EditableValueHolder").
Calendar 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:calendar value="#{CalendarBean.selectedDate}" timeZone="#{CalendarBean.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:calendar value="#{CalendarBean.selectedDate}" timeZone="GMT"/>
Please note that when the Calendar'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).
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.
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:
<o:calendar locale="#{CalendarBean.selectedLocale}" todayText="#{CalendarBean.currentTodayText}" noneText="#{CalendarBean.currentNoneText}" />
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 <o:dateRanges> tag. You can specify the actual ranges using:
- The value attribute of the <o: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 org.openfaces.component.calendar.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 <o:simpleDateRange> tags within the <o: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 <o: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 <o:simpleDateRange> tag(s) of the <o: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 <o:dateRanges> tag.
You can customize a style for a selected date, both in the normal and rollover states, using the following attributes of the <o:dateRanges> and <o: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 <o: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:
<o:calendar> <o:dateRanges value="#{DateManager.myRanges}" dayStyle="background: green; color: yellow;" rolloverDayStyle="background: yellow; color: green;" disableExcludes="false"/> </o:calendar>
The following example shows date ranges defined by the <o:simpleDateRange> tag. The ranges have different styles applied.
<o:calendar value="#{DateManager.introductionFromDate}" selectedDayStyle="color: #0033CC; background: #00CCFF;"> <o:dateRanges> <o:simpleDateRange fromDate="#{CalendarBean.introductionFromDate}"toDate=<span class="code-quote">"#{CalendarBean.introductionToDate}"</span> dayStyle=<span class="code-quote">"color: #0033CC; background: #00CCFF;"</span>/> <o:simpleDateRange fromDate=<span class="code-quote">"#{CalendarBean.lecturesFromDate}"</span> toDate=<span class="code-quote">"#{CalendarBean.lecturesToDate}"</span> dayStyle=<span class="code-quote">"color: #006600; background: #ADE9CB;"</span>/> <o:simpleDateRange fromDate=<span class="code-quote">"#{CalendarBean.practiceFromDate}"</span> toDate=<span class="code-quote">"#{CalendarBean.practiceToDate}"</span> dayStyle=<span class="code-quote">"color: #FF9900; background: #FFFFCC;"</span>/> <o:simpleDateRange fromDate=<span class="code-quote">"#{CalendarBean.examinationFromDate}"</span> toDate=<span class="code-quote">"#{CalendarBean.examinationToDate}"</span> dayStyle=<span class="code-quote">"color: #CC0000; background: #FFB9B9;"</span>/></o:dateRanges> </o:calendar>
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.
<o:calendar value="#{DateManager.selectedDate}" firstDayOfWeek="1" locale="fr_FR"/>
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 |
The selected date in the Calendar component can be controlled with keyboard when it has a keyboard focus with the Left/Right/Up/Down keys to move the selection within a month and PgUp/PgDown keys to move the selection between months. The Calendar can be made non-focusable and thus not having keyboard control by assigning false to its focusable attribute. The look of Calendar in the focused state can be customized with the focusedStyle/focusedClass attributes.
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. |
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.
All client-side API methods for the Calendar component are listed in the following table:
| Method | Description |
|---|---|
| getSelectedDate() | Gets a selected date from the Calendar component on which this function is invoked. This function returns a JavaScript object of Date type. |
| setSelectedDate(date) | Sets a date for the Calendar component. The date parameter is a JavaScript object of Date type. |
| focus() | Gives the keyboard focus to the component on which this method is invoked. |
| blur() | Removes the keyboard focus from the component on which this method is invoked. |