Methods

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

collapseAll(id)

Collapses all header items of a field.

Parameters:
The index in the fields array, dataField or caption of the field.

collapseHeaderItem(area, path)

Collapses a specified header item.

Parameters:
area: String
Area whose header item should be collapsed.
path: String
Path to an 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
A path to the cell in the 'column' area.
rowPath: Array
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
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
});

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:
The index in the fields array, dataField or caption of the field.

expandHeaderItem(area, path)

Expands a specified header item.

Parameters:
area: String
Area whose header item should be expanded.
path: Array
Path to an item.

field(id)

Gets current options of a specified field.

Parameters:
The index in the fields array, dataField or caption of the field.
Return Value: Object
Field options.

field(id, options)

Sets one or more options of a specified field.

Parameters:
The index in the fields array, dataField or caption of the field.
options: Object
Option/value pairs object.

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

fields()

Gets all fields from the data source.

Return Value: Array
Array of fields.

fields(fields)

Sets the fields option.

Parameters:
fields: Array
Array of fields.

filter()

Gets the current filter expression. Cannot be used for the XmlaStore store type.

Return Value: Object
A filter expression.

filter(filterExpr)

Applies a new filter expression. Cannot be used for the XmlaStore store type.

Parameters:
filterExpr: Object
A filter expression.

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

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

For information on filter expressions, refer to the Filtering section of the Data Layer article.

getAreaFields(area, collectGroups)

Gets all fields within a specified area.

Parameters:
area: String
Area type.
collectGroups: Boolean
Specifies whether to display groups as separate items.
Return Value: Array
An array of fields.

If the collectGroups parameter is set to true, this method will return groups as separate items without going into their structure.

getData()

Gets data displayed in a PivotGrid.

Return Value: Object
Pivot grid 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()

Indicates whether or not the PivotGridDataSource is currently being loaded.

Return Value: Boolean
If the PivotGridDataSource is being loaded, it returns true; otherwise, it returns false.

load()

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

Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object, which is resolved when data has been loaded.

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 the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
Return Value: Object
The object for which this method is called.

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
eventHandler: function
The handler to be detached from the specified event.
Return Value: Object
The object for which this method is called.

on(eventName, eventHandler)

Subscribes to a specified event.

Parameters:
eventName: String
The name of the event to be subscribed.
eventHandler: function
An event handler for the specified event.
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 the specified events.

Parameters:
events: Object
An object of the following structure: { "eventName1": handler1, "eventName2": handler2, ...}
Return Value: Object
The object for which this method is called.

Use this method to subscribe to several events at 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: jQuery.Promise
A Promise of the jQuery.Deferred object, which is resolved when data has been loaded.

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 (fields configuration, sorting, filters, expanded headers, etc.)

Return Value: Object
A current PivotGridDataSource state.

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
A PivotGridDataSource 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.