Caplin Trader 5.1.0

Interface: module:ct-grid/GridDataProvider

module:ct-grid/GridDataProvider

GridDataProvider classes allow data from different data sources to be displayed within a grid when used in conjunction with an instance of module:ct-grid/DataProviderRowModel. The GridDataProvider interface is much simpler to implement than the full module:ct-grid/GridRowModel interface, and should allow most, if not all, grid row models to be developed, and so is the preferred way of creating a module:ct-grid/GridRowModel.

The sdk contains a set of generic data providers for retrieving different data types from the Caplin Platform (implementations are listed below), it is also anticipated that customers may also need to create their own data provider classes for accessing other forms of data, e.g. a data provider that accesses a custom web-service. So, GridDataProvider is the interface that customers wishing to have custom data displayed within a grid must implement.

Implements:

Members

(static, readonly) FILTERING :int

A constant definition used with module:ct-grid/GridDataProvider#supportsFeature to allow data providers to declare whether they support filtering.

Data providers that do support filtering will need to correctly implement module:ct-grid/GridDataProvider#setFilters.

Type:
  • int

(static, readonly) PAGING :int

A constant definition used with module:ct-grid/GridDataProvider#supportsFeature to allow data providers to declare whether they support paging.

Type:
  • int
Deprecated:
  • This field is no longer used and all data providers should support paging.

(static, readonly) SORTING :int

A constant definition used with module:ct-grid/GridDataProvider#supportsFeature to allow data providers to declare whether they support sorting.

Data providers that do support sorting will need to correctly implement module:ct-grid/GridDataProvider#sortBy.

Type:
  • int

Methods

addDataProviderListener(listener)

Adds a listener to the data provider, to be communicated of all data provider events.

Parameters:
Name Type Description
listener module:ct-grid/GridDataProviderListener

The listener to add.
See:

canReceive()

Implements:
See:

canReceiveMultipleObjects()

Implements:
See:

canReceiveObjects()

Implements:
See:

clearFilterExpression(filterName)

Remove a named filter expression. Once removed the data provider will reset itself to display the data without the removed filter.

Parameters:
Name Type Description
filterName string

The name of the filter.

clearGroupByField()

Removes any grouping from the grid row model.

clearSortRule()

Removes any sorting from the grid row model.

configureDataProvider(xmlConfigurationNode, isDataProviderDefinedByParent)

Allow the data provider to configure itself based on the XML attributes from the node used to configure the data provider.

Parameters:
Name Type Description
xmlConfigurationNode Element

Access to the XML node that contains any configuration information the data provider needs to configure itself.
isDataProviderDefinedByParent boolean

Informs the data provider whether its configuration came via inheritance, or was configured locally — this will affect how the data provider should behave when its module:ct-grid/GridDataProvider#getSerializedState method is invoked.

getAllFilterExpressions() → {map}

A map of all the filter expressions added to this data provider.

Returns:

A map of module:ct-grid/filter/FilterExpression instances, if any exist, or an empty map otherwise.

Type
map

getFilterExpression(filterName) → {module:ct-grid/filter/FilterExpression}

Returns a named filter expression.

Parameters:
Name Type Description
filterName String

The name of the filter to return — 'default' is the name given to filters generated from XML which lack the name attribute.
Returns:

A FilterExpression, if one exists, or null otherwise.

Type
module:ct-grid/filter/FilterExpression

getGroupByField() → {string}

Get the field, if one has been set, that is used to group the rows contained within row model.

Returns:

a String, if one exists, or null otherwise.

Type
string

getLastReceiveFailureMessage()

Implements:
See:

getPermissionKey() → {module:ct-services/security/PermissionKey|null}

Returns a permissioning key tuple that can be used to query the permissioning system to determine whether the user is permitted to access the data that this data provider will be providing.

Data providers whose data is not permissioned need not return a permissioning key.

Returns:

a permissioning key, or null.

Type
module:ct-services/security/PermissionKey | null

getSerializedState() → {string}

Invoked when the grid row model needs to save the state of this data provider. It returns an XML string representation of the state.

This interface differs from the implemented module:ct-core/Serializable interface in the following way.

