# SpreadJS Sheets Collaboration

## Content

SpreadJS integrates the [Collaboration Framework](/spreadjs/docs/v18/spreadjs-collaboration-server/collaboration-framework) along with the extension packages `spread-sheets-collaboration` and the SpreadJS plugin `spread-sheets-collaboration-addon` to deliver a seamless experience for both local synchronization and remote collaboration. This enables real-time multi-user collaborative editing.

## Architecture Design

### Overall Process

![overview](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/overview.0c39e3.png)

### Core Components

* **[Collaboration Framework](/spreadjs/docs/v18/spreadjs-collaboration-server/collaboration-framework)**: The foundational framework for real-time collaboration, handling communication and operation synchronization between client and server.
* **[SpreadJS Sheets Collaboration](/spreadjs/docs/v18/spreadjs-collaboration-server/spreadjs-sheets-collaboration/spreadjs-sheets-collaboration-packages)**: An extension package for the Collaboration Service, providing dedicated **Operational Transformation (OT)** types for workbook. It includes **Reducer** and **Transform** logic to ensure data consistency during concurrent editing.
* **[SpreadJS Sheets Collaboration Add-on](/spreadjs/docs/v18/spreadjs-collaboration-server/spreadjs-sheets-collaboration/spreadjs-sheets-collaboration-add-on)**: A plugin for workbook that listens for changes in the data model, generates operations (ops), and integrates them into **ChangeSets** for server interaction. It also applies **ChangeSets** pushed from the server to the local data model.

## Working Mechanism

* **Local Synchronization**: Involves only the `spread-sheets-collaboration-addon` plugin, which monitors data model changes and synchronizes them across multiple workbook instances within the same page, without requiring server intervention.
* **Remote Collaboration**: The `spread-sheets-collaboration-addon` listens for changes in the workbook data model, generates corresponding operations, and integrates them into **ChangeSets**. These are transmitted to the server via the **Collaboration Service** framework. The server leverages the communication and processing capabilities of the **Collaboration Service**, combined with the OT types (including **Transform** and **Reducer** logic) registered in `spread-sheets-collaboration`, to process these operations. The processed operations are then broadcast to all connected clients, enabling real-time collaboration across users.

## Use Cases

* **Single-User Multi-View**: Using the `spread-sheets-collaboration-addon`, multiple workbook instances on the same page can operate on the same document, suitable for scenarios requiring different views or editing perspectives.
* **Team Collaboration**: Paired with `spread-sheets-collaboration`, it supports real-time multi-user editing, ideal for team sharing and collaborative processing of workbook documents.
* **Permission Control**: Allows assigning edit or read-only permissions to different users, enhancing collaboration flexibility and security.

## Feature Overview

**Real-Time Collaboration**

* **Multi-User Editing**: Enables multiple users to edit the same workbook document simultaneously, with all operations synchronized in real-time.
* **Operational Transformation (OT)**: Employs custom OT types to ensure the consistency and correctness of concurrent operations, such as cell updates and row insertions.

**Online Presence**

* **User Identification**: Displays the selection areas and initial letters of other collaborating users’ names, making it easy to identify collaborators’ working areas.
* **Custom Colors**: Allows users to set personalized colors, improving the visibility of different collaborators’ selection areas.

**Permission Management**

* **Edit Mode**: Users can directly modify the document content.
* **View Mode**: Users can only view the document without editing capabilities.

**Local Synchronization**

* **Multi-Instance Synchronization**: Multiple workbook instances on the same page can synchronize updates in real-time, suitable for single-user multi-view scenarios.

**Collaboration Editing Status**

* **Real-Time Editing States**: When conflict operations (e.g., row add, column hide) affect the current user’s editing state, it updates the editing state and ensures proper UI display.

## Current Limitations

Features Not Supported in Collaboration:

* All binding-related features (table-level binding, sheet-level binding, cell-level binding)
* All dataManager-related features (DataCharts, GanttSheet, TableSheet, ReportSheet)
* FloatingObject and LegacyCharts

**Slicers** module collaboration **will be supported in the near future**.
The **custom features** (cellType, custom function) **follow the product serialization policy**.

* Registering a custom cellType and deploying it for all clients can be collaborated.
* Registering a custom cellType only on parts of the client's env, the clients without the custom cellType will show #NAME!.

## The Policy of Modifying Nested Objects

In SpreadJS collaboration, **direct modifications to nested objects will not trigger synchronization** because the collaboration mechanism cannot detect changes to object references. To ensure changes are synchronized, the entire object must be reset to trigger collaboration.
**Core Strategy**

1. **Direct modifications only take effect locally:**
    Changes to properties of nested objects (e.g., a style object returned by `getStyle` or nested properties of `printInfo`) are effective locally but will not be synchronized across clients.
2. **Reset the object to trigger synchronization:**
    Use corresponding methods (e.g., `setStyle` or `pageHeaderFooter of printInfo`) to reset the entire object and explicitly notify the collaboration engine of the changes to ensure synchronization.

For more detailed technical implementations or example code, please refer to the documentation for each functional unit.