Chapter 16. Vaadin Calendar
Table of Contents
The Vaadin Calendar is a commercial add-on component for organizing and displaying calendar events. It can be used to view and manage events in monthly, weekly, and daily views.
The main features of the Vaadin Calendar include:
- Monthly, weekly, and daily views
- Two types of events: all-day events and events with a time range
-
Add events directly, from a
Container, or with an event provider - Control the range of the visible dates
- Selecting and editing date or time range by dragging
- Drag and drop events to calendar
- Support for localization and timezones
The data source of the calendar can be practically anything, as its events are queried dynamically by the component. You can bind the calendar to a Vaadin container, or to any other data source by implementing an event provider.
The Vaadin Calendar has two types of views that are shown depending on the date range of the calendar. The weekly view displays a week by default. It can show anything between one to seven days a week, and is also used as a single-day view. The view mode is determined from the date range of the calendar, defined by a start and an end date. Calendar will be shown in a monthly view when the date range is over than one week (seven days) long. The date range is always calculated in an accuracy of one millisecond.
The monthly view, shown in Figure 16.1, “Monthly view with All-Day and Normal Events”, can easily be used to control all types of events, but it is best suited for events that last for one or more days. You can drag the events to move them. In the figure, you can see two longer events that are highlighted with a blue and green background color. Other markings are shorter day events that last less than a 24 hours. These events can not be moved by dragging in the monthly view.
In Figure 16.2, “Weekly View”, you can see four normal day events and also all-day events at the top of the time line grid.
All occurrences in a calendar are represented as
events. You have three ways to manage the calendar
events: add them to the calendar and manage them by its API, from a Vaadin
Container, or with an event
provider.
Events are handled though the CalendarEvent
interface. The concrete class of the event depends on the specific
CalendarEventProvider used in the calendar. By
default, Calendar uses a
BasicEventProvider to provide events, which uses
BasicEvent instances.
Vaadin Calendar does not depend on any particular data source
implementation. Events are queried by the Calendar
from the provider that just has to implement the
CalendarEventProvider interface. It is up
to the event provider that Calendar gets the
correct events.
You can bind any Vaadin Container to a calendar, in
which case a ContainerEventProvider is used
transparently. The container must be ordered by start date and time of the
events. See Section 9.4, “Collecting Items in Containers” for basic information
about containers.
A calendar event requires a start time and an end time. These are the only
mandatory properties. In addition, an event can also be set as an all-day
event by setting the all-day property of the event. You
can also set the description of an event, which is
displayed as a tooltip in the user interface.
If the all-day field of the event is
true, then the event is always rendered as an all-day
event. In the monthly view, this means that no start time is displayed in
the user interface and the event has an colored background. In the weekly
view, all-day events are displayed in the upper part of the screen, and
rendered similarly to the monthly view. In addition, when the time range
of an event is 24 hours or longer, it is rendered as an all-day event in
the monthly view.
When the time range of an event is equal or less than 24 hours, with the accuracy of one millisecond, the event is considered as a normal day event. Normal event has a start and end times that may be on different days.
The date and week captions, as well as events, are clickable and the clicks can be listened for by the server. Also date/time range selections, event dragging, and event resizing can be listened by the server. Using the API, you have full control over the events caused by user interaction.
The weekly view has navigation buttons to navigate forward and backward in time. These actions are also listened by the server. Custom navigation can be implemented using event handlers, as described in Section 16.9, “Customizing the Calendar”.