Файл: book-of-vaadin.pdf

Vaadin Calendar

Interaction

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 18.9, “Customizing the Calendar”.

18.2. Installing Calendar

Vaadin Calendar is available for download from Vaadin Directory and from a Maven repository. Installing the add-on is the same as with Vaadin add-ons in general, so please refer to Chapter 17, Using Vaadin Add-ons. Vaadin Calendar includes a widget set, which you need to compile to your project widget set.

Calendar will be included in Vaadin core framework in Vaadin 7.1.

Vaadin Calendar is distributed under the Apache License version 2.0.

18.3. Basic Use

A Calendar is created just like any other Vaadin component. The component has undefined size by default and you usually want to give it a fixed or relative size, for example as follows.

Calendar cal = new Calendar("My Calendar"); cal.setWidth("600px"); cal.setHeight("300px");

You need to define a time range for the calendar, as described in the following subsection. The time range also controls the view mode of the calendar; whether it is a daily, weekly, or monthly view. You also need to provide events for the calendar, for which there are several ways.

18.3.1. Setting the Date Range

The view mode is controlled by the date range of the calendar. The weekly view is the default view mode.You can change the range by setting start and end dates for the calendar. The range must be between one and 60 days.

In the following, we set the calendar to show only one day, which is the current day.

cal.setStartDate(new Date()); cal.setEndDate(new Date());

Notice that although the range we set above is actually zero time long, the calendar still renders the time from 00:00 to 23:59. This is normal, as the Vaadin Calendar is guaranteed to render at least the date range provided, but may expand it. This behaviour is important to notice when we implement our own event providers.

18.3.2. Adding and Managing Events

The first thing the you will probably notice about the Calendar is that it is rather empty at first. The Calendar allows three different ways to add events:

Vaadin Calendar

•Add events directly to the Calendar object using the addEvent()

•Use a Container as a data source

•Use the event provider mechanism

The easiest way to add and manage events in a calendar is to use the basic event management API in the Calendar. You can add events with addEvent() and remove them with the removeEvent().These methods will use the underlying event provider to write the modifications to the data source.

For example, the following adds a two-hour event starting from the current time. The standard Java GregorianCalendar provides various ways to manipulate date and time.

// Add a short event

GregorianCalendar start = new GregorianCalendar();

start.getTime(), end.getTime()));

Calendar uses by default a BasicEventProvider, which keeps the events in memory in an internal reprensetation.

This adds a new event that lasts for 3 hours. As the BasicEventProvider and BasicEvent implement some optional event interfaces provided by the calendar package, there is no need to refresh the calendar. Just create events, set their properties and add them to the Event Provider.

18.3.3. Getting Events from a Container

You can use any Vaadin Container that implements the Indexed interface as the data source for calendar events. The Calendar will listen to change events from the container as well as write changes to the container. You can attach a container to a Calendar with setContainerDataSource().

In the following example, we bind a BeanItemContainer that contains built-in BasicEvent events to a calendar.

// Create the calendar

Calendar calendar = new Calendar("Bound Calendar");

//Use a container of built-in BasicEvents final BeanItemContainer<BasicEvent> container =

new BeanItemContainer<BasicEvent>(BasicEvent.class);

//Create a meeting in the container

container.addBean(new BasicEvent("The Event", "Single Event", new GregorianCalendar(2012,1,14,12,00).getTime(), new GregorianCalendar(2012,1,14,14,00).getTime()));

//The container must be ordered by the start time. You

//have to sort the BIC every time after you have added

//or modified events.

container.sort(new Object[]{"start"}, new boolean[]{true});

calendar.setContainerDataSource(container, "caption", "description", "start", "end", "styleName");

Vaadin Calendar

The container must either use the default property IDs for event data, as defined in the CalendarEvent interface, or provide them as parameters for the setContainerDataSource() method, as we did in the example above.

Keeping the Container Ordered

The events in the container must be kept ordered by their start date/time. Failing to do so may and will result in the events not showing in the calendar properly.

Ordering depends on the container. With some containers, such as BeanItemContainer, you have to sort the container explicitly every time after you have added or modified events, usually with the sort() method, as we did in the example above. Some container, such as JPAContainer, keep the in container automatically order if you provide a sorting rule.

For example, you could order a JPAContainer by the following rule, assuming that the start date/time is held in the startDate property:

//The container must be ordered by start date. For JPAContainer

//we can just set up sorting once and it will stay ordered. container.sort(new String[]{"startDate"}, new boolean[]{true});

Delegation of Event Management

Setting a container as the calendar data source with setContainerDataSource() automatically switches to ContainerEventProvider. You can manipulate the event data through the API in Calendar and the user can move and resize event through the user interface. The event provider delegates all such calendar operations to the container.

If you add events through the Calendar API, notice that you may be unable to create events of the type held in the container or adding them requires some container-specific operations. In such case, you may need to customize the addEvent() method.

For example, JPAContainer requires adding new items with addEntity(). You could first add the entity to the container or entity manager directly and then pass it to the addEvent(). That does not, however, work if the entity class does not implement CalendarEvent. This is actually the case always if the property names differ from the ones defined in the interface. You could handle creating the underlying entity objects in the addEvent() as follows:

// Create a JPAContainer

final JPAContainer<MyCalendarEvent> container = JPAContainerFactory.make(MyCalendarEvent.class,

"book-examples");

//Customize the event provider for adding events

//as entities

ContainerEventProvider cep =

new ContainerEventProvider(container) { @Override

public void addEvent(CalendarEvent event) { MyCalendarEvent entity = new MyCalendarEvent(

event.getCaption(), event.getDescription(), event.getStart(), event.getEnd(), event.getStyleName());

container.addEntity(entity);

}

}

// Set the container as the data source calendar.setEventProvider(cep);

Vaadin Calendar

// Now we can add events to the database through the calendar BasicEvent event = new BasicEvent("The Event", "Single Event",

new GregorianCalendar(2012,1,15,12,00).getTime(), new GregorianCalendar(2012,1,15,14,00).getTime());

calendar.addEvent(event);

18.4. Implementing an Event Provider

If the two simple ways of storing and managing events for a calendar are not enough, you may need to implement a custom event provider. It is the most flexible way of providing events. You need to attach the event provider to the Calendar using the setEventProvider() method.

Event queries are done by asking the event provider for all the events between two given dates. The range of these dates is guaranteed to be at least as long as the start and end dates set for the component.The component can, however, ask for a longer range to ensure correct rendering. In particular, all start dates are expanded to the start of the day, and all end dates are expanded to the end of the day.

18.4.1. Custom Events

An event provider could use the built-in BasicEvent, but it is usually more proper to define a custom event type that is bound directly to the data source. Custom events may be useful for some other purposes as well, such as when you need to add extra information to an event or customize how it is acquired.

Custom events must implement the CalendarEvent interface or extend an existing event class. The built-in BasicEvent class should serve as a good example of implementing simple events. It keeps the data in member variables.

public class BasicEvent

implements CalendarEventEditor, EventChangeNotifier {

...

public String getCaption() { return caption;

}

public String getDescription() { return description;

}

public Date getEnd() { return end;

}

public Date getStart() { return start;

}

public String getStyleName() { return styleName;

}

public boolean isAllDay() { return isAllDay;

}

public void setCaption(String caption) { this.caption = caption; fireEventChange();

}