Caplin Trader 4.8.0

Interface: module:caplin/grid/GridDataProvider

module:caplin/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:caplin/grid/DataProviderRowModel. The GridDataProvider interface is much simpler to implement than the full module:caplin/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:caplin/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.

Implementations:
Implements:

Members

(static, readonly) FILTERING :int

A constant definition used with module:caplin/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:caplin/grid/GridDataProvider#setFilters.

Type:
  • int

(static, readonly) PAGING :int

A constant definition used with module:caplin/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:caplin/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:caplin/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:caplin/grid/GridDataProviderListener The listener to add.
    Implementations:
    See:

    canReceive()

    Implementations:
    See:

    canReceiveMultipleObjects()

    Implementations:
    See:

    canReceiveObjects()

    Implementations:
    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.
    Implementations:

    clearGroupByField()

    Removes any grouping from the grid row model.
    Implementations:

    clearSortRule()

    Removes any sorting from the grid row model.
    Implementations:

    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:caplin/grid/GridDataProvider#getSerializedState method is invoked.
    Implementations:

    getAllFilterExpressions() → {map}

    A map of all the filter expressions added to this data provider.
    Implementations:
    Returns:
    A map of module:caplin/grid/filter/FilterExpression instances, if any exist, or an empty map otherwise.
    Type
    map

    getFilterExpression(filterName) → {module:caplin/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.
    Implementations:
    Returns:
    A FilterExpression, if one exists, or null otherwise.
    Type
    module:caplin/grid/filter/FilterExpression

    getGroupByField() → {string}

    Get the field, if one has been set, that is used to group the rows contained within row model.
    Implementations:
    Returns:
    a String, if one exists, or null otherwise.
    Type
    string

    getLastReceiveFailureMessage()

    Implementations:
    • module:caplin/grid/PersonalGridDataProvider#getLastReceiveFailureMessage
    See:

    getPermissionKey() → {module:caplin/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.

    Implementations:
    • module:caplin/grid/PersonalGridDataProvider#getPermissionKey
    • module:caplin/grid/RttpContainerGridDataProvider#getPermissionKey
    • module:caplin/grid/WebServiceGridDataProvider#getPermissionKey
    Returns:
    a permissioning key, or null.
    Type
    module:caplin/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:caplin/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:caplin/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:

    caplin.grid.RttpContainerGridDataProvider.prototype.getSerializedState = function() {
    if (this.m_bStateChanged || !this.m_bDataProviderDefinedByParent) {
        var sEncodedContainerName = caplin.core.XmlUtility.encodeValue(this.m_sOriginalContainerName);
        return '		\n';
    }
    return null;
};
    Implementations:
    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:caplin/grid/sort/SortRule}

    Get the rule, if one exists, that is used to sort the data within the row model.
    Implementations:
    Returns:
    a SortRule, if one exists, or null otherwise.
    Type
    module:caplin/grid/sort/SortRule

    getStartIndex() → {int|null}

    Returns the start index that is set on the Data Provider via the module:caplin/grid/GridDataProvider#setRowRange method.
    Implementations:
    • module:caplin/grid/RttpContainerGridDataProvider#getStartIndex
    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:caplin/grid/GridDataProviderSnapshotListener
    Implementations:

    getSuccessMessage()

    Implementations:
    • module:caplin/grid/PersonalGridDataProvider#getSuccessMessage
    See:

    getTransformMode() → {string}

    Get the transform mode that determines how grid updates are pushed out from the data source.
    Implementations:
    • module:caplin/grid/dataprovider/sljs/SLJSContainerDataProvider#getTransformMode
    • module:caplin/grid/PersonalGridDataProvider#getTransformMode
    • module:caplin/grid/RttpContainerGridDataProvider#getTransformMode
    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
    Implementations:

    pauseUpdates()

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

    This method is invoked as a consequence of module:caplin/grid/DataProviderRowModel#pauseUpdates being invoked. This method is a hint only, as the module:caplin/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.

    Implementations:
    See:

    receiveObjects()

    Implementations:
    • module:caplin/grid/PersonalGridDataProvider#receiveObjects
    See:

    removeDataProviderListener(listener)

    Removes a GridDataProviderListener that no longer wishes to listen to data updates.
    Parameters:
    Name Type Description
    listener module:caplin/grid/GridDataProviderListener The listener to remove.
    Implementations:
    See:

    resumeUpdates()

    Signals the GridDataProvider to resume updates to all GridDataProviderListener instances.
    Implementations:
    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:caplin/grid/filter/FilterExpression A filter expression to apply to this data provider.
    filterName string The name of the filter.
    Implementations:

    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:caplin/grid/GridColumnFilter instances.
    allColumns map A map of all GridView's column module:caplin/grid/GridColumn instances.
    Implementations:

    setGridView(gridView)

    The opportunity for the data provider to add itself as a listener to the the module:caplin/grid/GridView as a renderer event listener.
    Parameters:
    Name Type Description
    gridView module:caplin/grid/GridView The view that the data provider/controller can use to communicate with the View/Model.
    Implementations:

    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.
    Implementations:

    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.
    Implementations:

    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
    Implementations:

    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.
    Implementations:
    See:

    setSortRule(sortRule)

    Set a rule that will be used to sort the data within the row model.
    Parameters:
    Name Type Description
    sortRule module:caplin/grid/sort/SortRule The object containing the sort parameters.
    Implementations:

    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.
    Implementations:
    • module:caplin/grid/PersonalGridDataProvider#setTransformMode
    • module:caplin/grid/RttpContainerGridDataProvider#setTransformMode

    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.
    Implementations:
    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.

    Implementations: