Get to Know the New ace:schedule Component

The ICEfaces 4.2 release includes the powerful new ace:schedule component. The ace:schedule component displays Month, Week, and Day views of scheduled events and specific details about each of them. The event details can be displayed in a popup, on the sidebar, or on a tooltip. It also has built-in controls to add, edit, and delete events, as well as many other features.

In this article, you’ll see how easy it is to get started with ace:schedule and to use its powerful features, as well as getting a good idea of the full range of possibilities this component offers.

ace:achedule

.

Getting Started

To get started using this component all you need to do is to add the following markup on an xhtml document on your ICEfaces application:

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

And bind the ‘events’ property to a List of org.icefaces.ace.model.schedule.ScheduleEvent objects in your backing bean:

import org.icefaces.ace.model.schedule.ScheduleEvent;
...
private List<ScheduleEvent> events = new ArrayList<ScheduleEvent>();
public List<ScheduleEvent> getEvents() {
 return events;
}
public void setEvents(List<ScheduleEvent> events) {
 this.events = events;

}

This is all you need to start interacting with the component in your application. Note that ace:schedule descends from javax.faces.component.UIData, so you can use any data structure supported by UIData.

.
Event details dialog

You can now load your page and start adding new events by double clicking on any day square. By double-clicking on a day, a dialog will pop up with a form to add a new event on that day. Enter a title for the event and as many details as you want. When you’re done, press the ‘Add’ button, and you’ll see your event appearing in the square of the day that you double-clicked. If you didn’t enter a start time and/or an end time, these fields will take default values, which are configurable.

 If you want to change something about the event, simply click on it, and the same dialog will pop up. This time, you’ll be able to make changes and save them, or, if you prefer, you could delete this event and create a new one.

 

Flexibility

You’re free to decide how this component is going to be used by your end users. Perhaps, you want to post read only events for your users. In that case, simply set the ‘addEvents‘,  ‘deleteEvents‘, and ‘editEvents‘ attributes to false, and you’ll be in total control of what gets posted.  Perhaps, you have a small application to organize your projects and you want your team members to freely add events for the rest of the team to see. That’s easy to do with ace:schedule and a little application code. Or maybe you want each user in your application to have their own private schedule with their own events. You can do that too.

The events in the schedule can be visualized in many ways. You can display only the events of a given week or of a given day by setting the ‘viewMode‘ attribute to ‘week‘ or ‘day‘, respectively. In these views, events are displayed on a time grid, to easily visualize their duration, start and end times. In these views, you can also double-click on a specific time cell and a dialog will pop up to add a new event at that specific time and day.

sideBar

Besides displaying the events in a day or time grid, the events of the current period are also listed in a sidebar, in chronological order. This sidebar can be configured with the ‘sideBar‘ attribute. This same side bar can also be used to display event details, instead of displaying them in the pop-up dialog. This can be configured with the ‘showEventDetails‘ attribute. One more way to look at a specific event’s details is via a tooltip, which can be enabled with the ‘showTooltip‘ attribute.

You can use ‘scrollable‘ and ‘scrollHeight‘ to display a scroll bar on the week and day views. You can use ‘twelveHourClock‘ to display all times in the twelve-hour clock format. You can use ‘defaultDuration‘ to specify a default duration (in minutes) of new events, if no end time is specified when adding a new one. You can use ‘viewDate‘ to specify the date with which the component is loaded or to specify a different date programmatically.

 

Time Zones

When using the ace:schedule component it is important to talk about how times and time zones are handled internally by the component.

The key idea to understand when dealing with time in ace:schedule is simple: **Times are stored in UTC time and are displayed in the configured time zone**.

If the target audience of your application is located in the same time zone, let’s say, your company’s building, you probably don’t need to worry about handling time zones, but if your application is meant to be used by people of different countries or different regions, it’s very important that you have a good understanding of time zones and how they are handled by the ace:schedule component.

As noted previously, all event dates and times are stored in UTC time, in the ScheduleEvent instances. These UTC times are converted to the time zone configured in the component with the ‘timeZone‘ attribute. By default, the configured time zone is that of the operating system on which your server is running. Let’s say that your application is running on a physical server that resides at your workplace. Then, the default time zone for this component, if you don’t specify the ‘timeZone‘ attribute, will be the same as the time zone you’re used to in your daily life (as long as that server is configured with the same time zone it geographically belongs to). But if your server is located somewhere else or if it’s part of a cloud, then, you’ll have to specify the desired time zone that the component will use to display all dates and times.

Time zones are specified via the ‘timeZone‘ attribute in ace:schedule. The value of this attribute must be a time zone ID that is part of the set returned by calling java.util.TimeZone.getAvailableIDs() or an instance of java.util.TimeZone. You can offer different time zones in your application in a drop down menu so that each user can select their own time zone.

