29 Using Timeline Components

This chapter describes how to use the ADF Data Visualization timeline component to display data using simple UI-first development. The chapter defines the data requirements, tag structure, and options for customizing the look and behavior of the component.

If your application uses the Fusion technology stack, then you can also use data controls to create timelines. For more information, see the "Creating Databound Gantt Chart and Timeline Components" chapter of Developing Fusion Web Applications with Oracle Application Development Framework.

This chapter includes the following sections:

• About Timeline Components

• Using Timeline Components

• Adding Data to Timeline Components

• Customizing Timeline Display Elements

• Adding Interactive Features to Timelines

About Timeline Components

An ADF DVT Timeline is an interactive data visualization tool that allows users to view events in chronological order and easily navigate forwards and backwards within a defined time range. Events are represented as timeline items using simple ADF components to display information such as text and images, or supply actions such a links.

A dual timeline can be configured to display two series of events to allow a side-by-side comparison of related information. The timeline component also supports an adjustable time range to change the view for zooming in or out.

Timeline Use Cases and Examples

A timeline is composed of the display of events as timeline items along a time axis, a movable overview window that corresponds to the period of viewable time in the timeline, and an overview time axis that displays the total time increment for the timeline. A horizontal zoom control is available to change the viewable time range. Timeline items corresponding to events display related information or actions and are represented by a line feeler to the time axis and a marker in the overview time axis.

For example, the timeline in Figure 29-1 is configured to display the chronological order of Employee Presentations in the ADF Faces Components Demo application. In this example, timeline items representing each event display information about the event with a label and a subheading. The overview window defines the time range for the display of the timeline items, adjustable by changing the zoom control or by changing the edges of the window to a larger or smaller size. When selection is configured, the timeline item, line feeler, and the event marker in the overview panel are highlighted.

Figure 29-1 Timeline of Employee Hire Dates

A dual timeline can be used for comparison of up to two series of events. Figure 29-2 illustrates a dual timeline comparing employee change events for two employees over a ten year time period. Timeline events are displayed using a quarterly year time axis within the three plus year overview window. The current date is represented with a line in the overview time axis.

Figure 29-2 Dual Timeline Comparing Employee Change Events

End User and Presentation Features

To understand how timelines are used and can be customized, it is helpful to understand these elements and features.

Timeline Overview Options

By default timelines support an overview panel that includes a movable overview window corresponding to the period of viewable time in the timeline. An optional overview time axis that displays the total time increment for the timeline with adjustable zoom levels can be added to a timeline.

Figure 29-3 shows a timeline of speaking engagements with the overview panel displaying events occurring during a specific time period of the timeline. The time axis for the timeline displays the total time increment with adjustable zoom levels between hourly and half years.

Figure 29-3 Timeline Overview Panel and Time Axis

Description of "Figure 29-3 Timeline Overview Panel and Time Axis"

Layout Options

By default, timelines are displayed in a horizontal orientation with events laid out along a horizontal time axis and overview panel. You can change the layout to a vertical orientation with events displayed along a vertical time axis and overview panel. While you can specify that timeline items in a horizontal orientation will not overlap each other in the display, you cannot apply that configuration to items in a vertical orientation.

Figure 29-4 illustrates a timeline of speaking events, with a vertical orientation.

Figure 29-4 Timeline Horizontal and Vertical Orientations

Timeline Item Selection

Each event displayed in the timeline is represented as a timeline item that can include data display components such as images, text, and text labels, or actions such as links, buttons, and menus. A line feeler connects the event to the date in the time axis of the timeline. Events are represented in the overview panel as a configurable marker.

By default timeline items are not configured for selection at runtime. You can configure selection of a single or multiple timeline items. At runtime the event, the line feeler, and the marker in the overview panel are highlighted.

Content Delivery

Timelines can be configured for how data is delivered from the data source. The data can be delivered to the timeline either immediately upon rendering, as soon as the data is available, or lazily fetch after the shell of the component has been rendered. By default, timelines support the delivery of content from the data source when it is available. The contentDelivery attribute is set to whenAvailable by default.

Timelines are virtualized, meaning not all data on the server is delivered to and displayed on the client. You can configure timelines to fetch a certain number of rows or columns at a time from your data source based on date related values. Use fetchStartTime and fetchEndTime to configure fetch size.

Timeline Image Formats

