A datasource is used when using row models a) pagination and b) virtual paging. This section explains the datasource used in each fo these row models.

Setting up a Datasource

The datasource is set either as a grid property or by calling setDatasource API method.

// before grid initialised
gridOptions.datasource = myDatasource;

// using the api
If you are getting the error: "TypeError: Cannot read property 'setDatasource' of undefined" - it's because you are trying to set the datasource through the setDatasource method, but the API has not been attached to the gridOptions yet by the grid. To get around this, set the datasource in the 'ready()' method.

Changing a Datasource

Changing the datasource after the grid is initialised will reset the paging in the grid. This is useful if the context of your data changes, ie if you want to look at a different set of data.

Note: If you call setDatasource the grid will act assuming it's a new datasource, resetting the paging. However you can pass in the same datasource instance. So your application, for example, might have one instance of a datasource that is aware of some external context (eg the business date selected for a report, or the 'bank ATM instance' data you are connecting to), and when the context changes, you want to reset, but still keep the same datasource instance. In this case, just call setDatasource() and pass the same datasource in again.

The Datasource Object

The datasource you provide should implement the following interface:

// Datasource used by both PaginationController and VirtualPageRowModel
interface IDatasource {

    // If you know up front how many rows are in the dataset, set it here. Otherwise leave blank.
    rowCount?: number;

    // Callback the grid calls that you implement to fetch rows from the server. See below for params.
    getRows(params: IGetRowsParams): void;

Row Count

The total number of rows, if known, is set using the attribute rowCount. If it's unknown, do not set, or set to -1. This will put the grid into infinite scrolling mode until the last row is reached. The definition of infinite scrolling depends on whether you are doing pagination or virtual paging and is explained in each of those sections. rowCount is only used when you set the datasource - if you discover what the last row is after data comes back from the server, provide this info as the second parameter of the successCallback

Function getRows()

getRows is called by the grid to load pages into the browser side cache of pages. It takes parameter, called params, which has the following interface:

// Params for the above IDatasource.getRows()
interface IGetRowsParams {

    // The first row index to get.
    startRow: number;

    // The first row index to NOT get.
    endRow: number;

    // Callback to call for the result when successful.
    successCallback(rowsThisPage: any[], lastRow?: number): void;

    // Callback to call for the result when successful.
    failCallback(): void;

    // If doing server side sorting, contains the sort model
    sortModel: any,

    // If doing server side filtering, contains the filter model
    filterModel: any,

    // The grid context object
    context: any

startRow and endRow define the range expected for the call. For example, if page size is 100, the getRows function will be called with start = 0 and end = 100 and the grid will expect a result with rows 100 rows 0..99.

successCallback and failCallback are provided to either give the grid data, or to let it know the call failed. This is designed to work with the promise pattern that Javascript HTTP calls use. The datasource must call one, and exactly one, of these methods, to ensure correct operation of the grid. Even if your server request fails, you must call 'failCallback'.

successCallback expects the following parameters:

  • rowsThisPage: An array of rows loaded for this page.
  • lastRow: The total number of rows, if known.

failCallback expects no parameters. It is up to your application to inform the user of the error. Informing the grid is necessary for the grid to internally clean up after the failure.

lastRow is used to move the grid out of infinite scrolling. If the last row is known, then this should be the index of the last row. If the last row is unknown, then leave blank (undefined, null or -1). This attribute is only used when in infinite scrolling / paging. Once the total record count is known, the total numbers of rows is fixed and cannot be changed for this grid (unless a new datasource is provided).

context is the grids context. Use this is you want to pass some context information that the datasource then has access to.

Page Size

The page size is set using the grid property paginationPageSize. This is how large the 'pages' should be. Each call to your datasource will be for one page. For simple pagination, one page is display to the user at a time. For virtual pagination, the page size is the size of the page in the grids page cache.

Next Steps

Now that you can create a datasource, go onto the next sections to set up a datasource for pagination or virtual paging.