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.

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();
    }

    public void setDescription(String description) {
        this.description = description;
        fireEventChange();
    }

    public void setEnd(Date end) {
        this.end = end;
        fireEventChange();
    }

    public void setStart(Date start) {
        this.start = start;
        fireEventChange();
    }

    public void setStyleName(String styleName) {
        this.styleName = styleName;
        fireEventChange();
    }

    public void setAllDay(boolean isAllDay) {
        this.isAllDay = isAllDay;
        fireEventChange();
    }

    public void addListener(EventChangeListener listener) {
        ...
    }
    
    public void removeListener(EventChangeListener listener) {
        ...
    }

    protected void fireEventChange() {...}
}

You may have noticed that there was some additional code in the BasicEvent that was not in the CalendarEvent interface. Namely BasicEvent also implements two additional interfaces:

CalendarEditor

This interface defines setters for all the fields, and is required for some of the default handlers to work.

EventChangeNotifier

This interface adds the possibility to listen for changes in the event, and enables the Calendar to render the changes immediately.

The start time and end time are mandatory, but caption, description, and style name are not. The style name is used as a part of the CSS class name for the HTML DOM element of the event.

In addition to the basic event interfaces, you can enhance the functionality of your event and event provider classes by using the EventChange and EventSetChange events. They let the Calendar component to know about changes in events and update itself accordingly. The BasicEvent and BasicEventProvider examples given earlier include a simple implementation of these interfaces.