In our previous tutorials, we’ve covered several types of Primefaces components such as Primefaces Dashboard and Primefaces AccordionPanel. This tutorial intended for providing you a full explanation of how Calendar component could be used. This tutorial tends to provide you a Maven project configured to use JSF/Primefaces library. If you’ve ever configured a Maven project for using Primefaces before, it’s important for you looking for JSF/Primefaces introduction.

Calendar component is an input component used to select a date featuring display modes, paging, localization and ajax selection and more.

Calendar Basic Info

Tag Info
Component Class org.primefaces.component.calendar.Calendar
Component Type org.primefaces.component.Calendar
Component Family org.primefaces.component
Renderer Type org.primefaces.component.CalendarRenderer
Renderer Class org.primefaces.component.calendar.CalendarRenderer

Calendar Attributes

Name Default Type Description
id null String Unique identifier of the component
rendered true Boolean Boolean value to specify the rendering of the component.
binding null Object An el expression that maps to a server side
value null java.util.Date Value of the component
converter null Converter/String An el expression or a literal text that defines a converter for the component. When it’s an EL expression, it’s resolved to a converter instance. In case it’s a static text, it must refer to a converter id
immediate false Boolean When set true, process validations logic is executed at apply request values phase for this component.
required false Boolean Marks component as required
validator null MethodExpr A method expression that refers to a method validating the input
valueChangeListener null MethodExpr A method expression that refers to a method for handling a valueChangeEvent
requiredMessage null String Message to be displayed when required field validation fails
converterMessage null String Message to be displayed when conversion fails.
validatorMessage null String Message to be displayed when validation fails.
widgetVar null String Name of the client side widget.
mindate null Date or String Sets calendar’s minimum visible date
maxdate null Date or String Sets calendar’s maximum visible date
pages 1 Integer Enables multiple page rendering.
disabled false Boolean Disables the calendar when set to true.
mode popup String Defines how the calendar will be displayed.
pattern MM/dd/yyyy String DateFormat pattern for localization
locale null Object Locale to be used for labels and conversion.
popupIcon null String Icon of the popup button
popupIconOnly false Boolean When enabled, popup icon is rendered without the button
navigator false Boolean Enables month/year navigator
timeZone null TimeZone String or a java.util.TimeZone instance to specify the timezone used for date conversion, defaults to TimeZone.getDefault()
readonlyInput false Boolean Makes input text of a popup calendar readonly.
showButtonPanel false Boolean Visibility of button panel containing today and done buttons.
effect null String Effect to use when displaying and showing the popup calendar.
effectDuration normal String Duration of the effect.
showOn both String Client side event that displays the popup calendar.
showWeek false Boolean Displays the week number next to each week.
disabledWeekends false Boolean Disables weekend columns.
showOtherMonths false Boolean Displays days belonging to other months.
selectOtherMonths false Boolean Enables selection of days belonging to other months
yearRange null String Year range for the navigator, default “c-10:c+10”
timeOnly false Boolean Shows only timepicker without date.
stepHour 1 Integer Hour steps.
stepMinute 1 Integer Minute steps.
stepSecond 1 Integer</td > Second steps.
minHour 0 Integer Minimum boundary for hour selection.
maxHour 23 Integer Maximum boundary for hour selection.
minMinute 0 Integer Minimum boundary for minute selection.
maxMinute 59 Integer Maximum boundary for hour selection.
minSecond 0 Integer Minimum boundary for second selection.
maxSecond 59 Integer Maximum boundary for second selection.
pagedate null Object Initial date to display if value is null.
accesskey null String Access key that when pressed transfers focus to the input element.
alt null String Alternate textual description of the input field.
autocomplete null String Controls browser autocomplete behavior.
dir null String Direction indication for text that does not inherit directionality. Valid values are LTR and RTL.
label null String A localized user presentable name.
lang null String Code describing the language used in the generated markup for this component.
maxlength null Integer Maximum number of characters that may be entered in this field.
onblur null String Client side callback to execute when input element loses focus.
onchange null String Client side callback to execute when input element loses focus and its value has been modified since gaining focus.
onclick null String Client side callback to execute onclick event.
ondblclick null String Client side callback to execute when input element is double clicked.
onfocus null String Client side callback to execute when input element receives focus.
onkeydown null String Client side callback to execute when a key is pressed down over input element.
onkeypress null String Client side callback to execute when a key is pressed and released over input element.
onkeyup null String Client side callback to execute when a key is released over input element.
onmousedown null String Client side callback to execute when a pointer button is pressed down over input element.
onmousemove null String Client side callback to execute when a pointer button is moved within input element.
onmouseout null String Client side callback to execute when a pointer button is moved away from input element.
onmouseover null String Client side callback to execute when a pointer button is moved onto input element.
onmouseup null String Client side callback to execute when a pointer button is released over input element.
onselect null String Client side callback to execute when text within input element is selected by user.
placeholder null String Specifies a short hint.
readonly false Boolean Flag indicating that this component will prevent changes by the user.
style null String Inline style of the component.
styleClass null String Style class of the component.
size null Integer Number of characters used to determine the width of the input element.
tabindex null Integer Position of the input element in the tabbing order.
title null String Advisory tooltip informaton.
beforeShowDay null String Client side callback to execute before displaying a date, used to customize date display.
mask null String Applies a mask using the pattern.

Getting Started With Calendar

For using Calendar component properly, value attribute must be assigned for Date object. As you would see below.

Calendar-Default-View

The above demo has been achieved by using the following Primefaces view and CalendarManagedBean.

index.xhtml

Display Modes

Calendar has two main display modes, popup (default) and inline. The below samples would clarify you using inline as you’ve used the default value.

Calendar-Default-View

