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:
A 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 supports expanding and collapsing a group of related timeline items, such as shared hire dates, or a group of related activities such as completion of a number of employee forms. The timeline component also supports an adjustable time range to change the view for zooming in or out.
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 28-1 is configured to display the chronological order of the hire dates of employees in the Summit DVT example. In this example, timeline items representing each event display information about the employee using an image and text with labels. 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 28-1 Timeline of Employee Hire Dates
A dual timeline can be used for comparison of up to two series of events. Figure 28-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 28-2 Dual Timeline Comparing Employee Change Events
To understand how timelines are used and can be customized, it is helpful to understand these elements and features.
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 28-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 28-3 Timeline Overview Panel and Time Axis
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 28-4 illustrates the comparison of a timeline using a horizontal orientation with the same timeline using a vertical orientation.
Figure 28-4 Timeline Horizontal and Vertical Orientations
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.
Timeline items that share a common date can be configured to display as a group that can be expanded or collapsed at runtime. By default, a number counter displaying the number of items in a group is provided in the collapsed view. Clicking anywhere in the grouped timeline item opens all items in the collapsed view and clicking in the timeline collapses the expanded view.
Figure 28-5 shows a timeline item with a counter opened into an expanded view.
Figure 28-5 Timeline Group Counter and Expanded View
Timeline components support drag and drop operations to and from another collection component, for example, a table.
Figure 28-6 shows a timeline configured as a drop target and drag source. When the user drags one of the rows in the table onto the timeline, attributes are displayed as a timeline item. Timeline items can also be selected and dragged to the table to display attributes on a row.
Figure 28-6 Timeline Configured as a Drop Target and Drag Source
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.
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
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.
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: By default, timeline components are accessible. You can configure your application pages with timeline components to be accessible to screen reader users. For more information, 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.
To use the timeline
component in UI-first development, define the data, add the timeline to a page and complete the additional configuration in JDeveloper.
The data layer for the timeline
component is specified in its child, the timelineSeries
component. You must specify at least one timeline 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 more 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 timelineSeries
component must be at most one timelineItem
component. This component makes it possible to customize the event content through stamping. When you use stamping, child components are not created for every event represented in a timeline. Rather, the content of the component is repeatedly rendered, or stamped, once per timeline item, such as the events in the timeline.
Each time a timeline item is stamped, 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 timeline item component, for example, to pass the item value to a stamped af:outputText
component. 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.UITimelineSeries;
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();
UITimelineSeries _series =
(UITimelineSeries)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 28-7. You can find the complete source code for the TimelineCBBean
in the ADF Faces Components Demo application. For more information about the demo application, see ADF Faces Components Demo Application .
Figure 28-7 Timeline of Employee Presentations
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 (timelineSeries
): 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 (timelineItem
): The child of timelineSeries
that represents an event in the timeline. The components supports the use of many ADF Faces components, such as af:outputText
, af:image
, and af:panelGroupLayout
.
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 timelineItem
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.
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 28-8 shows the dropdown menu for a timeline endTime
attribute.
Figure 28-8 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:
In the ADF Data Visualization page of the Components window, from the Gantt section, drag and drop a Timeline
component onto the page.
In the Properties window, view the attributes for the timeline. Use the help button to display the complete tag documentation for the timeline
component.
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.
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
.
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.
To set the time axis for the timeline, do the following:
In the Structure window, right-click the timeline
node and select Insert Inside Timeline > Time Axis.
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
.
To add an optional timeline time axis to the timeline, do the following:
In the Structure window, right-click the timeline
node and select Insert Inside Timeline > Timeline Overview.
In the Structure window, right-click the timelineOverview
node and select Insert Inside TimelineOverview > Time Axis.
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
.
JDeveloper generates only a single 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="2012-06-27" endTime="2012-06-27" id="t1"/>
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. For more information, see the "Creating Databound Gantt Chart and Timeline Components" chapter of Developing Fusion Web Applications with Oracle Application Development Framework.
Timeline components require a collection data model to display attributes. For example, to create the Employee Presentation timeline illustrated in Figure 28-7, you must provide a data model that includes a qualifying date value and details about the events.
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. 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.
Add a timeline to your page. For help with adding a timeline to a page, 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 additional information and examples, see Timeline Component Data Requirements. If you need help creating classes, see the "Working with Java Code" chapter of 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:
In the Structure window, right-click the timeline
node and choose Insert Inside Timeline > Timeline Series.
Right-click the timelineSeries
node and choose Go to Properties.
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}
.
For help with creating EL expressions, see How to Create an EL Expression.
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.
In the Structure window, right-click the timelineSeries
node and choose Insert Inside Timeline Series > Timeline Item to add a component to display the timeline series data through stamping.
In the Properties window for the dvt:timelineItem
, 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}
.
Group: Optionally, you can configure timeline items that share a common date to display as a group that can be expanded or collapsed at runtime. By default, a number counter displaying the number of items in a group is provided in the collapsed view.
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. For more information, see Configuring a Timeline Item Duration.
To configure the timeline item to display the data collection attributes in the timeline item, do the following:
Use the Structure window context menu to insert components to define the layout of the timeline item.
Use the Properties window to specify the content and display attributes for the timeline item. For the value
attribute use an EL Expression that references the row in the data collection.
For example, the code highlighted in the example below shows the component structure and attribute definitions for the timeline item stamped in the employee presentations timeline in Figure 28-7.
<dvt:timeline id="tl1" startTime="2010-01-01" endTime="2011-12-31" inlineStyle="width:1000px;height:500px" itemSelection="single"> <dvt:timelineSeries id="ts1" var="evt" value="#{cb.model}"> <dvt:timelineItem id="ti1" value="#{evt.date}"> <af:panelGroupLayout id="pg1" layout="horizontal"> <af:image id="img1" inlineStyle="width:30px;height:30px" source="/resources/images/timeline/employment.png"/> <af:spacer width="3"/> <af:panelGroupLayout id="pg2" layout="vertical"> <af:outputText id="ot1" inlineStyle="color:#084B8A" value="#{evt.description}" noWrap="true"/> <af:outputText id="ot2" value="#{evt.date}" inlineStyle="color:6e6e6e" noWrap="true"> <af:convertDateTime dateStyle="medium"/> </af:outputText> </af:panelGroupLayout> </af:panelGroupLayout> </dvt:timelineItem> </dvt:timelineSeries> <dvt:timeAxis id="ta1" scale="weeks"/> <dvt:timelineOverview id="ov1"> <dvt:timeAxis id="ta2" scale="years"/> </dvt:timelineOverview> <f:ajax event="keyUp" execute="@this" listener="#{cb.handleKey}"/> </dvt:timeline>
Note:
You can specify the layout and contents of a timeline item in a number of ways. For more information, see Customizing Timeline Items.
To configure the marker representing the timeline item that displays in the timeline overview panel, do the following:
In the Structure window, right-click the overviewItem facet
and select Insert Inside f:facet-overviewItem > Marker.
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.
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 timelineSeries
component is the same.
The following example shows the code for the dual timeline displayed in Figure 28-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:timelineSeries id="ts1" var="evt" value="#{timeline.firstModel}" contentDelivery="lazy"> <dvt:timelineItem id="ti1" value="#{evt.date}" group="#{evt.group}"> <af:panelGroupLayout id="pg1" layout="horizontal"> <af:image id="img1" inlineStyle="width:30px;height:30px" source="/resources/images/timeline/#{evt.type}.png"/> <af:spacer width="3"/> <af:panelGroupLayout id="pg2" layout="vertical"> <af:outputText id="ot1" inlineStyle="color:#084B8A" value="#{evt.description}" noWrap="true"/> <af:outputText id="ot2" value="#{evt.date}" inlineStyle="color:#6e6e6e" noWrap="true"> <af:convertDateTime dateStyle="medium"/> </af:outputText> </af:panelGroupLayout> </af:panelGroupLayout> <f:facet name="overviewItem"> <dvt:marker id="m1" shape="circle" fillColor="#ff0000"/> </f:facet> </dvt:timelineItem> </dvt:timelineSeries> <dvt:timelineSeries id="ts2" var="evt" value="#{timeline.secondModel}" contentDelivery="lazy"> <dvt:timelineItem id="ti2" value="#{evt.date}"> <af:panelGroupLayout id="pg2" layout="horizontal"> <af:image id="img2" inlineStyle="width:30px;height:30px" source="/resources/images/timeline/#{evt.type}.png"/> <af:spacer width="3"/> <af:panelGroupLayout id="pg3" layout="vertical"> <af:outputText id="ot3" inlineStyle="color:#084B8A" value="#{evt.description}" noWrap="true"/> <af:outputText id="ot4" value="#{evt.date}" inlineStyle="color:#6e6e6e" noWrap="true"> <af:convertDateTime dateStyle="medium"/> </af:outputText> </af:panelGroupLayout> </af:panelGroupLayout> <f:facet name="overviewItem"> <dvt:marker id="m2" shape="circle" fillColor="#0000ff"/> </f:facet> </dvt:timelineItem> </dvt:timelineSeries> <dvt:timeAxis id="ta1" scale="quarters"/> <dvt:timelineOverview id="ov1"> <dvt:timeAxis id="ta2" scale="years"/> </dvt:timelineOverview> </dvt:timeline>
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.
You can configure timeline items and add a custom time scale to your timeline.
Timeline items represent the events displayed in the timeline. The timelineItem
component supports the following ADF components to display information and provide actions associated with the event:
Layout components including: af:panelFormLayout
, af:panelGroupLayout
, af:separator
, af:showDetailItem
, and af:spacer
. For more information about using these components, see Organizing Content on Web Pages.
Menu component af:menu
. For more information about these components, see Using Menus, Toolbars, and Toolboxes.
Output components including: af:outputFormatted
and af:outputText
. For more information about these components, see Using Output Components.
Message component af:outputLabelMessage
. For more information about this component, see Displaying Tips, Messages, and Help.
Navigation components including: af:button
and af:link
. For more information about these components, see Working with Navigation Components.
Image component af:image
. For information about how to use the af:image
component, see Displaying Images.
af:showPopupBehavior:
For information about how to use the af:showPopupBehavior
component, see Using Popup Dialogs, Menus, and Windows.
Timeline items are represented in the timeline overview panel as a configurable shape. You can specify the following attributes for a timeline 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.
Instead of specifying a specific instance of time for a timeline item you can configure a span or duration of time.
For example, Figure 28-9 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 28-9 Timeline Items with Time Durations
To specify a timeline duration bar, set both the value
and endTime
attributes for timelineItem
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"> <dvt:timelineSeries id="ts1" var="evt" value="#{timeline.durationModel}"> <dvt:timelineItem id="ti1" value="#{evt.date}" group="#{evt.group}" endTime="#{evt.endDate}"> <af:panelGroupLayout id="pg1" layout="horizontal"> <af:panelGroupLayout id="pg2" layout="vertical"> <af:outputText id="ot2" inlineStyle="color:#084B8A" value="#{evt.description}" noWrap="true"/> <af:outputText id="ot3" value="#{evt.date}" inlineStyle="color:#6e6e6e" noWrap="true"> <af:convertDateTime dateStyle="medium"/> </af:outputText> </af:panelGroupLayout> </af:panelGroupLayout> </dvt:timelineItem> </dvt:timelineSeries> <dvt:timeAxis id="ta1" scale="hours"/> <dvt:timelineOverview id="ov1"> <dvt:timeAxis id="ta2" scale="months"/> </dvt:timelineOverview> </dvt:timeline>
You can customize the styling of the duration bars using the following skin selectors:
af|dvt-timelineItem::duration
af|dvt-timelineItem::duration:focused
af|dvt-timelineItem::duration:selected
af|dvt-timelineItem::duration:highlighted
You can also customize the styling of the markers used in the overview panel using the following skin selectors:
af|dvt-timelineItemOverview::duration
af|dvt-timelineItemOverview::duration:focused
af|dvt-timelineItemOverview::duration:selected
af|dvt-timelineItemOveriew::duration:highlighted
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:
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.
You can add interactive features to timelines, including support for popups, custom context menus, and drag and drop operations.
Timeline timelineItem
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.
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
.
You can configure timelines as a drop target or drag source between collection components on a page.
For example, you can drag an item from one collection (for example, a row from a table), and drop it into a timeline, or drag an event from a timeline and drop it into a table, as illustrated in Figure 28-6.
To add drop support to a timeline, add the af:dropTarget
tag to the timeline
component and include the data flavors that the timeline will support. Add a dropListener
method to a timeline managed bean that will respond to the drop event.
To add drag support from a timeline to a collection component, add the af:dragSource
tag to the timeline
component and add the af:collectionDropTarget
tag to the component receiving the drag. The component receiving the drag must include the org.apache.myfaces.trinidad.model.RowKeySet
data flavor as a child of the af:collectionDropTarget
and also define a dropListener
method to respond to the drop event.
The example below shows the JSF page sample code for the ADF Faces Components Demo application illustrated in Figure 28-6. For additional information about the af:table
component, see Using Tables, Trees, and Other Collection-Based Components.
<dvt:timeline id="tl1" startTime="2010-01-01" endTime="2011-12-31" inlineStyle="width:800px;height:400px" itemSelection="single"> <f:attribute name="horizontalFetchSizeOverride" value="3000"/> <dvt:timelineSeries id="ts1" var="evt" value="#{dnd.timelineModel}"> <dvt:timelineItem id="ti1" value="#{evt.date}" group="#{evt.group}"> <af:panelGroupLayout id="pg1" layout="horizontal"> <af:image id="img1" inlineStyle="width:30px;height:30px" source="/resources/images/timeline/employment.png"/> <af:spacer width="3"/> <af:panelGroupLayout id="pg2" layout="vertical"> <af:outputText id="ot1" inlineStyle="color:#084B8A" value="#{evt.description}" noWrap="true"/> <af:outputText id="ot2" value="#{evt.date}" inlineStyle="color:#6e6e6e" noWrap="true"> <af:convertDateTime dateStyle="medium"/> </af:outputText> </af:panelGroupLayout> </af:panelGroupLayout> </dvt:timelineItem> <af:dragSource actions="COPY" discriminant="model"/> <af:dropTarget actions="COPY" dropListener="#{dnd.handleDropOnTimeline}"> <af:dataFlavor flavorClass="org.apache.myfaces.trinidad.model.RowKeySet" discriminant="model2"/> </af:dropTarget> </dvt:timelineSeries> <dvt:timeAxis id="ta1" scale="weeks"/> <dvt:timelineOverview id="ov1"> <dvt:timeAxis id="ta2" scale="years"/> </dvt:timelineOverview </dvt:timeline> <af:table var="row" value="#{dnd.tableModel}" rowSelection="single" inlineStyle="width:370px;height:400px"> <af:column headerText="ID" width="20"> <af:outputText value="#{row.id}"/> </af:column> <af:column headerText="Event" width="340"> <af:outputText value="#{row.description}"/> </af:column> <af:dragSource actions="COPY" discriminant="model2"/> <af:collectionDropTarget actions="COPY" modelName="model" dropListener="#{dnd.handleDropOnTable}"/> </af:table>
The data model for this example is defined in the TimelineDnDBean
managed bean using an ArrayList
class. You can find the source code for the class and the supporting EmpEvent
class in the ADF Faces Components Demo application. For more information about the demo application, seeADF Faces Components Demo Application .
Before you begin:
It may be helpful to have an understanding of how timeline attributes and 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.
You will need to complete these tasks:
Add a timeline to your page. For more information, see How to Add a Timeline to a Page
If you are configuring timeline items as a drag source and you did not bind the timeline to a data control when you added the component to the page, add data to the timeline. For information about adding data to timelines using UI-first development, see How to Add Data to a Timeline.
Create any additional components needed to support the drag and drop.
For example, if you are using a table as the drag source or drop target, you will need to add a table to your page.
To add drag and drop support to a timeline:
In the Structure window, right-click the timeline
component, and select Insert Inside Timeline > Drop Target.
In the Insert Drop Target dialog, enter the name of the drop listener or use the dropdown menu to choose Edit to add a drop listener method to the timeline's managed bean. Alternatively, use the dropdown menu to choose Expression Builder and enter an EL Expression for the drop listener.
For example, to add a method named handleDropOnTimeline()
on a managed bean named dnd
, choose Edit, select dnd from the dropdown menu, and click New on the right of the Method field to create the handleDropOnTimeline()
method.
The example below shows the sample drop listener and supporting methods for the timeline displayed in Figure 28-6.
// 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 javax.faces.bean.ManagedBean; import javax.faces.bean.SessionScoped; import javax.faces.bean.RequestScoped; import oracle.adf.view.rich.datatransfer.DataFlavor; import oracle.adf.view.rich.datatransfer.Transferable; import oracle.adf.view.rich.dnd.DnDAction; import oracle.adf.view.rich.event.DropEvent; import org.apache.myfaces.trinidad.context.RequestContext; import org.apache.myfaces.trinidad.model.CollectionModel; import org.apache.myfaces.trinidad.model.ModelUtils; import org.apache.myfaces.trinidad.model.RowKeySet; // drop listener public DnDAction handleDropOnTimeline(DropEvent event) { Date _date = (Date)event.getDropSite(); Transferable _transferable = event.getTransferable(); RowKeySet _rowKeySet = _transferable.getData(DataFlavor.ROW_KEY_SET_FLAVOR); Object _rowKey = _rowKeySet.iterator().next(); EmpEvent _event = (EmpEvent)m_tableModel.getRowData(_rowKey); _event.setDate(_date); orderInsert(_event); RequestContext.getCurrentInstance().addPartialTarget (event.getDragComponent()); return DnDAction.COPY; } private void orderInsert(EmpEvent event) { int _index = -1; ArrayList _list = (ArrayList)m_timelineModel.getWrappedData(); for (int i=0; i<_list.size(); i++) { EmpEvent _current = (EmpEvent)_list.get(i); if (event.getDate().before(_current.getDate())) { _index = i; break; } } if (_index == -1) _list.add(event); else _list.add(_index, event); ArrayList _list2 = (ArrayList)m_tableModel.getWrappedData(); _list2.remove(event); }
Click OK, and in the Insert Data Flavor dialog, enter org.apache.myfaces.trinidad.model.RowKeySet
.
In the Structure window, right-click the af:dropTarget
component and choose Go to Properties to set the following attributes in the Properties window:
Actions: Enter a list of the operations that the drop target will accept, separated by spaces. Allowable values are: COPY
, MOVE
, or LINK
. If you do not specify a value, the drop target will use COPY
.
Discriminant: Specify the model name shared by the drop target and drag source for compatibility purposes. The value of this attribute must match the value of the of the discriminant
attribute of the af:dragSource
component you will set for the collection component receiving the drags from the timeline in Step 5.
To configure another collection component as the drag source for drops into the timeline, do the following:
In the Components window, from the Operations panel, drag and drop a Drag Source tag as a child to the component that will be the source of the drag.
For example, drag and drop a Drag Source tag as a child to an af:table
component.
In the Properties window, for the component's Actions field, enter a list of the operations that the drop target will accept, separated by spaces.
For the component's Discriminant field, specify the model name shared by the drop target and drag source for compatibility purposes.
To configure the timeline as a drag source, in the Components window, from the Operations panel, drag and drop a Drag Source tag as a child to the timeline.
In the Structure window, right-click the af:dragSource
component and choose Go to Properties to set the following attributes in the Properties window:
Actions: Enter a list of the operations that the collection drop target component will accept, separated by spaces.
Discriminant: Specify the name of the model shared by the drag source and collection drop target for compatibility purposes. The value of this attribute must match the value of the of the modelName
attribute of the af:collectionDropTarget
component you will set for the collection component receiving the drags from the timeline in Step 8.
To make another collection component the drop target for drops from the timeline, do the following:
In the Components window, from the Operations panel, drag and drop a Collection Drop Target onto the component that will receive the drop.
For example, drag and drop a Collection Drop Target as a child to an af:table
component that displays the results of the drop.
In the Insert Drop Target dialog, enter the name of the drop listener or use the dropdown menu to choose Edit to add a drop listener method to the appropriate managed bean.
The example below shows the sample drop listener for the timeline displayed in Figure 28-6. This example uses the same imports and helper methods used in the previous example, and they are not included here.
//Drop Listener public DnDAction handleDropOnTable(DropEvent event) { Integer _dropSite = (Integer)event.getDropSite(); Transferable _transferable = event.getTransferable(); RowKeySet _rowKeySet = _transferable.getData(DataFlavor.ROW_KEY_SET_FLAVOR); Object _rowKey = _rowKeySet.iterator().next(); EmpEvent _event = (EmpEvent)m_timelineModel.getRowData(_rowKey); ArrayList _list = (ArrayList)m_tableModel.getWrappedData(); _list.add(_dropSite.intValue(), _event); ArrayList _list2 = (ArrayList)m_timelineModel.getWrappedData(); _list2.remove(_event); RequestContext.getCurrentInstance().addPartialTarget (event.getDragComponent()); return DnDAction.COPY; } private static Date parseDate(String date) { Date ret = null; try { ret = s_format.parse(date); } catch (ParseException e) { e.printStackTrace(); } return ret; }
Click OK, and in the Insert Data Flavor dialog, enter org.apache.myfaces.trinidad.model.RowKeySet
.
In the Structure window, right-click the af:dropTarget
component and choose Go to Properties.
In the Properties window, in the Actions field, enter a list of the operations that the drop target will accept, separated by spaces.
In the ModelName field, define the model for the collection. The value of the modelName
attribute is a String object used to identify the drag source for compatibility purposes. The value of this attribute must match the value of the discriminant
attribute of the af:dragSource
component you set in Step 7.
For more information about configuring drag and drop on ADF Faces or ADF Data Visualization components, see Adding Drag and Drop Functionality.