Server-Side Data (PageCacheDataSource)#

#Overview

PageCacheDataSource loads data from a remote server in pages, caching them in memory with LRU eviction. Cells that haven't been fetched yet render as skeleton loading placeholders.

#Creating a page cache

use rs_grid_core::page_cache::PageCacheDataSource;

let cache = PageCacheDataSource::new(
    10_000, // total rows (initial estimate)
    100,    // page size (rows per page)
);
cache.set_max_cached_pages(50); // default: 50

let model = GridModel::with_data_source(
    columns,
    Box::new(cache.clone()),
    32.0,
    36.0,
);
model.mode = DataSourceMode::ServerSide;

#Page lifecycle

needed_pages() → mark_pending() → fetch → insert_page() → NotifyPageLoaded

1. Detect needed pages — call cache.needed_pages(first_row, last_row) to find pages in the visible range that are neither loaded nor pending
2. Mark as pending — cache.mark_pending(page_num) prevents duplicate fetches
3. Fetch data — your application fetches the data from the server
4. Insert the page — cache.insert_page(page_num, rows) stores the data
5. Update the total — cache.set_total_rows(n) when the server response reveals the real count; also dispatch state.apply(GridCommand::SetTotalRowCount(n)) (see Row-number gutter width below — this is not automatic)
6. Notify the grid — state.apply(GridCommand::NotifyPageLoaded) triggers re-render

#FetchConfig (automatic fetching)

rs-grid-web provides a built-in fetch coordinator via FetchConfig:

pub struct FetchConfig {
    pub build_url: Box<dyn Fn(&PageFetchRequest) -> String>,
    pub parse_response: Box<dyn Fn(JsValue) -> Result<PageFetchResponse, String>>,
    pub buffer_pages: u64,  // prefetch ahead/behind
}

#PageFetchRequest

pub struct PageFetchRequest {
    pub page_num: u64,
    pub page_size: u64,
    pub sort: Option<SortState>,
    pub filters: HashMap<String, String>,
}

The fetcher automatically:

• Checks which pages are needed for the current viewport
• Prefetches buffer_pages pages ahead and behind
• Spawns async window.fetch() calls
• Parses JSON responses via your parse_response closure
• Updates the cache, dispatches SetTotalRowCount, and triggers NotifyPageLoaded

#API reference

#CellStatus

PageCacheDataSource returns meaningful CellStatus values:

The renderer draws a skeleton animation for Loading cells.

#LRU eviction

When the cache exceeds max_cached_pages, the least-recently-accessed pages are evicted. Re-accessing a page moves it to the back of the eviction queue.

#Invalidation on sort/filter change

When sort or filter changes in server-side mode, call cache.clear() to invalidate all pages, then let the fetcher re-fetch with the new parameters.

#Row-number gutter width

The row-number gutter's width (GridModel.row_number_width) is sized from the digit count of the row total (GridModel::compute_row_number_width) — when you start from a placeholder count (e.g. PageCacheDataSource::new(0, page_size) per the server-pagination guide), it's sized for that placeholder, not the real total.

GridCommand::SetTotalRowCount(n) recomputes it once the real total is known — the FetchConfig fetcher (above) dispatches this automatically alongside set_total_rows/NotifyPageLoaded, so you only need to think about this if you're driving the page cache manually (steps 1–6 above). If you've set an explicit width via GridCommand::SetRowNumberWidth, it's treated as a deliberate override and SetTotalRowCount no longer touches it.

#Shared state

PageCacheDataSource uses Rc<RefCell<...>> internally — cloning it creates a shared reference to the same cache. This is how the fetch coordinator and the grid model share the same data.