Schedule

Overview

Since 4.2

The ace:schedule component displays a month, week or day view of scheduled events as well as specific details about each of them. The event details can be displayed on a popup, on the sidebar or on a tooltip. It also has built-in functionality to add, edit and delete events. Individual days can be selected to look more closely at them when changing to the week or day views. The component can work in a lazy-loading mode, only loading the events that are visible in the current view for a given date. The component can be configured with a specific time zone for each user, so that international events can be displayed in the local user's time. There's ajax support for nine different actions within the component, and there are multiple other ways to configure the component for a more custom user experience.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

In its simplest form, an ace:schedule component only requires to have a list of ScheduleEvent objects bound to it.

            <ace:schedule id="schedule" value="#{bean.events}"/>

	private List<ScheduleEvent> events = new ArrayList<ScheduleEvent>() {{
		ScheduleEvent event = new ScheduleEvent();
		event.setStartDate(getDate());
		event.setTitle("My Event");
		event.setLocation("My Location");

		add(event);
	}};

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

The value should be a List, Array, DataModel or a type that can be adapted into a DataModel (java.sql.ResultSet, javax.servlet.jsp.jstl.sql.Result, and java.util.Collection). It must contain the org.icefaces.ace.model.schedule.ScheduleEvent objects to be displayed on the schedule. Alternatively, the value can be an implementation of org.icefaces.ace.model.schedule.LazyScheduleEventList to work in a lazy-loading mode, month per month.

The viewMode attribute specifies the range of days that should be displayed at a time in the calendar. Possible values are 'month', 'week', 'day'. The default value is 'month'.

The viewDate property holds a Date object specifying the date that is currently displayed in the client. This attribute can be used to set an initial date to display or to programmatically set a date to display. This attribute will be automatically updated with the current date being displayed in the client as the user interacts with the component. If the current view mode is set to 'month', this Date object will be automatically changed to the first day of the given month. If the current view mode is set to 'week', this Date object will be automatically changed to the previous Sunday, when the week starts. If the current view mode is set to 'day', this Date object will not change. The time values are irrelevant for this attribute. If this attribute is not specified, the current date is going to be used. This Date object is assumed to be in the time zone specified by the 'timeZone' attribute.

The timeZone attribute is used to specify a time zone ID String (matching an element of java.util.TimeZone.getAvailableIDs()) or a java.util.TimeZone instance to specify the time zone used for date conversion to and from UTC time. If not specified, the default value is TimeZone.getDefault(), which is the default time zone on the system.

The sideBar attribute specifies the location of the sidebar or whether it should be hidden. Possible values are 'right', 'left', and 'hidden'. The default value is 'right'.

The showEventDetails attribute specifies where to display the event details after clicking on an event tag on the calendar. Possible values are 'sidebar', 'popup', 'tooltip', and 'disabled'. The default value is 'popup'.

Client Behavior Events

eventClick	Fired when the user clicks on an event in the schedule. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleClickEvent.
dayDblclick	Fired when the user does double click on a blank area of a day in the month view, which would trigger a dialog to add a new event on that day. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleClickEvent.
timeDblclick	Fired when the user does double click on a blank area of a time cell in the grid of the week and day views, which would trigger a dialog to add a new event starting at that time on that day. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleClickEvent.
addEvent	Fired when the user clicks on the 'Add' button in the Event Details dialog to add a new event to the schedule. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleModifyEvent.
editEvent	Fired when the user clicks on the 'Save' button in the Event Details dialog to save the changes of an existing event in the schedule. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleModifyEvent.
deleteEvent	Fired when the user clicks on the 'Yes' button after having clicked on the 'Delete' button in the Event Details dialog to delete an existing event from the schedule The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleModifyEvent.
next	Fired when the user clicks on the right arrow of the schedule viewer to navigate to the next month, week or day. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleNavigationEvent.
previous	Fired when the user clicks on the left arrow of the schedule viewer to navigate to the previous month, week or day. The listener method for this event can take an event object of the type org.icefaces.ace.event.ScheduleNavigationEvent.

JavaScript APIs

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

var widget = ice.ace.instance('frm:componentId);

The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).

This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

Keyboard and ARIA Support

Not supported at the moment.

Known Issues

On IE8, when changing to the week or day views a javascript error is produced sometimes.

Tips

Because all the state variables that need to be synchronized between the client and the server, it is recommended that any other external components that modify the internal state of an ace:schedule instance, either by changing an attribute value or adding events, be in the same form as the ace:schedule instance they are modifying.

ScheduleEvent objects can have their own, custom style classes. This is useful to easily identify events of different types. This component comes with 8 predefined style classes that can be used out of the box and also include different shadings for different levels of overlapping events. These style classes have a similar look and feel as the enhanced styling and only work if this enhanced styling is enabled. The names of these classes are schedule-blue, schedule-red, schedule-green, schedule-yellow, schedule-orange, schedule-turquoise, schedule-magenta, and schedule-violet.