<ace:selectMenu id="timeZone" value="#{scheduleConfigurationBean.timeZone}">
     <ace:ajax render="@all"/>
     <f:selectItems value="#{scheduleConfigurationBean.timeZoneList}" />
</ace:selectMenu>

If you don’t want to deal with different time zones, simply make sure to specify somewhere in your application in which time zone the events are displayed.

 

Creating Events Programmatically

We’ve already seen that it’s very easy to create and store events by using the built-in controls. But in many cases you may want to create these events programmatically in your application. This could be because you are storing your event data in an external data source, or maybe you want to add a fixed number of events to every month by default, etc. To do so, you simply have to create instances of org.icefaces.ace.model.schedule.ScheduleEvent objects and add them to your list of events.

When you programmatically create an event, make sure to specify the Date objects for the ‘startDate‘ and ‘endDate‘ properties in UTC time. Note that the Java Date object doesn’t have any notion of time zones. You simply have to create Date objects that represent a date and a time in UTC time, which when converted to the configured time zone (by applying an offset) will represent the correct date and time for such time zone. Fortunately, you’re covered for dealing with these to/from UTC time conversions. The class org.icefaces.ace.component.schedule.ScheduleUtils contains two utility methods to deal with this: toUTCFromTimeZone(Date date, TimeZone timeZone) and toTimeZoneFromUTC(Date date, TimeZone timeZone). So, if you’re programmatically creating events and you want to think in terms of your own time zone, simply pass your date objects to toUTCFromTimeZone() along with a TimeZone instance that represents your own time zone, and you will obtain Date objects that can be treated as being in UTC time for the component’s internal operations.

Other properties in the ScheduleEvent class are self explanatory, such as ‘title‘, ‘location‘, and ‘notes‘. They are displayed in various parts of the component, and all of them are optional, but it’s recommended to at least specify a title. The boolean ‘allDay‘ property is used to mark an event as lasting all day long, with no specific start or end time. This could represent a statutory holiday, an anniversary, a public event that runs for many days, or something similar.

The ‘id‘ property in ScheduleEvent is not used internally by the component at all. The component uses it’s own system to index events. So, this property is your ticket to identify events internally in your application’s business logic for whatever purpose you may have.

Finally, the ‘styleClass‘ property in ScheduleEvent allows you to specify a custom CSS style class for an event. This custom style class is rendered on the div element containing the event in all the month, week, and day views. So you can easily override the default event styling to make an event easier to identify. For example, you can style events of the same type with the same style class. This custom style class is not rendered in the side bar events, only in the events appearing in the day and time grids.

 

Enhanced Styling

ace:schedule

As you may know, the ICEfaces ACE Components support Themeroller themes. Some themes are included in the ICEfaces distribution, and you also have the chance to create your own Themeroller themes. Because different themes can have different color combinations, and because the ace:schedule component can display a lot of information, some themes might make it harder to read the information contained in the schedule or might make the schedule look less appealing.
The ace:schedule component solves this issue by supporting an enhanced styling mode that will look the same across different themes, and that makes it easier to read and locate information in the component. This enhanced styling is enabled by default and can be easily disabled with the ‘enhancedStyling‘ attribute, so that the component is simply styled by the Themeroller theme in use if you prefer. This enhanced styling is only applied to the day and time grids and not to the title bar, side bar, event details dialog or tooltip. This enhanced styling also styles events that overlap other events with different shades of the same color.

Choose styleClass

When you’re programmatically creating events, you can assign them one of the 8 pre-defined style classes that work with this enhanced styling. These classes are included in the CSS resources of the ace:schedule component and are ready for you to use. All these classes have a similar look and feel and include different shadings for overlapping events. The names of these style classes are schedule-blue, schedule-red, schedule-green, schedule-yellow, schedule-orange, schedule-turquoise, schedule-magenta, and schedule-violet.

 

Lazy Loading

If your schedule contains a lot of events it is a good idea to use the lazy loading mode of the component, so that only the events of the time-period that is currently being viewed are loaded. You can also use this lazy loading mode to filter the events that are displayed based on your own criteria. Explaining how the lazy loading mode works is out of the scope of this article, but you can take a look at the Lazy Loading demo in the ICEfaces Showcase to get a very good idea of how it works and to copy the approach used in the demo for your own application or base your own approach on it.

.

Additional Resources

The new ace:schedule component makes it easy to add robust scheduling features into ICEfaces applications. See the following resources for more information:

Additional improvements are planned for this exciting component in future releases, beginning with a new ace:scheduleExporter component to be included in ICEfaces EE 4.2.0.GA.

 

Leave a Reply

Your email address will not be published. Required fields are marked *

three × 1 =