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.
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()
-
This callback is invoked when requested data is first received - before any calls to
module:caplin/grid/GridDataProviderListener#onRecordAdded
,module:caplin/grid/GridDataProviderListener#onRecordMoved
ormodule:caplin/grid/GridDataProviderListener#onSizeChanged
ormodule:caplin/grid/GridDataProviderListener#onStructureChangeComplete
are called.- 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 bymodule: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
ormodule:caplin/grid/GridDataProviderListener#onRecordMoved
invocation, or will be effectively removed by anmodule: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:- 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.
- The user wishes to track the current record they are looking at as new records appear at the top of the list.
- 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.
- 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
ormodule:caplin/grid/GridDataProviderListener#onSizeChanged
have been made, informing themodule:caplin/grid/DataProviderRowModel
, and underlyingmodule: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 toinnerHTML
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