Skip to content

DayTable 2.x

Jump to bottom
RomanPerin edited this page Aug 28, 2014 · 3 revisions

TOCSTART

TOCEND

DayTable is a component that allows displaying and editing schedule of events for a day. Each event has a start time, end time, event name, description and other fields. Although DayTable shows events for one day at a time, it is possible to change current day thus making it possible to specify a timetable for an arbitrary period of time. There is also the possibility to show timetable for multiple resources, for example the schedule of tasks for several people.


Online Demo

Key Features

  • Editable/read-only mode
  • Auto-saving changes with Ajax
  • Multi-resource timetables
  • Event time and duration editing with drag&drop
  • Embedding custom content areas
  • Support for custom event actions
  • Support for reserved-time events
  • Customizable event editors
  • Customizable time-scale
  • Support for large data sets
  • Flexible appearance customization

Basic Configuration

Configuring Displayed Events

The DayTable component can be added to a page using the <o:dayTable> tag. In order to get the simplest DayTable working you just need to specify the events attribute. This attribute should be specified as a value binding expression that refers a collection or array of TimetableEvent instances (or ReservedTimeEvent instances as described in the Specifying "Reserved Time" Events section below). The TimetableEvent class specifies the parameters for a single event in a timetable:

  • id: String. This should be a unique value that identifies this event in the whole timetable for all days.
  • resourceId: String. Specifies Id of a resource that this event belongs to if a timetable is set for displaying multiple resources. See Showing a Multi-Resource Timetable.
  • start: Date. Event start time. This is a required property.
  • end: Date. Event end time. This is a required property.
  • name: String. Event name. It is displayed in the top row of the appropriate event rectangle in a timetable.
  • description: String. Event description. It is displayed under event name of the appropriate event rectangle.
  • color: Color. Events can be displayed in different colors in order to make it possible to highlight separation onto different event types, priorities, or other characteristics. This property can be null, which will display the event using a default color (see the Customizing Event Appearance section).
  • customProperties: Map<String, Object>. Allows adding custom named properties to events for client-side access.

Although DayTable component displays events for one day at a time, it allows changing the current day thus making it possible to edit timetable for an arbitrary number of days. For this reason you should just provide events for all days through the events attribute, and the component will automatically separate these events onto days. It is also possible to avoid loading the whole data in case of dealing with large amounts of data, see the Handling Large Datasets section for details.

Here's the simplest DayTable declaration that displays the specified events:

<o:dayTable events="#{MyBean.timetableEvents}"/>

The backing bean class for MyBean should have the following method:

public List getTimetableEvents() {
  List events = retrieveEvents(); // this should return a list of TimetableEvent instances
  return events;
}

This code displays a read-only timetable. In order to make it editable, you should specify the means by which the changes can be saved as described in the Adding Editing Capability section below.

Specifying "Reserved Time" Events

Besides the usual events that commonly specify various activities, such as meetings, work periods, etc., there's also a special type of events called reserved time events that doesn't have name, description and color fields and which cannot be edited or removed. These events can be represented with instances of class ReservedTimetableEvent and they have the following fields: id, resourceId, start, end, customProperties. These events can be included in the displayed event list along with the usual events, and they are meant to be used for displaying the time intervals that shouldn't normally be occupied by normal events, e.g. launch breaks, etc.

Adding Day Switcher

You can add the interface that allows the user to view and switch the currently displayed day by placing the <o:daySwitcher> component into the "header" facet of <o:dayTable> tag. Here's a simple example:

<o:dayTable events="#{TimeTableBean.events}">
  <f:facet name="header">
    <o:daySwitcher/>
  </f:facet>
</o:dayTable>

Please see the details in the Header and Footer and Navigation Between Days sections below.

Adding Editing Capability

The editing capability can be added by specifying the timetableChangeListener attribute of <o:dayTable> tag. This attribute should be declared as a value binding expression that refers to a method with one parameter of TimetableChangeEvent type. This method will be invoked to save changes made by the user. The TimetableChangeEvent class has the following methods that can be used to identify the changes that need to be saved:

  • getAddedEvents() – returns a non-null array of TimetableEvent instances that should be added to the database. Note that adding an event to the database will in most cases be accompanied with generating an ID for this event. Be sure to assign these new IDs to the appropriate event instances in the passed collection to ensure the correct functionality of DayTable component.
  • getEditedEvents() – returns a non-null array of TimetableEvent instances whose changes should be updated in the database.
  • getRemovedEventIds() – returns a non-null array of event Ids that should be removed from the database. 
        <blockquote>
    Be sure to assign an ID for all events returned by the getAddedEvents() method. 
        <p>Here's an example of declaring an editable <b><cite>DayTable</cite></b> that uses the second approach:</p>

    <div class="code panel" style="border-width: 1px;">
        <div class="codeContent panelContent">

    <o:dayTable
    events="#{MyBean.timetableEvents}"
    timetableChangeListener="#{MyBean.processTimetableChanges}"/>

            </div>
    </div>
    <p>And here's how <tt>processTimetableChanges</tt> method is implemented:</p>

    <div class="code panel" style="border-width: 1px;">
        <div class="codeContent panelContent">

    public void processTimetableChanges(TimetableChangeEvent tce) {
  TimetableEvent[] addedEvents = tce.getAddedEvents();
  for (TimetableEvent event : addedEvents) {
    String eventId = addEvent(event);
    event.setId(eventId);
  }

  TimetableEvent[] editedEvents = tce.getChangedEvents();
  for (TimetableEvent event : editedEvents) {
    updateEvent(event);
  }

  String[] removedEventIds = tce.getRemovedEventIds();
  for (String eventId : removedEventIds) {
    removeEvent(eventId);
  }
}

            </div>
    </div>
    <p>The <b><cite>DayTable</cite></b> component also has an <b>editable</b> attribute that specifies whether the
        editing capability is turned on. This attribute is set to <i>true</i> by default.</p></li>

