# Integration with SpreadJS Components

## Content

DataManager provides the structured data model consumed by advanced SpreadJS components.
It does not render UI or handle interaction.
Instead, components bind to structured tables or views defined in the Workbook’s DataManager.

## Integration Pattern

The integration follows a consistent model:

1. Access the Workbook’s DataManager
2. Define a table
3. Optionally configure schema and relationships
4. Create a view (when required)
5. Bind the view or table to a component

Different components consume the model in different ways, but all rely on the same DataManager instance.

## TableSheet

TableSheet binds to a **view**.

```javascript
const dataManager = spread.dataManager();

// Define a table
const table = dataManager.addTable("Employees", {
    data: [
        { id: 1, name: "John" },
        { id: 2, name: "Jane" }
    ]
});

// Create a view
const view = table.addView("employeeView", [
    { value: "id", caption: "ID" },
    { value: "name", caption: "Name" }
]);

await view.fetch();

// Bind to TableSheet
const tableSheet = spread.addSheetTab(
    0,
    "Employees",
    GC.Spread.Sheets.SheetType.tableSheet
);

tableSheet.setDataView(view);
```

TableSheet consumes a view projection of the table.
All structural logic remains inside DataManager.
See the [TableSheet](/spreadjs/docs/features/tablesheet) documentation for component configuration details.

## GanttSheet

GanttSheet binds to a **hierarchical view**.

```javascript
const dataManager = spread.dataManager();

const taskTable = dataManager.addTable("Tasks", {
    data: [
        { id: 1, name: "Planning", parentId: null },
        { id: 2, name: "Execution", parentId: 1 }
    ],
    schema: {
        hierarchy: {
            type: "Parent",
            column: "parentId"
        },
        columns: {
            id: { isPrimaryKey: true }
        }
    }
});

const view = taskTable.addView("taskView", [
    { value: "name", caption: "Task Name" }
]);

await view.fetch();

const ganttSheet = spread.addSheetTab(
    0,
    "Gantt",
    GC.Spread.Sheets.SheetType.ganttSheet
);

ganttSheet.bindGanttView(view);
```

Hierarchy configuration is defined in the schema.
GanttSheet renders the hierarchical structure.
See the [GanttSheet](/spreadjs/docs/features/ganttsheet) documentation for component configuration details.

## ReportSheet

ReportSheet binds directly to a **table** using data bindings.

```javascript
const dataManager = spread.dataManager();

const orders = dataManager.addTable("Orders", {
    data: [
        { orderId: 1001, customer: "A" },
        { orderId: 1002, customer: "B" }
    ]
});

await orders.fetch();

const reportSheet = spread.addSheetTab(
    0,
    "Report",
    GC.Spread.Sheets.SheetType.reportSheet
);

const template = reportSheet.getTemplate();

template.setTemplateCell(1, 0, {
    type: "List",
    binding: "Orders[orderId]"
});

reportSheet.refresh();
```

ReportSheet consumes structured table data through binding expressions.
See the [ReportSheet](/spreadjs/docs/features/reportsheet) documentation for component configuration details.

## Data Chart

Data Chart uses table data for visualization.

```javascript
const dataManager = spread.dataManager();

const price = dataManager.addTable("Price", {
    data: [
        { product: "ItemA", price: 100 },
        { product: "ItemB", price: 120 }
    ]
});

await price.fetch();

const sheet = spread.getActiveSheet();

const chart = sheet.dataCharts.add("chart", 10, 10, 400, 300);

chart.setChartConfig({
    tableName: "Price",
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{ field: "price" }],
            category: { field: "product" }
        }
    }]
});
```

The chart references the table by name.
DataManager remains the source of structured data.
See the [Data Charts](/spreadjs/docs/features/data-charts) documentation for component configuration details.

## PivotTable

PivotTable can use a DataManager Table or View as a direct data source.
Use a DataManager Table source for single-table analysis. Use a DataManager View source when the PivotTable needs projected fields, filtered results, calculated fields, or relation-based fields exposed by a View.

```javascript
const dataManager = spread.dataManager();

const salesTable = dataManager.addTable("TableSales", {
    data: [
        { salesperson: "Alan", product: "Laptop", total: 2598 },
        { salesperson: "Bob", product: "Phone", total: 2697 }
    ],
    schema: {
        columns: {
            salesperson: { dataType: "string" },
            product: { dataType: "string" },
            total: { dataType: "number" }
        }
    }
});

await salesTable.fetch();

const sheet = spread.getActiveSheet();

const pivotTable = sheet.pivotTables.add(
    "dataManagerPivot",
    {
        source: "TableSales",
        autoRefresh: true
    },
    1,
    1,
    GC.Spread.Pivot.PivotTableLayoutType.outline,
    GC.Spread.Pivot.PivotTableThemes.medium8
);

pivotTable.add("salesperson", "Salesperson", GC.Spread.Pivot.PivotTableFieldType.rowField);
pivotTable.add("product", "Product", GC.Spread.Pivot.PivotTableFieldType.rowField);
pivotTable.add("total", "Total", GC.Spread.Pivot.PivotTableFieldType.valueField, GC.Pivot.SubtotalType.sum);
```

PivotTable creates or refreshes PivotCache data from the DataManager source. DataManager remains responsible for table definitions, views, relationships, fetch, and data changes.
For PivotTable creation details, see [Create Pivot Table.](/spreadjs/docs/features/pivot-table/create-pivot-table) For refresh behavior, see [Data Settings](/spreadjs/docs/features/pivot-table/refresh-data-source).

## Shared Data Model

Because DataManager belongs to the Workbook:

* Multiple components share the same tables
* A single table can support multiple views
* Updates propagate across bound components

This ensures consistent data behavior across the application.

## Responsibility Boundary

DataManager is responsible for:

* Table structure
* Schema rules
* Relationships
* Hierarchy configuration
* Calculation and synchronization

Components are responsible for:

* Rendering
* Layout
* Interaction
* Component-specific commands

Each component provides its own documentation for UI configuration and advanced features.

## Converting Worksheet Tables to Data Tables

In addition to defining tables directly through the DataManager API, SpreadJS allows you to convert an existing worksheet table into a DataManager table.
This enables a traditional sheet table to participate in the structured data modeling system, including:

* Schema configuration
* View creation
* Component binding
* Data relationships

The conversion process:

* Creates a new DataManager table
* Binds the original worksheet table to it
* Moves data management responsibility to the DataManager

After conversion, the worksheet table acts as a view of the underlying DataManager table.
Programmatic conversion is supported through dedicated APIs, and Designer also provides a visual conversion workflow.
For detailed conversion rules, constraints, and examples, see [Convert from/to Data Table](/spreadjs/docs/features/tablegen/convert-fromto-data-table).