# ExportPlugin

> _Since v0.1.1_

Export Plugin for tbw-grid

Lets users download grid data as CSV, Excel (XML), or JSON with a single click
or API call. Great for reporting, data backup, or letting users work with data
in Excel. Integrates with SelectionPlugin to export only selected rows.

## Installation

```ts
import { ExportPlugin } from '@toolbox-web/grid/plugins/export';
```

## Supported Formats

| Format | Method | Description |
|--------|--------|-------------|
| CSV | `exportToCSV()` | Comma-separated values |
| Excel | `exportToExcel()` | Excel XML format (.xlsx) |
| JSON | `exportToJSON()` | JSON array of objects |

## [Configuration Options](/grid/plugins/export/interfaces/exportconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `fileName?` | <code>string</code> | Default file name for exports (default: 'export') |
| `includeHeaders?` | <code>boolean</code> | Include column headers in export (default: true) |
| `onlyVisible?` | <code>boolean</code> | Export only visible columns (default: true) |
| `onlySelected?` | <code>boolean</code> | Export only selected rows (default: false) |

## Examples

### Basic Export with Button

```ts
import { queryGrid } from '@toolbox-web/grid';
import { ExportPlugin } from '@toolbox-web/grid/plugins/export';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ],
  plugins: [new ExportPlugin({ fileName: 'employees', includeHeaders: true })],
};

// Trigger export via button
document.getElementById('export-btn').addEventListener('click', () => {
  grid.getPluginByName('export').exportToCSV();
});
```

### Export Selected Rows Only

```ts
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';

grid.gridConfig = {
  plugins: [
    new SelectionPlugin({ mode: 'row' }),
    new ExportPlugin({ onlySelected: true }),
  ],
};
```

## See Also

- [`ExportConfig`](/grid/plugins/export/interfaces/exportconfig.md) for all configuration options
- [`ExportParams`](/grid/plugins/export/interfaces/exportparams.md) for method parameters
- SelectionPlugin for exporting selected rows

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Methods

### export()

Returns the row data that would be included in an export, without
producing a file. Honours `mode`, `onlyVisible`, `onlySelected`,
`columns`, `rowIndices`, `processCell`, and (for `mode: 'formatted'`)
`column.format`.

Each returned object is keyed by `column.field` in column order.

```ts
export(params: Partial<ExportParams>): Record<string, unknown>[]
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` | <code>Partial&lt;<a href="/grid/plugins/export/interfaces/exportparams/">ExportParams</a>&gt;</code> |  |

#### Example

```ts
// Underlying typed values (Date stays Date, number stays number)
const raw = exporter.export();

// What the user sees in each cell
const display = exporter.export({ mode: 'formatted' });
```

***

### getResolvedColumns()

Returns the columns (in order) that an export with these params would
include. Useful when handing rows to a third-party serializer that needs
header labels, widths, or types alongside the data.

```ts
getResolvedColumns(params: Partial<ExportParams>): ColumnConfig<any>[]
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` | <code>Partial&lt;<a href="/grid/plugins/export/interfaces/exportparams/">ExportParams</a>&gt;</code> |  |

***

### formatCsv()

Format an array of row objects as a CSV string. Column order, headers,
and which fields to emit are taken from the plugin's resolved columns
(respecting `onlyVisible` and `params.columns`).

This is a **pure formatter** — it does not re-resolve values from the
grid. Pass `data` produced by ExportPlugin.export (or any
compatible row objects keyed by `column.field`).

`params.processCell` is honoured: it runs once per cell on the values in
`data`. `mode` is **not** accepted here — apply it upstream via
`export({ mode: 'formatted' })`.

```ts
formatCsv(data: Record<string, unknown>[], params: FormatCsvParams, options: CsvOptions): string
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `data` | <code>Record&lt;string, unknown&gt;[]</code> |  |
| `params` | <code><a href="/grid/plugins/export/types/formatcsvparams/">FormatCsvParams</a></code> |  |
| `options` | <code><a href="/grid/plugins/export/interfaces/csvoptions/">CsvOptions</a></code> |  |

#### Example

```ts
const csv = exporter.formatCsv(exporter.export());
await navigator.clipboard.writeText(csv);
```

***

### formatExcel()

Format an array of row objects as an Excel XML Spreadsheet 2003 string.
See formatCsv for the data-shape contract — this method is also a
pure formatter and `params.processCell` is honoured the same way.

```ts
formatExcel(data: Record<string, unknown>[], params: FormatExcelParams): string
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `data` | <code>Record&lt;string, unknown&gt;[]</code> |  |
| `params` | <code><a href="/grid/plugins/export/types/formatexcelparams/">FormatExcelParams</a></code> |  |

***

### exportCsv()

Export data to CSV format.

```ts
exportCsv(params: Partial<ExportParams>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` | <code>Partial&lt;<a href="/grid/plugins/export/interfaces/exportparams/">ExportParams</a>&gt;</code> | Optional export parameters |

***

### exportExcel()

Export data to Excel format (XML Spreadsheet).

```ts
exportExcel(params: Partial<ExportParams>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` | <code>Partial&lt;<a href="/grid/plugins/export/interfaces/exportparams/">ExportParams</a>&gt;</code> | Optional export parameters |

***

### exportJson()

Export data to JSON format.

```ts
exportJson(params: Partial<ExportParams>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` | <code>Partial&lt;<a href="/grid/plugins/export/interfaces/exportparams/">ExportParams</a>&gt;</code> | Optional export parameters |

***

### isExporting()

Check if an export is currently in progress.

```ts
isExporting(): boolean
```

#### Returns

`boolean` - Whether export is in progress

***

### getLastExport()

Get information about the last export.

```ts
getLastExport(): object | null
```

#### Returns

`object | null` - Export info or null if no export has occurred

***