Class: ChartDataProviderUtils

Oracle® JavaScript Extension Toolkit (JET)
4.2.0

E91398-01

QuickNav

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

ChartDataProviderUtils

Version:
  • 4.2.0
Since:
  • 4.2.0

Chart DataProvider Utilities

Utility for generating the data attribute for an oj-chart element. Given a data provider that implements oj.DataProvider with row data that corresponds to chart data items, as well as an options object containing mapping and sorting functions, this utility will generate an object with a series array and a groups data provider that can be passed directly to the chart data attribute. The series array will contain either strings or objects of the ChartSeries type, and the groups data provider will be a DataProvider that provides an array of objects of the ChartGroup type.

Usage :


// an array of row data for each chart data item
var itemData = [
 {'id': 'iPad15', 'product': 'iPad', 'year': '2015', 'sold': '113000'},
 {'id': 'iPad16', 'product': 'iPad', 'year': '2016', 'sold': '110000'},
 {'id': 'Mac15', 'product': 'MacBook', 'year': '2015', 'sold': '150000'},
 {'id': 'Mac16', 'product': 'MacBook', 'year': '2016', 'sold': '157000'},
 {'id': 'iPhone15', 'product': 'iPhone', 'year': '2015', 'sold': '182000'},
 {'id': 'iPhone16', 'product': 'iPhone', 'year': '2016', 'sold': '197000'},
];
// create a data provider with the row data
var itemDataProvider = new oj.ArrayDataProvider(itemData);

// required: create an itemProperties callback that will map chart data item properties
// for each row, as well as set a required seriesId string and groupId array.
var itemPropertiesFunc = function(itemContext) {
 var data = itemContext.data;
 return {
   value: data['sold'],
   seriesId: data['product'],
   groupId: [data['year']]
 };
}

// Pass the data provider for the item rows and the object with mapping callbaks to createChartData(),
// and generate an object that can be used to set the chart data attrbute.
var data = oj.ChartDataProviderUtils.createChartData(itemDataProvider, {'itemProperties': itemPropertiesFunc});

Constructor

new ChartDataProviderUtils()

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Methods

<static> createChartData(dataProvider, options) → {Object}

Generates a chart data object from a data provider, where each row represents one chart data item.
Parameters:
Name Type Description
dataProvider oj.DataProvider A data provider that implements oj.DataProvider, and provides data rows where each row will map data for a single chart data item.
options Object A set of options thats contains functions responsible for mapping values from the DataProvider rows to chart data items, chart series objects, and chart group objects. Also contains functions responsible for determining the order of the series and group objects.
Properties
Name Type Argument Description
itemProperties Function A function that takes an itemContext object, provided by the utility, and returns an object for each data item that contains value and style property mappings, as well the seriesId and groupId for the data item. The seriesId is of type string, and the groupId is an array of strings. To establish hierarchical groups, the groupId array will contain more than one id, ordered from the outermost group to the innermost group. The itemContext object has the following properties:
  • data: The data row for the item
  • key: The data row key for the item
  • datasource: A reference to the data provider object passed into createChartData().
The returned properties object can contain any of the properties defined on the ChartDataItem type, and must also contain the following properties:
  • seriesId: The id for this data item's series.
  • groupId: An array of group ids for this data item's group, from the outermost group to the innermost group.
seriesProperties Function <optional>
A function that takes a seriesContext object, provided by the utility, and returns the properties object for a particular series. The seriesContext object has the following properties:
  • id: The series id.
  • data: An array of data rows that have been mapped to this series.
  • keys: An array of keys for all the data rows that have been mapped to this series.
  • datasource: A reference to the data provider object passed into createChartData().
  • index: The position of this series within the current series order.
The returned properties object can contain any of the properties defined on the ChartSeries type.
groupProperties Function <optional>
A function that takes a groupContext object, provided by the utility, and returns the properties object for a particular group. The groupContext object has the following properties:
  • id: An array of group ids, from the outermost group to the current group.
  • data: An array of data rows that have been mapped to this group.
  • keys: An array of keys for all the data rows that have been mapped to this group.
  • datasource: A reference to the data provider object passed into createChartData().
  • index: The position of this group relative to its parent.
  • depth: The depth of this group. The depth of the outermost group under the invisible root is 1.
  • leaf: A boolean value that expresses whether or not this group is a leaf.
The returned properties object can contain any of the properties defined on the ChartGroup type.
seriesComparator Function <optional>
A comparator function that determines the ordering of the series. If undefined, the series will follow the order in which they are found in the data.

This function takes two seriesContext objects, seriesContext1 and seriesContext2, provided by the utility. A seriesContext object has the following properties:

  • id: The series id.
  • data: An array of data rows that have been mapped to this series.
  • keys: An array of keys for all the data rows that have been mapped to this series.
  • datasource: A reference to the data provider object passed into createChartData().
  • index: The position of this series within the current series order.

This function should use information to compare the two seriesContext objects with any desired metrics, and return a numerical value.

  • If the returned value is less than 0, the series belonging to seriesContext1 will precede the series belonging to seriesContext2.
  • If the returned value is equal to 0, the order of the series for either seriesContext in respect to each other will not change.
  • If the returned value is greater than 0, the series belonging to seriesContext2 will precede the series belonging to seriesContext1.
groupComparator Function <optional>
A comparator function that determines the ordering of the groups. If undefined, the groups will follow the order in which they are found in the data. The function takes two groupContext objects, groupContext1 and groupContext2, provided by the utility. A groupContext object has the following properties:
  • id: An array of group ids, from the outermost group to the current group.
  • data: An array of data rows that have been mapped to this group.
  • keys: An array of keys for all the data rows that have been mapped to this group.
  • datasource: A reference to the data provider object passed into createChartData().
  • index: The position of this group relative to its parent.
  • depth: The depth of this group. The depth of the outermost group under the invisible root is 1.
  • leaf: A boolean value that expresses whether or not this group is a leaf.

This function should use information to compare the two groupContext objects with any desired metrics, and return a numerical value.

  • If the returned value is less than 0, the group belonging to groupContext1 will precede the group belonging to groupContext2.
  • If the returned value is equal to 0, the order of the group for either groupContext in respect to each other will not change.
  • If the returned value is greater than 0, the group belonging to groupContext2 will precede the group belonging to groupContext1.
Returns:
An object that contains the series Promise> and the groups DataProvider.
Type
Object