Changing Editing Options

It is possible to customize various parameters of event editing behavior by adding a <o:timetableEditingOptions> tag inside of the <o:dayTable> tag.

By default the DayTable component automatically saves each change on the fly with Ajax. Though this functionality can be changed by specifying the autoSaveChanges attribute to false. Turning auto saving changes off will make the DayTable handle changes like any other editable component – the changes will be saved along with the nearest form submission. Regardless of whether auto saving functionality is used or not, the same mechanism for saving the changes is used as described in the previous section.

The default duration for new events is 30 minutes. This default value can be changed by specifying the defaultEventDuration attribute. This attribute specifies the number of minutes as an integer number.

It is possible to disable changing event duration by assigning "false" to the eventDurationEditable attribute. In addition, you can disable moving events from one resource to another by assigning "false" to the eventResourceEditable attribute.

By default the user can create any configuration of events even if time spans of events overlap. Though it is possible to disable an ability to create overlapped events by assigning false to the overlappedEventsAllowed attribute. Note that will only prevent creating overlapped events by using the DayTable's editing capabilities, but it won't prevent displaying overlapped events if such events are provided through the component's data model.

Handling Large Datasets

If a component should deal with large sets of data, you can minimize the data loaded by the DayTable using the preloadedEvents attribute. It can take on of the two values:

  • "all" (the default value) – specifies that DayTable will preload all of the events for all days. Having all events preloaded has a benefit of quick switching between days, since no data should be retrieved from the server when selecting another day. Though this can be a problem in case of very large sets of data since this would require transferring large amounts of data over the network, which would affect page load time.
  • "none" – specifies that only the events that need to be displayed are loaded from the server, which minimizes the page load time and makes it independent from the set of data. The data for other days in loaded with Ajax automatically when the user switches between days.

Since the second mode loads data in portions, some additional logic should be implemented in the data retrieval method – the method that is bound to the events attribute of <o:dayTable> tag. When a DayTable with preloadedEvents of "none" invokes the data retrieval method, it assigns the two request-scope variables named startTime and endTime of type java.util.Date, which specify the time range for which events should be returned. All events which at least partially intersect the time period specified with these variables should be returned.

Here's a simple example of defining the DayTable that loads events on demand as the user switches the days:

<o:dayTable
      events="#{MyBean.timetableEvents}"
      preloadedNodes="none" />
...

public List getTimetableEvents() {
Date startTime = Faces.var("startTime", Date.class);
Date endTime = Faces.var("endTime", Date.class);
List events = retrieveEventsInRange(startTime, endTime);
return events;
}

Showing a Multi-Resource Timetable

It is possible to configure a DayTable component to display a timetable for multiple resources. In this case the DayTable is displayed in multiple columns, one column per resource. Each resource has an independent schedule, and this mode can be thought of as multiple schedules for the same day displayed on the same timetable for convenience. As an added benefit it's possible to move events between the resources. The multi-resource mode can be turned on by declaring the resources attribute of the dayTable tag. This attribute should be declared as a value binding expression that refers to a collection or array of TimetableResource instances. The TimetableResource class defines parameters for a single resource displayed in a timetable:

  • id: String. This is a unique Id that identifies the resource.
  • name: String. The resource name displayed in DayTable's headers and editors.
  • object: String. An optional resource object that can be helpful when configuring custom resource header components.

It is possible to specify the custom resource header components by specifying the "resourceHeader" facet for the dayTable tag. The component specified in this facet will be rendered in the resource column header cells. The declaration of the "resourceHeader" component can use the "resource" request-scope variable that refers to an instance of TimetableResource that corresponds to the currently rendered resource header.

Here's an example of defining the multi-resource DayTable with custom resource headers displayed with a GraphicText component.

<o:dayTable events="#{MyBean.timetableEvents}">
  <f:facet name="resourceHeader">
    <o:graphicText direction="15" value="#{resource.name}" style="font-family: Arial; font-size: 14pt;"/>
  </f:facet>
</o:dayTable/>

Header and Footer

The DayTable component has the header and footer areas that are displayed as the top and the bottom of the day table. The content of these areas can be specified with the "header" and "footer" facets of the <o:dayTable> tag. The styles for these areas can also be customized using corresponding headerStyle/headerClass and footerStyle/footerClass attributes.