Timelines support the following image formats: HTML5, Flash, and Portable Network Graphics (PNG). All image formats support locales using right-to-left display.

By default, timelines will display in the best output format supported by the client browser. If the best output format is not available on the client, the application will default to an available format. For example, if the client does not support HTML5, the application will use:

• Flash, if the Flash Player is available

  You can control the use of Flash content across the entire application by setting a flash-player-usage context parameter in adf-config.xml. For more information, see Configuring Flash as Component Output Format.

• PNG output format

  Although static rendering, such as maintaining pan and zoom state of the Flash display, is fully supported when using the printable PNG output format, certain interactive features are not available including:

  • Animation

  • Context menus

  • Drag and drop gestures

  • Popup support

  • Selection

Timeline Display in Printable or Emailable Pages

ADF Faces allows you to output your JSF page from an ADF Faces web application in a simplified mode for printing or emailing. For example, you may want users to be able to print a page (or a portion of a page), but instead of printing the page exactly as it is rendered in a web browser, you want to remove items that are not needed on a printed page, such as scrollbars and buttons. If a page is to be emailed, the page must be simplified so that email clients can correctly display it.

ADF Faces allows you to output your JSF page from an ADF Faces web application in a simplified mode for printing or emailing. For example, you may want users to be able to print a page (or a portion of a page), but instead of printing the page exactly as it is rendered in a web browser, you want to remove items that are not needed on a printed page, such as scrollbars and buttons. If a page is to be emailed, the page must be simplified so that email clients can correctly display it. For information about creating simplified pages for these outputs, see Using Different Output Modes .

When a timeline is displayed on a JSF page to be output in printable or emailable pages:

• Only the events currently in view on the timeline will be included in the content.

• In email mode, the events will be displayed as a table.

• In print mode, the timeline overview is not rendered.

Additional Functionality for Timeline Components

You may find it helpful to understand other ADF Faces features before you implement your timeline component. Additionally, once you have added a timeline to your page, you may find that you need to add functionality such as validation and accessibility.

Following are links to other functionality that timeline components can use:

• Partial page rendering: You may want a timeline to refresh to show new data based on an action taken on another component on the page. For more information, see Rerendering Partial Page Content.

• Personalization: When enabled, users can change the way the timeline displays at runtime. Those values will not be retained once the user leaves the page unless you configure your application to allow user customization. For information, see Allowing User Customization on JSF Pages.

• Accessibility: Timeline components are accessible, as long as you follow the accessibility guidelines for the component. See Developing Accessible ADF Faces Pages.

• Touch devices: When you know that your ADF Faces application will be run on touch devices, the best practice is to create pages specific for that device. For additional information, see Creating Web Applications for Touch Devices Using ADF Faces.

• Content Delivery: You can configure your timeline to fetch data from the data source immediately upon rendering the components, or on a second request after the components have been rendered using the contentDelivery attribute. For more information, see Content Delivery.

• Automatic data binding: If your application uses the Fusion technology stack, then you can create automatically bound timelines based on how your ADF Business Components are configured. For more information, see the "Creating Databound Gantt Chart and Timeline Components" chapter of Developing Fusion Web Applications with Oracle Application Development Framework.

  Note:

  If you know the UI components on your page will eventually use ADF data binding, but you need to develop the pages before the data controls are ready, then you should consider using placeholder data controls, rather than manually binding the components. Using placeholder data controls will provide the same declarative development experience as using developed data controls. For more information, see the "Designing a Page Using Placeholder Data Controls" section in Developing Fusion Web Applications with Oracle Application Development Framework.

Additionally, data visualization components share much of the same functionality, such as how content is delivered, automatic partial page rendering (PPR), and how data can be displayed and edited. For more information, see Common Functionality in Data Visualization Components.

Using Timeline Components

To use the ADF DVT Timeline component, add the timeline to a page using the Component Palette window. Then define the data for the timeline and complete the additional configuration in JDeveloper using the tag attributes in the Properties window.

Timeline Component Data Requirements

The data layer for the timeline component is specified in its child, the timeSeries component. You must specify at least one time series, at most two in the case of a dual timeline, using a model to access data from the underlying source.

The specific model class to use is an instance of org.apache.myfaces.trinidad.model.CollectionModel. This class extends the JSF DataModel class and adds on support for row keys. In the DataModel class, rows are identified entirely by index. However, to avoid issues if the underlying data changes, the CollectionModel class is based on row keys instead of indexes.

