Methods

This section describes the methods used to manipulate the PivotGridDataSource object.

collapseAll(id)

Collapses all header items of a field.

Parameters:
id:

Number

|

String

The field's index in the fields array, dataField or caption.

collapseHeaderItem(area, path)

Collapses a header item.

Parameters:
area:

String

The area whose header item should be collapsed.

path:

Array<String | Number | Date>

The path to the item.

createDrillDownDataSource(options)

Provides access to a list of records (facts) that were used to calculate a specific summary.

Parameters:
options:

Object

Configuration object.

Object structure:
columnPath:

Array<String | Number | Date>

A path to the cell in the 'column' area.

rowPath:

Array<String | Number | Date>

A path to the cell in the 'row' area.

dataIndex:

Number

An index of the summary value in the 'data' area.

maxRowCount:

Number

Maximum items count in the resulting list.

customColumns:

Array<String>

A list of field names that will be included in each fact.

Return Value:

DataSource

A drill-down data source.

Use this method if you need to get information on what facts were involved in the calculation of a specific summary value. To get a drill-down data source that provides such information, you need to specify a full path to a summary value (including the rowPath, columnPath and dataIndex). You can also specify a list of fields to display for each fact (customColumns) and the maximum number of acquired facts (maxRowCount).

NOTE
By default, data in the returned data source is paginated. This means that when trying to load items from it, you will get only the items of the first page. To get all items, use the following code.
JavaScript
drillDownDataSource.paginate(false);
drillDownDataSource.load().done(function (items) {
    // the "items" array contains all items
});

View Demo

dispose()

Disposes of all resources associated with this PivotGridDataSource.

Use this method only if you created the DataSource manually (not using a widget).

expandAll(id)

Expands all header items of a field.

Parameters:
id:

Number

|

String

The field's index in the fields array, dataField or caption.

expandHeaderItem(area, path)

Expands a header item.

Parameters:
area:

String

The area whose header item should be expanded.

path:

Array<Object>

The path to the item.

field(id)

Gets all options of a field with a specific identifier.

Parameters:
id:

Number

|

String

The field's index in the fields array, dataField or caption.

Return Value:

Object

The field's options.

field(id, options)

Updates the values of several field options.

Parameters:
id:

Number

|

String

The field's index in the fields array, dataField or caption.

options:

Object

Options with their new values.

To make changes visible, call the load() method after editing field options.

fields()

Gets all the fields.

Return Value:

Array<PivotGrid field>

All options of all the fields.

fields(fields)

Updates all the fields.

Parameters:

New field options.

filter()

Gets the filter option's value. Does not take effect for the XmlaStore.

Return Value:

Object

The current filter expression; described in the Filtering section.

filter(filterExpr)

Sets the filter option's value. Does not take effect for the XmlaStore.

Parameters:
filterExpr:

Object

A filter expression; described in the Filtering section.

To apply a new filtering expression, call the reload() method. The usage example is shown below.

JavaScript
pivotGridDataSource.filter("price", "<", 100);
pivotGridDataSource.reload()

getAreaFields(area, collectGroups)

Gets all the fields within an area.

Parameters:
area:

String

The area's type.

collectGroups:

Boolean

Specifies whether to display groups as separate items.

Return Value:

Array<PivotGrid field>

All options of all the fields.

getData()

Gets the PivotGrid's data.

Return Value:

Object

The data.

This method returns pivot grid data in the following structure.

JavaScript
{
    "rows":[
        {
            "value": /*Row 1 value*/,
            "index": /*Row 1 index*/,
            "text": /*Row 1 caption*/
        },
        {
            "value": /*Row 2 value*/,
            "index": /*Row 2 index*/,
            "text": /*Row 2 caption*/
            "children":[
                {
                    "value": /*Row 2.1 value*/,
                    "index": /*Row 2.1 index*/,
                    "text": /*Row 2.1 caption*/,
                    "children": [/*Level 3 and deeper*/]
                },
                . . .
            ]
        },
        . . .
    ],
    "columns":[
        {
            "value": /*Column 1 value*/,
            "index": /*Column 1 index*/,
            "text": /*Column 1 caption*/
        },
        {
            "value": /*Column 2 value*/,
            "index": /*Column 2 index*/,
            "text": /*Column 2 caption*/
            "children":[
                {
                    "value": /*Column 2.1 value*/,
                    "index": /*Column 2.1 index*/,
                    "text": /*Column 2.1 caption*/,
                    "children": [/*Level 3 and deeper*/]
                },
                . . .
            ]
        },
        . . .
    ],
    "values":[
        [
            [
                /*Measure 1 value*/,
                /*Measure 2 value*/,
                . . .
            ],
            . . .
        ],
        . . .
    ]
}
NOTE
Measure is an alternative name for a field to be used for calculating summary values. Such fields are located in the Data Fields section of the Field Chooser.

As shown above, the object has three fields — rows, columns and values. The rows and columns arrays contain the following fields:

  • value — the item as it was retrieved from the data source;
  • index — the row/column index pointing to the corresponding summary value from the values array;
  • text — the item's caption as it appears in the pivot grid;
  • children — the optional array that contains items of the deeper hierarchical levels.

The values array contains the summary values, each one has three indexes. You can get a summary value using the following pattern.

JavaScript
var value = values[/*row index*/][/*column index*/][/*measure index*/];
NOTE
If you use XmlaStore and your data area is empty, this function will return values of the default measure, which were sent by an OLAP server. Although the OLAP server sends such values, they are hidden from the UI and can be obtained by this function only.

isLoading()

Checks whether the PivotGridDataSource is being loaded.

Return Value:

Boolean

true if it is being loaded; otherwise false.

load()

Starts updating the data source. Reloads data from the XMLA store only.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

Use this method to update the pivot grid after making changes in the data source, for example after editing a field using the field(id, options) method.

Use the following code to access loaded data.

JavaScript
    dataSource.load()
    .done(function(result) {
        // 'result' contains the loaded data
    })
    .fail(function(error) {
        // handle error
    });
NOTE
If you need to fully reload data from a store that differs from XMLA, use the reload() method.

off(eventName)

Detaches all event handlers from a single event.

Parameters:
eventName:

String

The event's name.

Return Value:

Object

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from a single event.

Parameters:
eventName:

String

The event's name.

eventHandler:

function

The event's handler.

Return Value:

Object

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to an event.

Parameters:
eventName:

String

The event's name.

eventHandler:

function

The event's handler.

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

See Also

on(events)

Subscribes to events.

Parameters:
events:

Object

Events with their handlers: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

reload()

Starts reloading data from any store and updating the data source.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

Use this method to update the pivot grid if you expect changes in data.

Use the following code to access loaded data.

JavaScript
    dataSource.reload()
    .done(function(result) {
        // 'result' contains the loaded data
    })
    .fail(function(error) {
        // handle error
    });

state()

Gets the current PivotGridDataSource state.

Return Value:

Object

The PivotGridDataSource state - fields configuration, filters, expanded headers, etc.

Use the returned object as an argument of the state(state) method to restore the pivot grid state.

NOTE
This method is a part of the state storing feature. Refer to the PivotGrid configuration options for details.

state(state)

Sets the PivotGridDataSource state.

Parameters:
state:

Object

The state returned by the state() method.

Use this method to restore the pivot grid state you have saved using the state() method earlier. You can return the widget to its default state by calling this method with the empty array or null argument

NOTE
This method is a part of the state storing feature. Refer to the PivotGrid configuration options for details.