As described in the Showing a Multi-Resource Timetable section, the DayTable can also contain an additional header row that displays resource names. The style for this row can be customized with the resourceHeadersRowStyle/resourceHeadersRowClass attributes, and the style of the line that separates resource header row from events area can be specified with the resourceHeadersRowSeparator attribute, which is specified as the CSS border property but without the "border:" prefix, for example "1px solid gray".

Navigation Between Days

The DayTable component provides interface for switching the selected day. The navigation can be implemented using the exposed client side API that contains functions to swicth DayTable to next/previous day, for today or on any particular date (please refer to Client-Side API section for more information).
Another way to enable navigation in the DayTable is DaySwitcher component.

The DaySwitcher Component

The DaySwitcher component is denoted by the <o:daySwitcher> tag. It can be placed within the DayTable component, inside its "header" and "footer" facets or somewhere else on the page.

<o:dayTable id="conferenceSchedule" events="#{TimeTableBean.events}">
  <f:facet name="header">
    <o:daySwitcher/>
  </f:facet>
</o:dayTable>

The code above will produce the following output in the browser:

In case when <o:daySwitcher> specified outside of day table the for attribute should point to id of the corresponding <o:dayTable>.

<o:daySwitcher for="conferenceSchedule"/>
Specifying Date Format for DaySwitcher

The DaySwitcher component provides ability to specify date format to display selected date.
The pattern attribute specifies the date format with the pattern similar to that in the java.text.SimpleDateFormat class. Note that the DaySwitcher component supports only "d", "M", "y" and "E" pattern letters, which represent the components of the date. If an empty string is specified as pattern the corresponding text won't be displayed.
If no pattern is specified the dateFormat attribute can be used to set day format. It can take the following values: "short", "medium", "long", "full" and defines which of the predefined date formats should be used (default value is "long").
Similar attributes upperPattern and upperDateFormat for upper text format customization.

Here's examples of defining date format for DaySwitcher.

<o:daySwitcher for="dayTable" pattern="MMMM, dd" upperPattern="yyyy"/>
<o:daySwitcher for="dayTable" dateFormat="medium" upperPattern=""/>
Customizing Appearance of DaySwitcher

Besides the standard style and styleClass attributes DaySwitcher provides ability to set rolloverStyle and rolloverClass attributes. It is also possible to customize appearance of buttons using the following attributes:

<table class="confluenceTable">
    <tbody>
    <tr>
        <th class="confluenceTh"><u><i>Next</i></u> button attributes</th>
        <th class="confluenceTh"><u><i>Previous</i></u> button attributes</th>
    </tr>
    <tr>
        <td class="confluenceTd"><b>nextButtonStyle</b>/<b>nextButtonClass</b></td>
        <td class="confluenceTd"><b>previousButtonStyle</b>/<b>previousButtonClass</b></td>
    </tr>
    <tr>
        <td class="confluenceTd"><b>nextButtonRolloverStyle</b>/<b>nextButtonRolloverStyle</b></td>
        <td class="confluenceTd"><b>previousButtonRolloverStyle</b>/<b>previousButtonRolloverClass</b></td>
    </tr>
    <tr>
        <td class="confluenceTd"><b>nextButtonPressedStyle</b>/<b>nextButtonPressedClass</b></td>
        <td class="confluenceTd"><b>previousButtonPressedStyle</b>/<b>previousButtonPressedClass</b></td>
    </tr>
    <tr>
        <td class="confluenceTd"><b>nextButtonImageUrl</b></td>
        <td class="confluenceTd"><b>previousButtonImageUrl</b></td>
    </tr>
    </tbody>
</table>

    <p>and text using next attributes:</p>
Text attributes Upper text attributes
textStyle/textClass/textRolloverStyle/textRolloverClass upperTextStyle/upperTextClass

Internationalization

The DayTable allows specifying the locale used for displaying time strings using the locale attribute of <o:dayTable> tag. If not specified, the application's default locale is used, that is the locale returned by UIViewRoot's getLocale() method.

All Date instances that a DayTable is working on, e.g. event start and end dates are interpreted in a time zone specified with the timeZone attribute of <o:dayTable> tag. If not specified explicitly, the server's default time zone as defined by the TimeZone.getDefault() method is used.

It is also possible to customize all of the auxiliary texts and displayed by the component and its parts (day switcher, event editor, etc.), and patterns for formatting dates and times displayed in the component. Please refer to the Appearance Customization, Event Editor Dialog, and The DaySwitcher Component sections for details.

Appearance Customization

Like any other component, the style for the entire DayTable component can be customized with its style/styleClass attributes. Note that if the height CSS attribute is specified using these attributes then the DayTable component's scrollable mode is turned on automatically, which allows scrolling through the "invisible" part of the timeline using the vertical scrollbar.

Customizing Time Scale