You may use other model instances, such as java.util.List, java.util.ArrayList, and javax.faces.model.DataModel. The timeline series component will automatically convert the instance into a CollectionModel, but without any additional functionality. For information about the CollectionModel class, see the MyFaces Trinidad Javadoc at http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.html.

Timelines require that the following attributes be set for the timelineSeries component in JDeveloper:

• value: An EL Expression that references the data model represented in the timeline.

• var: The name of a variable to be used during the rendering phase to reference each element in the timeline collection. This variable is removed or reverted back to its initial value once rendering is complete.

Each immediate child of a timeSeries component must be at most one timeItem component. This component makes it possible to customize the event content through its title, description and thumbnail attributes.

Each time a time item is created, the value for the current item is copied into a var property, and optionally, additional data for the item is copied into a varStatus property. These properties can be accessed in EL expressions inside the time item component, for example, to pass the item value to the title attribute. Once the timeline has completed rendering, the var and varStatus properties are removed, or reverted back to their previous values.

The values for the value, var, and optionally, varStatus attributes must be stored in the timeline's data model or in classes and managed beans if you are using UI-first development.

The example below shows a code sample that adds a TimelineCBBean managed bean to your application that references the class or bean that contains the data, and optionally, adds any other methods to customize the timeline. Not all list items in the data set specified by the ArrayList class are included in the example.

