# Worksheet Table Binding with DataManager

## Content

A worksheet table can bind directly to a DataManager table. When collaboration is enabled, the worksheet table can participate in collaboration as a DataManager-based binding scenario.
The collaboration behavior depends on whether the bound DataManager table uses Local Data or Remote Data.

## Local Data

When the worksheet table is bound to a DataManager table that uses JSON-based in-memory local data, supported table state and supported data changes can participate in collaboration.
In this mode, collaborators can view and operate on the same bound worksheet table. Supported operations are synchronized through the collaboration system.
Local Data is suitable when the DataManager table data is managed by SpreadJS during the collaboration session.

## Remote Data

When the worksheet table is bound to a DataManager table that uses Remote Data, the remote data source itself does not participate in collaboration.
SpreadJS synchronizes supported binding-related state, such as:

* Binding configuration
* Worksheet table range
* Related worksheet table state

Remote data consistency is controlled by the business application. The business application is responsible for backend data persistence, remote data change notifications, refresh timing, and layout synchronization decisions.
In collaboration, operations that modify remote bound data or affect the bound data area are not applied as normal worksheet table editing operations.

## Supported Operations

The following table summarizes worksheet table behavior when the table is bound directly to a DataManager table.

| Operation | Local Data | Remote Data |
| --------- | ---------- | ----------- |
| Sort and filter | Supported | Supported |
| Show or hide table header or footer | Supported | Supported |
| Modify binding columns | Supported | Supported |
| Rebind the worksheet table | Supported | Supported |
| Move the worksheet table | Supported | Supported |
| Edit bound data cells | Supported | Not supported |
| Copy, paste, or drag fill within the bound data area | Supported | Not supported |
| Insert or delete table rows or columns | Supported | Not supported |
| Insert or delete worksheet rows or columns when the affected range includes the bound worksheet table | Supported | Not supported |
| Resize or expand the worksheet table range | Supported | Not supported |

For Remote Data, unsupported operations are not applied in collaboration.

## Remote Data Refresh and Table Layout Synchronization

For a worksheet table bound to Remote Data, SpreadJS does not synchronize the remote data source through the collaboration system.
When the remote data changes in the backend, the business application must decide:

* How clients are notified that the remote data changed
* Which clients fetch the latest remote data
* When the worksheet table layout should be synchronized with the latest data
* Which clients are allowed to perform layout synchronization

SpreadJS provides two refresh patterns.

## Default Refresh Mode

Use the default refresh mode when the application wants to fetch the latest remote data and update the bound worksheet table layout in one step.
Call `fetch(true)` on the DataManager table.
This flow:

1. Fetches the latest Remote Data.
2. Updates the worksheet table layout bound to that data source according to the latest data.

This mode is straightforward and suitable when there are relatively few online clients or when the application wants to update the bound worksheet table immediately after receiving a remote data change notification.

## Split Refresh Mode

Use split refresh mode when the application needs more control over when table layout synchronization occurs.
This mode separates remote data refresh from worksheet table layout synchronization.
The flow uses the following APIs:

* `refreshRemoteData()` on the DataManager table
* `isTableLayoutDirty()` on the worksheet table
* `adjustTableRangeForBind()` on the worksheet table

The typical flow is:

1. Call `refreshRemoteData()` to fetch the latest Remote Data.
2. Call `isTableLayoutDirty()` to determine whether the worksheet table layout no longer matches the latest data.
3. Call `adjustTableRangeForBind()` when the application decides to synchronize the worksheet table layout.

This mode is useful when many collaborators are online, when remote data changes frequently, or when the application needs to control which client performs layout synchronization.

## Business-Side Responsibilities

For Remote Data, SpreadJS does not determine which client has the newest remote data and does not merge conflicts based on remote data content.
The business application should manage:

* Remote data versioning
* Change notification order
* Retry behavior when remote requests fail
* Which clients can synchronize worksheet table layout
* When layout synchronization should occur

If multiple clients attempt to synchronize layout based on different remote data states, the final collaboration result depends on the collaboration flow. To reduce conflicts, allow only clients with the latest known remote data version to perform layout synchronization.