It is possible to restrict the range of the displayed time range using the startTime and endTime attributes of the <o:dayTable> tag. Thes attributes should be specified in the "HH:mm" format, for example "16:00". Each of these attributes is optional, and if both of them are omitted then the whole time range from 00:00 to 24:00 is displayed. There's also the scrollTime attribute, works only for the scrollable DayTable (when it's height is specified), and it specifies the scroll position as the time in format "HH:mm" at the top component's border. For example, if "10:00" is specified, then the DayTable will be loaded to visually start from 10:00am though the user will be able to scroll the view to reveal the events before that time. The scrollTime attribute supports a two-side binding, which means that you can bind it to your backing bean to save the scroll position that might have been changted by the user.

All date/time formats are specified with the standard Java notation as specified by the SimpleDateFormat class.

The time scale represented by the DayTable compnent has a two-fold subdivision: there are major time intervals, and each major time interval is separated onto minor time intervals. These time intervals are displayed as the table rows on top of which the events are displayed. By default, the major time interval corresponds to one hour, and a minor one corresponds to half an hour, which results in two minor intervals per one major one by default. The size of these intervals can be customized using the majorTimeInterval and minorTimeInterval attributes of the <o:dayTable> tag respectively. These attributes should be specified as an integer number specifying the interval's duration in minutes, and the default values are 60 and 30 respectively. Note that the value of majorTimeInterval should be a multiple of minorTimeInterval value.

The separators displayed at major and minor intervals have different styles and they can be customized with the primaryRowSeparator and secondaryRowSeparator attributes, whose values are specified as the CSS border attribute value, but without the "border:" prefix, for example, "1px solid gray".

The height and background CSS attributes of the time slot rows can be customized with the rowStyle/rowClass attributes of the <o:dayTable> tag.

Time Column Customization

The style for the time column can be specified using the timeColumnStyle/timeColumnClass attributes. The style of the line that separates time column from the events are can be customized using the timeColumnSeparator attribute, which is specified in the same format as the primaryRowSeparator and secondaryRowSeparator attributes described above (for example "1px solid gray").

By default, the time strings in the time column are displayed in the H mm pattern, with the minute part being displayed as a superscript. Technically, the time string consists of two parts, displayed beside each other, where each part has its own time pattern and a style, which allows to display the minutes as superscript in the default display. The patterns for the first and the second part are specified with the timePattern and timeSuffixPattern attributes, which have the default values of "H" and "mm" respectively. The main part of time text, specified by the timePattern is displayed with the style inherited from the column class, as defined by the columnStyle/columnClass attributes. The style for the "time suffix" part of time string can be customized using the timeSuffixStyle/timeSuffixClass attributes.

The horizontal time slot separators within the time column can be customized using the timeColumnPrimaryRowSeparator and timeColumnSecondaryRowSeparator attributes, which specify the style of grid lines for the primary time intervals and secondary time intervals respectively.

As was mentioned in the Customizing Time Scale seciton, there are horizontal and minor time intervals. By default, the time column displays time only for the major intervals. You can turn on displaying time for the minor intervals by specifying the showTimeForMinorIntervals attribute with a value of true. The styles for major and minor time texts can be customized individually with the majorTimeStyle/majorTimeClass and minorTimeStyle/minorTimeClass attributes respectively.

By default, the time text is displayed under the grid-line that marks the appropriate time. It is change the time text position so that it be displayed right against the appropriate grid-line. This can be done by specifying the timeTextPosition attribute with a value of "againstMark" (the default value is "underMark".

Customizing Event Appearance

As it was mentioned in the Configuring Displayed Events section, each event can be displayed with its individual color according to the color field of the event object. Though the value of the color field is optional and if it is not specified (has a value of null) then the appropriate event is displayed with the default event color. This color can be customized using the defaultEventColor attribute of <o:dayTable> tag.

There's a range of settings that define various aspects of how events are displayed and behaving in the <o:timetableEvent> tag, which should be placed inside of <o:dayTable> tag.

Event's border and background color is calculated automatically based on the event's color field.

The CSS style for the events can be customized with the style and styleClass attributes of the <o:timetableEvent> tag. The border is displayed in the unchanged event's color, and the background color is displayed in the same color but of less intensity. The level of color intensity for event's background can be customized with the backgroundIntensity, which is specified as a double number in range 0..1. 0 corresponds to the least-intense color – white, and 1 corresponds to a fully intense color – a color specified for this event (the same color as used for displaying event's borders). The default value is 0.25 to ensure good reading contrast while still displaying the event color. Note that the behavior of automatic border and background calculation can be overridden by explicit specification of border and/or background CSS attributes in the style and styleClass attributes.

The event's background also has a certain degree of transparency, which can be customized with the backgroundTransparency attribute, which is also specified as a double value in range 0..1 where 0 corresponds to fully opaque background and 1 means fully transparent one (the default value is 0.2).

The style for the rollover event (the event located under the mouse pointer) can be customized using the rolloverStyle/rolloverClass attributes of the <o:timetableEvent> tag.

By default, any HTML formatting characters contained in the event's name and description strings are escaped to show the pure textual representation as defined by the strings, which makes it impossible to use HTML constructs for example to highlight certain portions of name or description. The escaping behavior can be turned off by assigning false to the escapeName and/or escapeDescription attribute of the <o:timetableEvent> tag.
The style for the whole name and description strings can be customized separately using the nameStyle/nameClass and descriptionStyle/descriptionClass attributes respectively.

The <o:timetableEvent> tag also has a set of attributes allowing to specify client-side event handlers for the HTML element that displays the timetable event: onclick, ondblclick, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup. There's also an additional timetable-event-specific oncreate event, which is when a client-side representation element is created for each individual event. Each of these events receive the usual event variable, though this event variable has an additional field named timetableEvent, which refers to the client-side timetable event object for which the event is triggered. See the Client Side API section for details on this object. This allows adding custom interactions for the event's HTML representation elements.

"Reserved Time" Events Appearance

As it was mentioned in the Configuring Displayed Events section, there's a special type of events called "reserved events" and specified with ReservedTimeEvent instances in the event list. These events are displayed in a special way: they don't have a name and description and have a separate set of attributes that customize their appearance:

  • reservedTimeEventColor – the ReservedTimeEvent class doesn't have the color field, and all of the reserved time events are displayed with the color specified in this attribute.
  • reservedTimeEventStyle/reservedTimeEventClass – specify the CSS style for all reserved time events. In particular, the background CSS attribute will often be used to specify custom shading images.
Customizing Event Action Bar

The event action bar is an area that appears on the event's bottom side when hovering a mouse over the event element. It contains an auxiliary text that notifies of the "click on edit" behavior, and contains the event deletion button by default. The contents of the event action bar can be customized using the <o:eventActionBar> tag, which should be placed into the <o:dayTable> tag.

Like background color of the event element, background color of the event action bar and its buttons is calculated using the event's color. The intensity of the action bar's background color can be customized using the backgroundIntensity attribute, and intensity for the various states of action bar's buttons is specified with the actionRolloverBackgroundIntensity/actionPressedBackgroundIntensity attributes. As usual, the style of the event action bar itself can be customized with the style/styleClass attributes.

The text displayed in the action bar can be changed using the noteText attribute.

And the main feature of the action bar is an ability to specify event-specific actions. By default, it just contains the "delete event" action, but you can add more events and/or remove the default one by placing one of the following tags inside of the <o:eventActionBar>:

  • deleteEventAction – the standard event deletion action, which can be specified explicitly to customize its appearance or remove it at all (see below).
  • eventAction – allows adding custom event actions.

When at least one action tag is added inside of <o:eventActionBar>, the default set of buttons (or just the "delete" button actually) is removed and replaced with the explicitly specified set of actions. In order to remove the default "delete" button you should place the deleteEventAction tag and specify its rendered attribute with a value of false. Each of the action tags has a set of attributes that specify its appearance: style/styleClass, rolloverStyle/rolloverClass, pressedStyle/pressedClass – for customizing the styles, and imageUrl/rolloverImageUrl/pressedImageUrl for customizing action button's images in various state. There's also the hint attribute, which specifies the tool tip text for the action button.

The <o:deleteEventAction> tag has the showConfirmation attribute, which as the name says defines whether the event deletion confirmation will be shown when pressing the action button.

The <o:eventAction> tag has the usual attributes that are normally available for all button tags: acitonListener and onclick for implementing server-side and client-side event handlers appropriately. The event parameter of the onclick handler function has an additional non-standard field named timetableEvent which refers to the client-side timetable event object corresponding to the event on which the action button is clicked. Specifying the acitonListener attribute will trigger the specified server action. The optional scope attribute specifies the amount of page's area, which can be affected by the server action:

  • "page" (default value) – the whole page is submitted and reloaded when the action is invoked;
  • "timetable" – only the timetable is submitted and reloaded with Ajax when the action is invoked.
Customizing Event Deletion Confirmation

The appearance of the event deletion confirmation (if not turned off as described in the Customizing Event Action Bar section above) can be customized by adding the <o:confirmation> tag to the "deleteEventConfirmation" facet of the <o:dayTable} tag and customizing its attributes appropriately. Here's an example:

<o:dayTable ...>
  <f:facet name="deleteEventConfirmation">
    <o:confirmation message="Removing event" details="Proceed with removing?" okButtonText="YES" cancelButtonText="NO"/>
  </f:facet/>
  ...
</o:dayTable>
Attaching Additional Event Areas

If the standard output displayed in the event elements (name, description, action bar, etc.) is not enough, it is possible to attach custom output areas to event elements. This can be done by placing one or more <o:eventArea> tags inside of <o:dayTable> tag. Each <o:eventArea> defines an area that should be attached to each event element. Here's a simple example:

<o:dayTable id="dayTable" eventVar="event" ...>
  <o:eventArea verticalAlignment="above">
    <o:commandLink render="dayTable" actionListener="#{MyBean.postpone}" value="Postpone #{event.name}"/>
  </o:eventArea>
  ...
</o:dayTable>
...

public void postpone(ActionEvent actionEvent) {
TimetableEvent event = Faces.var("event", TimetableEvent.class);
...
}

As you can see in the example, you can place any components into the <o:eventArea> tag and those components can use the request-scope variable whose name is specified in the eventVar attribute of the <o:dayTable> tag. This variable refers to the to the TimetableEvent whose event area is currently being rendered. Similarly, you can use the same variable in the event handler code to discover the TimetableEvent on which for which server-side event has been triggered. The <o:eventArea> tag has the following two attributes that define where the area is to be positioned relative to the event's rectangle: horizontalAlignment and verticalAlignment. The horizontalAlignment attribute can take one of the following values:

  • "leftOutside" – makes an area to be displayed to the left of an event rectangle.
  • "left" – makes the left edge of an area to be algined with the left edge of an event rectangle.
  • "center" – makes an area centered horizontally relative to an event rectangle.
  • "right" – makes the right edge of an area to be algined with the right edge of an event rectangle.
  • "rightOutside" – makes an area to be displayed to the right of an event rectangle rectangle.

And the verticalAlignment attribute can take the following values:

  • "above" – makes an area to be displayed above an event rectangle.
  • "top" – makes the top edge of an area to be algined with the top edge of an event rectangle.
  • "center" – makes an area centered vertically relative to an event rectangle.
  • "bottom" – makes the bottom edge of an area to be algined with the bottom edge of an event rectangle.
  • "below" – makes an area to be displayed below an event rectangle.

The event area doesn't have any style of its own by default, though you can specify one using the style and styleClass attributes. As usual, there's also the client-side event handler attributes: onclick, ondblclick, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup.

It is possible to attach several event areas by specifying several <o:eventArea> tags.

Displaying Event Preview

In certain application scenarios, event description can be quite a long one and since event height is identified by event's duration it might not be possible to read the full description in some cases. This can be solved by displaying the "event preview" area when the mouse hovers over an event for some time. This functionality can be turned on by placing the <o:eventPreview> tag to the <o:dayTable> tag.

Adding this tag will make the event preview rectangle to be displayed above the element automatically when the mouse hovers over the event for a while. The event preview area will show the full event name and description. The delay after which the preview is shown can be customized by specifying the appropriate number of milliseconds in the showingDelay tag of the <o:eventPreview> tag. The position relative to the event rectangle is customized with the horizontalAlignment and verticalAlignment attributes, which have the same values as the analogous attributes of the eventArea tag described in the Attaching Additional Event Areas section above. In addition to the alignment attributes, it's also possible to specify the distance between the event rectangle and the event preview rectangle using the horizontalDistance and verticalDistance attributes. The event preview is automatically hidden when the user moves the mouse pointer out of the event rectangle.

The style for the event preview itself can be customized with the style/styleClass attributes, and the style for event name and description with the eventNameStyle/eventNameClass and eventDescriptionStyle/eventDescriptionClass respectively.

Customizing Effects

The DayTable component smoothens transition between time-slots when using event drag&drop. That is, when a user drags an event to another time slot, the event doesn't "jump" to the new position instantaneously but is gradually moved to the new position. The speed of this transition can be customized with the dragAndDropTransitionPeriod attribute which accepts the transition duration as a number in milliseconds. The default value is 70. You can turn off smooth transition by specifying 0 as the value for this attribute.

When time-overlapping events are disabled with the overlappedEventsAllowed attribute of the <o:timetableEditingOptions> tag, and the user is trying to drag an event over another event or resize it so that it becomes overlapped with some other event, the DayTable returns the event to its original position as it was before moving/resizing. This is also done by gradual transition of event's rectangle instead of just "jumping" to the original place, and the duration for this transition is customizible with the dragAndDropCancelingPeriod.

In addition, while a user is dragging an event and it is an "undroppable" position (that is over another event), the DayTable makes the dragged event semitransparent to let the user know of this situation. The transparency level for the "undroppable" state can be customized with the undroppableEventTransparency attribute (as a double number in range 0..1), and the gradual transition period to and from "undroppable" state is customizible with the undroppableStateTransitionPeriod attribute.

Customizing Event Editor

When a user clicks an event of an editable DayTable or clicks an empty area to create a new event, the event editor is shown. The default behavior is showing a dialog for event editing, though the kind of event editor and its appearance can be customized using the "eventEditor" facet of <o:dayTable> tag. There are two kinds of event editors that can be specified in this facet:

  • Event editor dialog, which is specified by the <o:eventEditorDialog> tag. This is the default kind of event editor, though you use this tag explicitly to customize the dialog.
  • Event editor page, which is specified by the <o:eventEditorPage> tag. Displays a custom event editor page instead of the dialog when a user clicks on an event.
Event Editor Dialog

You can customize the default event editor dialog by placing the <o:eventEditorDialog> tag into the "eventEditor" facet of <o:dayTable> tag.

Event editor dialog is displayed as a modal window, so most of the customization settings available for the Window component are available for the EventEditorDialog component as well. That is you can customize window options with the following attributes:

  • draggable and draggableByContent for customizing if and how an editor window can be dragged around on the page (by default, draggable is true and draggableByContent is false, which means that the window can be dragged by window's caption);
  • resizable for specifying whether the window is resizable (true by default);
  • left/top for customizing the default position of the editor window;
  • style/styleClass, rolloverStyle/rolloverClass for customizing style for the entire window;
  • width/height and minWidth/minHeight for customizing the default size and the minimal size for the editor window respectively;
  • modalLayerStyle/modalLayerClass for customizing the style of the background layer that covers the page when the window is shown;
  • captionStyle/captionClass and contentStyle/contentClass for customizing styles for window's caption area content areas respectively.

The window's caption can be customized with the createEventCaption and editEventCaption attributes which specify a caption text to be shown in an editor window in case of creating a new event and editing an existing event respectively.

The texts for field labels and buttons in the editor dialog can be customized with the following attributes: nameLabel, resourceLabel, startLabel, endLabel, descriptionLabel, okButtonText, cancelButtonText, and deleteButtonText.

Style for the labels can be customized using the labelStyle/labelClass attributes. Button styles are customizeable using the following attributes: okButtonStyle/okButtonClass, cancelButtonStyle/cancelButtonClass, deleteButtonStyle/deleteButtonClass.

You can customize the style and appearance of all editing fields by placing the properly customized components into the appropriate facets as shown below. Note that no data-specific configuration should be performed when declaring the components because the data is managed by the dialog automatically. Instead, you can specify the style and appearance-related attributes to make these components look in an application-specific manner.

  • "nameField" facet. Accepts <h:inputText> or <o:inputText> components.
  • "resourceField" facet. Accepts <o:dropDownField> component.
  • "startDateField" and "endDateField" facets. Accept <o:dateChooser> components.
  • "startTimeField" and "endTimeField" facets. Accept <h:inputText> or <o:inputText> components.
  • "descriptionArea" facet. Accepts <h:inputTextarea> or <o:inputTextarea> components.

Here's an example that demonstrates customizing editor dialog's caption, labels and some of the editor fields:

<o:dayTable ...>
  <f:facet name="eventEditor">
    <o:eventEditorDialog labelStyle="font: normal 10pt Tahoma, Arial; color: darkgrey"
            captionStyle="font: normal 12pt Tahoma, Arial; color: darkgrey"
            deleteButtonStyle="color: red;">
      <f:facet name="nameField">
        <h:inputText style="color: blue"/>
      </f:facet>
      <f:facet name="startDateField">
        <o:dateChooser fieldStyle="color: blue" calendarStyle="border: 1px solid blue"/>
      </f:facet>
      <f:facet name="descriptionArea">
        <o:inputTextarea promptText="Enter event description here"/>
      </f:facet>
    </o:eventEditorDialog>
  </f:facet>
  ...
</o:dayTable>

Like the ordinary Window component, the event editor dialog has all of the standard events (onclick, ondblclick, onmousedown, onmouseover, onmousemove, onmouseout, onmouseup, onkeydown, onkeyup, onhkeypress), and two custom events onshow and onhide that are fired when the window is shown and hidden respectively.

Event Editor Page

You can replace the standard event editor dialog with a custom page for editing an event by placing the <o:eventEditorPage> tag into the "eventEditor" facet of <o:dayTable> tag.

You can specify the actual event editor page in two ways:

  • using the url attribute where you should specify a url of the editor page just like you would specify in an output link, or
  • using the action attribute that allows executing an action on the server before showing the editor page. This attribute should be specified in the same way as the action attribute of <h:commandLink> tag, which means that the backing bean method should return a proper navigation string that will lead to the actual editor page.

All of the parameters of the edited (or created) event are passed in the following request parameters:

  • "mode" parameter. Specifies the kind of editing that the user has requested – event creation ("create" value), or event * editing ("update" value). (*)
  • "eventId" parameter. Applicable only for the "update" mode, e.g. when the user is editing an event. Specifies id of the event that should be edited. (*)
  • "eventStart" parameter. Applicable only for the "create" mode, e.g. when the user is creating an event. Specifies the start time of the created event according to the user's click in the "dd/MM/yyyy HH:mm" format.(**)
  • "eventEnd" parameter. Applicable only for the "create" mode, e.g. when the user is creating an event. Specifies the end time of the created event according to the user's click in the "dd/MM/yyyy HH:mm" format.(**)
  • "resourceId" parameter. Applicable only for the "create" mode, e.g. when the user is creating an event. Specifies the resource id for the created event according to the user's click. You can ingnore this parameter for DayTables where resource separation is not used. (*)

(*) You can simplify retrieving the request parameters by using the org.openfaces.util.Faces.var(String varName) function.
(**) You can simplify retrieving the request parameters formatted as date in the mentioned format by using the org.openfaces.util.Faces.requestParam(String paramName, Class<T> expectedType) function, e.g. Faces.requestParam("eventStart", Date.class).

Note that these are passed as request parameters to the first request of the specified page and are not resubmitted automatically upon with a next request, so you'll need to save them in a "session" or another appropriate scope to save these parameters between requests.

Your custom editor page should process these parameters and configure the editing components appropriately. You can use the provided eventId for retrieval of all data data for the edited event.

Upon pressing on the "Save" button (or any analog on your page) you should manually update the underlying data storage for the DayTable component (or add a new event in case of event creation) and navigate back to the DayTable page.

Custom Event Editor

You can create a custom event editor by placing the <o:customEventEditor> tag into the "eventEditor" facet of <o:dayTable> tag. This tag has the following two attributes:

  • oncreate: specifies the JavaScript code that should show the event editor for creating a new event according to the passed parameters.
  • onedit: specifies the JavaScript code that should show the event editor for editing an existing event according to the passed parameters.

In both cases the code specified in these attributes has access to following variables

  • timetable: a reference to the DayTable component for which the editor is invoked.
  • timetableEvent: a reference to the timetable event object that should be edited. In case of event editing it contains the current data of the appropriate event, and in case of event creation this object contains just the start and end times according to user's click.

The custom event editor should update the passed timetableEvent instance and invoke the following client-side methods of DayTable component depending on situation:

  • addEvent(event) when editing is finished on adding a new event and event should actually be created. This method will update event presentation and save data to the server if required by the current editing settings.
  • cancelEventCreation(event) when event creation is canceled within the custom editor. This method should be invoked to hide the temporary event presentation that was shown when a user clicked on a timetable to create an event. This method shouldn't be invoked when editor is shown for an existing event, or when a user confirms editing.
  • updateEvent(event) when editing for an existing event is completed and the appropriate timetable event fields are updated. This method will update event presentation and save data to the server if required by the current editing settings.
  • deleteEvent(event) if an event should be deleted.

See the Client-Side API section for the description of all DayTable's client-side methods and event object fields.

Client-Side API

All client-side API methods for the DayTable component are listed in the following table:

Method Description
getDay() Returns a Date object that defines a day currently selected in the DayTable component.
setDay(day) Switches the currently displayed day for the DayTable component. The day parameter should be a JavaScript Date object.
nextDay() Switches the currently displayed day in the DayTable component to the next day.
previousDay() Switches the currently displayed day in the DayTable component to the previous day.
today() Switches the currently displayed day in the DayTable component to today.
updateLayout() Updates layout for visible events in the DayTable component. This function can be useful in case of page layout changes where the size of DayTable is affected, and thus events might need a relayout.
saveChanges() Sends all unsaved changes to the server and updates all events for the current day. This can particularly be useful for DayTables with autoSaveChanges set to false in <o:timetableEditingOptions>.
refreshEvents(serverAction) Reloads the displayed events from the server and invokes the specified server action as part of the request. The serverAction parameter should be specified in the "Bean.methodName" format.
getEventById(eventId)  
addEvent(event) Adds a timetable event as specified by the passed event object (see below). The added event is also asynchronously saved in case when autoSaveChanges attribute of <o:timetableEditingOptions> is set to true.
updateEvent(event) Accepts a timetable event object that exists in a timetable though contains some unsaved modifications. This method makes the changes in the passed event to be picked up and displayed appropriately. This method also asynchronously sends the modifications to the server if autoSaveChanges attribute of <o:timetableEditingOptions> is set to true.
deleteEvent(event) Deletes the specified event from a timetable. This method asynchronously sends this modification to the server if autoSaveChanges attribute of <o:timetableEditingOptions> is set to true.
cancelEventCreation(event) This method should be invoked when canceling an event creation in a custom event editor to remove the temporary event presentation.

The client-side timetable event objects manipulated by the methods mentioned above are direct counterparts of server-side TimetableEvent instances. The timetable event objects have the following structure:

Member Description
id String identifier of this event. Counterpart of TimetableEvent's id attribute.
name Event name. Counterpart of TimetableEvent's name attribute.
description Event description. Counterpart of TimetableEvent's description attribute.
resourceId If specified, defines string identifier of a resource to which this event is assigned. Counterpart of TimetableEvent's resourceId attribute.
start Event start time as a JavaScript Date object. Counterpart of TimetableEvent's start attribute.
end Event end time as a JavaScript Date object. Counterpart of TimetableEvent's end attribute.
color An optional event color string as a hexadecimal value in a form #RRGGBB, e.g."#80FFB0". Counterpart of TimetableEvent's color attribute.
customProperties Associative JavaScript array of custom event's custom properties. This field can be undefined if an event has no custom properties. Counterpart of TimetableEvent's customProperties attribute. Note that changes made in the custom properties array on the client-side are not sent back to the server as part of the saved data.
type Defines the type of an event. It is equal to "reserved" for reserved time events and is undefined for ordinary events.
mainElement A reference to a DOM element that displays this event. This variable can be undefined if a corresponding event is not being shown on the currently displayed day.
backgroundElement A reference to an additional DOM element that displays a background this event. This variable can be undefined if a corresponding event is not being shown on the currently displayed day.
updatePresentation() Updates presentation for this event according to the current state of this event's fields.
Clone this wiki locally