For creating an instance Calendar component like above, you have to implement the Primefaces view and CalendarManagedBean like below.

index.xhtml

In case you’ve used the popup default view type, you can control the event that you would your Calendar get displayed once it’s fired. ShowOn attribute listed above, defines the client side event to display the calendar. Valid values are:

  1. focus: When input field receives focus.
  2. button: When the popup button is clicked.
  3. both [Default]: Both focus and button cases.

You’re already experiencing the default behavior, focusing on Calendar input get caused the Calendar component to be displayed. This time we’ve left the displaying mode into popup and at the same time we will provide a button for showOn attribute. Let’s see below what’s the result of:

Calendar-Default-View

As you’ve noticed above, the Calendar component has never shown if you set the focus, rather it would be displayed once you’ve clicked on the button that attached beside. That’s caused by showOn=”button”. Let’s see the required Primefaces view and the CalendarManagedBean.

index.xhtml

Calendar Paging

The calendar can also be rendered in multiple pages where each page corresponds to one month. This feature is tuned with the pages attribute.

Calendar-Default-View-Pages-Demo

Once the Calendar component is focused, instead of viewing one month, three months are displayed according to the pages attribute. Let’s see the required Primefaces view changes.

index.xhtml

Calendar Localization

Calendar component supported multiple kinds of locales as its default localization get determined by the view’s locale itself. However, default value can be overridden, by providing the locale attribute that can take a locale key as a String or a java.util.locale instance.

For localized the Calendar component you should follow the below steps:

  1. Download your locale translation from here. By default, Calendar component’s language of labels are English and you need to add the necessary translations to your page manually as Primefaces doesn’t include language translations. The provided link here will lead you into a community-driven page that helps you get the required translation. The translation is a simple JavaScript object, as you can adding it into your page by using the <script/> tag.
  2. Specify the wanted locale by using the locale attribute onto Calendar component.

The demonstration below shows you Three Calendar components have localized using German, English, and French receptively.

Calendar-German-Locale

Calendar-English-Locale

Now, let’s look at the project directory, JavaScript files and the Primefaces view itself.

Calendar-Project-Directory

index.xhtml

de.js

fr.js

en.js

Ajax Behavior Events

Calendar provides a dateSelect ajax behavior event to execute an instant ajax selection whenever a data is selected. If you define a method as a listener, it will be invoked by passing an org.primefaces.event.SelectEvent instance.

Look at the below demonstration

Calendar-Fire-Ajax-Behavior-DateSelect

Calendar-Ajax-Behavior

By now, let’s see the all required files for doing that work.

index.xhtml

One important note mentioned here, In case you’ve used popup as a mode value, regular ajax behavior events like: blur, keyup and more are supported.

Date Ranges

Using mindate and maxdate options, selectable dates can be restricted. Values for these attributes can be a String or java.util.Date.

As you would see below, we’ve enclosed the available dates between 06/20/14 to 06/20/15, so the calendar won’t allow the user to navigate out of specified scope.

Calendar-Range-Dates-Start-Period

Calendar-Range-Dates-Start-Period

As you’ve noticed, no way for exceeding the date period. Now, let’s look at the required files for doing that.

index.xhtml

Advanced Customization

Use beforeShowDay JavaScript callback to customize the look of each date. The callback JavaScript method should return an array of two values; first value would be used for determining whether the date has enabled or disabled, while the second value should be used for determining the date’s style. The below demonstration will show you how could the callback method be used for disabling all the dates in the Calendar component.

Calendar-Advanced-Customization-Disabled-All-Dates

And all that we need for applying like that customization has been mentioned in the below Primefaces view.

index.xhtml

Client Side API

Finally, Primefaces has provided an implicit object called PF. It’s possible for all of those want controlling the Calendar through using of JavaScript client code to use the PF implicit object.

Primefaces provides you four methods can be invoked against Calendar object and through the PF object.

  1. getDate(): return the selected date.
  2. setDate(DateAsParameter): sets display date.
  3. disable: Disables calendar.
  4. enable: Enable Calendar.

Let’s see the demonstrations below for respective above methods:

Calendar-Client-Side-API-Get-Date

  • Figure above shows you the result of calling getDate().
  • Figure above shows you the result of setDate(), we already set the date to be 20/6/2014.
  • For both remaining methods, the calendar input will be disabled and enabled respectively. And by that, the user won’t be able to focus the input component until it’s enabled again.

Import Attached Source Code Into Your IDE

Many developers may face problems in getting the source code attached here imported into their IDE’s. For those suffering from issues like that, this section has been introduced for them.

For importing the attached source code smoothly, make sure that you follow the below steps:

  • Open your Eclipse IDE. We’ve used latest Eclipse Kepler 4.3.
  • From the project explorer, by Right clicking on – choosing Import  and Import again will cause an import wizard to be opened.
  • From the Maven node, select Existing Maven Project.
  • Existing-Maven-Project
  • Click next and browsing your project’s root directory. In our case we’ve browsing Primefaces-Calendar-Sample and click Okay.
  • Wait a while until the wizard recognized your pom.xml file that’s located there.
  • Make sure you’re selected your pom.xml and click next and finish.
  • It’s probably you may got set of errors that are talking about missing configurations or missing libraries like below.
  • Don’t pay attention for them cause you’ve created your project using Maven while the Eclipse is trying to read the project as Dynamic Web Project.
  • Select all of these errors and remove them and from Project menu choose Clean.
  • If your JDK was configured properly, you’re almost getting a clear result.
  • Just deploy your WAR into any of Java EE compliant container and make fun through investigating the Calendar component.

Summary

Calendar component is a component provided by the Primefaces library. This tutorial tends to discuss it and all of its features. Download the project from below link and play around with it to learn more.

By admin

Leave a Reply

%d bloggers like this: