You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/grid/configuration.md
+2-22Lines changed: 2 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2671,12 +2671,10 @@ This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) pac
2671
2671
2672
2672
The Grid component provides the [functionality for interacting with the clipboard](grid/usage_clipboard.md), such as copying, cutting, and pasting data from a selected range of cells, as well as integrating with other grids or external applications like Google Spreadsheets.
2673
2673
2674
-
To enable the clipboard functionality within a grid, you should use the `Clipboard` module. To initialize the module, enable the [`clipboard`](grid/api/grid_clipboard_config.md) property in the Grid configuration.
2675
-
2676
-
The `Clipboard` module requires the [`RangeSelection`](#managing-range-selection-in-grid) module to be enabled. For convenient range selection via the UI, it is recommended to use the [`BlockSelection`](#managing-block-selection-in-grid) module with the `mode: "range"` setting. It allows users to visually select areas before copying or pasting.
2674
+
To enable the clipboard functionality within a grid, you should use the `Clipboard` module. To initialize the module, enable the [`clipboard`](grid/api/grid_clipboard_config.md) property in the Grid configuration. The `Clipboard` module requires the [`RangeSelection`](#managing-range-selection-in-grid) module to be enabled. For convenient range selection via the UI, it is recommended to use the [`BlockSelection`](#managing-block-selection-in-grid) module with the `mode: "range"` setting. It allows users to visually select areas before copying or pasting.
2677
2675
2678
2676
:::note
2679
-
The `blockSelection: { mode: "range" }` property is initialized in the Grid configuration when the `Clipboard` module is enabled.
2677
+
The `blockSelection: { mode: "range" }` property is automatically initialized in the Grid configuration when the `Clipboard` module is enabled.
2680
2678
:::
2681
2679
2682
2680
~~~jsx
@@ -2723,24 +2721,6 @@ const grid = new dhx.Grid("grid_container", {
-**Iftherangeissmallerthanthecopiedelements**:allthecopiedelementswillbepastedifthereisenoughspaceinthegrid (i.e., sufficient rows and columns exist beyond the range's starting point). For example, if 4 cells (2 rows x 2 columns) are copied and the range is set to 1 row x 2 columns, the data will be fully pasted, expanding the range to 2 rows, if rows are available.
2739
-
2740
-
- **If the range is larger than the copied elements**: the copied elements will repeat cyclically to fill the entire range. For example, if 2 cells ("A1", "A2") are copied and the range is 4 cells (2 rows x 2 columns), the result will be "A1", "A2", "A1", "A2".
2741
-
2742
-
The repetition of elements follows the order of copying, starting from the first cell.
Copy file name to clipboardExpand all lines: docs/grid/usage_clipboard.md
+88-66Lines changed: 88 additions & 66 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,20 +10,16 @@ description: You can explore how to work with Clipboard module of Grid in the do
10
10
This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.
11
11
:::
12
12
13
-
You can manage the clipboard functionality within a grid via the API of the [`Clipboard`](grid/configuration.md/#clipboard) module. It enables copying, cutting, and pasting data from a selected range of cells. Besides, it allows integrating with other grids or external applications like Google Spreadsheets.
13
+
You can manage the clipboard functionality within a grid via the API of the [`Clipboard`](grid/configuration.md/#clipboard) module. It enables copying, cutting, and pasting data from a selected range of cells. Besides, it allows [integrating with other grids or external applications](#interaction-between-grids-and-external-widgets) like Google Spreadsheets.
14
14
15
15
## Initializing the Clipboard module
16
16
17
17
To initialize the `Clipboard` module, use the [`clipboard`](grid/api/grid_clipboard_config.md) property in the **dhx.Grid** component configuration. After the Grid component is created, the module is accessible through the `grid.clipboard` property.
18
18
19
19
:::note
20
-
The module requires the [`RangeSelection`](grid/usage_rangeselection.md) module to be enabled and is best used in conjunction with the [`BlockSelection`](grid/usage_blockselection.md) module in the `"range"` mode (enabled on initialization of the `Clipboard` module) for convenient range selection via the UI.
20
+
The module requires the [`RangeSelection`](grid/usage_rangeselection.md) module to be enabled and is best used in conjunction with the [`BlockSelection`](grid/usage_blockselection.md) module in the `"range"` mode (enabled on initialization of the `Clipboard` module) for convenient range selection via the UI.[Check the details below](#interaction-with-cell-selection)
21
21
:::
22
22
23
-
The `clipboard` property can be set:
24
-
- as a *boolean* value to enable/disable the `Clipboard` module upon the component initialization
25
-
- as an *object* to enable the module and define the [modifier functions](#using-formatter-functions) for data processing: `copyModifier`, `cutModifier` and `pasteModifier`. The example below demonstrates the clipboard configuration with all the modifiers in use:
26
-
27
23
~~~jsx
28
24
constgrid=newdhx.Grid("grid_container", {
29
25
columns: [
@@ -34,71 +30,16 @@ const grid = new dhx.Grid("grid_container", {
34
30
{ id:"1", a:"A1", b:"B1" },
35
31
{ id:"2", a:"A2", b:"B2" },
36
32
],
37
-
clipboard:true
33
+
blockSelection: { mode:"range" }, // required for Clipboard to function (initializes automatically)
34
+
clipboard:true// enables the Clipboard module
38
35
});
39
36
~~~
40
37
41
-
## Using the events of the Clipboard object
42
-
43
-
To make the process of working with clipboard more flexible, you can apply the related events of the `clipboard` object:
When **Clipboard API** is enabled (e.g., via `grid.config.clipboard: true`), the **BlockSelection API** is automatically activated in the `range` mode unless another mode is specified.
52
-
53
-
### Usage in other BlockSelection modes
54
-
55
-
If the `BlockSelection` module is configured in the `manual` mode, the **Clipboard API** does not automatically receive a range. In this case, you should manually set the range using the **Range API**. For this purpose, you need to call
Without a set range, copying and pasting will not work, as **Clipboard API** relies on data from the **Range API**.
60
-
:::
61
-
62
-
### Data source for Clipboard
63
-
64
-
The **Clipboard API** always uses data from the **Range API** to determine the cells that will be copied or into which data will be pasted.
65
-
66
-
:::note
67
-
The `cut`/`paste` operations will be blocked in the [*grouping*](grid/usage.md/#grouping-data) mode.
68
-
:::
69
-
70
-
## Interaction between Grids and external widgets
71
-
72
-
### Columns with type "date"
73
-
74
-
When copying cells with the column type `type: "date"`, the *formatted* value is copied to the clipboard (not the original string or date object). For example, if the data contains `"2025-04-11"` and the display format is set to `"dd/mm/yyyy"`, the copied value will be `"11/04/2025"`. This behavior simplifies working with dates in tables and other applications.
75
-
76
-
When pasting, values are validated after applying [`pasteModifier`](#using-formatter-functions) (if defined). The value is checked for compliance with the column's `dateFormat` (e.g., `"dd/mm/yyyy"`) or whether it can be parsed as a valid `Date` object (e.g., `"2025-04-11"` or `"April 11, 2025"`). If the value is valid, it is converted to the grid's expected format and inserted. If invalid (e.g., `"abc"` or `"31 12 2025"`), the paste operation is ignored, and the cell's current value remains unchanged.
77
-
78
-
### Columns with type "number"
79
-
80
-
When copying cells with the column type `type: "number"`, the values are copied to the clipboard as numbers, even if `numberMask` or `patternMask` is applied. For example, if a cell displays `"1,234.56"` due to a mask, the copied value will be `1234.56`. This is done to maintain data purity and compatibility with other systems, such as spreadsheets or data processing software.
81
-
82
-
When pasting, values are validated after applying [`pasteModifier`](#using-formatter-functions) (if defined). The value must be a valid number (e.g., `1234.56` or `"1,234.56"` after cleaning). If the value is not a number (e.g., `"abc"`), the paste operation is ignored, and the cell's current value remains unchanged.
83
-
84
-
### Columns with type "string"
85
-
86
-
If `patternMask` is applied to a cell (e.g., for formatting phone numbers or currency), the *formatted* value is copied to the clipboard.
87
-
For example, if the data contains `"1234567890"` and the mask is `"+# (###) ###-##-##"`, the copied value will be `"+1 (234) 567-89-0"`. This preserves readability for the end user.
88
-
89
-
### Templates
90
-
91
-
Templates applied to cell values (e.g., via the `template` property) are not included in the data during copying. This prevents unwanted HTML or formatted text from entering the clipboard, which could disrupt the functionality of external widgets or tables (e.g., Google Spreadsheets). Only the "raw" value from the data is copied.
92
-
93
-
### Columns with editors "combobox", "multiselect", "select"
94
-
95
-
If a column has `editorType: "combobox"`, `"multiselect"`, or `"select"`, the value stored in the data (typically an `id` or a key) is copied to the clipboard, not the displayed portion (e.g., the option text).
96
-
97
-
For example, if the data contains `{ id: "1", value: "Option 1" }` and the cell displays `"Option 1"`, the copied value will be `"1"`. This ensures data consistency when transferring between systems.
38
+
The `clipboard` property can be set as an *object* to enable the module and define the [modifier functions](#using-formatter-functions) for data processing: `copyModifier`, `cutModifier` and `pasteModifier`.
98
39
99
40
## Using formatter functions
100
41
101
-
If you need a specific data format during copying or pasting, the default behavior can be modified using the formatter functions (`copyModifier`, `cutModifier`, `pasteModifier`). Check the example below:
42
+
If you need a specific data format during copying or pasting, the default behavior can be modified using the formatter functions: `copyModifier`, `cutModifier`, `pasteModifier`. Check the example below:
When `Clipboard` module is enabled (e.g., via `grid.config.clipboard: true`), the `BlockSelection` module is automatically activated in the `range` mode unless another mode is specified.
163
+
164
+
### Usage in other BlockSelection modes
165
+
166
+
If the [`BlockSelection`](grid/usage_blockselection.md) module is configured in the `manual` mode, the `Clipboard` module does not automatically receive a range. In this case, you should manually set the range using the [`RangeSelection` API](grid/api/api_overview.md/#rangeselection-api). For this purpose, you need to call `grid.range.setRange({ xStart, xEnd, yStart, yEnd })`.
167
+
168
+
:::note
169
+
Without a set range, copying and pasting will not work, as **Clipboard API** relies on data from the **RangeSelection API**.
170
+
:::
171
+
172
+
### Data source for Clipboard
173
+
174
+
The **Clipboard API** always uses data from the **RangeSelection API** to determine the cells that will be copied or into which data will be pasted.
175
+
176
+
:::note
177
+
The `cut`/`paste` operations will be blocked in the [*grouping*](grid/usage.md/#grouping-data) mode.
178
+
:::
179
+
180
+
### Pasting from clipboard
181
+
182
+
Data from the clipboard is pasted into the range defined by `rangeSelection`. The behavior depends on the size of the selected range and the number of copied elements:
183
+
184
+
-**If the range is smaller than the copied elements**: all the copied elements will be pasted if there is enough space in the grid (i.e., the sufficient number of rows and columns exist beyond the range's starting point). For example, if 4 cells (2 rows x 2 columns) are copied and the range is set to 1 row x 2 columns, the data will be fully pasted, expanding the range to 2 rows, if rows are available.
185
+
186
+
-**If the range is larger than the copied elements**: the copied elements will repeat cyclically to fill the entire range. For example, if 2 cells ("A1", "A2") are copied and the range contains 4 cells (2 rows x 2 columns), the result will be "A1", "A2", "A1", "A2".
187
+
188
+
The repetition of elements follows the order of copying, starting from the first cell.
189
+
190
+
## Interaction between Grids and external widgets
191
+
192
+
The `Clipboard` module enables data exchange between multiple `dhx.Grid` instances or with external applications like Google Spreadsheets, Microsoft Excel, or similar widgets. Data is copied to the clipboard in a text format with tab separators (`\t`) between columns and newlines (`\n`) between rows, matching the standard table format.
193
+
194
+
**Related sample**: [Clipboard. Employee data transfer between Grids](https://snippet.dhtmlx.com/qll7bcv5)
195
+
196
+
Below you'll find the details on copying/pasting data depending on the type of a column.
197
+
198
+
### Columns with type "date"
199
+
200
+
When copying cells with the column type `type: "date"`, the *formatted* value is copied to the clipboard (not the original string or date object). For example, if the data contains `"2025-04-11"` and the display format is set to `"dd/mm/yyyy"`, the copied value will be `"11/04/2025"`. This behavior simplifies working with dates in tables and other applications.
201
+
202
+
When pasting, values are validated after applying [`pasteModifier`](#using-formatter-functions) (if defined). The value is checked for compliance with the column's `dateFormat` (e.g., `"dd/mm/yyyy"`) or whether it can be parsed as a valid `Date` object (e.g., `"2025-04-11"` or `"April 11, 2025"`). If the value is valid, it is converted to the grid's expected format and inserted. If invalid (e.g., `"abc"` or `"31 12 2025"`), the paste operation is ignored, and the cell's current value remains unchanged.
203
+
204
+
### Columns with type "number"
205
+
206
+
When copying cells with the column type `type: "number"`, the values are copied to the clipboard as numbers, even if `numberMask` or `patternMask` is applied. For example, if a cell displays `"1,234.56"` due to a mask, the copied value will be `1234.56`. This is done to maintain data purity and compatibility with other systems, such as spreadsheets or data processing software.
207
+
208
+
When pasting, values are validated after applying [`pasteModifier`](#using-formatter-functions) (if defined). The value must be a valid number (e.g., `1234.56` or `"1,234.56"` after cleaning). If the value is not a number (e.g., `"abc"`), the paste operation is ignored, and the cell's current value remains unchanged.
209
+
210
+
### Columns with type "string"
211
+
212
+
If `patternMask` is applied to a cell (e.g., for formatting phone numbers or currency), the *formatted* value is copied to the clipboard.
213
+
For example, if the data contains `"1234567890"` and the mask is `"+# (###) ###-##-##"`, the copied value will be `"+1 (234) 567-89-0"`. This preserves readability for the end user.
214
+
215
+
### Templates
216
+
217
+
Templates applied to cell values (e.g., via the `template` property) are not included in the data during copying. This prevents unwanted HTML or formatted text from entering the clipboard, which could disrupt the functionality of external widgets or tables (e.g., Google Spreadsheets). Only the "raw" value from the data is copied.
218
+
219
+
### Columns with editors "combobox", "multiselect", "select"
220
+
221
+
If a column has `editorType: "combobox"`, `"multiselect"`, or `"select"`, the value stored in the data (typically an `id` or a key) is copied to the clipboard, not the displayed portion (e.g., the option text).
222
+
223
+
For example, if the data contains `{ id: "1", value: "Option 1" }` and the cell displays `"Option 1"`, the copied value will be `"1"`. This ensures data consistency when transferring between systems.
224
+
225
+
### Integration with Google Spreadsheets
226
+
227
+
Data from a grid can be copied to the clipboard and pasted directly into Google Spreadsheets. Similarly, data from Google Spreadsheets can be copied and pasted into the grid. Use [`pasteModifier`](#using-formatter-functions) to process data formats (e.g., converting strings to numbers).
228
+
229
+
**Related sample**: [Clipboard. Clipboard operations between Grid and Spreadsheet](https://snippet.dhtmlx.com/mfmvbbda)
0 commit comments