Caplin Trader 4.8.0

Interface: module:caplin/grid/GridDataProviderListener

module:caplin/grid/GridDataProviderListener

This interface is implemented by the module:caplin/grid/DataProviderRowModel so that GridDataProvider instances are able to communicate data changes as they occur. GridDataProvider instances are given a reference to any listeners that may be interested in these events via the module:caplin/grid/GridDataProvider#addDataProviderListener method.

Implementations:

Methods

onDataProviderStateChange(subject, state, sourceState)

This callback is invoked when the state of the container subscription changes.
Parameters:
Name Type Description
subject string The container subject
state string The container state
sourceState object additional information provided by the upstream source detailing the reason for this event. The information provided is wholly dependant upon the upstream source implementation.
Properties
Name Type Description
code string The upstream source's status code
status string The upstream source's status description
Implementations:
  • module:caplin/grid/DataProviderRowModel#onDataProviderStateChange

onDataReceived()

Implementations:
  • module:caplin/grid/DataProviderRowModel#onDataReceived

onDataRequested()

This callback is invoked when a request for a data has been initiated (but not a window-adjusting request)
Implementations:
  • module:caplin/grid/DataProviderRowModel#onDataRequested

onDataUnavailable(reason)

This callback is invoked when a request for data fails.
Parameters:
Name Type Description
reason string A brief description of what the error is. The enumeration module:caplin/grid/RowDataUnavailable provides a list of the possible values.
Implementations:
  • module:caplin/grid/DataProviderRowModel#onDataUnavailable

onRecordAdded(recordId, recordIndex, record, alternateId)

Callback that occurs when one or more of the visible records are replaced by new records and need to be completely redrawn.

This may happen because the user has scrolled the grid display causing different records to be displayed at the old indices, or when the underlying data changes, such that records are inserted, deleted or removed. When module:caplin/grid/GridDataProvider.PAGING is in use then only records within the range defined by module:caplin/grid/GridDataProvider#setRowRange are reported on.

Parameters:
Name Type Description
recordId String the unique identifier that the module:caplin/grid/GridDataProvider is using to track the records that it reports on.
recordIndex int The row index at which the record exists.
record Map The map of name value/pairs that contain the record data.
alternateId String Alternate Identifier (Deprecated, as there is no known need for an alternate id)
Implementations:
  • module:caplin/grid/DataProviderRowModel#onRecordAdded

onRecordContentsChanged(recordId, recordUpdates)

Callback that occurs when there are updates to one or more of the visible records.
Parameters:
Name Type Description
recordId String the unique identifier that the module:caplin/grid/GridDataProvider is using to track the records that it reports on.
recordUpdates Map a map containing the updated field data.
Implementations:
  • module:caplin/grid/DataProviderRowModel#onRecordContentsChanged

onRecordMoved(recordId, newIndex)

Callback that occurs when a visible record is moved to a new location, and remains visible within the current page.

If a record moves out of view, then the data provider does not need to perform any action, since that record will either be overwritten by some other module:caplin/grid/GridDataProviderListener#onRecordAdded or module:caplin/grid/GridDataProviderListener#onRecordMoved invocation, or will be effectively removed by an module:caplin/grid/GridDataProviderListener#onSizeChanged invocation with a smaller size that means that some of the previous row indices no longer exist at all.

Parameters:
Name Type Description
recordId String the unique identifier that the module:caplin/grid/GridDataProvider is using to track the records that it reports on.
newIndex int The row index at which the record will now exist.
Implementations:
  • module:caplin/grid/DataProviderRowModel#onRecordMoved

onRecordRemoved(recordId)

Callback that occurs when a visible record is removed/deleted.

If a record is deleted from the source of the data provider's data then calling this should clean up any reference to the now defunct row.

Parameters:
Name Type Description
recordId String the unique identifier that the module:caplin/grid/GridDataProvider is using to track the records that it reports on.
Implementations:
  • module:caplin/grid/DataProviderRowModel#onRecordRemoved
  • module:caplin/grid/PersonalGridDataProvider#onRecordRemoved

onSizeChanged(newSize, oldSize)

Callback that occurs when the number of underlying records available changes.

This has no relation to the number of records that are being displayed, and is only a measure of the available records.

Parameters:
Name Type Description
newSize int the total number of available records.
oldSize int the previous total number of available records.
Implementations:
  • module:caplin/grid/DataProviderRowModel#onSizeChanged
  • module:caplin/grid/PersonalGridDataProvider#onSizeChanged

onStartIndexChanged(newStartIndex)

Callback that occurs when, for some reason, the data provider wishes to change the start index that the view is currently looking at.

This event allows the data provider to adjust the start index that the view has previously set using module:caplin/grid/GridDataProvider#setRowRange. There are a number of reasons a data provider might wish to do this:

  1. The number of available records is updated to be smaller than the currently displayed start index, meaning that the view would otherwise now display zero records.
  2. The user wishes to track the current record they are looking at as new records appear at the top of the list.
  3. If the user is already scrolled to the top, then they wish to stay at the top even when new records appear above the previous top one.
  4. If the user is already scrolled to the bottom, then they wish to stay at the bottom even when new records appear below the previous bottom one.

All of these scrolling strategies could be, and probably should be, implemented within the module:caplin/grid/DataProviderRowModel, but for the purposes of efficiency it is also useful to allow them to be implemented directly within data provider, since this allows the number of round trips for data to be reduced.

Parameters:
Name Type Description
newStartIndex int
Implementations:
  • module:caplin/grid/DataProviderRowModel#onStartIndexChanged

onStructureChangeComplete()

Callback that occurs after a number of invocations to module:caplin/grid/GridDataProviderListener#onRecordAdded, module:caplin/grid/GridDataProviderListener#onRecordMoved or module:caplin/grid/GridDataProviderListener#onSizeChanged have been made, informing the module:caplin/grid/DataProviderRowModel, and underlying module:caplin/grid/GridView that all updates can now be rendered.

Allowing updates to be batched like this allows the module:caplin/grid/GridView class to perform more efficiently since it is able to use a single call to innerHTML to re-render a changed grid, rather than making lots of expensive, individual DOM calls.

Implementations:
  • module:caplin/grid/DataProviderRowModel#onStructureChangeComplete
  • module:caplin/grid/decorator/SubjectDecorator#onStructureChangeComplete