//imports needed by methods
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.Iterator;
import java.util.Set;
import javax.faces.bean.ManagedBean;
import javax.faces.bean.SessionScoped;
import javax.faces.bean.RequestScoped;
import javax.faces.component.behavior.ClientBehavior;
import javax.faces.component.behavior.ClientBehaviorHint;
import javax.faces.event.AjaxBehaviorEvent;
import oracle.adf.view.faces.bi.component.timeline.UITimeSeries;
import org.apache.myfaces.trinidad.model.CollectionModel;
import org.apache.myfaces.trinidad.model.ModelUtils;
import org.apache.myfaces.trinidad.model.RowKeySet;
@ManagedBean(name="cb")
public class TimelineCBBean
{
  private CollectionModel m_model;
  public TimelineCBBean()
  {
    super();
  }
  public CollectionModel getModel()
  {
    if (m_model != null)
    return m_model;
    ArrayList _list = new ArrayList(10);
      _list.add(new EmpEvent("0", parseDate("01.13.2010"), "Oracle Application
          Express", "se198AyXcsk", null));
      _list.add(new EmpEvent("1", parseDate("01.27.2010"), "Larry Ellison on the
          Sun-Oracle Close", "ylNgcD2Ay6M", null));
      ...

    m_model = ModelUtils.toCollectionModel(_list);
    return m_model;
  }        
  public void handleKey(AjaxBehaviorEvent event)
  {
    ClientBehavior _behavior = (ClientBehavior)event.getBehavior();
    Set<ClientBehaviorHint> _hints = _behavior.getHints();
    UITimeSeries _series =
      (UITimeSeries)event.getComponent().findComponent("ts1");
    if (_series == null)
      return;
      RowKeySet _rowKeySet = _series.getSelectedRowKeys();
      Iterator _iterator = _rowKeySet.iterator();
      ArrayList _list = (ArrayList)m_model.getWrappedData();
      while (_iterator.hasNext())
      {
        Object _rowKey = _iterator.next();
        Object _event = m_model.getRowData(_rowKey);            
        _list.remove(_event);
      }
    }
    private static Date parseDate(String date)
    {
      Date ret = null;
      try
      {
        ret = s_format.parse(date);
      }
      catch (ParseException e)
      {
        e.printStackTrace();
      }
        return ret;
    }
static DateFormat s_format = new SimpleDateFormat("MM.dd.yyyy");

The managed bean example provides the data model for the Employee Presentations timeline displayed in Figure 29-5. You can find the complete source code for the TimelineCBBean in the ADF Faces Components Demo application. For information about the demo application, see ADF Faces Components Demo Application .

Figure 29-5 Timeline of Employee Presentations

Configuring Timelines

The timeline component has configurable attributes and child components that you can add or modify to customize the display or behavior of the timeline. The prefix dvt: occurs at the beginning of each timeline component name indicating that the component belongs to the ADF Data Visualization Tools (DVT) tag library.

You can configure timeline child components, attributes, and supported facets in the following areas:

• Timeline component (timeline): The parent component that wraps the timeline child components and facets.

• Timeline series (timeSeries): The immediate child of the timeline component used to specify the data layer for the timeline. You must specify at least one series in a timeline. You can also specify up to one additional series to be used for a comparison between timelines.

  The timeline series component supports facets that can be used to configure context menus including:

  • bodyContextMenu: Specifies a context menu that is displayed on non-selectable elements in the timeline component.

  • contextMenu: Specifies a context menu that is displayed on any selectable element in the timeline component.

• Timeline item (timeItem): The child of timeSeries that represents an event in the timeline.

• Marker (marker): A configurable shape that represents the event in the overview panel. The attributes are specified in a named overviewItem facet child of the timeItem component.

• Time axis (timeAxis): Child of timeline used to specify the time axis and timelineOverview used to specify the overview time axis.

• Timeline overview (timelineOverview): An optional component used to provide a macro view of all of the events from all timeline series in the timeline. Users can scroll through the timeline using a zoom control.

How to Add a Timeline to a Page

When you are designing your page using UI-first development, you use the Components window to add a timeline to a JSF page. When you drag and drop a timeline component onto the page, a timeline artifact and source code is added to the Visual Editor, and the tag structure is added to the Structure window.

After the timeline is added to your page, you can use the Properties window to specify data values and configure display attributes. In the Properties window you can use the dropdown menu for each attribute field to display a property description and options such as displaying an EL Expression Builder or other specialized dialogs. Figure 29-6 shows the dropdown menu for a timeline endTime attribute.

Figure 29-6 Timeline endTime Attribute Value

Note:

If your application uses the Fusion technology stack, then you can use data controls to create a timeline and the binding will be done for you. For more information, see the "Creating Databound Timelines" section in Developing Fusion Web Applications with Oracle Application Development Framework.

Before you begin:

It may be helpful to have an understanding of how timeline attributes and timeline child tags can affect functionality. For more information, see Configuring Timelines.

You may also find it helpful to understand functionality that can be added using other ADF Faces features. For more information, see Additional Functionality for Timeline Components.

To add a timeline to a Page:

1. In the ADF Data Visualization page of the Components window, from the Gantt section, drag and drop a Timeline component onto the page.

2. In the Properties window, view the attributes for the timeline. Use the help button to display the complete tag documentation for the timeline component.

3. Expand the Appearance section, and enter values for the following attributes:

   • EndTime: Enter the ending date to use for the timeline time range using the format yyyy-mm-dd. Select an end date that will include events in the data collection you wish to display on the timeline. By default the current date is used for this attribute.

   • StartTime: Enter the starting date to use for the timeline time range using the format yyyy-mm-dd. Select a start date that will include events in the data collection you wish to display on the timeline. By default the current date is used for this attribute.

4. Optionally, enter values for the following attributes:

   • Orientation: Use the attribute's dropdown menu to change the default layout from horizontal to vertical.

     For sample images of timeline orientation, see Layout Options.

   • ItemPosition: If you are using a vertical orientation for the timeline, by default timeline items will not overlap each other vertically in the available space for the timeline. The default value is noOverlap. In a vertical orientation, this attribute does not apply to the horizontal display of timeline items.

     You can use an attribute value of random to specify that timeline items will randomly lay out the items vertically in the available space for the timeline.

   • Summary: Enter a summary of the timeline's purpose and structure for screen reader support.

   • TimeZone: Enter the time zone to use for the timeline. If not set, the value is identified from the AdfFacesContext.

5. Expand the Behavior section, and optionally enter values for the following attributes:

   • ItemSelection: Use the dropdown list to specify whether or not timeline items in the timeline are selectable. Valid values are single (default), multiple, or none. This setting applies to both timeline series in a dual timeline.

   • SortData: Use to set whether timeline events are sorted automatically by the timeline based on the time of the event, or manually sorted by the data model to which it is bound. Valid values are auto (default) or none.

   • FetchStartTime and FetchEndTime: Use these attributes to specify the start and end dates to use for delivering content from the data source.

6. To set the time axis for the timeline, do the following:

   1. In the Structure window, right-click the timeline node and select Insert Inside Timeline > Time Axis.

   2. In the Insert Time Axis dialog, enter the scale to use for the time axis of the timeline. Valid values are twoyears, years, quarters, twomonths, months, twoweeks, weeks, days, sixhours, threehours, hours, halfhours, and quarterhours.

7. To add an optional timeline time axis to the timeline, do the following:

   1. In the Structure window, right-click the timeline node and select Insert Inside Timeline > Timeline Overview.

   2. In the Structure window, right-click the timelineOverview node and select Insert Inside TimelineOverview > Time Axis.

   3. In the Insert Time Axis dialog, enter the scale to use for the overview time axis display of the timeline. Valid values are twoyears, years, quarters, twomonths, months, twoweeks, weeks, days, sixhours, threehours, hours, halfhours, and quarterhours.

What Happens When You Add a Timeline to a Page

JDeveloper generates a single timeline tag and a default axis tag when you drag and drop a timeline from the Components window onto a JSF page without setting any additional attributes in the Properties window.

The example below shows the generated code.

<dvt:timeline startTime="2017-02-21" endTime="2017-02-21" id="t1">
	<dvt:timeAxis scale="months" id="ta5"/>
</dvt:timeline>

If you choose to use the Data Controls panel to bind the data to a data control when creating the timeline, JDeveloper generates code based on the data model. See Creating Databound Gantt Chart and Timeline Components in Developing Fusion Web Applications with Oracle Application Development Framework.

Adding Data to Timeline Components

You can add data to the ADF DVT Timeline using UI-first development by creating classes and managed beans, and then using methods to automate the creation of the tree model and reference the data classes and beans. Timeline components require a collection data model to display attributes.

For example, to create the Employee Presentation timeline illustrated in Figure 29-5, you must provide a data model that includes a qualifying date value and details about the events.

How to Add Data to a Timeline

To add data to the timeline using UI-first development, create the classes, managed beans, and methods that will create the model and reference the classes, beans, or methods in JDeveloper.

Before you begin:

It may be helpful to have an understanding of how timeline attributes and timeline child tags can affect functionality, as described in Configuring Timelines.

You may also find it helpful to understand functionality that can be added using other ADF Faces features, as described in Additional Functionality for Timeline Components.

Add a timeline to your page. For help, see How to Add a Timeline to a Page. Confirm that the start time and end time for the timeline is consistent with the data model you are using.

Create the classes and managed beans that will define the timeline's data model and supply the data to the timeline. For information and examples, see Timeline Component Data Requirements. If you need help creating classes, see Working with Java Code in Developing Applications with Oracle JDeveloper. For help with managed beans, see Creating and Using Managed Beans.

To add data to the timeline in UI-first development:

1. In the Structure window, right-click the timeline node and choose Insert Inside Timeline > Time Series.

2. Right-click the timeSeries node and choose Go to Properties.

3. In the Properties window, expand the Common section, and set the following attributes:

   • Value: Specify an EL expression for the model to which you want the timeline to be bound. This must be an instance of org.apache.myfaces.trinidad.model.CollectionModel.

     Note:

     You may use other model instances, such as java.util.List, array, and javax.faces.model.DataModel. The timeline component will automatically convert the instance into a CollectionModel.

     For example, reference the managed bean you created to instantiate the timeline. In the employee presentation example, the timeline managed bean is named cb, and the data is instantiated when the timeline is referenced. To use the employee presentation data example with a timeline, enter the following in the Value field for the EL expression: #{cb.Model}.

   • Var: Enter the name of a variable to be used during the rendering phase to reference each element in the timeline collection. This variable is removed or reverted back to its initial value once rendering is complete.

     For example, enter evt in the Var field to reference each element in the employees presentation data example.

   • VarStatus: Optionally, enter the name of a variable during the rendering phase to access contextual information about the state of the component, such as the collection model or loop counter information. This variable is removed or reverted back to its initial value once rendering is complete.

4. In the Structure window, right-click the timeSeries node and choose Insert Inside Time Series > Time Item to add a component to display the timeline series data.

5. In the Properties window for the dvt:timeItem, expand the Common section and enter the following values

   • Value: Enter an EL Expression that references the date-related value you wish to display as an item on the timeline. For example, in a collection of date-related employee presentations, you could display presentation date as a timeline item.

     For example, to reference the employee presentations data source, enter #{evt.date}.

   • EndTime: Optionally, you can configure timeline items to represent a duration in time. By adding an end time to the value of the timeline item, you can represent a span of time instead of a single instant in time.

   • Title: Enter an EL Expression that references the main text output for each date-related value in the time item. For example, in a collection of date-related employee presentations, you could display the presentation subject as a title.

     To use the presentation subject as suggested, enter #{evt.description}.

   • Description: Enter an EL Expression that references the subtext output for each date-related value in the time item. For example, in a collection of date-related employee presentations, you could display the presentation date and time as a description.

     To use the date for the subtitle as suggested, enter #{evt.date}.

   • Thumbnail: Enter the image URL to use as a thumbnail for every individual time item. If you have to use multiple images depending on your time items, you can use an EL expression in the URL.

     For example, to use the categories of presentations for the thumbnail, enter /resources/images/timeline/#{evt.type}.png"/, where the specified images folder contains files that match the names of the presentation types in the data collection. The EL expression will evaluate to the type name and search for a PNG file of the same name to use as the item thumbnail.

6. To configure the marker representing the timeline item that displays in the timeline overview panel, do the following:

   1. In the Structure window, right-click the overviewItem facet and select Insert Inside f:facet-overviewItem > Marker.

   2. In the Properties window, set values to specify shape, size, and fill color as desired. By default, the marker displayed in the overview panel is a square shape.

For help with creating EL expressions, see How to Create an EL Expression.

For information about timeline items, see Configuring a Timeline Item Duration.

What You May Need to Know About Configuring Data for a Dual Timeline

You can add up to one additional timeline series to configure a dual timeline to compare two series of events. The procedure for adding and configuring another timeSeries component is the same.

The following example shows the code for the dual timeline displayed in Figure 29-2:

<af:panelGroupLayout layout="horizontal">
  <af:selectOneChoice id="soc" label="Employee (TOP)" value="#{timeline.firstEmp}"
                      autoSubmit="true"
                      valueChangeListener="#{timeline.handleValueChange}">
    <af:forEach items="#{timeline.employees}" var="ce">
    <af:selectItem label="#{ce.name}" value="#{ce.id}"/>
     </af:forEach>
   </af:selectOneChoice>
   <af:spacer width="5"/>
     <af:outputText value="vs."/>
   <af:spacer width="5"/>
 <af:selectOneChoice id="soc2" label="Employee (BOTTOM)"
                     value="#{timeline.secondEmp}"
                     autoSubmit="true"
                     valueChangeListener="#{timeline.handleValueChange}">
    <af:forEach items="#{timeline.employees}" var="ce">
    <af:selectItem label="#{ce.name}" value="#{ce.id}"/>
    </af:forEach>
  </af:selectOneChoice>
</af:panelGroupLayout>
 
 <dvt:timeline id="tl1" startTime="2000-01-01" endTime="2011-12-31"
               inlineStyle="width:1024px;height:500px" itemSelection="single"
               currentTime="2010-04-01">
   <dvt:timeSeries id="ts1" var="evt" value="#{timeline.firstModel}"
                       contentDelivery="lazy">
     <dvt:timeItem id="ti1" value="#{evt.date}" group="#{evt.group}"
                   title="#{evt.description}" description="#{evt.date}"
                   thumbnail="/resources/images/timeline/#{evt.type}.png">
       <f:facet name="overviewItem">
         <dvt:marker id="m1" shape="circle" fillColor="#ff0000"/>
       </f:facet>
   </dvt:timeItem>
 </dvt:timeSeries>
 <dvt:timeSeries id="ts2" var="evt" value="#{timeline.secondModel}"
                     contentDelivery="lazy">
   <dvt:timeItem id="ti2" value="#{evt.date}"
                 title="#{evt.description}" description="#{evt.date}"
                 thumbnail="/resources/images/timeline/#{evt.type}.png">
     <f:facet name="overviewItem">
        <dvt:marker id="m2" shape="circle" fillColor="#0000ff"/>
     </f:facet>
   </dvt:timeItem>
  </dvt:timeSeries>
  <dvt:timeAxis id="ta1" scale="quarters"/>
  <dvt:timelineOverview id="ov1">
   <dvt:timeAxis id="ta2" scale="years"/>
  </dvt:timelineOverview>
</dvt:timeline>

What You May Need to Know About Adding Data to Timelines

The examples in this chapter use classes and managed beans to provide the data to the timeline. If your application uses the Fusion technology stack, then you can use data controls to create a timeline and the binding will be done for you.

For more information, see the "Creating Databound Gantt Charts and Timelines" chapter of Developing Fusion Web Applications with Oracle Application Development Framework.

Alternatively, if you know the UI components on your page will eventually use ADF data binding, but you need to develop the pages before the data controls are ready, then you should consider using placeholder data controls, rather than manually binding the components. Using placeholder data controls will provide the same declarative development experience as using developed data controls. For more information, see the "Designing a Page Using Placeholder Data Controls" section in Developing Fusion Web Applications with Oracle Application Development Framework.

Customizing Timeline Display Elements

You can configure ADF DVT Timeline items using a number of customization options and attributes. You can also add a custom time scale to your timeline and its overview window.

Customizing Timeline Items

Time items represent the events displayed in the timeline. The timeItem component does not currently support customization via stamping.

Time items are represented in the timeline overview panel as a configurable shape. You can specify the following attributes for a time item marker:

• fillColor: The color of the marker shape. Valid values are RGB hexadecimal colors.

• opacity: The opacity of the fill color of the marker. Valid values range from 0 percent for transparent, to 100 percent for opaque.

• shape: The shape of the overview marker for each selected timeline series value. Valid values are one of seven prebuilt shapes circle (default), diamond, human, plus, square, triangleDown, and triangleUp. This attribute is not supported for timelines with a vertical orientation.

• scaleX and scaleY: The scaleX (horizontal) and scaleY (vertical) scale factor. Valid value is a numerical percentage. JDeveloper will automatically resize a marker to fit within the timeline overview area if the marker is too large. These attributes are not supported for timelines with a vertical orientation.

Configuring a Timeline Item Duration

Instead of specifying a specific instance of time for a timeline item you can configure a span or duration of time.

For example, Figure 29-7 shows a timeline with timeline items that span one or more hours in duration and display as a bar. The timeline overview panel also represents the timeline items using a bar display.

Figure 29-7 Timeline Items with Time Durations

Description of "Figure 29-7 Timeline Items with Time Durations"

To specify a timeline duration bar, set both the value and endTime attributes for the timeItem component. The values must be stored in the timeline's data model or in classes and managed beans if you are using UI-first development. In the following sample code, the timeline item dates are configured as a duration bar:

<dvt:timeline id="tl1" startTime="2013-09-21" endTime="2013-09-27" itemSelection="multiple"
                                  orientation="horizontal" summary="Timeline Durations Demo">
  <dvt:timeSeries id="ts1" var="evt" value="#{timeline.durationModel}">
  	<dvt:timeItem id="ti1" value="#{evt.date}" endTime="#{evt.endDate}"
									title="#{evt.description}" description="#{evt.date}"/>
  </dvt:timeSeries>
  <dvt:timeAxis id="ta1" scale="hours" zoomOrder="weeks days hours"/>
  <dvt:timelineOverview id="ov1">
  	<dvt:timeAxis id="ta2" scale="months"/>
  </dvt:timelineOverview>
</dvt:timeline>

How to Add a Custom Time Scale to a Timeline

You can create a custom time scale for the timeline and overview axes. The custom time scale is configured in the scale attribute of the dvt:timeAxis.

Before you begin:

It may be helpful to have an understanding of how timeline attributes and timeline child components can affect functionality. For more information, see Configuring Timelines.

You may also find it helpful to understand functionality that can be added using other ADF Faces features. For more information, see Additional Functionality for Timeline Components.

You should already have a timeline on your page. If you do not, follow the instructions in this chapter to create a timeline. For information, see How to Add a Timeline to a Page.

To create and use a custom time axis:

1. Implement the CustomTimescale.java interface to call the method getNextDate(Date currentDate) in a loop to build the time axis. The example below shows sample code for the interface.

   public interface CustomTimescale
   {
       public String getScaleName();
       public Date getPreviousDate(Date timelineStartDate);
       public Date getNextDate(Date currentDate);
       public String getLabel(Date date);
   }
   

2. In the Structure window, right-click a timeline node and choose Go to Properties.
3. Expand the Advanced category of the Properties window, for the CustomTimeScales attribute, register the implementation of the interface for the custom time axis.

   The customTimeScales attribute's value is a java.util.Map object. The specified map object contains pairs of key/values. The key is the time scale name (fiveyears), and the value is the implementation of the CustomTimeScale.java interface. For example:

   customTimesScales="#{timeline.customTimescales}"
   

4. To use the custom time scale in the time axis or overview time axis, in the Structure window, right-click the dvt:timeAxis node and in the Properties window, enter the custom time scale name.

   The example below shows sample code for setting a threeyears time axis and a fiveyears overview time axis.

   <dvt:timeline>
     <dvt:timeAxis id="ta1" scale="threeyears"/>
     <dvt:timelineOverview id="ov1">
        <dvt:timeAxis id="ta2" scale="fiveyears"/>
     </dvt:timelineOverview>
   </dvt:timeline>

What You May Need to Know About Skinning and Customizing the Appearance of Timelines

For the complete list of timeline skinning keys, see the Oracle Fusion Middleware Documentation Tag Reference for Oracle Data Visualization Tools Skin Selectors. To access the list from JDeveloper, from the Help Center, choose Documentation Library, and then Fusion Middleware Reference and APIs. For additional information about customizing your application using skins, see Customizing the Appearance Using Styles and Skins.

Adding Interactive Features to Timelines

You can add interactive features to ADF DVT Timeline components, including support for popups, custom context menus, and drag and drop operations.

How to Add Popups to Timeline Items

Timeline timeItem components can be configured to display popup dialogs, windows, and menus that provide information or request input from end users. Using the af:popup component with other ADF Faces components, you can configure functionality to allow your end users to show and hide information in secondary windows, input additional data, or invoke functionality such as a context menu.

With ADF Faces components, JavaScript is not needed to show or hide popups. The af:showPopupBehavior tag provides a declarative solution, so that you do not have to write JavaScript to open a popup component or register a script with the popup component. For more information about these components, see Using Popup Dialogs, Menus, and Windows.

Configuring Timeline Context Menus

You can define timeline context menus using these context menu facets:

• bodyContextMenu: Specifies a context menu that is displayed on non-selectable elements in the timeline component.

• contextMenu: Specifies a context menu that is displayed on any selectable element in the timeline component.

Each facet supports a single child component. Context menus are currently only supported in Flash and HTML5.

You create a context menu by using af:menu components within an af:popup component. You can then invoke the context menu popup from another component, based on a specified trigger. For more information about configuring context menus, see Using Popup Dialogs, Menus, and Windows.

Due to technical limitations when using the Flash rendering format, context menu contents are currently displayed using the Flash Player's context menu. This imposes several limitations defined by the Flash Player:

• Flash does not allow for submenus it its context menu.

• Flash limits custom menu items to 15. Any built-in menu items for the component, for example, a pie graph interactiveSliceBehavior menu item, will count towards the limit,

• Flash limits menu items to text-only. Icons or other controls possible in ADF Faces menus are not possible in Flash menus.

• Each menu caption must contain at least one visible character. Control characters, new lines, and other white space characters are ignored. No caption can be more than 100 characters long.

• Menu captions that are identical to another custom item are ignored, whether the matching item is visible or not. Menu captions are compared to built-in captions or existing custom captions without regard to case, punctuation, or white space.

• The following captions are not allowed, although the words may be used in conjunction with other words to form a custom caption: Save, Zoom In, Zoom Out, 100%, Show All, Quality, Play, Loop, Rewind, Forward, Back, Movie not loaded, About, Print, Show Redraw Regions, Debugger, Undo, Cut, Copy, Paste, Delete, Select All, Open, Open in new window, and Copy link.

• None of the following words can appear in a custom caption on their own or in conjunction with other words: Adobe, Macromedia, Flash Player, or Settings.

Additionally, since the request from Flash for context menu items is a synchronous call, a server request to evaluate EL is not possible when the context menu is invoked. To provide context menus that vary by selected object, the menus will be pre-fetched if the context menu popup uses the setting contentDelivery="lazyUncached". For context menus that may vary by state, this means that any EL expressions within the menu definition will be called repeatedly at render time, with different selection and currency states. When using these context menus that are pre-fetched, the application must be aware of the following:

• Long running or slow code should not be executed in any EL expression that may be used to determine how the context menu is displayed. This does not apply to af:commandMenuItem attributes that are called after a menu item is selected, such as actionListener.

• In the future, if the Flash limitations are solved, the ADF context menu may be displayed in place of the Flash context menu. To ensure upgrade compatibility, you should code such that an EL expression will function both in cases where the menu is pre-fetched, and also where the EL expression is evaluated when the menu is invoked. The only component state that applications should rely on are selection and currency.