# Named Cell Templates

## Content

Named Cell Templates allow you to define reusable cell configurations that can be applied to any supported range in a workbook.
Unlike Named Styles, which encapsulate visual style properties only, Named Cell Templates can include multiple cell-related settings in a single reusable definition:

* Style
* Conditional formatting rules
* Data validation rules
* Cell states

By grouping these configurations into a template, you can ensure consistency and reduce repetitive setup across worksheets and other supported sheet types.

## Core Concepts

### Template Definition

A Named Cell Template is:

* Identified by a unique name
* Managed at the workbook level
* Case-insensitive by name

If a template is added using a name that already exists, the previous definition is replaced.
Templates are managed through `workbook.namedCellTemplates`.

### Apply-Only Model

Named Cell Templates follow an apply-only model:

* A template takes effect only at the moment it is applied.
* No binding relationship is maintained between the template and the target range.
* Updating a template does not affect ranges where it has already been applied.

To reflect changes in previously formatted ranges, the template must be reapplied.

### Immutable Retrieval

Calling `get(name)` on the template manager returns a deep copy of the stored template.
Modifying the returned object does not affect the registered template.
To update an existing template definition, call `add()` again using the same name. The previous definition will be overwritten.

## Application Behavior

When a named cell template is applied to a target range, each configuration behaves according to the following rules:

| Setting | Behavior |
| ------- | -------- |
| Style | Overwrites existing style |
| Data Validation | Overwrites existing validation |
| Conditional Formatting | Appends new rules |
| Cell States | Appends new states |

Additional rules:

* No merging or deduplication is performed.
* Existing conditional formatting and cell state rules are preserved.
* The insertion priority of newly added rules follows the standard SpreadJS rule ordering behavior.

Because templates are apply-only, subsequent changes to the template do not propagate to previously formatted ranges.

## Managing Templates

Templates are managed through the `INamedCellTemplatesManager` exposed on the workbook:

* Add a template
* Create a template from an existing cell
* Retrieve a template
* Remove a template
* Enumerate all templates
* Clear all templates
* Serialize and deserialize via JSON

Templates are stored at the workbook level and participate in workbook serialization.
Refer to the API Reference for full method signatures and options.

* `INamedCellTemplatesManager`
* `INamedCellTemplate`

### Example: Create a Template

```javascript
spread.namedCellTemplates.add("Financial Amount", {
    style: {
        formatter: "#,##0.00",
        hAlign: GC.Spread.Sheets.HorizontalAlign.right
    },
    conditionalFormats: [{
        ruleType: GC.Spread.Sheets.ConditionalFormatting.RuleType.cellValueRule,
        operator: GC.Spread.Sheets.ConditionalFormatting.ComparisonOperators.lessThan,
        value1: 0,
        style: { foreColor: "Accent 2" }
    }]
});
```

## Sheet Type Support

Named Cell Templates can be applied to multiple sheet types. Behavior may vary slightly depending on the sheet implementation.

### Worksheet

Use `applyNamedCellTemplate` on a worksheet or a range.

```javascript
sheet.applyNamedCellTemplate("Financial Amount", "A1:A10");

// or
sheet.getRange("B1:B10")
     .applyNamedCellTemplate("Financial Amount");
```

**Supported Address Formats**

* A1-style ranges (`"A1:C3"`)
* Entire rows or columns (`"A:A"`, `"1:3"`)
* Table structured references(`"Table1"`, `"Table1[[#Data]]"`, `"Table1[[#Headers]]"`)

See the API Reference for:

* `Worksheet.applyNamedCellTemplate`
* `CellRange.applyNamedCellTemplate`

### ReportSheet

`ReportSheet` does not directly expose template application methods.
Instead, apply templates to its TemplateSheet, which defines layout and formatting:

```javascript
const report = spread.addSheetTab(0, "Report", GC.Spread.Sheets.SheetType.reportSheet);
const templateSheet = report.getTemplate();

templateSheet.applyNamedCellTemplate("Financial Amount", "A1:A5");
```

### TableSheet

On a `TableSheet`, templates are applied by specifying data source field names.

```javascript
tableSheet.applyNamedCellTemplate("Financial Amount", ["price", "quantity"]);
```

**Behavior**

* A bound `dataSource` is required. If no data source is present, the template is not applied.
* Templates are applied column by column for the specified field names.
* Field names that do not exist in the data source are ignored.
* `cellStates` in templates are not supported and are ignored.
* Regular conditional formatting rules are applied per column.
* State-based rules are applied at the sheet level.

See the API Reference for:

* `TableSheet.applyNamedCellTemplate`

### GanttSheet

`GanttSheet` supports Named Cell Templates using the same method as `TableSheet`.
**Additional behavior**

* Gantt chart columns are automatically skipped.
* Built-in functional columns retain their interactive editors.

## When to Use Named Cell Templates

Use Named Cell Templates when:

* A reusable configuration includes more than style.
* Conditional formatting and validation rules must stay consistent.
* Interactive cell states need to be standardized.

If you only need reusable visual formatting, consider using Named Styles instead.

## Integration with SpreadJS Designer

Named Cell Templates are fully supported through the SpreadJS runtime API.
SpreadJS Designer provides a visual interface for creating, editing, and applying templates, and may include additional preset templates for convenience.
Refer to the SpreadJS Designer documentation for details: [Named Cell Templates](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/named-cell-templates).