ServerSidePlugin

Server-Side Data Plugin for tbw-grid

Central data orchestrator for the grid. Manages fetch, cache, and row-model for server-side data loading. Structural plugins (Tree, GroupingRows) can claim data via events; the core grid uses it as flat rows when unclaimed.

Installation

import { ServerSidePlugin } from '@toolbox-web/grid/plugins/server-side';

DataSource Interface

interface ServerSideDataSource {
  getRows(params: GetRowsParams): Promise<GetRowsResult>;
  getChildRows?(params: GetChildRowsParams): Promise<GetChildRowsResult>;
}

Configuration Options

Option	Type	Description
pageSize?	number	Number of nodes to request per fetch. This determines the endNode - startNode range passed to getRows(). Smaller values mean faster initial loads but more frequent requests while scrolling.
cacheBlockSize?	number	Number of nodes kept in each cache block. When a block is evicted (e.g. scrolled far away), re-scrolling back triggers a new fetch. Should be ≥ pageSize; larger values reduce re-fetches at the cost of memory.
maxConcurrentRequests?	number	Maximum number of concurrent getRows() requests. Limits how many blocks can be fetched simultaneously during fast scrolling. Set to 1 for strict sequential loading; higher values improve perceived performance.
loadThreshold?	number	Prefetch slack in node count (rows). When > 0, blocks are loaded as soon as the user is within loadThreshold rows of an unloaded block, rather than only when the visible window enters it. This reduces the number of placeholder rows the user sees during gentle scrolling at the cost of slightly more eager fetching.
dataSource?	ServerSideDataSource<unknown>	Data source for server-side loading. When provided, the plugin auto-initializes on attach — no need to call setDataSource().
sortMode?	server | local	How sort changes affect the cache. - 'server' (default): purge cache and refetch via getRows({ sortModel }). Use when the backend supports the requested sort shape natively. - 'local': keep the loaded blocks; sort the loaded rows in-place via the active sort plugin (MultiSort or core sort). sortModel is not sent on subsequent block fetches. Placeholder rows (__loading: true) are pinned to the end regardless of direction.
filterMode?	server | local	How filter changes affect the cache. - 'server' (default): purge cache and refetch via getRows({ filterModel }). - 'local': keep the loaded blocks; filter only the rows currently in cache via FilteringPlugin’s normal pipeline. filterModel is not sent on subsequent block fetches.

Example

Basic Server-Side Loading

import '@toolbox-web/grid';
import '@toolbox-web/grid/features/server-side';

grid.gridConfig = {
  columns: [...],
  features: {
    serverSide: {
      pageSize: 50,
      dataSource: {
        async getRows(params) {
          const response = await fetch(
            `/api/data?start=${params.startNode}&end=${params.endNode}`
          );
          const data = await response.json();
          return { rows: data.rows, totalNodeCount: data.total };
        },
      },
    },
  },
};

See Also

• ServerSideConfig for configuration options
• ServerSideDataSource for data source interface

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Methods

setDataSource()

Set the data source for server-side loading.

setDataSource(dataSource: ServerSideDataSource): void

Parameters

Name	Type	Description
dataSource	ServerSideDataSource	Data source implementing the getRows method (and optionally getChildRows)

---

refresh()

Refresh all data from the server. Purges cache and refetches from block 0.

refresh(): void

---

purgeCache()

Clear all cached data without refreshing.

purgeCache(): void

---

getTotalNodeCount()

Get the total node count from the server.

getTotalNodeCount(): number

---

getTotalRowCount()

⚠️ Deprecated: Use getTotalNodeCount instead. Will be removed in a future version.

getTotalRowCount(): number

---

isNodeLoaded()

Check if a specific node is loaded in the cache.

isNodeLoaded(nodeIndex: number): boolean

Parameters

Name	Type	Description
nodeIndex	number	Node index to check

---

isRowLoaded()

⚠️ Deprecated: Use isNodeLoaded instead. Will be removed in a future version.

isRowLoaded(rowIndex: number): boolean

Parameters

Name	Type	Description
rowIndex	number

---

getLoadedBlockCount()

Get the number of loaded cache blocks.

getLoadedBlockCount(): number

---