diff --git a/docs/TOC.md b/docs/TOC.md index add70b771..48e4ff5e0 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -44,6 +44,7 @@ * [Custom Tooltip](grid-functionalities/custom-tooltip.md) * [Context Menu](grid-functionalities/Context-Menu.md) * [Custom Footer](grid-functionalities/Custom-Footer.md) +* [Excel Copy Buffer Plugin](grid-functionalities/excel-copy-buffer.md) * [Export to Excel](grid-functionalities/Export-to-Excel.md) * [Export to File (csv/txt)](grid-functionalities/Export-to-Text-File.md) * [Grid Menu](grid-functionalities/Grid-Menu.md) diff --git a/docs/events/Available-Events.md b/docs/events/Available-Events.md index 46ff4cabe..41d5b1ba8 100644 --- a/docs/events/Available-Events.md +++ b/docs/events/Available-Events.md @@ -38,6 +38,7 @@ handleOnHeaderMenuCommand(e) { - `onCopyCells` - `onCopyCancelled` - `onPasteCells` + - `onBeforePasteCell` #### SlickContextMenu (extension) - `onContextMenuClearGrouping` diff --git a/docs/grid-functionalities/excel-copy-buffer.md b/docs/grid-functionalities/excel-copy-buffer.md new file mode 100644 index 000000000..ca03ea688 --- /dev/null +++ b/docs/grid-functionalities/excel-copy-buffer.md @@ -0,0 +1,129 @@ +### Description +Just like Excel you can select multiple cell and copy (`Ctrl+C`) and paste to Excel (`Ctrl+V`). However what you must know is that this plugin evaluate every single cell by their values (the raw value unless you specify otherwise, continue reading for more info). + +### Usage +All you need to do is enable the Grid Option `enableExcelCopyBuffer: true` and give it a try. From your grid, start selecting multiple cells with the mouse then copy (with `Ctrl+C`) and paste to Excel (with `Ctrl+V`) + +##### Component +```typescript +this.columnDefinitions = [ + { id: 'title', name: 'Title', field: 'id' }, + { id: 'description', name: 'Description', field: 'description' }, + { id: 'duration', name: 'Duration (days)', field: 'duration', type: FieldType.number }, +]; +this.gridOptions = { + enableExcelCopyBuffer: true, +}; +``` + +### Copy & Paste with Cell Formatter +What if you have a date in UTC format in your dataset but your grid shows it as a Date ISO format? In that case, you are using a Formatter (e.g. `formatter: Formatters.dateIso`) and you wish to use that formatter. Good news, that is supported with and to make is simpler for the implementation, we will use a flag that already exist which is `exportWithFormatter` and is used by the `Export to File` service (for more info, read [Wiki - Export to File](Export-to-Text-File.md) + +The `exportWithFormatter` can be used in 2 ways, on each column definition independently or for the entire grid through it's grid option. +##### `exportWithFormatter` through each Column Definition +```typescript +this.columnDefinitions = [ + { + id: 'start', name: 'Start', field: 'start', + formatter: Formatters.dateIso, + exportWithFormatter: true + }, + { + id: 'finish', name: 'Finish', field: 'finish', + formatter: Formatters.dateIso, + exportWithFormatter: true + }, +]; + +this.gridOptions = { + enableExcelCopyBuffer: true, +}; +``` + +##### `exportWithFormatter` through Grid Options +```typescript +this.columnDefinitions = [ + { id: 'start', name: 'Start', field: 'start', formatter: Formatters.dateIso }, + { id: 'finish', name: 'Finish', field: 'finish', formatter: Formatters.dateIso }, +]; + +this.gridOptions = { + enableExcelCopyBuffer: true, + exportOptions: { + // set at the grid option level, meaning all column will evaluate the Formatter (when it has a Formatter defined) + exportWithFormatter: true + }, +}; +``` +#### Sanitize Formatter Ouput +In some cases a Formatter can be formed of HTML and that will end up showing in your Copy+Paste. You can simply use the `sanitizeDataExport` flag which will remove any HTML tags from the output. For an example below, let say that our first Title column are all displayed in bold in the grid (e.g. `Title 1`), we want to sanitize that output a regular text output (e.g. `Title 1`) + +##### `exportWithFormatter` through each Column Definition +```typescript +this.columnDefinitions = [ + { + id: 'title', name: 'Title', field: 'id', + formatter: Formatters.bold, + exportWithFormatter: true, + sanitizeDataExport: true + } +]; + +this.gridOptions = { + enableExcelCopyBuffer: true +}; +``` + +##### `exportWithFormatter` through Grid Options +```typescript +this.columnDefinitions = [ + { id: 'title', name: 'Title', field: 'id', formatter: Formatters.bold } +]; + +this.gridOptions = { + enableExcelCopyBuffer: true, + exportOptions: { + exportWithFormatter: true, + sanitizeDataExport: true + }, +}; +``` + +### Disable pasting on specific columns +If you want to disable pasting values for specific columns you can deactivate it using the denyPaste property on the Column config. + +```typescript +this.columnDefinitions = [ + { + id: 'colA', name: 'Col A', field: 'col_a', + formatter: Formatters.bold, + exportWithFormatter: true, + sanitizeDataExport: true, + denyPaste: true // <------------ + } +]; +``` + +This will even work in situations where your table copy buffer stretches over disabled cells, by simply skipping them. So for the following config (x = paste disabled; o = paste enabled), pasting a 3 cell stretching table buffer will result in Col A and C being updated but ColB ignoring the paste and keeping its original value + +Col A | Col B | Col C \ +\---------------------\ +   o    |     x    |     o \ +NEW |     x    |  NEW + +### Disable pasting on specific cells +If you need even more fine grained control, you can make use of the gridOption `onBeforePasteCell`: + +```typescript +this.gridOptions = { + enableExcelCopyBuffer: true, + excelCopyBufferOptions: { + onBeforePasteCell: (e, args) => { + // e.g deny paste on first cell + return args.cell > 0; + } + } +}; +``` + +This way you have full control, via the args parameters, to get a ref to the current row and cell being updated. Also keep in mind that while performing a buffered table paste (e.g three cols at once) and only one of them has a denying condition, the other cells paste will pass successfully. \ No newline at end of file diff --git a/examples/vite-demo-vanilla-bundle/src/examples/example11-modal.ts b/examples/vite-demo-vanilla-bundle/src/examples/example11-modal.ts index 9de2eb8b7..677ebbb97 100644 --- a/examples/vite-demo-vanilla-bundle/src/examples/example11-modal.ts +++ b/examples/vite-demo-vanilla-bundle/src/examples/example11-modal.ts @@ -1,7 +1,6 @@ import { type Column, type DOMEvent, - emptyElement, type Formatter, Formatters, type GridOption, diff --git a/examples/vite-demo-vanilla-bundle/src/examples/example19.html b/examples/vite-demo-vanilla-bundle/src/examples/example19.html index 59a910709..95581f7d2 100644 --- a/examples/vite-demo-vanilla-bundle/src/examples/example19.html +++ b/examples/vite-demo-vanilla-bundle/src/examples/example19.html @@ -1,3 +1,10 @@ +

Example 19 - ExcelCopyBuffer with Cell Selection (with Salesforce Theme) @@ -11,7 +18,8 @@

- Grid - using enableExcelCopyBuffer which uses SlickCellSelectionModel + Grid - using enableExcelCopyBuffer which uses SlickCellSelectionModel
+ The complete first row and the cells C - E of the second row are not allowing to paste values.