Server-side Datasource

This section describes the Server-side Datasource and demonstrates how it can be used to lazy load data from a server through an infinite scroll.

The Server-side Row Model requires a datasource to fetch rows for the grid. When users scroll or perform grid operations such as sorting or grouping more data will be requested via the datasource.

The Server-side Datasource does not impose any restrictions on the server side technologies used. It is left up to applications to decide how and where data is sourced for the grid.

Enabling Server-side Row Model

When no row model is specified the grid will use the Client-side Row Model by default. To use the Server-side Row Model instead, set the rowModelType as follows:

gridOptions.rowModelType = 'serverSide'

Implementing the Server-side Datasource

A datasource is used by the Server-side Row Model to fetch rows for the grid. Applications are required to implement a datasource that conforms to the Server-side Datasource Interface.

The following snippet shows a simple datasource implementation:

function createDatasource(server) { return { // called by the grid when more rows are required getRows: function(params) { // get data for request from server var response = server.getData(params.request); if (response.success) { // supply rows for requested block to grid params.successCallback(response.rows, response.lastRow); } else { // inform grid request failed params.failCallback(); } } }; }

Notice that the datasource contains a single method getRows(params) which is called by the grid when more rows are required. A request is supplied in the params which contains all the information required by the server to fetch data from the server.

Rows fetched from the server are supplied to the grid via params.successCallback(rows,lastRowIndex). Note the lastRowIndex can be optionally supplied to the grid. If the server knows how many rows are in the dataset, then lastRowIndex informs the grid of this number so the grid can adjust the range of the vertical scrollbar to match the entire dataset contained on the server. Otherwise the grid will assume the total number of rows is not known and the vertical scrollbar range will grow as the user scrolls down (the default behaviour for infinite scroll).

Registering the Datasource

The datasource is registered with the grid via the grid api as follows:

var myDatasource = createDatasource(); gridOptions.api.setServerSideDatasource(myDatasource);

Example: Infinite Scroll

The example below demonstrates lazy loading of data with an infinite scroll. Notice the following:

  • The Server-side Row Model is selected using the grid options property: rowModelType = 'serverSide'.
  • The datasource is registered with the grid using: api.setServerSideDatasource(datasource).
  • A request is contained in params supplied to getRows(params) with startRow and endRow. This is used by the server to determine the range of rows to return.
  • When scrolling down there is a delay as more rows are fetched from the server.
  • Open the browsers dev console to view the contents of the requests made by the grid for more rows.

Datasource Interface

The interface for the Server-sie Datasource is show below:

interface IServerSideDatasource { // grid calls this to get rows getRows(params: IServerSideGetRowsParams): void; // optional destroy method, if your datasource has state it needs to clean up destroy?(): void; }

Each time the grid requires more rows, it will call the getRows() method. The method is passed a params object that contains two callbacks (one for success and one for failure) and a request object with details what row the grid is looking for.

The interface for the params is shown below:

interface IServerSideGetRowsParams { // details for the request, simple object, can be converted to JSON request: IServerSideGetRowsRequest; // the parent row node. is the RootNode (level -1) if request is top level. // this is NOT part fo the request as it cannot be serialised to JSON (a rowNode has methods) parentNode: RowNode; // success callback, pass the rows back the grid asked for. // if the total row count is known, provide it via lastRow, so the // grid can adjust the scrollbar accordingly. successCallback(rowsThisPage: any[], lastRow: number): void; // fail callback, tell the grid the call failed so it can adjust its state failCallback(): void; // grid API api: GridApi; // column API columnApi: ColumnApi; }

The request gives details on what the grid is looking for. The success and failure callbacks are not included inside the request object to keep the request object simple data (ie simple data types, no functions). This allows the request object to be serialised (eg via JSON) and sent to your server.

The interface for the request is shown below:

interface IServerSideGetRowsRequest { // first row requested startRow: number; // last row requested endRow: number; // row group columns rowGroupCols: ColumnVO[]; // value columns valueCols: ColumnVO[]; // pivot columns pivotCols: ColumnVO[]; // true if pivot mode is one, otherwise false pivotMode: boolean; // what groups the user is viewing groupKeys: string[]; // if filtering, what the filter model is filterModel: any; // if sorting, what the sort model is sortModel: any; } // we pass a VO (Value Object) of the column and not the column itself, // so the data can be converted to a JSON string and passed to server-side export interface ColumnVO { id: string; displayName: string; field: string; aggFunc: string; }

Next Up

Continue to the next section to learn about Server-side Configuration.