Grouping

Views that support grouping: Timetable / Week Range / List / Resource. The Resource view can only operate when grouping is enabled. The other views do not support grouping.

In order to enable grouping the following steps should be done:

• The resources should be created and added to the appropriate collection in the schedule: Schedule.Contacts for contacts, Schedule.Locations for locations, Schedule.Tasks for tasks, and Schedule.Resources for general and custom resources.
• The selected resources by which to group should be added to the appropriate collection in the control: Calendar.Contacts for contacts, and so on. The selected resources are a subset of all resources defined in the schedule.
• The Calendar.GroupType should be set to the appropriate value, for example GroupType.GroupByContacts to group by contacts.

The following code illustrates how to enable grouping by contacts:

Java

// Define two contacts to group by
Contact c1 = new Contact();
c1.setFirstName("John");

Contact c2 = new Contact();
c2.setFirstName("Jack");

// Add the contacts to the schedule
calendar.getSchedule().getContacts().add(c1);
calendar.getSchedule().getContacts().add(c2);

// Select these contacts for grouping by adding them to
// the appropriate Calendar collection
calendar.getContacts().add(c1);
calendar.getContacts().add(c2);

// Enable grouping by contacts
calendar.setGroupType(GroupType.GroupByContacts);

The text displayed in the header of the corresponding resource depends on the type of the resource and is as follows:

• A string formatted according to Calendar.ContactNameFormat for contacts.
• The Resource.Name for general and custom resources, and locations.
• The Task.Subject for tasks.

Grouping and Appearance

• In resource view a single row is dedicated to each individual resource. The row has a header, displaying the text for that resource and contains all items, associated with that resource for the specified time interval. The row can be additionally subdivided to lanes depending on the ResourceViewSettings.ViewStyle.
• In timetable view each column (or row in a horizontal view) that represents a day is additionally subdivided to the number of grouped resources. For example, if there are 3 resources selected to group by, each day column in the view is subdivided to 3 columns. The sub-columns represent individual resources and contain only the items specific for them. The sub-columns have headers containing the resource text. The header of the day column is displayed above the headers of its underlying resource columns.
• The week range view displays a separate view for grouped resources. For example, if there are two resources, two views are displayed alongside, each of which contains the items associated with its corresponding resource.

Multiple Grouping

The Resource view allows grouping by two resource types simultaneously. The primary resource type is still specified through the setGroupType method. The secondary resource type is specified through the setSecondaryGroupType method. When multiple grouping is enabled the view is divided by the primary resources first. Then each primary resource is additionally subdivided by all secondary resources. For example, if there are two primary resources and three secondary resources specified, the view will display two main headers, divided by three subheaders each, for a total of six rows.

Custom Grouping

Usually the setGroupType and setSecondaryGroupType methods are set to different values. For example, setGroupType can be set to GroupByContacts and setSecondaryGroupType can be set to GroupByResources, to group by contacts and resources respectively. However, it is possible to group resources by their runtime type. In this case both the primary and the secondary resources need to be placed in the Calendar.Resources collection and both setGroupType and setSecondaryGroupType need to be set to GroupByResources. In addition, setCustomGroupType and setCustomSecondaryGroupType must be set to the appropriate runtime types of the resources. The following example illustrates how to enable grouping by custom resources of type Machine and Worker:

Java

calendar.setGroupType(GroupType.GroupByResources);
calendar.setSecondaryGroupType(GroupType.GroupByResources);
calendar.setCustomGroupType(Machine.class);
calendar.setCustomSecondaryGroupType(Worker.class);

It might not always be desired that a primary resource is associated with all secondary resources. In the above case for example, only a subset of the workers could be associated with a machine. This can achieved in JPlanner through the customizeGrouping method of the CalendarListener interface. Let us assume that the Machine class provides a list of workers that are qualified to work with that machine. In this case, the following customizeGrouping override enables grouping only by the qualified workers:

Java

public void customizeGrouping(CustomizeGroupingEvent e)
{
    Machine machine = (Machine)e.getParents()[0];
    e.getGroupByResources().clear();
    e.getGroupByResources().addAll(machine.getQualifiedWorkers());
}