If the state of the data provider has changed since deserialization, or the data provider state has ever changed in the past (i.e. the isDataProviderDefinedByParent passed within the module:ct-grid/GridDataProvider#configureDataProvider method was false, then the data provider should return a serialized representation of itself. If this is not the case, however, the data provider should otherwise return null.

Example:

RttpContainerGridDataProvider.prototype.getSerializedState = function() {
    if (this.m_bStateChanged || !this.m_bDataProviderDefinedByParent) {
        var sEncodedContainerName = XmlUtility.encodeValue(this.m_sOriginalContainerName);
        return '		\n';
    }
    return null;
};
Implements:
Throws:

if this method is not implemented by the subclass.

Type
module:br/Errors.UnimplementedInterfaceError
Returns:

An XML string representation of the state of this component, or null if there have not been any changes to the data provider. Must not be undefined.

Type
string

getSortRule() → {module:ct-grid/sort/SortRule}

Get the rule, if one exists, that is used to sort the data within the row model.

Returns:

a SortRule, if one exists, or null otherwise.

Type
module:ct-grid/sort/SortRule

getStartIndex() → {int|null}

Returns the start index that is set on the Data Provider via the module:ct-grid/GridDataProvider#setRowRange method.

Returns:

A number representing the start index the data provider has been set at, or null if not yet set.

Type
int | null

getSubjectIdentifiers(snapshotListener)

Returns the array of subject identifiers provided by the data provider.

This will include all subject identifiers, not just those within the current view.

Parameters:
Name Type Description
snapshotListener module:ct-grid/GridDataProviderSnapshotListener

getSuccessMessage()

Implements:
See:

getTransformMode() → {string}

Get the transform mode that determines how grid updates are pushed out from the data source.

Returns:

The transform mode - either 'snapshot' or 'live'

Type
string

injectData(subject, fieldData)

Injects a map of Data consisting of field_name:value pairs into a record given by its subject.

The GridDataProvider will notify all its observers about a record change with this data

Parameters:
Name Type Description
subject string
fieldData map

pauseUpdates()

Signals the GridDataProvider to temporarily pause updates to any GridDataProviderListener instances.

This method is invoked as a consequence of module:ct-grid/DataProviderRowModel#pauseUpdates being invoked. This method is a hint only, as the module:ct-grid/DataProviderRowModel will also perform caching of updates so they do not need to be rendered to the screen. By implementing pausing at the data provider level, however, additional processor usage can be conserved allowing multiple sheets to be opened without increasing the burden placed on they processor.

See:

receiveObjects()

Implements:
See:

removeDataProviderListener(listener)

Removes a GridDataProviderListener that no longer wishes to listen to data updates.

Parameters:
Name Type Description
listener module:ct-grid/GridDataProviderListener

The listener to remove.
See:

resumeUpdates()

Signals the GridDataProvider to resume updates to all GridDataProviderListener instances.

See:

setFilterExpression(filterExpression, filterName)

Set a filter expression on this data provider. This will filter the grid data according to the operator and values of the filter expression.

Parameters:
Name Type Description
filterExpression module:ct-grid/filter/FilterExpression

A filter expression to apply to this data provider.
filterName string

The name of the filter.

setFilters(activeColumnFilters, allColumns)

Informs the GridDataProvider of the currently active column filters.

Parameters:
Name Type Description
activeColumnFilters Array

An array of all the currently active module:ct-grid/GridColumnFilter instances.
allColumns map

A map of all GridView's column module:ct-grid/GridColumn instances.

setGridView(gridView)

The opportunity for the data provider to add itself as a listener to the the module:ct-grid/GridView as a renderer event listener.

Parameters:
Name Type Description
gridView module:ct-grid/GridView

The view that the data provider/controller can use to communicate with the View/Model.

setGroupByField(fieldName)

Sets the field to be used for grouping the rows within the row model.

Parameters:
Name Type Description
fieldName string

The field name that will be used for grouping.

setRequiredFields(fieldNames)

Sets the required fields that this data provider should provide within each record.

Parameters:
Name Type Description
fieldNames Array.<string>

A list of field names.

setRowData(subject, fieldData)

Updates the data on editable row.

Currently the data received is updated in a local cache and merged with received data works only if supported by implementing class (bEditable is set to true)

Parameters:
Name Type Description
subject String

subject (objectName) of the row to be updated
fieldData Object

map with field name and values to be updated for the subject specified

setRowRange(startIndex, size)

Sets the start index and total number of rows that this GridDataProvider should supply when notifying listeners of row updates — this will change as the view is scrolled or resized to reveal different rows.

Parameters:
Name Type Description
startIndex int

The start index of the first row within the range.
size int

The number of rows within the range.
See:

setSortRule(sortRule)

Set a rule that will be used to sort the data within the row model.

Parameters:
Name Type Description
sortRule module:ct-grid/sort/SortRule

The object containing the sort parameters.

setTransformMode(transformMode)

Sets the update mode that determines how grid updates are pushed out from the data source.

Parameters:
Name Type Description
transformMode string

The update mode to use.

supportsFeature(feature)

Determine whether this instance of GridDataProvider supports a particular feature.

Parameters:
Name Type Description
feature int

the feature constant that is being queried.
See:

terminateUpdates()

Signals the GridDataProvider to permanently terminate updates to any GridDataProviderListener instances.

This method is essentially the destructor for classes implementing GridDataProvider, and is the opportunity to perform any clean-up that may be required.