diff --git a/docs/assets/grid/blockselection_module.png b/docs/assets/grid/blockselection_module.png new file mode 100644 index 00000000..99961c6c Binary files /dev/null and b/docs/assets/grid/blockselection_module.png differ diff --git a/docs/assets/grid/dragpanel_module.png b/docs/assets/grid/dragpanel_module.png new file mode 100644 index 00000000..01c8c24b Binary files /dev/null and b/docs/assets/grid/dragpanel_module.png differ diff --git a/docs/grid/api/api_overview.md b/docs/grid/api/api_overview.md index 583b67d2..656e8c69 100644 --- a/docs/grid/api/api_overview.md +++ b/docs/grid/api/api_overview.md @@ -43,8 +43,12 @@ description: You can explore the API of Grid in the documentation of the DHTMLX :::info important - Use [the methods of DataCollection](data_collection.md) to work with data. -- Apply [the methods of Selection](grid/api/api_overview.md#selection-methods) to manage the selection of Grid cells. - Use [the methods of TreeCollection](tree_collection.md#methods) to work with data of Grid in the TreeGrid mode. +- Use [the methods of the Selection object](grid/api/api_overview.md#selection-methods) to work with the selection of Grid cells. +- Use [the methods of the RangeSelection module](grid/api/api_overview.md#rangeselection-methods) to work with the range selection within Grid. +- Use [the methods of the BlockSelection module](grid/api/api_overview.md#blockselection-methods) to work with the block selection within Grid. +- Use [the methods of the Export module](grid/api/api_overview.md#export-methods) to work with data export within Grid. +- Use [the methods of the History module](grid/api/api_overview.md#history-methods) to work with the history of actions within Grid. ::: ## Grid events @@ -163,9 +167,14 @@ description: You can explore the API of Grid in the documentation of the DHTMLX | [](grid/api/grid_beforerowresize_event.md) | @getshort(grid/api/grid_beforerowresize_event.md) | :::info important -- Use [the events of DataCollection](data_collection.md#events) to work with data of Grid. -- Apply [the events of Selection](grid/api/api_overview.md#selection-events) to handle the selection of Grid cells. -- Use [the events of TreeCollection](tree_collection.md#events) to work with data of Grid in the TreeGrid mode. +- Use [the events of DataCollection](data_collection.md#events) to work with data of Grid. +- Use [the events of TreeCollection](tree_collection.md#events) to work with data of Grid in the TreeGrid mode. +- Use [the events of the Selection object](grid/api/api_overview.md#selection-events) to work with the selection of Grid cells. +- Use [the events of the RangeSelection module](grid/api/api_overview.md#rangeselection-events) to work with the range selection within Grid. +- Use [the events of the BlockSelection module](grid/api/api_overview.md#blockselection-events) to work with the block selection within Grid. +- Use [the events of the Clipboard module](grid/api/api_overview.md#clipboard-events) to work with clipboard within Grid. +- Use [the events of the DragPanel module](grid/api/api_overview.md#dragpanel-events) to work with drag panel within Grid. +- Use [the events of the History module](grid/api/api_overview.md#history-events) to work with the history of actions within Grid. ::: ## Grid properties @@ -176,7 +185,9 @@ description: You can explore the API of Grid in the documentation of the DHTMLX | [](grid/api/grid_autoemptyrow_config.md) | @getshort(grid/api/grid_autoemptyrow_config.md) | | [](grid/api/grid_autoheight_config.md) | @getshort(grid/api/grid_autoheight_config.md) | | [](grid/api/grid_autowidth_config.md) | @getshort(grid/api/grid_autowidth_config.md) | +| [](grid/api/grid_blockselection_config.md) | @getshort(grid/api/grid_blockselection_config.md) | | [](grid/api/grid_bottomsplit_config.md) | @getshort(grid/api/grid_bottomsplit_config.md) | +| [](grid/api/grid_clipboard_config.md) | @getshort(grid/api/grid_clipboard_config.md) | | [](grid/api/grid_closable_config.md) | @getshort(grid/api/grid_closable_config.md) | | [](grid/api/grid_collapsed_config.md) | @getshort(grid/api/grid_collapsed_config.md) | | [](grid/api/grid_columns_config.md) | @getshort(grid/api/grid_columns_config.md) | @@ -186,6 +197,7 @@ description: You can explore the API of Grid in the documentation of the DHTMLX | [](grid/api/grid_dragexpand_config.md) | @getshort(grid/api/grid_dragexpand_config.md) | | [](grid/api/grid_dragitem_config.md) | @getshort(grid/api/grid_dragitem_config.md) | | [](grid/api/grid_dragmode_config.md) | @getshort(grid/api/grid_dragmode_config.md) | +| [](grid/api/grid_dragpanel_config.md) | @getshort(grid/api/grid_dragpanel_config.md) | | [](grid/api/grid_editable_config.md) | @getshort(grid/api/grid_editable_config.md) | | [](grid/api/grid_eventhandlers_config.md) | @getshort(grid/api/grid_eventhandlers_config.md) | | [](grid/api/grid_exportstyles_config.md) | @getshort(grid/api/grid_exportstyles_config.md) | @@ -198,11 +210,13 @@ description: You can explore the API of Grid in the documentation of the DHTMLX | [](grid/api/grid_headerrowheight_config.md) | @getshort(grid/api/grid_headerrowheight_config.md) | | [](grid/api/grid_headertooltip_config.md) | @getshort(grid/api/grid_headertooltip_config.md) | | [](grid/api/grid_height_config.md) | @getshort(grid/api/grid_height_config.md) | +| [](grid/api/grid_history_config.md) | @getshort(grid/api/grid_history_config.md) | | [](grid/api/grid_htmlenable_config.md) | @getshort(grid/api/grid_htmlenable_config.md) | | [](grid/api/grid_keynavigation_config.md) | @getshort(grid/api/grid_keynavigation_config.md) | | [](grid/api/grid_leftsplit_config.md) | @getshort(grid/api/grid_leftsplit_config.md) | | [](grid/api/grid_multiselection_config.md) | @getshort(grid/api/grid_multiselection_config.md) | | [](grid/api/grid_multisort_config.md) | @getshort(grid/api/grid_multisort_config.md) | +| [](grid/api/grid_rangeselection_config.md) | @getshort(grid/api/grid_rangeselection_config.md) | | [](grid/api/grid_resizable_config.md) | @getshort(grid/api/grid_resizable_config.md) | | [](grid/api/grid_rightsplit_config.md) | @getshort(grid/api/grid_rightsplit_config.md) | | [](grid/api/grid_rootparent_config.md) | @getshort(grid/api/grid_rootparent_config.md) | @@ -227,14 +241,15 @@ You will find the list of all the available configuration properties of a Grid c ### Selection methods -| Name | Description | -| ----------------------------------------------------- | ------------------------------------------------------------ | -| [](grid/api/selection/selection_disable_method.md) | @getshort(grid/api/selection/selection_disable_method.md) | -| [](grid/api/selection/selection_enable_method.md) | @getshort(grid/api/selection/selection_enable_method.md) | -| [](grid/api/selection/selection_getcell_method.md) | @getshort(grid/api/selection/selection_getcell_method.md) | -| [](grid/api/selection/selection_getcells_method.md) | @getshort(grid/api/selection/selection_getcells_method.md) | -| [](grid/api/selection/selection_removecell_method.md) | @getshort(grid/api/selection/selection_removecell_method.md) | -| [](grid/api/selection/selection_setcell_method.md) | @getshort(grid/api/selection/selection_setcell_method.md) | +| Name | Description | +| --------------------------------------------------------- | --------------------------------------------------------------- | +| [](grid/api/selection/selection_disable_method.md) | @getshort(grid/api/selection/selection_disable_method.md) | +| [](grid/api/selection/selection_enable_method.md) | @getshort(grid/api/selection/selection_enable_method.md) | +| [](grid/api/selection/selection_getcell_method.md) | @getshort(grid/api/selection/selection_getcell_method.md) | +| [](grid/api/selection/selection_getcells_method.md) | @getshort(grid/api/selection/selection_getcells_method.md) | +| [](grid/api/selection/selection_isselectedcell_method.md) | @getshort(grid/api/selection/selection_isselectedcell_method.md)| +| [](grid/api/selection/selection_removecell_method.md) | @getshort(grid/api/selection/selection_removecell_method.md) | +| [](grid/api/selection/selection_setcell_method.md) | @getshort(grid/api/selection/selection_setcell_method.md) | ### Selection events @@ -245,7 +260,61 @@ You will find the list of all the available configuration properties of a Grid c | [](grid/api/selection/selection_beforeselect_event.md) | @getshort(grid/api/selection/selection_beforeselect_event.md) | | [](grid/api/selection/selection_beforeunselect_event.md) | @getshort(grid/api/selection/selection_beforeunselect_event.md) | -## Export methods +## RangeSelection API + +### RangeSelection methods + +| Name | Description | +| ----------------------------------------------------- | ------------------------------------------------------------ | +| [](grid/api/rangeselection/disable_method.md) | @getshort(grid/api/rangeselection/disable_method.md) | +| [](grid/api/rangeselection/enable_method.md) | @getshort(grid/api/rangeselection/enable_method.md) | +| [](grid/api/rangeselection/getrange_method.md) | @getshort(grid/api/rangeselection/getrange_method.md) | +| [](grid/api/rangeselection/getrangedcells_method.md) | @getshort(grid/api/rangeselection/getrangedcells_method.md) | +| [](grid/api/rangeselection/isdisabled_method.md) | @getshort(grid/api/rangeselection/isdisabled_method.md) | +| [](grid/api/rangeselection/isranged_method.md) | @getshort(grid/api/rangeselection/isranged_method.md) | +| [](grid/api/rangeselection/resetrange_method.md) | @getshort(grid/api/rangeselection/resetrange_method.md) | +| [](grid/api/rangeselection/setrange_method.md) | @getshort(grid/api/rangeselection/setrange_method.md) | + + +### RangeSelection events + +| Name | Description | +| -------------------------------------------------------- | --------------------------------------------------------------- | +| [](grid/api/rangeselection/afterresetrange_event.md) | @getshort(grid/api/rangeselection/afterresetrange_event.md) | +| [](grid/api/rangeselection/aftersetrange_event.md) | @getshort(grid/api/rangeselection/aftersetrange_event.md) | +| [](grid/api/rangeselection/beforeresetrange_event.md) | @getshort(grid/api/rangeselection/beforeresetrange_event.md) | +| [](grid/api/rangeselection/beforesetrange_event.md) | @getshort(grid/api/rangeselection/beforesetrange_event.md) | + + + +## BlockSelection API + +### BlockSelection methods + +| Name | Description | +| ----------------------------------------------------- | ------------------------------------------------------------ | +| [](grid/api/blockselection/disable_method.md) | @getshort(grid/api/blockselection/disable_method.md) | +| [](grid/api/blockselection/enable_method.md) | @getshort(grid/api/blockselection/enable_method.md) | +| [](grid/api/blockselection/isdisabled_method.md) | @getshort(grid/api/blockselection/isdisabled_method.md) | + +### BlockSelection events + +| Name | Description | +| ------------------------------------------------------------- | --------------------------------------------------------------------- | +| [](grid/api/blockselection/afterblockhandleapply_event.md) | @getshort(grid/api/blockselection/afterblockhandleapply_event.md) | +| [](grid/api/blockselection/afterblockselectionapply_event.md) | @getshort(grid/api/blockselection/afterblockselectionapply_event.md) | +| [](grid/api/blockselection/afterblockselectionmove_event.md) | @getshort(grid/api/blockselection/afterblockselectionmove_event.md) | +| [](grid/api/blockselection/beforeblockhandleapply_event.md) | @getshort(grid/api/blockselection/beforeblockhandleapply_event.md) | +| [](grid/api/blockselection/beforeblockselectionapply_event.md)| @getshort(grid/api/blockselection/beforeblockselectionapply_event.md) | +| [](grid/api/blockselection/beforeblockselectionmove_event.md) | @getshort(grid/api/blockselection/beforeblockselectionmove_event.md) | +| [](grid/api/blockselection/blockhandlemousedown_event.md) | @getshort(grid/api/blockselection/blockhandlemousedown_event.md) | +| [](grid/api/blockselection/blockselectionend_event.md) | @getshort(grid/api/blockselection/blockselectionend_event.md) | +| [](grid/api/blockselection/blockselectionstart_event.md) | @getshort(grid/api/blockselection/blockselectionstart_event.md) | +| [](grid/api/blockselection/blockselectionvalidate_event.md) | @getshort(grid/api/blockselection/blockselectionvalidate_event.md) | + +## Export API + +### Export methods | Name | Description | | --------------------------------------- | ---------------------------------------------- | @@ -254,3 +323,57 @@ You will find the list of all the available configuration properties of a Grid c | [](grid/api/export/grid_png_method.md) | @getshort(grid/api/export/grid_png_method.md) | | [](grid/api/export/grid_xlsx_method.md) | @getshort(grid/api/export/grid_xlsx_method.md) | +## Clipboard API + +### Clipboard events + +| Name | Description | +| ------------------------------------------ | ------------------------------------------------- | +| [](grid/api/clipboard/aftercopy_event.md) | @getshort(grid/api/clipboard/aftercopy_event.md) | +| [](grid/api/clipboard/afterpaste_event.md) | @getshort(grid/api/clipboard/afterpaste_event.md) | +| [](grid/api/clipboard/beforecopy_event.md) | @getshort(grid/api/clipboard/beforecopy_event.md) | +| [](grid/api/clipboard/beforepaste_event.md)| @getshort(grid/api/clipboard/beforepaste_event.md)| +| [](grid/api/clipboard/copyerror_event.md) | @getshort(grid/api/clipboard/copyerror_event.md) | +| [](grid/api/clipboard/pasteerror_event.md) | @getshort(grid/api/clipboard/pasteerror_event.md) | + +## DragPanel API + +### DragPanel events + +| Name | Description | +| ----------------------------------------------------- | ------------------------------------------------------------- | +| [](grid/api/dragpanel/dragpanelitemclick_event.md) | @getshort(grid/api/dragpanel/dragpanelitemclick_event.md) | +| [](grid/api/dragpanel/dragpanelitemmousedown_event.md)| @getshort(grid/api/dragpanel/dragpanelitemmousedown_event.md) | + +## History API + +### History methods + +| Name | Description | +| ----------------------------------------------------- | ------------------------------------------------------------ | +| [](grid/api/history/add_method.md) | @getshort(grid/api/history/add_method.md) | +| [](grid/api/history/canredo_method.md) | @getshort(grid/api/history/canredo_method.md) | +| [](grid/api/history/canundo_method.md) | @getshort(grid/api/history/canundo_method.md) | +| [](grid/api/history/disable_method.md) | @getshort(grid/api/history/disable_method.md) | +| [](grid/api/history/enable_method.md) | @getshort(grid/api/history/enable_method.md) | +| [](grid/api/history/gethistory_method.md) | @getshort(grid/api/history/gethistory_method.md) | +| [](grid/api/history/isdisabled_method.md) | @getshort(grid/api/history/isdisabled_method.md) | +| [](grid/api/history/redo_method.md) | @getshort(grid/api/history/redo_method.md) | +| [](grid/api/history/remove_method.md) | @getshort(grid/api/history/remove_method.md) | +| [](grid/api/history/removeall_method.md) | @getshort(grid/api/history/removeall_method.md) | +| [](grid/api/history/undo_method.md) | @getshort(grid/api/history/undo_method.md) | + + +### History events + +| Name | Description | +| ----------------------------------------------------- | ------------------------------------------------------------ | +| [](grid/api/history/afteradd_event.md) | @getshort(grid/api/history/afteradd_event.md) | +| [](grid/api/history/afterredo_event.md) | @getshort(grid/api/history/afterredo_event.md) | +| [](grid/api/history/afterundo_event.md) | @getshort(grid/api/history/afterundo_event.md) | +| [](grid/api/history/beforeadd_event.md) | @getshort(grid/api/history/beforeadd_event.md) | +| [](grid/api/history/beforeredo_event.md) | @getshort(grid/api/history/beforeredo_event.md) | +| [](grid/api/history/beforeundo_event.md) | @getshort(grid/api/history/beforeundo_event.md) | +| [](grid/api/history/error_event.md) | @getshort(grid/api/history/error_event.md) | + + diff --git a/docs/grid/api/blockselection/afterblockhandleapply_event.md b/docs/grid/api/blockselection/afterblockhandleapply_event.md new file mode 100644 index 00000000..2288a13e --- /dev/null +++ b/docs/grid/api/blockselection/afterblockhandleapply_event.md @@ -0,0 +1,60 @@ +--- +sidebar_label: afterBlockHandleApply +title: JavaScript Grid - afterBlockHandleApply Event +description: You can explore the afterBlockHandleApply event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterBlockHandleApply + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered after applying the handle action + +### Usage + +~~~jsx +afterBlockHandleApply: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + dragDirection: "up" | "down" | "left" | "right" | null, + event: MouseEvent | TouchEvent +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the end cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
dragDirection(string) determines the direction of movement of the focused cell: `"up"` | `"down"` | `"left"` | `"right"` | `null`
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@example: +grid.block.events.on("afterBlockHandleApply", (startCell, endCell, dir) => { + console.log("Handle applied:"); +}); + +@descr: + +**Related API**: [`beforeBlockHandleApply`](grid/api/blockselection/beforeblockhandleapply_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/afterblockselectionapply_event.md b/docs/grid/api/blockselection/afterblockselectionapply_event.md new file mode 100644 index 00000000..3b6b0713 --- /dev/null +++ b/docs/grid/api/blockselection/afterblockselectionapply_event.md @@ -0,0 +1,60 @@ +--- +sidebar_label: afterBlockSelectionApply +title: JavaScript Grid - afterBlockSelectionApply Event +description: You can explore the afterBlockSelectionApply event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterBlockSelectionApply + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered after applying the selection + +### Usage + +~~~jsx +afterBlockSelectionApply: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + handle: boolean, + event: MouseEvent | TouchEvent +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the end cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
handle(boolean) indicates whether the handle was used (`true`) or a regular selection (`false`)
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@example: +grid.block.events.on("afterBlockSelectionApply", (startCell, endCell) => { + console.log("Selection applied:", startCell.column.id, endCell.column.id); +}); + +@descr: + +**Related API**: [`beforeBlockSelectionApply`](grid/api/blockselection/beforeblockselectionapply_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/afterblockselectionmove_event.md b/docs/grid/api/blockselection/afterblockselectionmove_event.md new file mode 100644 index 00000000..689015bb --- /dev/null +++ b/docs/grid/api/blockselection/afterblockselectionmove_event.md @@ -0,0 +1,65 @@ +--- +sidebar_label: afterBlockSelectionMove +title: JavaScript Grid - afterBlockSelectionMove Event +description: You can explore the afterBlockSelectionMove event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterBlockSelectionMove + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered after moving the selection boundary + +### Usage + +~~~jsx +afterBlockSelectionMove: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + focusCell: { row: object; column: object } | null, + dragDirection: "up" | "down" | "left" | "right" | null, + event: MouseEvent | TouchEvent +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the current end cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
focusCell(object) an object that contains the focus cell (if the handle is used) or `null`, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
dragDirection(string) determines the direction of movement of the focused cell: `"up"` | `"down"` | `"left"` | `"right"` | `null`
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@example: +grid.block.events.on("afterBlockSelectionMove", (startCell, endCell) => { + console.log("Selection updated to:", endCell.column.id, endCell.row.id); +}); + +@descr: + +**Related API**: [`beforeBlockSelectionMove`](grid/api/blockselection/beforeblockselectionmove_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/beforeblockhandleapply_event.md b/docs/grid/api/blockselection/beforeblockhandleapply_event.md new file mode 100644 index 00000000..3f1c4283 --- /dev/null +++ b/docs/grid/api/blockselection/beforeblockhandleapply_event.md @@ -0,0 +1,66 @@ +--- +sidebar_label: beforeBlockHandleApply +title: JavaScript Grid - beforeBlockHandleApply Event +description: You can explore the beforeBlockHandleApply event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeBlockHandleApply + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered before applying the handle action + +### Usage + +~~~jsx +beforeBlockHandleApply: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + dragDirection: "up" | "down" | "left" | "right" | null, + event: MouseEvent | TouchEvent +) => boolean | void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the end cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
dragDirection(string) determines the direction of movement of the focused cell: `"up"` | `"down"` | `"left"` | `"right"` | `null`
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@returns: +Return `false` to cancel the action; otherwise, `true`. + +@example: +grid.block.events.on("beforeBlockHandleApply", (startCell, endCell, dir) => { + if (dir === "right" | dir === "left") { + console.log("Horizontal change canceled"); + return false; + } +}); + +@descr: + +**Related API**: [`afterBlockHandleApply`](grid/api/blockselection/afterblockhandleapply_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/beforeblockselectionapply_event.md b/docs/grid/api/blockselection/beforeblockselectionapply_event.md new file mode 100644 index 00000000..f6ab4d89 --- /dev/null +++ b/docs/grid/api/blockselection/beforeblockselectionapply_event.md @@ -0,0 +1,66 @@ +--- +sidebar_label: beforeBlockSelectionApply +title: JavaScript Grid - beforeBlockSelectionApply Event +description: You can explore the beforeBlockSelectionApply event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeBlockSelectionApply + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered before applying the selection (e.g., to a range) + +### Usage + +~~~jsx +beforeBlockSelectionApply: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + handle: boolean, + event: MouseEvent | TouchEvent +) => boolean | void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the end cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
handle(boolean) indicates whether the handle was used (`true`) or a regular selection (`false`)
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@returns: +Return `false` to cancel the action; otherwise, `true`. + +@example: +grid.block.events.on("beforeBlockSelectionApply", (startCell, endCell) => { + if (endCell.row.id === "2") { + console.log("Application canceled if the range ends with row 2"); + return false; + } +}); + +@descr: + +**Related API**: [`afterBlockSelectionApply`](grid/api/blockselection/afterblockselectionapply_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/beforeblockselectionmove_event.md b/docs/grid/api/blockselection/beforeblockselectionmove_event.md new file mode 100644 index 00000000..346564cd --- /dev/null +++ b/docs/grid/api/blockselection/beforeblockselectionmove_event.md @@ -0,0 +1,69 @@ +--- +sidebar_label: beforeBlockSelectionMove +title: JavaScript Grid - beforeBlockSelectionMove Event +description: You can explore the beforeBlockSelectionMove event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeBlockSelectionMove + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered before moving the selection boundary + +### Usage + +~~~jsx +beforeBlockSelectionMove: ( + startCell: { row: object; column: object }, + nextCell: { row: object; column: object }, + focusCell: { row: object; column: object } | null, + dragDirection: "up" | "down" | "left" | "right" | null, + event: MouseEvent | TouchEvent +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
nextCell(object) an object that contains the next cell to which the boundary is moving or the end cell of the previously selected boundary during the handle movement, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
focusCell(object) an object that contains the last focus cell (if the handle is used) or `null`, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
dragDirection(string) determines the direction of movement of the focused cell: `"up"` | `"down"` | `"left"` | `"right"` | `null`
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@returns: +Return `false` to cancel the action; otherwise, `true`. + +@example: +grid.block.events.on("beforeBlockSelectionMove", (startCell, nextCell) => { + console.log("Moving to:", nextCell.column.id, nextCell.row.id); +}); + +@descr: + +**Related API**: [`afterBlockSelectionMove`](grid/api/blockselection/afterblockselectionmove_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/blockhandlemousedown_event.md b/docs/grid/api/blockselection/blockhandlemousedown_event.md new file mode 100644 index 00000000..05743df5 --- /dev/null +++ b/docs/grid/api/blockselection/blockhandlemousedown_event.md @@ -0,0 +1,34 @@ +--- +sidebar_label: blockHandleMouseDown +title: JavaScript Grid - blockHandleMouseDown Event +description: You can explore the blockHandleMouseDown event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# blockHandleMouseDown + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered when clicking on the selection handle + +### Usage + +~~~jsx +blockHandleMouseDown: (event: MouseEvent | TouchEvent) => void; +~~~ + +@params: +The callback of the event is called with the following parameter: + +- `event` - the browser event: `MouseEvent` or `TouchEvent` + +@example: +grid.block.events.on("blockHandleMouseDown", (event) => { + console.log("Handle clicked:", event.type); +}); + +@descr: + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/blockselectionend_event.md b/docs/grid/api/blockselection/blockselectionend_event.md new file mode 100644 index 00000000..ebf582e3 --- /dev/null +++ b/docs/grid/api/blockselection/blockselectionend_event.md @@ -0,0 +1,60 @@ +--- +sidebar_label: blockSelectionEnd +title: JavaScript Grid - blockSelectionEnd Event +description: You can explore the blockSelectionEnd event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# blockSelectionEnd + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered when the selection has been completed + +### Usage + +~~~jsx +blockSelectionEnd: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + handle: boolean, + event: MouseEvent | TouchEvent +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the end cell at the time of selection completion, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
handle(boolean) indicates whether the handle was used (`true`) or a regular selection (`false`)
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@example: +grid.block.events.on("blockSelectionEnd", (startCell, endCell) => { + console.log("Selection completed:", startCell.column.id, endCell.column.id); +}); + +@descr: + +**Related API**: [`blockSelectionStart`](grid/api/blockselection/blockselectionstart_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/blockselectionstart_event.md b/docs/grid/api/blockselection/blockselectionstart_event.md new file mode 100644 index 00000000..dcde355e --- /dev/null +++ b/docs/grid/api/blockselection/blockselectionstart_event.md @@ -0,0 +1,63 @@ +--- +sidebar_label: blockSelectionStart +title: JavaScript Grid - blockSelectionStart Event +description: You can explore the blockSelectionStart event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# blockSelectionStart + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered when selection has been started + +### Usage + +~~~jsx +blockSelectionStart: ( + startCell: { row: object; column: object }, + endCell: { row: object; column: object }, + handle: boolean, + event: MouseEvent | TouchEvent +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + + + + + +
startCell(object) an object that contains the initial cell of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
endCell(object) an object that contains the end cell at the start of the selection, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
handle(boolean) indicates whether the handle is used (`true`) or a regular selection (`false`)
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@returns: +Return `false` to cancel the action; otherwise, `true`. + +@example: +grid.block.events.on("blockSelectionStart", (startCell, endCell, handle) => { + console.log("Selection started:", startCell.column.id, startCell.row.id); +}); + +@descr: + +**Related API**: [`blockSelectionEnd`](grid/api/blockselection/blockselectionend_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/blockselectionvalidate_event.md b/docs/grid/api/blockselection/blockselectionvalidate_event.md new file mode 100644 index 00000000..0cbb3b2a --- /dev/null +++ b/docs/grid/api/blockselection/blockselectionvalidate_event.md @@ -0,0 +1,72 @@ +--- +sidebar_label: blockSelectionValidate +title: JavaScript Grid - blockSelectionValidate Event +description: You can explore the blockSelectionValidate event of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# blockSelectionValidate + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered to check the possibility of starting a selection + +### Usage + +~~~jsx +blockSelectionValidate: ( + validateCell: { row: object; column: object }, + handle: boolean, + event: MouseEvent | TouchEvent +) => boolean | void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + + + + + + + + + +
validateCell(object) an object that contains the cell where the selection starts, includes the following properties:
  • `row` - (object) the row configuration object
  • `column` - (object) the column configuration object
handle(boolean) indicates whether the handle is used (`true`) or a regular selection (`false`)
event(Event) the browser event: `MouseEvent` or `TouchEvent`
+ +@returns: +Return `false` to cancel the action; otherwise, `true`. + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true +}); + +grid.block.events.on("blockSelectionValidate", (validateCell, handle, event) => { + if (cell.column.id === "b") { + console.log("Selection cannot start from column B"); + return false; + } +}); + +@descr: + + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/disable_method.md b/docs/grid/api/blockselection/disable_method.md new file mode 100644 index 00000000..bf9284ec --- /dev/null +++ b/docs/grid/api/blockselection/disable_method.md @@ -0,0 +1,41 @@ +--- +sidebar_label: disable() +title: JavaScript Grid - disable Method +description: You can explore the disable method of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# disable() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: disables the BlockSelection module and resets processing of block selection in Grid + +@signature: {'disable(): void;'} + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true +}); + +// disabling the block selection module +grid.block.disable(); +console.log(grid.block.isDisabled()); // -> true + +@descr: + +**Related article**: [Work with BlockSelection module](grid/usage_blockselection.md) + +**Related API**: [`enable()`](grid/api/blockselection/enable_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/enable_method.md b/docs/grid/api/blockselection/enable_method.md new file mode 100644 index 00000000..71623cbb --- /dev/null +++ b/docs/grid/api/blockselection/enable_method.md @@ -0,0 +1,41 @@ +--- +sidebar_label: enable() +title: JavaScript Grid - enable Method +description: You can explore the enable method of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# enable() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: enables the BlockSelection module and activates the capabilities of block selection in Grid + +@signature: {'enable(): void;'} + +@example: +// this example shows enabling the module after deactivation +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { disabled: true } // disabled on initialization +}); + +grid.block.enable(); // activating the module +console.log(grid.block.isDisabled()); // -> false + +@descr: + +**Related article**: [Work with BlockSelection module](grid/usage_blockselection.md) + +**Related API**: [`disable()`](grid/api/blockselection/disable_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/blockselection/isdisabled_method.md b/docs/grid/api/blockselection/isdisabled_method.md new file mode 100644 index 00000000..a1a9e74c --- /dev/null +++ b/docs/grid/api/blockselection/isdisabled_method.md @@ -0,0 +1,49 @@ +--- +sidebar_label: isDisabled() +title: JavaScript Grid - isDisabled Method +description: You can explore the isDisabled method of Grid block selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# isDisabled() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: returns the module's current state + +### Usage + +~~~jsx +isDisabled(): boolean; +~~~ + +@returns: +`true` if the module is disabled, `false` if the module is enabled + +@example: +// this example shows checking the module's activity status +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true +}); + +console.log(grid.block.isDisabled()); // -> false +grid.block.disable(); +console.log(grid.block.isDisabled()); // -> true + +@descr: + +**Related article**: [Work with BlockSelection module](grid/usage_blockselection.md) + +**Related API**: [`disable()`](grid/api/blockselection/disable_method.md), [`enable()`](grid/api/blockselection/enable_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/clipboard/aftercopy_event.md b/docs/grid/api/clipboard/aftercopy_event.md new file mode 100644 index 00000000..fba0e0b4 --- /dev/null +++ b/docs/grid/api/clipboard/aftercopy_event.md @@ -0,0 +1,49 @@ +--- +sidebar_label: afterCopy +title: JavaScript Grid - afterCopy Event +description: You can explore the afterCopy event of Grid clipboard in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterCopy + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires after successfully copying or cutting data + +### Usage + +~~~jsx +afterCopy: (isCut: boolean) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + +- `isCut` - indicates whether the operation was a cut (`true`) or a copy (`false`) + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + ], + clipboard: true +}); + +grid.clipboard.events.on("afterCopy", (isCut) => { + console.log(isCut ? "Data cut" : "Data copied"); +}); + +@descr: + +**Related API**: [`beforeCopy`](grid/api/clipboard/beforecopy_event.md) + +**Related article**: [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/clipboard/afterpaste_event.md b/docs/grid/api/clipboard/afterpaste_event.md new file mode 100644 index 00000000..9365e16f --- /dev/null +++ b/docs/grid/api/clipboard/afterpaste_event.md @@ -0,0 +1,45 @@ +--- +sidebar_label: afterPaste +title: JavaScript Grid - afterPaste Event +description: You can explore the afterPaste event of Grid clipboard in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterPaste + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires after successfully pasting data + +### Usage + +~~~jsx +afterPaste: () => void; +~~~ + + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + ], + clipboard: true +}); + +grid.clipboard.events.on("afterPaste", () => { + console.log("Data pasted"); +}); + +@descr: + +**Related API**: [`beforePaste`](grid/api/clipboard/beforepaste_event.md) + +**Related article**: [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/clipboard/beforecopy_event.md b/docs/grid/api/clipboard/beforecopy_event.md new file mode 100644 index 00000000..74a58a54 --- /dev/null +++ b/docs/grid/api/clipboard/beforecopy_event.md @@ -0,0 +1,55 @@ +--- +sidebar_label: beforeCopy +title: JavaScript Grid - beforeCopy Event +description: You can explore the beforeCopy event of Grid clipboard in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeCopy + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires before copying or cutting data + +### Usage + +~~~jsx +beforeCopy: (isCut: boolean) => boolean | void; +~~~ + +@params: +The callback of the event is called with the following parameters: + +- `isCut` - indicates whether the operation is a cut (`true`) or a copy (`false`) + +@returns: +Return `false` to cancel the operation; otherwise, `true` + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + ], + clipboard: true +}); + +grid.clipboard.events.on("beforeCopy", (isCut) => { + if (isCut) { + console.log("Cutting canceled"); + return false; + } +}); + +@descr: + +**Related API**: [`afterCopy`](grid/api/clipboard/aftercopy_event.md) + +**Related article**: [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/clipboard/beforepaste_event.md b/docs/grid/api/clipboard/beforepaste_event.md new file mode 100644 index 00000000..9f973639 --- /dev/null +++ b/docs/grid/api/clipboard/beforepaste_event.md @@ -0,0 +1,50 @@ +--- +sidebar_label: beforePaste +title: JavaScript Grid - beforePaste Event +description: You can explore the beforePaste event of Grid clipboard in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforePaste + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires before pasting data from the clipboard + +### Usage + +~~~jsx +beforePaste: () => boolean | void; +~~~ + +@returns: +Return `false` to cancel the operation; otherwise, `true` + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + ], + clipboard: true +}); + +grid.clipboard.events.on("beforePaste", () => { + if (!grid.range.getRange()) { + console.log("Paste canceled: no range specified"); + return false; + } +}); + +@descr: + +**Related API**: [`afterPaste`](grid/api/clipboard/afterpaste_event.md) + +**Related article**: [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/clipboard/copyerror_event.md b/docs/grid/api/clipboard/copyerror_event.md new file mode 100644 index 00000000..065550cf --- /dev/null +++ b/docs/grid/api/clipboard/copyerror_event.md @@ -0,0 +1,50 @@ +--- +sidebar_label: copyError +title: JavaScript Grid - copyError Event +description: You can explore the copyError event of Grid clipboard in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# copyError + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires when an error occurs during copying or cutting (e.g., clipboard access is blocked) + +### Usage + +~~~jsx +copyError: (error: string) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + +- `error` - an error message + + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + ], + clipboard: true +}); + +grid.clipboard.events.on("copyError", (error) => { + console.log("Copy error:", error); +}); + +@descr: + +**Related API**: [`pasteError`](grid/api/clipboard/pasteerror_event.md) + +**Related article**: [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/clipboard/pasteerror_event.md b/docs/grid/api/clipboard/pasteerror_event.md new file mode 100644 index 00000000..2b37aeee --- /dev/null +++ b/docs/grid/api/clipboard/pasteerror_event.md @@ -0,0 +1,50 @@ +--- +sidebar_label: pasteError +title: JavaScript Grid - pasteError Event +description: You can explore the pasteError event of Grid clipboard in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# pasteError + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires when an error occurs during pasting (e.g., clipboard is empty or data is invalid) + +### Usage + +~~~jsx +pasteError: (error: string) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + +- `error` - an error message + + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + ], + clipboard: true +}); + +grid.clipboard.events.on("pasteError", (error) => { + console.log("Paste error:", error); +}); + +@descr: + +**Related API**: [`copyError`](grid/api/clipboard/copyerror_event.md) + +**Related article**: [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/dragpanel/dragpanelitemclick_event.md b/docs/grid/api/dragpanel/dragpanelitemclick_event.md new file mode 100644 index 00000000..51cd7552 --- /dev/null +++ b/docs/grid/api/dragpanel/dragpanelitemclick_event.md @@ -0,0 +1,49 @@ +--- +sidebar_label: dragPanelItemClick +title: JavaScript Grid - dragPanelItemClick Event +description: You can explore the dragPanelItemClick event of Grid drag panel in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# dragPanelItemClick + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered when the drag panel item is clicked + +### Usage + +~~~jsx +dragPanelItemClick: (id: string, event: MouseEvent | TouchEvent) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + +- `id` - the ID of the row associated with the drag panel item +- `event` - a browser event: `MouseEvent` or `TouchEvent` + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + dragPanel: true +}); + +grid.events.on("dragPanelItemClick", (id, event) => { + console.log(`Drag panel clicked for row ID: ${id}`); +}); + +@descr: + +**Related article**: [Work with DragPanel module](grid/usage_dragpanel.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/dragpanel/dragpanelitemmousedown_event.md b/docs/grid/api/dragpanel/dragpanelitemmousedown_event.md new file mode 100644 index 00000000..4d5c7d57 --- /dev/null +++ b/docs/grid/api/dragpanel/dragpanelitemmousedown_event.md @@ -0,0 +1,49 @@ +--- +sidebar_label: dragPanelItemMouseDown +title: JavaScript Grid - dragPanelItemMouseDown Event +description: You can explore the dragPanelItemMouseDown event of Grid drag panel in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# dragPanelItemMouseDown + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered when the mouse button is pressed on the drag panel item + +### Usage + +~~~jsx +dragPanelItemMouseDown: (id: string, event: MouseEvent | TouchEvent) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + +- `id` - the ID of the row associated with the drag panel item +- `event` - a browser event: `MouseEvent` or `TouchEvent` + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + dragPanel: true +}); + +grid.events.on("dragPanelItemMouseDown", (id, event) => { + console.log(`Mouse down on drag panel for row ID: ${id}`); +}); + +@descr: + +**Related article**: [Work with DragPanel module](grid/usage_dragpanel.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/export/grid_csv_method.md b/docs/grid/api/export/grid_csv_method.md index 09f04cbe..80c1ede6 100644 --- a/docs/grid/api/export/grid_csv_method.md +++ b/docs/grid/api/export/grid_csv_method.md @@ -13,7 +13,7 @@ description: You can explore the csv export method of Grid in the documentation @params: - `config` - (optional) an object with export settings. You can specify the following settings for export to CSV: - `asFile?: boolean` - (optional) defines whether Grid should be exported to a file, *true* by default. To export Grid only as a CSV string, you need to set *asFile:false* - - `name?: string` - (optional) the name of the exported CSV file (if asFile is not set to *false*) + - `name?: string` - (optional) "grid" by default. The name of the exported CSV file (if asFile is not set to *false*) - `rowDelimiter?: string` - (optional) a newline ("\n") by default. A separator between rows, can be a tab - "\t", or any other value - `columnDelimiter?: string` - (optional) a comma (",") by default. A separator between columns, can be a semicolon - ";", or any other value @@ -26,9 +26,9 @@ grid.export.csv(); // export with config settings grid.export.csv({ - name:"grid_data", // grid data will be exported to a CSV file named "grid_data" - rowDelimiter: "\t", // the tab delimiter will be used to separate rows - columnDelimiter: ";" // the semicolon delimiter will be used to separate columns + name: "my_file", // the name of a ready CSV file + rowDelimiter: "\t", // the delimiter used to separate rows + columnDelimiter: ";" // the delimiter used to separate columns }); diff --git a/docs/grid/api/export/grid_xlsx_method.md b/docs/grid/api/export/grid_xlsx_method.md index 11190db2..13fb7b8f 100644 --- a/docs/grid/api/export/grid_xlsx_method.md +++ b/docs/grid/api/export/grid_xlsx_method.md @@ -8,13 +8,18 @@ description: You can explore the xlsx export method of Grid in the documentation @short: Exports data from a grid to an Excel file +:::info +DHTMLX Grid uses the WebAssembly-based library [Json2Excel](https://github.com/dhtmlx/json2excel) for export of data to Excel. [Check the details](grid/usage.md/#exporting-data-to-excel). +::: + @signature: {'xlsx(config?: object): void;'} @params: -- `config` - (optional) an object with export settings. You can specify the following settings for export to EXCEL: - - `url?: string` - (optional) the link to the server side where export will be processed. By default, it is **"//export.dhtmlx.com/excel"** - - `name?: string` - (optional) the name of a ready Excel file - +- `config` - (optional) an object with export settings. You can specify the following settings for export to Excel: + - `url?: string` - (optional) a local path to the **worker.js** file of the [Json2Excel](https://github.com/dhtmlx/json2excel) library (where export will be processed) set as `"../libs/json2excel/1.3/worker.js?vx"` + - `name?: string` - (optional) "grid" by default. The name of a ready Excel file + - `tableName?: string` - (optional) "data" by default. The name of a sheet with grid data in the Excel file + - `dateFormatMask?: string` - (optional) "dd/mm/yy" by default. The mask used for [dates formatting in Excel](https://support.microsoft.com/en-us/office/format-a-date-the-way-you-want-in-excel-8e10019e-d5d8-47a1-ba95-db95123d273e) @example: // default export @@ -22,13 +27,14 @@ grid.export.xlsx(); // export with config settings grid.export.xlsx({ - name:"grid_data", - url: "//export.dhtmlx.com/excel" + url: "../libs/json2excel/1.3/worker.js?vx", // a local path to the `worker.js` file of the export module + name: "my_file", // the name of a ready Excel file + tableName: "grid", // the name of a sheet with grid data in the Excel file + dateFormatMask: "mm.dd.yy" // the date format mask for Excel }); - @descr: **Related samples**: [Grid. Export to xlsx and csv](https://snippet.dhtmlx.com/58oqij47) -**Related article:** [Exporting Grid](grid/usage.md) \ No newline at end of file +**Related article:** [Exporting Grid](grid/usage.md/#exporting-data-to-excel) \ No newline at end of file diff --git a/docs/grid/api/grid_adjust_config.md b/docs/grid/api/grid_adjust_config.md index 47dbbec2..4393a704 100644 --- a/docs/grid/api/grid_adjust_config.md +++ b/docs/grid/api/grid_adjust_config.md @@ -60,8 +60,8 @@ The width the columns will be adjusted to also depends on the values of the [`mi - in case of complex HTML data, usage of the `adjust` config may lead to incorrect size calculations - the enabled `adjust` config (including the "header", "footer", "data" modes) adjusts the width of columns taking into account the [`template`](grid/api/api_gridcolumn_properties.md) added to cells. You need to set the **content** attribute of the [`header/footer`](grid/api/api_gridcolumn_properties.md) properties to one of the following modes: "avg" | "sum" | "max" | "min" | "count", otherwise **text** will be calculated -@changelog: added in v6.4 +**Related API**: [`adjustColumnWidth()`](grid/api/grid_adjustcolumnwidth_method.md) -[comment]: # (@relatedapi: grid/api/grid_adjustcolumnwidth_method.md) +**Related article**: [Autosize for columns](grid/configuration.md#autosize-for-columns) -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#autosize-for-columns) +@changelog: added in v6.4 diff --git a/docs/grid/api/grid_adjustcolumnwidth_method.md b/docs/grid/api/grid_adjustcolumnwidth_method.md index 7b5add19..2487c65f 100644 --- a/docs/grid/api/grid_adjustcolumnwidth_method.md +++ b/docs/grid/api/grid_adjustcolumnwidth_method.md @@ -21,4 +21,4 @@ grid.adjustColumnWidth("b", "header"); If no value is set to the `adjust` parameter, the `adjustColumnWidth()` method sets it to *true*. -[comment]: # (@relatedapi: grid/api/grid_adjust_config.md) +**Related API**: [`adjust`](grid/api/grid_adjust_config.md) diff --git a/docs/grid/api/grid_autoheight_config.md b/docs/grid/api/grid_autoheight_config.md index 30744991..75ff5eb4 100644 --- a/docs/grid/api/grid_autoheight_config.md +++ b/docs/grid/api/grid_autoheight_config.md @@ -6,7 +6,7 @@ description: You can explore the autoHeight config of Grid in the documentation # autoHeight -:::tip Pro version only +:::tip pro version only This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. ::: diff --git a/docs/grid/api/grid_beforecolumndrag_event.md b/docs/grid/api/grid_beforecolumndrag_event.md index dcebc81d..bd1417bb 100644 --- a/docs/grid/api/grid_beforecolumndrag_event.md +++ b/docs/grid/api/grid_beforecolumndrag_event.md @@ -6,7 +6,9 @@ description: You can explore the beforeColumnDrag event of Grid in the documenta # beforeColumnDrag -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires before dragging of a column has started diff --git a/docs/grid/api/grid_beforecolumndrop_event.md b/docs/grid/api/grid_beforecolumndrop_event.md index 7c562f43..b47d15b1 100644 --- a/docs/grid/api/grid_beforecolumndrop_event.md +++ b/docs/grid/api/grid_beforecolumndrop_event.md @@ -6,7 +6,9 @@ description: You can explore the beforeColumnDrop event of Grid in the documenta # beforeColumnDrop -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires before the user has finished dragging and released the mouse button over a target column diff --git a/docs/grid/api/grid_beforerowresize_event.md b/docs/grid/api/grid_beforerowresize_event.md index ea0e1c70..46f0b5b5 100644 --- a/docs/grid/api/grid_beforerowresize_event.md +++ b/docs/grid/api/grid_beforerowresize_event.md @@ -6,7 +6,9 @@ description: You can explore the beforeRowResize event of Grid in the documentat # beforeRowResize -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires before the height of a row is changed diff --git a/docs/grid/api/grid_blockselection_config.md b/docs/grid/api/grid_blockselection_config.md new file mode 100644 index 00000000..69d2a1d9 --- /dev/null +++ b/docs/grid/api/grid_blockselection_config.md @@ -0,0 +1,206 @@ +--- +sidebar_label: blockSelection +title: JavaScript Grid - blockSelection Config +description: You can explore the blockSelection config of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# blockSelection + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: Optional. Enables/disables the BlockSelection module during the Grid initialization + +### Usage + +~~~jsx +blockSelection?: + | boolean + | { + disabled?: boolean; + mode?: "range" | "manual"; + handle?: boolean | { + allowAxis?: "x" | "y" | "xy"; + handler?: + | boolean + | ((args: { + cell: { row: object; column: object }; + array: { row: object; column: object }[]; + range: { row: object; column: object }[]; + dir: "up" | "down" | "right" | "left"; + index: number; + grid: IProGrid; + }) => { prev: any; current: any } | void); + }; + area?: boolean; + }; +~~~ + +@default: false + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true // enables the BlockSelection module +}); + +@descr: +### Parameters + +The `blockSelection` property can be set in two ways: + +- as a *boolean* value it enables or disables the block selection module upon the component initialization +- as an *object* it enables the module and allows setting additional configuration options during the component initialization. The following options are available: + + + + + + + + + + + + + + + + + + + + +
disabled(boolean) disables the module on startup, `false` by default
mode(string) the operating mode of the module:
handle(boolean | object) enables the handle for resizing or provides additional configuration options, `true` by default. As an *object* can contain the following properties:
  • allowAxis - (string) restricts the handle movement: `"x"` (horizontal), `"y"` (vertical), `"xy"` (both directions). `"xy"` by default
  • handler - (function | boolean) a *function* to process the handle actions or *boolean* to enable/disable. As a *function*, the property takes the following parameters:
    • cell - (object) the object of the current cell. Contains the following properties:
      • *row* - the configuration object of a row
      • *column* - the configuration object of a column
    • array - (array) an array of all selected cells. Each cell object contains the following properties:
      • *row* - the configuration object of a row
      • *column* - the configuration object of a column
    • range - (array) an array of pre-selected cells. Each cell object contains the following properties:
      • *row* - the configuration object of a row
      • *column* - the configuration object of a column
    • dir - (string) the direction of cells selection: "up" | "down" | "right" | "left"
    • index - (number) the index of the iterated cell
    • grid - (object) the `dhx.Grid` component object
    The handler function may return an object with the history of Grid actions. The returned object contains the following properties:
    • prev - the previous cell value
    • current - the new cell value
area(boolean) enables the display of the selection area, `true` by default
+ +:::note +By default, the `blockSelection` property is set to `false`. When `blockSelection` is set to `true` or the module is set to the "range" mode, the [`RangeSelection`](grid/usage_rangeselection.md) module is initialized. +::: + +This example demonstrates configuring the module with the handle disabled and the "range" mode enabled: + +~~~jsx {10-13} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { + mode: "range", // setting the "range" mode + handle: false // the handle is disabled + } +}); +~~~ + +This example demonstrates configuring the handle and its behavior: + +~~~jsx +/* Define grid columns configuration */ +const columns = [ + { id: "productId", header: [{ text: "Product ID" }] }, // Column for the unique product identifier + { id: "productName", header: [{ text: "Product Name" }] }, // Column for the product name + { id: "category", header: [{ text: "Category" }] }, // Column for the product category + { id: "receivedDate", header: [{ text: "Received Date" }], type: "date", dateFormat: "%d.%m.%Y" }, // Date column with the specified format + { id: "stock", header: [{ text: "Stock" }], type: "number" }, // Numeric column for the stock quantity + { id: "price", header: [{ text: "Price" }], type: "number", numberMask: { prefix: "$" } } // Numeric column for the price with the dollar prefix +]; + +/* Initialize DHTMLX Grid with the specified configuration */ +const grid = new dhx.Grid("grid_container", { + columns, + data, + autoWidth: true, + history: true, // Enable history tracking for undo/redo + blockSelection: { + handle: { + allowAxis: "y", // Allow selection along the y-axis (rows) + handler: blockSelectionHandler, // Custom handler for block selection + }, + }, +}); + +/* Set initial selection range for the grid */ +grid.range.setRange({ + xStart: "productId", // Start selection at the "productId" column + yEnd: grid.data.getId(0), // End selection at the first row +}); + +/* Initialize objects to store initial values and column indices */ +let initValues = {}; // Store initial values for each column +let columnIndex = {}; // Track index increments for each column + +/* The handler function for block selection events */ +function blockSelectionHandler({ cell, array, index, grid }) { + // Reset tracking objects if this is the first cell in the selection + if (!index) { + initValues = {}; + columnIndex = {}; + } + const columnId = cell.column.id; + // Initialize values for a new column if not already set + if (!initValues[columnId]) { + initValues[columnId] = cell.row[columnId]; // Store the initial cell value + columnIndex[columnId] = 0; // Initialize the index counter + return { prev: initValues[columnId], current: initValues[columnId] }; // Return unchanged values + } + + // Increment column index for the current column + const colIndex = columnIndex[columnId] += 1; + const initValue = initValues[columnId]; // Get the initial value for a column + let prev = current = cell.row[columnId]; // Set the default previous and current values + + // Modify the current value based on the column type + switch (cell.column.type) { + case "number": + current = initValue + colIndex * 10; // Increment the number by 10 per row + break; + case "date": + // Parse ISO date and increment the day by colIndex + const [year, month, day] = initValue.split("-"); + current = new Date(Number(year), Number(month) - 1, Number(day) + colIndex).toISOString(); + break; + default: + current = initValue; // Keep the default value for other types + break; + } + + // Custom formatting for specific columns + if (columnId === "productId") { + // Generate a new product ID with the format P00N + current = `P00${parseInt(initValue.replace(/\D/g, "")) + colIndex}`; + } + if (columnId === "category") { + // Append the index in parentheses to the category + current = `${current} (${colIndex})`; + } + + // Create the history object for undo/redo + const history = { prev, current }; + // Update grid data with the new value + grid.data.update(cell.row.id, { [columnId]: current }, + index < array.length - 1 // Continue updating if it isn't the last cell in selection + ); + return history; // Return the history for tracking +} +~~~ + +**Related sample:** [Grid. BlockSelection. Work with the handle configuration](https://snippet.dhtmlx.com/sryiguxu) + +**Related articles:** +- [Managing block selection in Grid](grid/configuration.md/#managing-block-selection-in-grid) +- [Work with BlockSelection module](grid/usage_blockselection.md) + +@changelog: added in v9.2 + diff --git a/docs/grid/api/grid_cancelcolumndrop_event.md b/docs/grid/api/grid_cancelcolumndrop_event.md index 518abab6..67bb5c01 100644 --- a/docs/grid/api/grid_cancelcolumndrop_event.md +++ b/docs/grid/api/grid_cancelcolumndrop_event.md @@ -6,7 +6,9 @@ description: You can explore the cancelColumnDrop event of Grid in the documenta # cancelColumnDrop -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires on moving a mouse pointer out of borders of a column while dragging the column diff --git a/docs/grid/api/grid_cancolumndrop_event.md b/docs/grid/api/grid_cancolumndrop_event.md index f2438d92..2219653d 100644 --- a/docs/grid/api/grid_cancolumndrop_event.md +++ b/docs/grid/api/grid_cancolumndrop_event.md @@ -6,7 +6,9 @@ description: You can explore the canColumnDrop event of Grid in the documentatio # canColumnDrop -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires when a dragged column is placed over a target column diff --git a/docs/grid/api/grid_clipboard_config.md b/docs/grid/api/grid_clipboard_config.md new file mode 100644 index 00000000..e08eab05 --- /dev/null +++ b/docs/grid/api/grid_clipboard_config.md @@ -0,0 +1,83 @@ +--- +sidebar_label: clipboard +title: JavaScript Grid - clipboard Config +description: You can explore the clipboard config of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# clipboard + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: Optional. Enables/disables the Clipboard module during the Grid initialization + +:::note +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. +::: + +### Usage + +~~~jsx +clipboard?: + | boolean + | { + copyModifier?: (value: any, cell: { row: object; column: object }, cut: boolean) => string; + cutModifier?: (value: any, cell: { row: object; column: object }) => string; + pasteModifier?: (value: any, cell: { row: object; column: object }) => any; + }; +~~~ + +@default: false + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { mode: "range" }, // required for Clipboard to function (initializes automatically) + clipboard: true // enables the Clipboard module +}); + +@descr: +The `clipboard` property can be set in two ways: + +- as a *boolean* value it enables or disables the `clipboard` module upon the component initialization +- as an *object* it enables the module and allows defining [modifier functions](grid/usage_clipboard.md/#using-formatter-functions) for data processing. The following properties are available: + - `copyModifier` - (*function*) modifies data before copying to the clipboard. Accepts as parameters the cell value, the cell object, and the `cut` flag (set to `true`, if it's a cut operation) + - `cutModifier` - (*function*) modifies the cell data before cutting (before clearing the cell). Accepts as parameters the cell value and the cell object + - `pasteModifier` - (*function*) modifies data from the clipboard before pasting into a cell. Accepts as parameters the cell value and the cell object + +The example below demonstrates the clipboard configuration with all the modifiers in use: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + clipboard: { + // adds a suffix based on the operation + copyModifier: (value, cell, cut) => `${value}${cut ? "-cut" : "-copied"}`, + cutModifier: (value, cell) => `${value}-removed`, // before cutting a value + pasteModifier: (value, cell) => value.replace("-copied", "") // removes the suffix on pasting + } +}); +~~~ + +**Related sample**: [Grid. Clipboard. Custom copy/cut/paste for number and date columns](https://snippet.dhtmlx.com/dfj49xah) + +**Related articles:** +- [Clipboard](grid/configuration.md/#clipboard) +- [Work with Clipboard module](grid/usage_clipboard.md) + +@changelog: added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/grid_dragcolumnin_event.md b/docs/grid/api/grid_dragcolumnin_event.md index 50ae5a2c..4ef0a480 100644 --- a/docs/grid/api/grid_dragcolumnin_event.md +++ b/docs/grid/api/grid_dragcolumnin_event.md @@ -6,7 +6,9 @@ description: You can explore the dragColumnIn event of Grid in the documentation # dragColumnIn -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires when a column is dragged to another potential target diff --git a/docs/grid/api/grid_dragcolumnout_event.md b/docs/grid/api/grid_dragcolumnout_event.md index 7986cc06..e9dab30b 100644 --- a/docs/grid/api/grid_dragcolumnout_event.md +++ b/docs/grid/api/grid_dragcolumnout_event.md @@ -6,7 +6,9 @@ description: You can explore the dragColumnOut event of Grid in the documentatio # dragColumnOut -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires when a column is dragged out of a potential target diff --git a/docs/grid/api/grid_dragcolumnstart_event.md b/docs/grid/api/grid_dragcolumnstart_event.md index d1539b66..1eeae7a8 100644 --- a/docs/grid/api/grid_dragcolumnstart_event.md +++ b/docs/grid/api/grid_dragcolumnstart_event.md @@ -6,7 +6,9 @@ description: You can explore the dragColumnStart event of Grid in the documentat # dragColumnStart -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: fires when dragging of a column has started diff --git a/docs/grid/api/grid_dragpanel_config.md b/docs/grid/api/grid_dragpanel_config.md new file mode 100644 index 00000000..36d8c5b9 --- /dev/null +++ b/docs/grid/api/grid_dragpanel_config.md @@ -0,0 +1,95 @@ +--- +sidebar_label: dragPanel +title: JavaScript Grid - dragPanel Config +description: You can explore the dragPanel config of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# dragPanel + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: Optional. Enables/disables the DragPanel module during the Grid initialization + +### Usage + +~~~jsx +dragPanel?: + | boolean + | { + css?: string; + icon?: string; + width?: number; + }; +~~~ + +@default: false + +:::note +The module is automatically enabled, if the [row Drag-and-Drop](grid/configuration.md/#drag-n-drop) functionality is active (e.g. via the `dragItem: "row"` or `dragItem: "both"` properties), and either the [`BlockSelection`](grid/usage_blockselection.md) or [`Clipboard`](grid/usage_clipboard.md) modules are enabled. +::: + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + dragItem: "both", // enables row Drag-and-Drop + blockSelection: true, // triggers the `DragPanel` activation, when `dragItem` is enabled + // or + dragPanel: true // enables the `DragPanel` module +}); + +@descr: + +The `dragPanel` property can be set in two ways: + +- as a *boolean* value it enables or disables the `dragPanel` module upon the component initialization +- as an *object* it enables the module and allows defining additional configuration during initialization: + - `css` - (*string*) specifies a custom CSS class for styling the drag panel + - `icon` - (*string*) defines a custom icon for the drag handle + - `width` - (*number*) sets the width of the drag panel in pixels + +The following example demonstrates configuring the `DragPanel` module with custom styling and width: + +~~~html + + + +~~~ + +**Related sample:** [Grid (TreeGrid). DragPanel. Initialization](https://snippet.dhtmlx.com/uevdwjuo) + +**Related articles:** +- [Adjusting DragPanel module](grid/configuration.md/#adjusting-dragpanel-module) +- [Work with DragPanel module](grid/usage_dragpanel.md) + + +@changelog: added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/grid_footerautoheight_config.md b/docs/grid/api/grid_footerautoheight_config.md index f1c55b35..7be6839f 100644 --- a/docs/grid/api/grid_footerautoheight_config.md +++ b/docs/grid/api/grid_footerautoheight_config.md @@ -6,10 +6,13 @@ description: You can explore the footerAutoHeight config of Grid in the document # footerAutoHeight -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: Optional. Allows adjusting the height of the footer for the content to fit in -@signature: footerAutoHeight?: boolean; + +@signature: {'footerAutoHeight?: boolean;'} @default: false diff --git a/docs/grid/api/grid_getsubrow_method.md b/docs/grid/api/grid_getsubrow_method.md index 56e50053..2979c185 100644 --- a/docs/grid/api/grid_getsubrow_method.md +++ b/docs/grid/api/grid_getsubrow_method.md @@ -6,6 +6,10 @@ description: You can explore the getSubRow method of Grid in the documentation o # getSubRow() +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + @short: returns the configuration and content of a sub-row for the specified row :::info diff --git a/docs/grid/api/grid_headerautoheight_config.md b/docs/grid/api/grid_headerautoheight_config.md index 7a1625eb..8e2536a4 100644 --- a/docs/grid/api/grid_headerautoheight_config.md +++ b/docs/grid/api/grid_headerautoheight_config.md @@ -6,7 +6,9 @@ description: You can explore the headerAutoHeight config of Grid in the document # headerAutoHeight -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @short: Optional. Allows adjusting the height of the header for the content to fit in diff --git a/docs/grid/api/grid_height_config.md b/docs/grid/api/grid_height_config.md index c4755a01..aec8624e 100644 --- a/docs/grid/api/grid_height_config.md +++ b/docs/grid/api/grid_height_config.md @@ -11,7 +11,10 @@ description: You can explore the height config of Grid in the documentation of t @signature: {'height?: number | "auto";'} @descr: -{{pronote The **height: "auto"** option requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} + +:::tip note +The **height: "auto"** option requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: @example: const grid = new dhx.Grid("grid_container", { diff --git a/docs/grid/api/grid_history_config.md b/docs/grid/api/grid_history_config.md new file mode 100644 index 00000000..774aecd9 --- /dev/null +++ b/docs/grid/api/grid_history_config.md @@ -0,0 +1,75 @@ +--- +sidebar_label: history +title: JavaScript Grid - history Config +description: You can explore the history config of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# history + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: Optional. Enables/disables the History module during the Grid initialization + +### Usage + +~~~jsx +history?: + | boolean + | { + limit?: number; + disabled?: boolean; + }; +~~~ + +@default: false + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + history: true // enables the History module +}); + +@descr: +The `history` property can be set in two ways: +- as a *boolean* value it enables or disables the `History` module upon the component initialization +- as an *object* it enables the module and allows setting additional parameters: + - `limit` - (*number*) the maximum number of actions stored in the history. When the limit is exceeded, the oldest actions are removed + - `disabled` - (*boolean*) if `true`, the module is disabled on initialization, and no actions are recorded in the history + +The example below demonstrates configuring the module with a history limit of 10 actions. The module is disabled on initialization: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + history: { + limit: 10, // limits history to 10 actions + disabled: true // module is disabled on start + } +}); + +grid.history.enable(); // enabling the module +~~~ + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +**Related articles:** +- [History of Grid actions](grid/configuration.md/#history-of-grid-actions) +- [Work with History module](grid/usage_history.md) + +@changelog: added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/grid_multisort_config.md b/docs/grid/api/grid_multisort_config.md index 6cd0f008..1494655e 100644 --- a/docs/grid/api/grid_multisort_config.md +++ b/docs/grid/api/grid_multisort_config.md @@ -6,11 +6,12 @@ description: You can explore the multiSort config of Grid in the documentation o # multiSort +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + @short: Optional. Enables the possibility of sorting Grid data by multiple columns -:::tip Pro version only -This functionality is available in the PRO edition only. -::: @signature: {'multiSort?: boolean;'} @@ -29,4 +30,7 @@ const grid = new dhx.Grid("grid_container", { **Related sample**: [Grid. Sorting by multiple columns (multisorting)](https://snippet.dhtmlx.com/4ej0i3qi) -**Related article**: [Sorting by multiple columns](grid/usage.md#sorting-by-multiple-columns) \ No newline at end of file +**Related article**: [Sorting by multiple columns](grid/usage.md#sorting-by-multiple-columns) + +@changelog: +- Added in v9.1 \ No newline at end of file diff --git a/docs/grid/api/grid_rangeselection_config.md b/docs/grid/api/grid_rangeselection_config.md new file mode 100644 index 00000000..5b40cbc3 --- /dev/null +++ b/docs/grid/api/grid_rangeselection_config.md @@ -0,0 +1,67 @@ +--- +sidebar_label: rangeSelection +title: JavaScript Grid - rangeSelection Config +description: You can explore the rangeSelection config of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# rangeSelection + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: Optional. Enables/disables the RangeSelection module during the Grid initialization + +### Usage + +~~~jsx +rangeSelection?: + | boolean + | { + disabled?: boolean; + }; +~~~ + +@default: false + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true // enables the Range module +}); + +@descr: +The `rangeSelection` configuration object can have the following properties: + +- `disabled` - (*boolean*) makes the module inactive upon initialization of the component + +~~~jsx {11,15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: { disabled: true } +}); + +console.log(grid.range.isDisabled()); // -> `true` - module is inactive +grid.range.setRange({ xStart: "a", yStart: "1" }); // the range will not be set +~~~ + +**Related articles:** +- [Managing RangeSelection in Grid](grid/configuration.md/#managing-range-selection-in-grid) +- [Work with RangeSelection module](grid/usage_rangeselection.md) + +@changelog: added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/grid_selection_config.md b/docs/grid/api/grid_selection_config.md index 1b35dc03..578da658 100644 --- a/docs/grid/api/grid_selection_config.md +++ b/docs/grid/api/grid_selection_config.md @@ -27,4 +27,6 @@ When you set `selection:true`, the "complex" mode is applied. **Related sample**: [Grid. Selection](https://snippet.dhtmlx.com/ad6roqsx) -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#selection) +**Related articles:** +- [Selection](grid/configuration.md#selection) +- [Work with Selection object](grid/usage_selection.md) diff --git a/docs/grid/api/grid_spans_config.md b/docs/grid/api/grid_spans_config.md index d74c9464..5c11ae37 100644 --- a/docs/grid/api/grid_spans_config.md +++ b/docs/grid/api/grid_spans_config.md @@ -120,9 +120,10 @@ const grid = new dhx.Grid("grid_container", { - All necessary columns or rows will be in a span if the **spans** property is set for the columns located within the frozen area. - If the **spans** property is set for a number of columns or rows placed as in the frozen part as in the movable one, then the columns remained in the movable part only will be in a span. +**Related article:** [Spans](grid/configuration.md#spans) + @changelog: - The `tooltipTemplate` property is added in v9.0 - The ability to set the `tooltip` config as an object is added in v8.4 - The `tooltip` property is added in v6.5. -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#spans) diff --git a/docs/grid/api/grid_subrow_config.md b/docs/grid/api/grid_subrow_config.md index 812b78ab..6bd28521 100644 --- a/docs/grid/api/grid_subrow_config.md +++ b/docs/grid/api/grid_subrow_config.md @@ -6,6 +6,10 @@ description: You can explore the subRow config of Grid in the documentation of t # subRow +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + @short: Optional. Defines the sub-row content for each row of the main Grid :::note @@ -66,4 +70,7 @@ const grid = new dhx.Grid("grid_container", { **Related API**: [subRowConfig](grid/api/grid_subrowconfig_config.md) +@changelog: +- Added in v9.1 + \ No newline at end of file diff --git a/docs/grid/api/grid_subrowconfig_config.md b/docs/grid/api/grid_subrowconfig_config.md index 3dc47044..6095e329 100644 --- a/docs/grid/api/grid_subrowconfig_config.md +++ b/docs/grid/api/grid_subrowconfig_config.md @@ -6,6 +6,10 @@ description: You can explore the subRowConfig config of Grid in the documentatio # subRowConfig +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + @short: Optional. Specifies the configuration settings of a sub-row @signature: {'subRowConfig?: ((row: IRow) => ISubRowConfig) | ISubRowConfig;'} @@ -83,4 +87,7 @@ const grid = new dhx.Grid("grid_container", { **Related article:** [Row expander](grid/configuration.md#row-expander) **Related API**: [subRow](grid/api/grid_subrow_config.md) + +@changelog: +- Added in v9.1 \ No newline at end of file diff --git a/docs/grid/api/grid_summary_config.md b/docs/grid/api/grid_summary_config.md index feadbe2c..c0b77ab5 100644 --- a/docs/grid/api/grid_summary_config.md +++ b/docs/grid/api/grid_summary_config.md @@ -84,7 +84,7 @@ console.log(summary); // { totalPopulation: 1000000, totalArea: 50000, density: **Related article:** [Custom statistics in the column header/footer and spans](../../configuration/#custom-statistics-in-the-column-headerfooter-and-spans) -**Related API**: [getSummary](grid/api/grid_getsummary_method.md) +**Related API**: [getSummary()](grid/api/grid_getsummary_method.md) @changelog: - Added in v9.0 \ No newline at end of file diff --git a/docs/grid/api/grid_tooltip_config.md b/docs/grid/api/grid_tooltip_config.md index cac62057..01815eb7 100644 --- a/docs/grid/api/grid_tooltip_config.md +++ b/docs/grid/api/grid_tooltip_config.md @@ -47,8 +47,9 @@ const grid = new dhx.Grid("grid_container", { - [Grid. Hiding tooltips](https://snippet.dhtmlx.com/mq4t3t3w) - [Grid. Tooltip config](https://snippet.dhtmlx.com/qpqnalyt) +**Related article:** [Tooltip](grid/configuration.md#tooltip) + @changelog: - The ability to set the `tooltip` config as an object is added in v8.4 - Added in v6.5 -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#tooltip) diff --git a/docs/grid/api/history/add_method.md b/docs/grid/api/history/add_method.md new file mode 100644 index 00000000..3517faec --- /dev/null +++ b/docs/grid/api/history/add_method.md @@ -0,0 +1,74 @@ +--- +sidebar_label: add() +title: JavaScript Grid - add Method +description: You can explore the add method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# add() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: adds a new action into the history of actions within the Grid + +### Usage + +~~~jsx +type ActionType = "add" | "remove" | "removeAll" | "change"; + +interface IAction { + type: ActionType; + batch: IRow[]; + inverse?: IAction; +} + +add(action: IAction): void; +~~~ + +@params: + +- `action: IAction` - the action object containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (mandatory for the "change" and "removeAll" types, not required for other types) + +:::note +The `action` argument must conform to the `IAction` interface. If the module is disabled, the action type is invalid, or the `inverse` property is missing (for actions with the "change" and "removeAll" types), the [`error`](grid/api/history/error_event.md) event is triggered. +::: + +@example: +// The example shows adding a new row via `DataCollection` +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding a new row via DataCollection +const newItem = { id: "2", name: "New Item", value: 20 }; +grid.data.add(newItem); + +// recording the action in the history +grid.history.add({ + type: "add", + batch: [{ ...newItem }], +}); + +// checking the history +const history = grid.history.getHistory(); +console.log(history.length); // ->1 + +@descr: + +**Related article**: [Adding/removing Grid history actions](grid/usage_history.md/#addingremoving-grid-history-actions) + +**Related API**: [`remove()`](grid/api/history/remove_method.md), [`removeAll()`](grid/api/history/removeall_method.md), [`getHistory()`](grid/api/history/gethistory_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/afteradd_event.md b/docs/grid/api/history/afteradd_event.md new file mode 100644 index 00000000..4f8167d1 --- /dev/null +++ b/docs/grid/api/history/afteradd_event.md @@ -0,0 +1,49 @@ +--- +sidebar_label: afterAdd +title: JavaScript Grid - afterAdd Event +description: You can explore the afterAdd event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterAdd + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered after successfully adding an action to the history + +@signature: {'afterAdd: (action: IAction) => void;'} + +@params: +The callback of the event is called with the following parameters: +- `action: IAction` - the object of the added action containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("afterAdd", (action) => { + console.log("Action added to history:", action.type); +}); + +@descr: + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +**Related article**: [Adding/removing Grid history actions](grid/usage_history.md/#addingremoving-grid-history-actions) + +**Related API**: [`add()`](grid/api/history/add_method.md), [`beforeAdd()`](grid/api/history/beforeadd_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/afterredo_event.md b/docs/grid/api/history/afterredo_event.md new file mode 100644 index 00000000..4d4c7fe1 --- /dev/null +++ b/docs/grid/api/history/afterredo_event.md @@ -0,0 +1,49 @@ +--- +sidebar_label: afterRedo +title: JavaScript Grid - afterRedo Event +description: You can explore the afterRedo event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterRedo + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered after successfully redoing an action + +@signature: {'afterRedo: (action: IAction) => void;'} + +@params: +The callback of the event is called with the following parameters: +- `action: IAction` - the object of the executed action containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("afterRedo", (action) => { + console.log("Action redone:", action.type); +}); + +@descr: + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`redo()`](grid/api/history/redo_method.md), [`beforeRedo()`](grid/api/history/beforeredo_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/afterundo_event.md b/docs/grid/api/history/afterundo_event.md new file mode 100644 index 00000000..56aebc37 --- /dev/null +++ b/docs/grid/api/history/afterundo_event.md @@ -0,0 +1,49 @@ +--- +sidebar_label: afterUndo +title: JavaScript Grid - afterUndo Event +description: You can explore the afterUndo event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterUndo + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered after successfully undoing an action + +@signature: {'afterUndo: (action: IAction) => void;'} + +@params: +The callback of the event is called with the following parameters: +- `action: IAction` - the object of the executed action containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("afterUndo", (action) => { + console.log("Action undone:", action.type); +}); + +@descr: + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`undo()`](grid/api/history/undo_method.md), [`beforeUndo()`](grid/api/history/beforeundo_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/beforeadd_event.md b/docs/grid/api/history/beforeadd_event.md new file mode 100644 index 00000000..b2b926b4 --- /dev/null +++ b/docs/grid/api/history/beforeadd_event.md @@ -0,0 +1,53 @@ +--- +sidebar_label: beforeAdd +title: JavaScript Grid - beforeAdd Event +description: You can explore the beforeAdd event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeAdd + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered before adding an action to the history + +@signature: {'beforeAdd: (action: IAction) => boolean | void;'} + +@params: +The callback of the event is called with the following parameters: +- `action: IAction` - the action object to be added containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@returns: +Returning `false` cancels the operation. + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("beforeAdd", (action) => { + if (action.type === "add") { + console.log("Adding a new row is prohibited"); + return false; + } +}); + +@descr: + +**Related article**: [Adding/removing Grid history actions](grid/usage_history.md/#addingremoving-grid-history-actions) + +**Related API**: [`add()`](grid/api/history/add_method.md), [`afterAdd()`](grid/api/history/afteradd_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/beforeredo_event.md b/docs/grid/api/history/beforeredo_event.md new file mode 100644 index 00000000..316373d5 --- /dev/null +++ b/docs/grid/api/history/beforeredo_event.md @@ -0,0 +1,53 @@ +--- +sidebar_label: beforeRedo +title: JavaScript Grid - beforeRedo Event +description: You can explore the beforeRedo event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeRedo + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered before redoing an action + +@signature: {'beforeRedo: (action: IAction) => boolean | void;'} + +@params: +The callback of the event is called with the following parameters: +- `action: IAction` - the action object from the redo stack containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@returns: +Returning `false` cancels the operation. + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("beforeRedo", (action) => { + if (action.type === "remove") { + console.log("Redoing removal is prohibited"); + return false; + } +}); + +@descr: + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`redo()`](grid/api/history/redo_method.md), [`afterRedo()`](grid/api/history/afterredo_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/beforeundo_event.md b/docs/grid/api/history/beforeundo_event.md new file mode 100644 index 00000000..f9d2060c --- /dev/null +++ b/docs/grid/api/history/beforeundo_event.md @@ -0,0 +1,53 @@ +--- +sidebar_label: beforeUndo +title: JavaScript Grid - beforeUndo Event +description: You can explore the beforeUndo event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeUndo + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered before undoing an action + +@signature: {'beforeUndo: (action: IAction) => boolean | void;'} + +@params: +The callback of the event is called with the following parameters: +- `action: IAction` - the action object containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@returns: +Returning `false` cancels the operation. + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("beforeUndo", (action) => { + if (action.type === "change") { + console.log("Undoing change is prohibited"); + return false; + } +}); + +@descr: + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`undo()`](grid/api/history/undo_method.md), [`afterUndo()`](grid/api/history/afterundo_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/canredo_method.md b/docs/grid/api/history/canredo_method.md new file mode 100644 index 00000000..4048c14c --- /dev/null +++ b/docs/grid/api/history/canredo_method.md @@ -0,0 +1,55 @@ +--- +sidebar_label: canRedo() +title: JavaScript Grid - canRedo Method +description: You can explore the canRedo method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# canRedo() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: checks whether an action within the Grid history can be redone + +@signature: {'canRedo(): boolean;'} + +@returns: Returns `true` if the redo stack contains actions and the module is not disabled. + +@example: +// The example shows checking whether redo is possible after undoing +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// modifying data +const updatedItem = { id: "1", name: "Updated Item", value: 15 }; +grid.data.update("1", updatedItem); +grid.history.add({ + type: "change", + batch: [{ ...updatedItem }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); + +// undoing and checking +grid.history.undo(); +if (grid.history.canRedo()) { + console.log("Redo is possible"); + grid.history.redo(); +} + +@descr: + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`redo()`](grid/api/history/redo_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/canundo_method.md b/docs/grid/api/history/canundo_method.md new file mode 100644 index 00000000..2b8a8d7b --- /dev/null +++ b/docs/grid/api/history/canundo_method.md @@ -0,0 +1,53 @@ +--- +sidebar_label: canUndo() +title: JavaScript Grid - canUndo Method +description: You can explore the canUndo method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# canUndo() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: checks whether an action within the Grid history can be undone + +@signature: {'canUndo(): boolean;'} + +@returns: Returns `true` if the history contains actions and the module is not disabled. + +@example: +// The example shows checking whether undo is possible after removing a row +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// removing a row +const removedItem = { id: "1", name: "Item 1", value: 10 }; +grid.data.remove("1"); +grid.history.add({ + type: "remove", + batch: [{ ...removedItem }], +}); + +// checking +if (grid.history.canUndo()) { + console.log("Undo is possible"); + grid.history.undo(); +} + +@descr: + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`undo()`](grid/api/history/undo_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/disable_method.md b/docs/grid/api/history/disable_method.md new file mode 100644 index 00000000..c849778b --- /dev/null +++ b/docs/grid/api/history/disable_method.md @@ -0,0 +1,55 @@ +--- +sidebar_label: disable() +title: JavaScript Grid - disable Method +description: You can explore the disable method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# disable() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: disables the module, preventing the addition of new actions to the Grid history and the execution of any operations + +@signature: {'disable(): void;'} + +@example: +// The example shows disabling the module after adding an action +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding an action +grid.history.add({ + type: "change", + batch: [{ id: "1", name: "Updated Item", value: 15 }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); + +// disabling the module +grid.history.disable(); +console.log(grid.history.isDisabled()); // -> true + +// attempting to add a new action +grid.history.add({ + type: "add", + batch: [{ id: "2", name: "New Item", value: 20 }], +}); +console.log(grid.history.getHistory().length); // -> 1 (the new action hasn't been added) + +@descr: + +**Related article**: [Enabling/disabling History module](grid/usage_history.md/#enablingdisabling-history-module) + +**Related API**: [`enable()`](grid/api/history/enable_method.md), [`isDisabled()`](grid/api/history/isdisabled_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/enable_method.md b/docs/grid/api/history/enable_method.md new file mode 100644 index 00000000..40ecdab5 --- /dev/null +++ b/docs/grid/api/history/enable_method.md @@ -0,0 +1,53 @@ +--- +sidebar_label: enable() +title: JavaScript Grid - enable Method +description: You can explore the enable method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# enable() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: enables the module, allowing the addition of new actions to the Grid history + +@signature: {'enable(): void;'} + +@example: +// The example shows how the module is enabled after deactivation on initialization +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + // disabled on initialization + history: { disabled: true } +}); + +// checking the state +console.log(grid.history.isDisabled()); // -> true + +// enabling the module +grid.history.enable(); +console.log(grid.history.isDisabled()); // -> false + +// adding an action +grid.history.add({ + type: "change", + batch: [{ id: "1", name: "Updated Item", value: 15 }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); +console.log(grid.history.getHistory().length); // -> 1 + +@descr: + +**Related article**: [Enabling/disabling History module](grid/usage_history.md/#enablingdisabling-history-module) + +**Related API**: [`disable()`](grid/api/history/disable_method.md), [`isDisabled()`](grid/api/history/isdisabled_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/error_event.md b/docs/grid/api/history/error_event.md new file mode 100644 index 00000000..b4c26745 --- /dev/null +++ b/docs/grid/api/history/error_event.md @@ -0,0 +1,51 @@ +--- +sidebar_label: error +title: JavaScript Grid - error Event +description: You can explore the error event of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# error + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: triggered when an error occurs + +:::note +The event is triggered when an error occurs, such as the module is disabled, the history is empty, the action type is invalid, or the inverse action is missing for the `undo` operation. +::: + +@signature: {'error: (error: string, action: IAction | null) => void;'} + +@params: +The callback of the event is called with the following parameters: +- `error` - the error message +- `action: IAction` - the action object associated with the error, or `null`. The `action` object contains the following properties: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.events.on("error", (error, action) => { + console.log("Error:", error, action); +}); + +@descr: + +**Related article**: [Work with History module](grid/usage_history.md) + + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/gethistory_method.md b/docs/grid/api/history/gethistory_method.md new file mode 100644 index 00000000..98b6f3fc --- /dev/null +++ b/docs/grid/api/history/gethistory_method.md @@ -0,0 +1,58 @@ +--- +sidebar_label: getHistory() +title: JavaScript Grid - getHistory Method +description: You can explore the getHistory method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# getHistory() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: returns a copy of the array of all actions in the Grid history to prevent accidental modification of the internal structure + +@signature: {'getHistory(): IAction[];'} + +@returns: +Returns a copy of the array of all actions in the history. Each `action` object may contain: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing + +@example: +// The example shows retrieving the history +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding actions +grid.history.add({ + type: "change", + batch: [{ id: "1", name: "Updated Item", value: 15 }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); +grid.history.add({ + type: "add", + batch: [{ id: "2", name: "New Item", value: 20 }], +}); + +// retrieving the history +const history = grid.history.getHistory(); +console.log(history.length); // -> 2 + +@descr: + +**Related article**: [Getting the history of Grid actions](grid/usage_history.md/#getting-the-history-of-grid-actions) + +**Related API**: [`add()`](grid/api/history/add_method.md), [`remove()`](grid/api/history/remove_method.md), [`removeAll()`](grid/api/history/removeall_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/isdisabled_method.md b/docs/grid/api/history/isdisabled_method.md new file mode 100644 index 00000000..dc6747e7 --- /dev/null +++ b/docs/grid/api/history/isdisabled_method.md @@ -0,0 +1,46 @@ +--- +sidebar_label: isDisabled() +title: JavaScript Grid - isDisabled Method +description: You can explore the isDisabled method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# isDisabled() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: returns the module's current state + +@signature: {'isDisabled(): boolean;'} + +@returns: +Returns `true` if the module is disabled. + +@example: +// The example shows checking the module's state after disabling it +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.disable(); +console.log(grid.history.isDisabled()); // -> true + +grid.history.enable(); +console.log(grid.history.isDisabled()); // -> false + +@descr: + +**Related article**: [Enabling/disabling History module](grid/usage_history.md/#enablingdisabling-history-module) + +**Related API**: [`enable()`](grid/api/history/enable_method.md), [`disable()`](grid/api/history/disable_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/redo_method.md b/docs/grid/api/history/redo_method.md new file mode 100644 index 00000000..8c86f165 --- /dev/null +++ b/docs/grid/api/history/redo_method.md @@ -0,0 +1,55 @@ +--- +sidebar_label: redo() +title: JavaScript Grid - redo Method +description: You can explore the redo method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# redo() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: reapplies the last undone action in the Grid history + +:::note +If the redo stack is empty or the module is disabled, the `error` event is triggered. +::: + +@signature: {'redo(): void;'} + +@example: +// The example shows redoing the undone row addition +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding a new row +const newItem = { id: "2", name: "New Item", value: 20 }; +grid.data.add(newItem); +grid.history.add({ + type: "add", + batch: [{ ...newItem }], +}); + +// undoing and redoing +grid.history.undo(); +grid.history.redo(); +console.log(grid.history.getHistory().length); // -> 1 +console.log(grid.history.canUndo()); // -> true + +@descr: + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`undo()`](grid/api/history/undo_method.md), [`canRedo()`](grid/api/history/canredo_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/remove_method.md b/docs/grid/api/history/remove_method.md new file mode 100644 index 00000000..cb0378ae --- /dev/null +++ b/docs/grid/api/history/remove_method.md @@ -0,0 +1,56 @@ +--- +sidebar_label: remove() +title: JavaScript Grid - remove Method +description: You can explore the remove method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# remove() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: removes the last action from the Grid history + +:::note +If the history is empty or the module is disabled, the operation is ignored, and the [`error`](grid/api/history/error_event.md) event is triggered (for a disabled module). +::: + +@signature: {'remove(): void;'} + +@example: +// The example shows removing the last action from the history after modifying a value +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// modifying a value via DataCollection +const updatedItem = { id: "1", name: "Updated Item", value: 15 }; +grid.data.update("1", updatedItem); + +// adding the action to history +grid.history.add({ + type: "change", + batch: [{ ...updatedItem }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); + +// removing the last action +grid.history.remove(); +console.log(grid.history.getHistory().length); // -> 0 + +@descr: + +**Related article**: [Adding/removing Grid history actions](grid/usage_history.md/#addingremoving-grid-history-actions) + +**Related API**: [`add()`](grid/api/history/add_method.md), [`removeAll()`](grid/api/history/removeall_method.md), [`getHistory()`](grid/api/history/gethistory_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/removeall_method.md b/docs/grid/api/history/removeall_method.md new file mode 100644 index 00000000..2e967aa9 --- /dev/null +++ b/docs/grid/api/history/removeall_method.md @@ -0,0 +1,56 @@ +--- +sidebar_label: removeAll() +title: JavaScript Grid - removeAll Method +description: You can explore the removeAll method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# removeAll() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: clears the entire Grid history and the redo stack + +:::note +If the module is disabled, the operation is ignored, and the [`error`](grid/api/history/error_event.md) event is triggered. +::: + +@signature: {'removeAll(): void;'} + +@example: +// The example shows clearing the history after adding multiple rows +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding two actions +grid.history.add({ + type: "add", + batch: [{ id: "2", name: "New Item 1", value: 20 }], +}); +grid.history.add({ + type: "add", + batch: [{ id: "3", name: "New Item 2", value: 30 }], +}); + +// clearing the history +grid.history.removeAll(); +console.log(grid.history.getHistory().length); // -> 0 +console.log(grid.history.canRedo()); // -> false + +@descr: + +**Related article**: [Adding/removing Grid history actions](grid/usage_history.md/#addingremoving-grid-history-actions) + +**Related API**: [`add()`](grid/api/history/add_method.md), [`remove()`](grid/api/history/remove_method.md), [`getHistory()`](grid/api/history/gethistory_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/history/undo_method.md b/docs/grid/api/history/undo_method.md new file mode 100644 index 00000000..876157cb --- /dev/null +++ b/docs/grid/api/history/undo_method.md @@ -0,0 +1,58 @@ +--- +sidebar_label: undo() +title: JavaScript Grid - undo Method +description: You can explore the undo method of Grid history in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# undo() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: undoes the last action in the Grid history + +Depending on the type of the action, the method either applies the inverse action (for the "change" and "removeAll" types) or restores data (for the "add" and "remove" types). + +:::note +If the history is empty, the module is disabled, or no inverse action is available (for actions with the "change" and "removeAll" types), the [`error`](grid/api/history/error_event.md) event is triggered. +::: + +@signature: {'undo(): void;'} + +@example: +// The example shows undoing the removal of all rows +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + { id: "2", name: "Item 2", value: 20 }, + ], + history: true +}); + +// removing all rows +const removedData = grid.data.serialize(); +grid.data.removeAll(); +grid.history.add({ + type: "removeAll", + batch: [], + inverse: { type: "add", batch: removedData }, +}); + +// undoing the action +grid.history.undo(); +console.log(grid.history.getHistory().length); // -> 0 +console.log(grid.history.canRedo()); // -> true + +@descr: + +**Related article**: [Applying undo/redo operations to Grid history actions](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) + +**Related API**: [`redo()`](grid/api/history/redo_method.md), [`canUndo()`](grid/api/history/canundo_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/afterresetrange_event.md b/docs/grid/api/rangeselection/afterresetrange_event.md new file mode 100644 index 00000000..ed7b5de9 --- /dev/null +++ b/docs/grid/api/rangeselection/afterresetrange_event.md @@ -0,0 +1,62 @@ +--- +sidebar_label: afterResetRange +title: JavaScript Grid - afterResetRange Event +description: You can explore the afterResetRange event of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterResetRange + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires after a range has been successfully reset + +### Usage + +~~~jsx +afterResetRange: ( + range: { + xStart: string | number; + xEnd: string | number; + yStart: string | number; + yEnd: string | number; + } +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + +
range(object) the object with the reset range coordinates that contains the following options:
  • `xStart` - (string | number) the starting column id
  • `xEnd` - (string | number) the ending column id
  • `yStart` - (string | number) the starting row id
  • `yEnd` - (string | number) the ending row id
+ +@example: +const grid = new dhx.Grid("grid_container", { + // other configuration + rangeSelection: true +}); + +grid.range.events.on("afterResetRange", (range) => { + console.log("The range is reset, the previous range is:", range); +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.resetRange(); // logs the previous range + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md), +[`resetRange()`](grid/api/rangeselection/resetrange_method.md), +[`beforeResetRange`](grid/api/rangeselection/beforeresetrange_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/aftersetrange_event.md b/docs/grid/api/rangeselection/aftersetrange_event.md new file mode 100644 index 00000000..cbc0d81b --- /dev/null +++ b/docs/grid/api/rangeselection/aftersetrange_event.md @@ -0,0 +1,60 @@ +--- +sidebar_label: afterSetRange +title: JavaScript Grid - afterSetRange Event +description: You can explore the afterSetRange event of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# afterSetRange + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires after a range has been successfully set + +### Usage + +~~~jsx +afterSetRange: ( + range: { + xStart: string | number; + xEnd: string | number; + yStart: string | number; + yEnd: string | number; + } +) => void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + +
range(object) the object with the set range coordinates that contains the following options:
  • `xStart` - (string | number) the starting column id
  • `xEnd` - (string | number) the ending column id
  • `yStart` - (string | number) the starting row id
  • `yEnd` - (string | number) the ending row id
+ +@example: +const grid = new dhx.Grid("grid_container", { + // other configuration + rangeSelection: true +}); + +grid.range.events.on("afterSetRange", (range) => { + console.log("The range is set:", range); +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); // logs the range object + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md), +[`beforeSetRange`](grid/api/rangeselection/beforesetrange_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/beforeresetrange_event.md b/docs/grid/api/rangeselection/beforeresetrange_event.md new file mode 100644 index 00000000..b1ecb2dd --- /dev/null +++ b/docs/grid/api/rangeselection/beforeresetrange_event.md @@ -0,0 +1,66 @@ +--- +sidebar_label: beforeResetRange +title: JavaScript Grid - beforeResetRange Event +description: You can explore the beforeResetRange event of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeResetRange + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires before resetting the range + +### Usage + +~~~jsx +beforeResetRange: ( + range: { + xStart: string | number; + xEnd: string | number; + yStart: string | number; + yEnd: string | number; + } +) => boolean | void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + +
range(object) an object with the range coordinates that contains the following options:
  • `xStart` - (string | number) the starting column id
  • `xEnd` - (string | number) the ending column id
  • `yStart` - (string | number) the starting row id
  • `yEnd` - (string | number) the ending row id
+ +@returns: +Return `false` to prevent resetting of the range; otherwise, `true`. + +@example: +const grid = new dhx.Grid("grid_container", { + // other configuration + rangeSelection: true +}); + +grid.range.events.on("beforeResetRange", (range) => { + console.log("Resetting the range:", range); + return false; // cancels resetting of the range +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.resetRange(); // resetting of the range is canceled + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md), +[`resetRange()`](grid/api/rangeselection/resetrange_method.md), +[`afterResetRange`](grid/api/rangeselection/afterresetrange_event.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/beforesetrange_event.md b/docs/grid/api/rangeselection/beforesetrange_event.md new file mode 100644 index 00000000..ed362d0b --- /dev/null +++ b/docs/grid/api/rangeselection/beforesetrange_event.md @@ -0,0 +1,68 @@ +--- +sidebar_label: beforeSetRange +title: JavaScript Grid - beforeSetRange Event +description: You can explore the beforeSetRange event of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# beforeSetRange + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: fires before setting a new range + +### Usage + +~~~jsx +beforeSetRange: ( + range: { + xStart: string | number; + xEnd: string | number; + yStart: string | number; + yEnd: string | number; + } +) => boolean | void; +~~~ + +@params: +The callback of the event is called with the following parameters: + + + + + + + + +
range(object) an object with the range coordinates that contains the following options:
  • `xStart` - (string | number) the starting column id
  • `xEnd` - (string | number) the ending column id
  • `yStart` - (string | number) the starting row id
  • `yEnd` - (string | number) the ending row id
+ +@returns: +Return `false` to prevent setting a range; otherwise, `true`. + +@example: +const grid = new dhx.Grid("grid_container", { + // other configuration + rangeSelection: true +}); + +grid.range.events.on("beforeSetRange", (range) => { + if (range.xStart === "b") { + console.log("Range can't start with the column B"); + return false; // cancels setting a range + } +}); + +grid.range.setRange({ xStart: "b", yStart: "1" }); // setting a new range is canceled + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md), +[`afterSetRange`](grid/api/rangeselection/aftersetrange_event.md) + +**Related sample**: [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/disable_method.md b/docs/grid/api/rangeselection/disable_method.md new file mode 100644 index 00000000..2fef90bb --- /dev/null +++ b/docs/grid/api/rangeselection/disable_method.md @@ -0,0 +1,49 @@ +--- +sidebar_label: disable() +title: JavaScript Grid - disable Method +description: You can explore the disable method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# disable() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: disables the RangeSelection module and resets the current range in Grid + +### Usage + +~~~jsx +disable(): void; +~~~ + +@example: +// this example shows disabling of the module +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.disable(); // disabling the module +console.log(grid.range.getRange()); // -> null +grid.range.setRange({ xStart: "a", yStart: "1" }); // the range won't be set + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`enable()`](grid/api/rangeselection/enable_method.md), [`getRange()`](grid/api/rangeselection/getrange_method.md), +[`setRange()`](grid/api/rangeselection/setrange_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/enable_method.md b/docs/grid/api/rangeselection/enable_method.md new file mode 100644 index 00000000..3ddaeb2e --- /dev/null +++ b/docs/grid/api/rangeselection/enable_method.md @@ -0,0 +1,47 @@ +--- +sidebar_label: enable() +title: JavaScript Grid - enable Method +description: You can explore the enable method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# enable() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: enables the RangeSelection module and activates the capabilities of range selection in Grid + +### Usage + +~~~jsx +enable(): void; +~~~ + +@example: +// this example shows enabling the module after deactivation +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: { disabled: true } // disabled on initialization +}); + +grid.range.enable(); // activating the module +grid.range.setRange({ xStart: "a", yStart: "1" }); // the range will be set + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`disable()`](grid/api/rangeselection/disable_method.md), [`getRange()`](grid/api/rangeselection/getrange_method.md), +[`setRange()`](grid/api/rangeselection/setrange_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/getrange_method.md b/docs/grid/api/rangeselection/getrange_method.md new file mode 100644 index 00000000..f64a307c --- /dev/null +++ b/docs/grid/api/rangeselection/getrange_method.md @@ -0,0 +1,78 @@ +--- +sidebar_label: getRange() +title: JavaScript Grid - getRange Method +description: You can explore the getRange method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# getRange() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: returns the current selection range + +### Usage + +~~~jsx +getRange(): + | null + | { + xStart?: string | number; + xEnd?: string | number; + yStart?: string | number; + yEnd?: string | number; + }; +~~~ + +@returns: +- an object with the current selection range, where: + + + + + + + + + + + + + + + + + + + +
xStart(string | number) the starting column id
xEnd(string | number) the ending column id
yStart(string | number) the starting row id
yEnd(string | number) the ending row id
+- `null` if no range is set + +@example: +// this example shows retrieving of the current range +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1", xEnd: "b", yEnd: "2" }); +console.log(grid.range.getRange()); // -> { xStart: "a", xEnd: "b", yStart: "1", yEnd: "2" } + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md) + + +@changelog: +added in v9.2 diff --git a/docs/grid/api/rangeselection/getrangedcells_method.md b/docs/grid/api/rangeselection/getrangedcells_method.md new file mode 100644 index 00000000..cff88c5e --- /dev/null +++ b/docs/grid/api/rangeselection/getrangedcells_method.md @@ -0,0 +1,60 @@ +--- +sidebar_label: getRangedCells() +title: JavaScript Grid - getRangedCells Method +description: You can explore the getRangedCells method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# getRangedCells() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: returns an array of cells within the current range + +### Usage + +~~~jsx +getRangedCells(): { row: object; column: object; }[]; +~~~ + +@returns: +- an array of objects where: + + + + + + + + + + + +
row(object) the row object
column(object) the column object
+ +@example: +// this example shows retrieving of the range of selected cells +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1", xEnd: "b", yEnd: "1" }); +console.log(grid.range.getRangedCells()); // -> [{ row: { id: "1", ... }, column: { id: "a", ... }}, ...] + +@descr: +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md) + +@changelog: +added in v9.2 diff --git a/docs/grid/api/rangeselection/isdisabled_method.md b/docs/grid/api/rangeselection/isdisabled_method.md new file mode 100644 index 00000000..c489d71d --- /dev/null +++ b/docs/grid/api/rangeselection/isdisabled_method.md @@ -0,0 +1,51 @@ +--- +sidebar_label: isDisabled() +title: JavaScript Grid - isDisabled Method +description: You can explore the isDisabled method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# isDisabled() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: returns the module's current state + +### Usage + +~~~jsx +isDisabled(): boolean; +~~~ + +@returns: +`true` if the module is disabled, `false` if the module is enabled + +@example: +// this example shows checking the module's activity status +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.disable(); +console.log(grid.range.isDisabled()); // -> true +grid.range.enable(); +console.log(grid.range.isDisabled()); // -> false + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`enable()`](grid/api/rangeselection/enable_method.md), [`disable()`](grid/api/rangeselection/disable_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/isranged_method.md b/docs/grid/api/rangeselection/isranged_method.md new file mode 100644 index 00000000..b6c955da --- /dev/null +++ b/docs/grid/api/rangeselection/isranged_method.md @@ -0,0 +1,65 @@ +--- +sidebar_label: isRanged() +title: JavaScript Grid - isRanged Method +description: You can explore the isRanged method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# isRanged() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: checks whether a cell is within the current range + +### Usage + +~~~jsx +isRanged(cell: { x: string | number; y: string | number }): boolean; +~~~ + +@params: + + + + + + + +
cell(object) - an object with the `x` and `y` coordinates of a cell, where:
  • `x` - (*string | number*) - the column id
  • `y` - (*string | number*) - the row id
+ +:::note +You can specify just `x` or `y` to check a column or a row, correspondingly. +::: + +@returns: +`true`, if the cell is within the current range, `false` otherwise + +@example: +// this example shows checking whether an ID belongs to the selected range of cells +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1", xEnd: "b", yEnd: "2" }); +console.log(grid.range.isRanged({ x: "a", y: "1" })); // -> true +console.log(grid.range.isRanged({ x: "a" })); // -> true +console.log(grid.range.isRanged({ y: "3" })); // -> false + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`setRange()`](grid/api/rangeselection/setrange_method.md) + +@changelog: +added in v9.2 diff --git a/docs/grid/api/rangeselection/resetrange_method.md b/docs/grid/api/rangeselection/resetrange_method.md new file mode 100644 index 00000000..4a348809 --- /dev/null +++ b/docs/grid/api/rangeselection/resetrange_method.md @@ -0,0 +1,51 @@ +--- +sidebar_label: resetRange() +title: JavaScript Grid - resetRange Method +description: You can explore the resetRange method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# resetRange() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: resets the current selection range + +### Usage + +~~~jsx +resetRange(): boolean; +~~~ + +@returns: +`true` - on success, `false` if the module is disabled, or if reset is canceled by an event. + + +@example: +// this example shows resetting of the current range +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.resetRange(); +console.log(grid.range.getRange()); // -> null + +@descr: + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`getRange()`](grid/api/rangeselection/getrange_method.md), [`setRange()`](grid/api/rangeselection/setrange_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/rangeselection/setrange_method.md b/docs/grid/api/rangeselection/setrange_method.md new file mode 100644 index 00000000..3ad4e8c4 --- /dev/null +++ b/docs/grid/api/rangeselection/setrange_method.md @@ -0,0 +1,101 @@ +--- +sidebar_label: setRange() +title: JavaScript Grid - setRange Method +description: You can explore the setRange method of Grid range selection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# setRange() + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +@short: sets the selection range + +### Usage + +~~~jsx +setRange( + range: { + xStart?: string | number; + xEnd?: string | number; + yStart?: string | number; + yEnd?: string | number; + }, + join?: boolean +): boolean; +~~~ + +@params: + + + + + + + + + + + +
range(object) an object with the range coordinates that contains the following options:
  • `xStart` - (string | number) the starting column id
  • `xEnd` - (string | number) the ending column id
  • `yStart` - (string | number) the starting row id
  • `yEnd` - (string | number) the ending row id
join(boolean) defines whether a new range is merged with the current one: +
  • if `join: true` is set, the method merges the new range with the current one. In this case, you can specify just the ending ids of the range, while the starting ids are optional
  • if the `join: false` setting is specified, the method resets the previous range
+ +:::note +If not all coordinates are provided, the missing ones are automatically filled (e.g., the last visible column for `xEnd`). The starting id for at least one coordinate is required. +::: + +@returns: +`true` - on success, `false` - on error, event cancellation, or if the module is disabled. + +@descr: +### Example + +~~~jsx +// this example shows setting of a range with omitted ending coordinates +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); // sets range from "a1" to the end +console.log(grid.range.getRange()); // -> { xStart: "a", xEnd: "b", yStart: "1", yEnd: "2" } +~~~ + +~~~jsx +// this example demonstrates merging of a range +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.setRange({ xEnd: "b", yEnd: "2" }, true); // merges with the current range +console.log(grid.range.getRange()); // -> { xStart: "a", xEnd: "b", yStart: "1", yEnd: "2" } +~~~ + +**Related article**: [Work with Range Selection object](grid/usage_rangeselection.md) + +**Related API**: [`getRange()`](grid/api/rangeselection/getrange_method.md), +[`resetRange()`](grid/api/rangeselection/resetrange_method.md) + +**Related sample**: [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/selection/selection_isselectedcell_method.md b/docs/grid/api/selection/selection_isselectedcell_method.md new file mode 100644 index 00000000..9ea1caff --- /dev/null +++ b/docs/grid/api/selection/selection_isselectedcell_method.md @@ -0,0 +1,44 @@ +--- +sidebar_label: isSelectedCell() +title: JavaScript Grid - isSelectedCell Method +description: You can explore the isSelectedCell method of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# isSelectedCell() + +@short: checks whether the cell with the specified row and column parameters is selected + +@signature: {'isSelectedCell(row: IRow | Id, column?: ICol | Id): boolean;'} + +@params: +- `row: IRow | Id` - an object with a cell to be checked or the id of a row +- `column: ICol | Id` - the config of a column or its id + +@returns: +Returns `true` if the cell is selected, otherwise `false` + +@example: +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + selection:"cell", + multiselection: false, + data: dataset +}); + +const row = grid.data.getItem(grid.data.getId(0)); +const column = grid.getColumn("project"); +grid.selection.setCell(row,column); + +const selectedCell = grid.selection.isSelectedCell(row,column); +console.log(selectedCell); // -> true + +@descr: + +**Related article**: [Selection](grid/usage_selection.md) + +**Related API**: [`setCell()`](grid/api/selection/selection_setcell_method.md) + +@changelog: +added in v9.2 \ No newline at end of file diff --git a/docs/grid/api/selection/selection_setcell_method.md b/docs/grid/api/selection/selection_setcell_method.md index ba8fcb2e..c6925fd2 100644 --- a/docs/grid/api/selection/selection_setcell_method.md +++ b/docs/grid/api/selection/selection_setcell_method.md @@ -13,8 +13,8 @@ description: You can explore the setCell method of Grid in the documentation of @params: - `row: object | string | number` - an object with a cell to be selected or the id of a row - `column: object | string | number` - the config of a column or its id -- `ctrlUp: boolean` - *true* - to select the desired rows or cells, otherwise - *false* (for multiselection mode) -- `shiftUp: boolean` - *true* - to select a range of rows or cells, otherwise - *false* (for multiselection mode) +- `ctrlUp: boolean` - *true* - to select the desired rows or cells, otherwise - *false* (for the `multiselection` mode) +- `shiftUp: boolean` - *true* - to select a range of rows or cells, otherwise - *false* (for the `multiselection` mode) @example: const grid = new dhx.Grid("grid_container", { @@ -32,10 +32,12 @@ grid.selection.setCell(row, column); @descr: -{{note For details about how to set selection to multiple cells/rows, see [Setting selection to cells](grid/usage_selection.md#setting-selection-to-cells).}} +:::note +For details about how to set selection to multiple cells/rows, see [Setting selection to cells](grid/usage_selection.md#setting-selection-to-cells). +::: **Related sample**: [Grid. Multiselection](https://snippet.dhtmlx.com/4nj0e9ye) -[comment]: # (@related: grid/usage_selection.md) +**Related article**: [Selection](grid/usage_selection.md) -[comment]: # (@relatedapi: grid/api/selection/selection_enable_method.md grid/api/selection/selection_removecell_method.md) +**Related API**: [`enable()`](grid/api/selection/selection_enable_method.md), [`removeCell()`](grid/api/selection/selection_removecell_method.md) diff --git a/docs/grid/configuration.md b/docs/grid/configuration.md index b3cb274c..82e9a61f 100644 --- a/docs/grid/configuration.md +++ b/docs/grid/configuration.md @@ -804,6 +804,10 @@ const grid = new dhx.Grid("grid_container", { }); ~~~ +:::info +Note that on scrolling the grid the cell editor will be closed only when the cell is not in the visible area of the table anymore. +::: + ### Types of column editor You can specify the way of editing the cells of a Grid column depending on its content as a simple input, a date picker, a textarea control, a checkbox, a select, a multiselect or a combobox. The type of the used editor can be defined either by the `editorType` property of a [column](grid/api/grid_columns_config.md) or via the `type` one. @@ -1628,1180 +1632,1632 @@ const grid = new dhx.Grid("grid_container", { **Related sample**: [Grid. Frozen columns and rows](https://snippet.dhtmlx.com/hcgl9nth) -## Row expander +## Spans -The row expander functionality allows using nested content in Grid sub-rows. You can add a Grid or any other Suite widget, as well as some HTML content into a sub-row. +The Grid component has the [`spans`](grid/api/grid_spans_config.md) property that allows you to specify all necessary columns and rows spans right through the initial configuration. It represents an array with spans objects. -:::tip Pro version only -This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. -::: +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + spans: [ + {row:"0", column:"a", rowspan:5 }, + {row:"0", column:"b", rowspan:9, text:"

Some content here

"}, + {row:"0", column:"c", colspan:2, text:"Some content"}, + {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"} + ], + data: dataset +}); +~~~ -![](../assets/grid/row_expander.png) +Each span object contains the following properties: -### Adding sub-rows +- `row` - (*string | number*) obligatory, the id of a row +- `column` - (*string|number*) obligatory, the id of a column +- `rowspan` - (*number*) optional, the number of rows in a span +- `colspan` - (*number*) optional, the number of columns in a span +- `text` - (*string|number*) optional, the content of a span. You can specify the text of the column span via the `text` property. It can be set either as a *string* or a *callback function* which is called with the following parameter: + - `content` - an object with the content of the span tooltip that contains the calculated values of the `summary` property, set as *key:value* pairs where: + - the *key* is either the key defined in the list or the functor name + - the *value* can be a *string*, *number* or *null* -In order to enable the row expander feature, you should use the [`subRow`](grid/api/grid_subrow_config.md) configuration option. It defines the content of sub-rows for each row of the Grid. The `subRow` property is a callback function which is called with the row object as a parameter and should return an HTML string or the constructor of a Suite component (Grid, Chart, Form, DataView, etc.). +The calculated values are taken from the [`summary`](grid/api/grid_summary_config.md) config option of the component and the [`summary`](grid/api/api_gridcolumn_properties.md) config option of a column. :::note -Note that when the `subRow` config is used, Grid doesn't support the [TreeGrid mode](grid/treegrid_mode.md) and the [data grouping](grid/usage.md#grouping-data) functionality. +In case key names in the `summary` configs are the same, values are taken from the column's configuration option. ::: -Check the example of using a sub-row with an HTML content: +:::info important +If the value of a spanned cell is initialized with the `text` property set as a *callback function*, the cell content can't be edited. +::: -~~~jsx {8-10} +~~~jsx {17} const grid = new dhx.Grid("grid_container", { columns: [ - { id: "zone_name", header: [{ text: "Zone name" }] }, - { id: "temperature", header: [{ text: "Temperature" }] }, - { id: "status", header: [{ text: "Status" }] }, + { width: 200, id: "country", header: [{ text: "Country" }] }, + { + width: 150, + id: "population", + header: [{ text: "Population" }], + summary: "count" + } ], - data: dataset, - subRow: ({ zone_name }) => { - return `
Details for ${zone_name}
`; - }, + summary: { totalPopulation: ["population", "sum"] }, + spans: [ + { + row: "rowid", + column: "population", + rowspan: 9, + text: ({ count }) => ("Count population:" + count) + }, + ], + data: dataset }); ~~~ -**Related sample:** [Grid. Row expander. Custom HTML and hiding toggle icon](https://snippet.dhtmlx.com/pvgyd3z9) - -In the example below a sub-row contains a subgrid: +- `css` - (*string*) optional, the name of a CSS class applied to a span +- [`tooltip`](#column-and-spans-tooltips) - (*boolean|object*) optional, enables a tooltip on hovering over the content of a span, or sets the configuration object with the tooltip settings; *true* by default. When set as an object, the `tooltip` config can have the following properties: + - `force` - (optional) forces opening of a tooltip; if set to true, the `showDelay` and `hideDelay` settings are ignored, *false* by default + - `showDelay` - (optional) the time period that should pass before showing a tooltip, in ms + - `hideDelay` - (optional) the time period that should pass before hiding a tooltip, in ms + - `margin` - (optional) the margin between the node and tooltip + - `position` - (optional) the position of a tooltip: *"right"*, *"bottom"*, *"center"*, *"left"*, *"top"*; *"bottom"* by default + - `css` - (optional) the style of a tooltip box -~~~jsx {7-16} +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - { id: "zone_name", header: [{ text: "Zone name" }] }, - { id: "temperature", header: [{ text: "Temperature" }] }, + // columns config ], - data: dataset, - subRow: ({ data }) => { - return new dhx.Grid(null, { - columns: [ - { id: "animal_type", header: [{ text: "Animal type" }] }, - { id: "name", header: [{ text: "Name" }] }, - ], - data, - autoWidth: true, - }); - }, + spans: [ + {row:"0", column:"a", rowspan:5 }, + {row:"0", column:"b", rowspan:9, text:"

Some content here

"}, + {row:"0", column:"c", colspan:2, text:"Some content"}, + {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"} + ], + data: dataset }); ~~~ -**Related sample:** [Grid. Row expander. Full config](https://snippet.dhtmlx.com/xdw2037t) - -### Adjusting configuration of sub-rows +- [`tooltipTemplate`](#adding-templates-for-column-and-spans-tooltip) - (*function*) sets a template for the span tooltip. The value of the `tooltipTemplate` property is a callback function which is called with the following parameters: + - `content` - an object with the content of the span tooltip. Contains two properties which are available either from the component's or from the column's configuration: + - `value` - the value rendered in a cell, including the applied templates + - an object with the calculated values of the `summary` property, set as *key:value* pairs where: + - the *key* is either the key defined in the list or the functor name + - the *value* can be a *string*, *number* or *null* + - `span` - the object of the column span -You can define common configuration settings of all sub-rows or provide specific options for each sub-row via the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration property of Grid. +~~~jsx {17-18} +const grid = new dhx.Grid("grid_container", { + columns: [ + { width: 200, id: "country", header: [{ text: "Country" }] }, + { + width: 150, + id: "population", + header: [{ text: "Population" }], + summary: "count" + } + ], + summary: { totalPopulation: ["population", "sum"] }, + spans: [ + { + row: "rowid", + column: "population", + rowspan: 9, + text: "Some text", + tooltipTemplate: ({ value, count }) => (`value: ${value}; count: ${count}`), + }, + ], + data: dataset +}); +~~~ -This property can be used either as a callback function or as an object: +**Related sample**: [Grid. Grouped cells (spans)](https://snippet.dhtmlx.com/1775dwbl) -- when set as an *object*, the specified parameters are applied to all the rows -- when set as a *callback function*, it is called with the row object as a parameter and returns an object, which allows providing specific configuration for each particular row +**Note**, that if both the `spans` and [`leftSplit`](grid/api/grid_leftsplit_config.md) properties are set in the Grid config, the following rules will be applied: -The **subRowConfig** object may contain the following properties: +- All necessary columns or rows will be in a span if the `spans` property is set for the columns located within the frozen area. +- If the `spans` property is set for a number of columns or rows placed as in the frozen part as in the movable one, then the columns remained in the movable part only will be in a span. -- `expanded` - (*boolean*) defines whether a sub-row is expanded by default, *false* by default -- `preserve` - (*boolean*) saves the state of sub-rows when they are expanded/collapsed, hidden from the visible area, the data is updated, *false* by default -- `toggleIcon` - (*boolean*) enables the icon for sub-rows expanding/collapsing, *true* by default -- `height` - (*number*) the height of a sub-row in pixels, *200* by default -- `padding` - (*string|number*) the inner padding of a sub-row, *8* by default -- `css` - (*string*) user-defined CSS classes for a sub-row -- `fullWidth` - (*boolean*) defines whether a sub-row will take all the width of Grid, *false* by default +## Tooltip -:::info note -The `fullWidth` property works only if the `subRowConfig` property is initialized as an object. -::: +### Grid tooltips -The following example shows how to provide global configuration options for sub-rows: +The default configuration of Grid provides tooltips that are rendered when a user hovers over the content of a column's cell. All the tooltips can be controlled via the [](grid/api/grid_tooltip_config.md) configuration property of Grid. By default, the tooltips are enabled. You can disable them, by setting the config to *false*: -~~~jsx {7-11} +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - { id: "zone_name", header: [{ text: "Zone name" }] }, - { id: "temperature", header: [{ text: "Temperature" }] }, + //columns config ], data: dataset, - subRowConfig: { - height: 200, - padding: 8, - fullWidth: true, - }, - subRow: ({ zone_name }) => `
Details for ${zone_name}
`, + tooltip: false }); ~~~ -**Related sample:** [Grid. Row expander. Full config](https://snippet.dhtmlx.com/xdw2037t) +**Related sample**: [Grid. Hiding tooltips](https://snippet.dhtmlx.com/mq4t3t3w) -### Dynamic configuration of sub-rows +The `tooltip` configuration option can be set as an object with the following properties: -You can dynamically expand/collapse certain sub-rows or adjust their appearance (specify the size of a cell, provide particular styles for sub-rows, etc.) on initialization of Grid depending on some conditions, using the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration property of Grid set as a callback function. Check the example below: +- `force` - (optional) forces opening of a tooltip; if set to true, the `showDelay` and `hideDelay` settings are ignored, *false* by default +- `showDelay` - (optional) the time period that should pass before showing a tooltip, in ms +- `hideDelay` - (optional) the time period that should pass before hiding a tooltip, in ms +- `margin` - (optional) the margin between the node and tooltip +- `position` - (optional) the position of a tooltip: *"right"*, *"bottom"*, *"center"*, *"left"*, *"top"*; *"bottom"* by default +- `css` - (optional) the style of a tooltip box -~~~jsx {7-11} +~~~jsx {6-8} const grid = new dhx.Grid("grid_container", { columns: [ - { id: "zone_name", header: [{ text: "Zone name" }] }, - { id: "temperature", header: [{ text: "Temperature" }] }, + // columns config ], data: dataset, - subRowConfig: (row) => ({ - height: 200, - expanded: row.temperature > 30, - css: row.temperature > 30 ? "hot-zone" : "cool-zone", - }), - subRow: ({ zone_name }) => `
Details for ${zone_name}
`, + tooltip: { + force: true + } }); ~~~ -In the above example the sub-rows are dynamically configured depending on the value in the column with the "temperature" id. If the temperature value is more than 30, a sub-row will be expanded and gets the CSS "hot-zone" class (or "cool-zone", if the temperature value is less than 30). The height of an expanded sub-row cell will be 200px. - -#### Adding sub-rows for specific rows - -You can define which row a sub-row should be created for with the help of the `height` property of the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration option. If you don't want to create sub-rows for particular rows, specify the `height:0` setting in the `subRowConfig` property. +**Related sample**: [Grid. Tooltip config](https://snippet.dhtmlx.com/qpqnalyt) -:::note -The described functionality works only if the `subRowConfig` property is initialized as a callback function. -::: +It is also possible to control the header and footer tooltips, independently. There are the [`headerTooltip`](grid/api/grid_headertooltip_config.md) and [`footerTooltip`](grid/api/grid_footertooltip_config.md) Grid configuration properties, that you can use for this purpose: -~~~jsx {7-10} +~~~jsx {7-8} const grid = new dhx.Grid("grid_container", { columns: [ // columns config ], data: dataset, - autoWidth: true, - subRowConfig: (row) => ({ - height: row.data.length ? 250 : 0, - expanded: true - }), - subRow: (row) => new dhx.Grid(null, { - columns: [ - // columns config - ], - data: row.data - }), + tooltip: false, // Disable all tooltips + headerTooltip: true, // Enable all header tooltips + footerTooltip: true, // Enable all footer tooltips }); ~~~ -![](../assets/grid/subgrid_specific_rows.png) - -In the above example the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) config set as a callback function defines that sub-rows with the height 250px will be created for rows that have some data. For rows without data the `height:0` setting is specified, so sub-rows won't be created for these rows. - -**Related sample:** [Grid. Row expander. Subgrid only in specific rows](https://snippet.dhtmlx.com/03udbtmr) - -### Saving state of nested components or data in sub-rows - -You can save the state of the nested components or the data of sub-rows while updating data, scrolling or collapsing sub-rows by using the `preserve` property of the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration option of Grid. By default, sub-rows are destroyed when they are hidden (e.g. if a row leaves the visible area during scrolling) or collapsed, which leads to resetting of any changes made in the inner components. - -When the `preserve: true` setting is specified, sub-rows aren't destroyed when hidden or collapsed and their content is saved. It means that any change (such as sorting, data input or state change) is saved and the sub-row is restored in the same state when displayed again. - -:::info note -It's important to take into account that the `preserve: true` setting increases the size of the used memory, since the sub-rows data are kept in the memory even when they aren't displayed. -::: - -#### When using `preserve` is useful - -- When the data of sub-rows should be interactive. It means when a sub-row contains a form or any other component the content of which can be changed by a user and the changes shouldn't be reset -- For complex sub-rows with a state. For example, if a sub-row renders a component with a dynamic content and a complex user interface - -#### When `preserve` shouldn't be used +The `headerTooltip` and `footerTooltip` configs can be specified as objects the same as the main [`tooltip`](grid/configuration.md#grid-tooltips) config. -- When sub-rows are used just for rendering static information. If a sub-row presents a simple text or a static HTML, the use of `preserve` is not rational -- In case a large amount of data is used. If a grid has a lot of rows and sub-rows, using `preserve` may increase the size of the used memory, which will affect the performance +### Column and spans tooltips -In the example below the `preserve` config is used to save the context of the Form nested in a sub-row: +There is a possibility to enable/disable tooltips for separate columns or spans by using the `tooltip` option in the configuration object of the [`columns`](grid/configuration.md#columns) or [`spans`](grid/configuration.md#spans) accordingly: -~~~jsx {7-9} +~~~jsx {3,7,10} const grid = new dhx.Grid("grid_container", { columns: [ - { id: "name", header: [{ text: "Name" }] }, - { id: "age", header: [{ text: "Age" }] }, + { width: 200, id: "country", header: [{ text: "Country" }], tooltip: true }, + { width: 150, id: "population", header: [{ text: "Population" }] }, + ], + spans: [ + { row: "1", column: "country", rowspan: 5, tooltip: true }, ], data: dataset, - subRowConfig: { - preserve: true, // saves the state of sub-rows - }, - subRow: (row) => { - return new dhx.Form(null, { - rows: [ - { type: "input", name: "details", label: "Details", value: row.details }, - ], - }); - }, + tooltip: false }); ~~~ -### Loading data into a sub-row +The same as with the common Grid tooltips, column and span tooltips can be set as objects with the following properties: -You can dynamically load data into a sub-row using the `load()` method of [DataCollection](/data_collection/) or [TreeCollection](/tree_collection/), depending on the nested component: +- `force` - (optional) forces opening of a tooltip; if set to true, the `showDelay` and `hideDelay` settings are ignored, *false* by default +- `showDelay` - (optional) the time period that should pass before showing a tooltip, in ms +- `hideDelay` - (optional) the time period that should pass before hiding a tooltip, in ms +- `margin` - (optional) the margin between the node and tooltip; *8px* by default +- `position` - (optional) the position of a tooltip: *"right"*, *"bottom"*, *"center"*, *"left"*, *"top"*; *"bottom"* by default +- `css` - (optional) the style of a tooltip box -~~~jsx {16-18} +~~~jsx {3,7,10} const grid = new dhx.Grid("grid_container", { columns: [ - { id: "country", header: [{ text: "Country" }] }, - { id: "population", header: [{ text: "Population" }] }, + { width: 200, id: "country", header: [{ text: "Country" }], tooltip: { force: true } }, + { width: 150, id: "population", header: [{ text: "Population" }] }, + ], + spans: [ + { row: "1", column: "country", rowspan: 5, tooltip: { force: true } }, ], data: dataset, - subRowConfig: { height: 400 }, - subRow: () => { - const subGrid = new dhx.Grid(null, { - columns: [ - { id: "title", header: [{ text: "Title" }] }, - { id: "authors", header: [{ text: "Authors" }] }, - ], - }); - - subGrid.data.load("https://some/dataset.json").then(() => { - subGrid.selection.setCell(subGrid.data.getId(0)); - }); - - return subGrid; - }, + tooltip: false }); ~~~ -In the above example the `load()` method of [DataCollection](/data_collection/) is used for loading data into a nested Grid. - -**Related sample:** [Grid. Row expander. Subgrid data loading](https://snippet.dhtmlx.com/03ndqrqt) +#### Adding templates for column and spans tooltip -### Handling events +You can add a template for a column or spans tooltip. -#### Grid event handlers +- to set a template for a column tooltip use a function which takes 3 parameters: + - `value` - (required) the value of a cell + - `row` - (required) an object with all cells in a row + - `column` - (required) an object with the configuration of a column -If a sub-row initializes a nested component (any Suite component), the sub-component's events can be set in the [`subRow`](grid/api/grid_subrow_config.md) callback function. It allows specifying event handlers directly for the nested component: +Returning *false* from the function will block showing of the tooltip. -~~~jsx {16-18} +~~~jsx {6-8} const grid = new dhx.Grid("grid_container", { columns: [ - { width: 200, id: "zone_name", header: [{ text: "Zone Name" }] }, - { width: 150, id: "temperature", header: [{ text: "Temperature" }] }, + { + width: 200, id: "country", header: [{ text: "Country" }], align: "left", + htmlEnable: true, + tooltipTemplate: function (value, row, column) { + // the template logic + } + }, + { width: 150, id: "population", header: [{ text: "Population" }] }, + { width: 150, id: "yearlyChange", header: [{ text: "Yearly Change" }] }, + // more options ], - data: dataset, - subRow: ({ zone_name }) => { - const subGrid = new dhx.Grid(null, { - columns: [ - { id: "animal", header: [{ text: "Animal" }] }, - { id: "count", header: [{ text: "Count" }] }, - ], - data: zooMap[zone_name], - }); - - subGrid.events.on("cellClick", (row, column) => { - console.log(`${row} ${column}`); - }); - - return subGrid; - }, + data: dataset }); ~~~ -**Related sample:** [Grid. Row expander. Subgrid events handling](https://snippet.dhtmlx.com/3364si14) - -#### HTML template event handlers +You can [check an example of applying a template for a column tooltip](grid/customization.md#adding-template-to-tooltip). -To specify the event handlers for a sub-row with an HTML content, use the [`eventHandlers`](grid/api/grid_eventhandlers_config.md) configuration option of Grid: +- to set a template for a spans tooltip use the `tooltipTemplate` configuration property. The value of the `tooltipTemplate` property is a callback function which is called with the following parameters: + - `content` - an object with the content of the span tooltip. Contains two properties which are available either from the component's or from the column's configuration: + - `value` - the value rendered in a cell, including the applied templates + - an object with the calculated values of the `summary` property, set as *key:value* pairs where: + - the *key* is either the key defined in the list or the functor name + - the *value* can be a *string*, *number* or *null* + - `span` - the object of the column span -~~~jsx {13-20} +~~~jsx {18} const grid = new dhx.Grid("grid_container", { columns: [ - { width: 200, id: "name", header: [{ text: "Name" }] }, - { width: 150, id: "details", header: [{ text: "Details" }] }, + { width: 200, id: "country", header: [{ text: "Country" }] }, + { + width: 150, + id: "population", + header: [{ text: "Population" }], + summary: "count" + } ], - data: dataset, - subRow: (row) => ` -
-

Details for ${row.name}

- -
- `, - eventHandlers: { - onclick: { - // the button click event in a sub-row - subrow_button: (event, data) => { - console.log(`A button click in the row ${data.row.id}`); // subRow id - } + summary: { totalPopulation: ["population", "sum"] }, + spans: [ + { + row: "rowid", + column: "population", + rowspan: 9, + text: "Some text", + tooltipTemplate: ({ value, count }) => (`value: ${value}; count: ${count}`), }, - } + ], + data: dataset }); ~~~ -### Multi-level Grid nesting - -It is possible to create as many levels of nested subgrids, as necessary. - -![](../assets/grid/multi_level_nesting.png) - -To specify the structure of a multi-level Grid nesting, do the following: - -- create a Grid with columns and data -- in the Grid configuration specify the [`subRow`](grid/api/grid_subrow_config.md) option as a callback function, which: - - returns a nested Grid that contains the `subRow` config set as a callback function that may return: - - some Suite component - - HTML as string - - a subgrid instance for another nesting level (that contains the `subRow` config set as a callback function to return another subgrid, a Suite component, or HTML content) +#### Column header/footer tooltip -Check the example below: +The tooltip set for a column enables/disables all its tooltips. However, you can control the tooltips of the column header/footer separately, by specifying the `tooltip` property in the corresponding header/footer object inside the column: -~~~jsx {12,24,36} +~~~jsx {4} const grid = new dhx.Grid("grid_container", { columns: [ - { id: "col_1", header: [{ text: "Grid. Level 1" }] }, - { id: "col_2", header: [{ text: "Second Column" }] }, + // Enables a tooltip for the country title + { id: "country", header: [{ text: "Country", tooltip: true }] }, + { id: "population", header: [{ text: "Population" }] }, + // more columns ], data: dataset, - autoWidth: true, - subRowConfig: (row) => ({ - height: 300, - expanded: row.col_1 === "Row 1", - }), - subRow: ({ data }) => { - return new dhx.Grid(null, { - columns: [ - { id: "col_1", header: [{ text: "Grid. Level 2" }] }, - { id: "col_2", header: [{ text: "Second Column" }] }, - ], - data, - autoWidth: true, - subRowConfig: (row) => ({ - height: 300, - expanded: row.col_1 === "Row 1", - }), - subRow: ({ data }) => { - return new dhx.Grid(null, { - columns: [ - { id: "col_1", header: [{ text: "Grid. Level 3" }] }, - { id: "col_2", header: [{ text: "Second Column" }] }, - ], - data, - autoWidth: true, - subRowConfig: (row) => ({ - height: 300, - expanded: row.col_1 === "Row 1", - }), - subRow: () => (`Subrow. Level 4`), - }) - }, - }) - }, + tooltip: false, }); ~~~ -**Related sample:** [Grid. Row expander. Subgrid with rows expanded by criteria](https://snippet.dhtmlx.com/dih3z7cz) - -### Adjusting sub-row width - -You can adjust the sub-row width depending on the width of its parent Grid via the `fullWidth` property of the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration object. - -:::info note -The `fullWidth` property works only if the `subRowConfig` property is initialized as an object. -::: +What is more, you can specify a necessary template for the header/footer tooltip via the `tooltipTemplate` configuration property. The value of the `tooltipTemplate` property is a callback +function which is called with the following parameters: -If the `fullWidth: true` configuration option is specified, the sub-row width is the same as the full width of the Grid content, including the area outside the visible area borders (it means that the sub-row will be scrolled together with the horizontal scroll). By default, a sub-row takes just the width of the visible Grid area. +- `content` - an object with the content of the header/footer tooltip. Contains two properties which are available either from the component's or from the column's configuration: + - `value` - (*string*) the value rendered in a cell, including the applied templates + - an object with the calculated values of the `summary` property, set as *key:value* pairs where: + - the *key* is either the key defined in the list or the functor name + - the *value* can be a *string*, *number* or *null* +- `header/footer` - (*object*) the object of the column header/footer +- `column` - (*object*) the object of a column -Check the example below: +and returns a string with the tooltip template for the header/footer or *false* to disable a tooltip. -~~~jsx {12-14} +~~~jsx {9} const grid = new dhx.Grid("grid_container", { - width: 400, columns: [ - { id: "name", header: [{ text: "Name" }], width: 150 }, - { id: "value", header: [{ text: "Value" }], width: 150 }, - { id: "description", header: [{ text: "Description" }], width: 300 }, + { + width: 150, + id: "population", + header: [ + { + text: "Population", + tooltipTemplate: ({ totalPopulation, count }) => `Total: ${totalPopulation}, Count: ${ count }` + } + ], + summary: "count" + } + // more columns ], - data: dataset, - subRow: (row) => { - return `
Details for ${row.name}
`; - }, - subRowConfig: { - fullWidth: true, // makes the sub-row width equal to the Grid content width - }, -}); + summary: { totalPopulation: ["population", "sum"] }, + data: dataset ~~~ -In the above example: +**Related sample**: [Grid. Header/footer tooltip](https://snippet.dhtmlx.com/fgstf2mq) -- the width of the Grid container is set as 400px -- if the `fullWidth` config isn't enabled, the sub-row width will be equal to the Grid width (400px) -- the common width of all the columns is 600px, thus if the `fullWidth: true` setting is specified, the sub-row width will be equal to 600px +#### Tooltips for filters -### Getting sub-row config and content +You can provide a tooltip template for the header content of any type, which allows showing tooltips for filters. -You can get the configuration settings applied to a sub-row and the content inside it using the [`getSubRow()`](grid/api/grid_getsubrow_method.md) method. - -:::info -Note that the method works if a sub-row is in the visible area or if the `preserve:true` property is specified in the `subRowConfig` object of the sub-row. -::: +Check the example below: -The method takes as a parameter the id of a row and returns an object that includes the following properties: +~~~jsx {14,26} +const balanceTemplate = value => { + return value > 0 + ? `
⬆ $${value}
` + : `
⬇ $${value}
`; +}; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
css(string) user-defined CSS classes for a sub-row
element(HTMLElement | null) the parent container of the current sub-row
expanded(boolean) defines whether a sub-row is expanded by default, false by default
fullWidth(boolean) defines whether a sub-row will take all the width of Grid, false by default
height(number) the height of a sub-row in pixels, 200 by default
padding(string | number) the inner padding of a sub-row, 8 by default
preserve(boolean) saves the state of sub-rows while expanding/collapsing, disappearing from the visible area, data updating, false by default
toggleIcon(boolean) enables the icon for expanding/collapsing, true by default
view(string | object | null) that can be presented by:
  • a string, if the sub-row is set by the HTML content
  • an object instance to interact with, if a sub-row is an instance of a nested component (for example, Grid)
  • null, if the sub-row is unavailable (for example, it is hidden or placed outside the visible area and the `preserve` config is not specified)
+const grid = new dhx.Grid("grid_container", { + columns: [ + { + minWidth: 150, + id: "project", + header: [ + {text: "Project"}, + {content: "comboFilter", tooltipTemplate: () => "Select project"} + ], + footer: [{text: "Total"}], + resizable: true, + draggable: false + }, + { + width: 130, + id: "balance", + header: [{text: "Balance"}, {content: "inputFilter"}], + footer: [ + { + tooltipTemplate: balanceTemplate + }, + ], + template: balanceTemplate, + htmlEnable: true, + numberMask: { + prefix: "$" + } + }, + ], +}); +~~~ -## Drag-n-drop +## Row expander -The drag-n-drop functionality allows you to reorder one or several rows or columns inside the grid or between several grids. +The row expander functionality allows using nested content in Grid sub-rows. You can add a Grid or any other Suite widget, as well as some HTML content into a sub-row. :::tip Pro version only -If you use the GPL version of DHTMLX Grid (or DHTMLX Suite), you will be able to reorder only rows and only one by one. - -**Note**, to be able to drag-n-drop a column and (or) multiple rows, you need to use PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. ::: -### Drag-n-drop inside the grid +![](../assets/grid/row_expander.png) -It is possible to reorder a row or column of Grid by drag and drop. To enable the functionality, define the [`dragItem: "both"`](grid/api/grid_dragitem_config.md) property in the configuration object of Grid: +### Adding sub-rows -~~~jsx {5} +In order to enable the row expander feature, you should use the [`subRow`](grid/api/grid_subrow_config.md) configuration option. It defines the content of sub-rows for each row of the Grid. The `subRow` property is a callback function which is called with the row object as a parameter and should return an HTML string or the constructor of a Suite component (Grid, Chart, Form, DataView, etc.). + +:::note +Note that when the `subRow` config is used, Grid doesn't support the [TreeGrid mode](grid/treegrid_mode.md) and the [data grouping](grid/usage.md#grouping-data) functionality. +::: + +Check the example of using a sub-row with an HTML content: + +~~~jsx {8-10} const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { id: "zone_name", header: [{ text: "Zone name" }] }, + { id: "temperature", header: [{ text: "Temperature" }] }, + { id: "status", header: [{ text: "Status" }] }, ], - dragItem: "both", - data: dataset + data: dataset, + subRow: ({ zone_name }) => { + return `
Details for ${zone_name}
`; + }, }); ~~~ -**Related sample**: [Grid. Drag-n-drop](https://snippet.dhtmlx.com/zwc91d50) - -:::note -To activate the functionality for columns or rows separately, use `dragItem: "column"` or `dragItem: "row"` respectively. -::: +**Related sample:** [Grid. Row expander. Custom HTML and hiding toggle icon](https://snippet.dhtmlx.com/pvgyd3z9) -If needed, you can disable the drag-n-drop functionality for a separate column via the `draggable` configuration option of the column: +In the example below a sub-row contains a subgrid: -~~~jsx {5,8} +~~~jsx {7-16} const grid = new dhx.Grid("grid_container", { columns: [ - { width: 200, id: "country", header: [{ text: "Country" }]}, - { width: 150, id: "land", header: [{ text: "Land" }] }, - { width: 150, id: "density", header: [{ text: "Density" }], draggable: false } + { id: "zone_name", header: [{ text: "Zone name" }] }, + { id: "temperature", header: [{ text: "Temperature" }] }, ], data: dataset, - dragItem: "column", + subRow: ({ data }) => { + return new dhx.Grid(null, { + columns: [ + { id: "animal_type", header: [{ text: "Animal type" }] }, + { id: "name", header: [{ text: "Name" }] }, + ], + data, + autoWidth: true, + }); + }, }); ~~~ -:::tip -To make the process of work with drag and drop more flexible, you can apply the related drag-n-drop events of Grid for [columns](grid/api/api_overview.md#column-drag-and-drop) and [rows](grid/api/api_overview.md/#row-drag-and-drop). -::: +**Related sample:** [Grid. Row expander. Full config](https://snippet.dhtmlx.com/xdw2037t) -### Drag-n-drop between grids +### Adjusting configuration of sub-rows -DHTMLX Grid supports drag-n-drop of rows/columns between grids in several modes. To begin with, you should specify the [dragMode](grid/api/grid_dragmode_config.md) property in the configuration object of Grid. Then define which mode you need: +You can define common configuration settings of all sub-rows or provide specific options for each sub-row via the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration property of Grid. -- "target" - a grid takes a row/column from other grids, while its row/colmn can't be dragged out of it -- "source" - a grid allows dragging its row/column out and can't take a row/column from other grids -- "both" - a grid both takes a row/column from other grids and allows dragging its row/column out as well +This property can be used either as a callback function or as an object: -~~~jsx {7} -const grid = new dhx.Grid("grid_container", { +- when set as an *object*, the specified parameters are applied to all the rows +- when set as a *callback function*, it is called with the row object as a parameter and returns an object, which allows providing specific configuration for each particular row + +The **subRowConfig** object may contain the following properties: + +- `expanded` - (*boolean*) defines whether a sub-row is expanded by default, *false* by default +- `preserve` - (*boolean*) saves the state of sub-rows when they are expanded/collapsed, hidden from the visible area, the data is updated, *false* by default +- `toggleIcon` - (*boolean*) enables the icon for sub-rows expanding/collapsing, *true* by default +- `height` - (*number*) the height of a sub-row in pixels, *200* by default +- `padding` - (*string|number*) the inner padding of a sub-row, *8* by default +- `css` - (*string*) user-defined CSS classes for a sub-row +- `fullWidth` - (*boolean*) defines whether a sub-row will take all the width of Grid, *false* by default + +:::info note +The `fullWidth` property works only if the `subRowConfig` property is initialized as an object. +::: + +The following example shows how to provide global configuration options for sub-rows: + +~~~jsx {7-11} +const grid = new dhx.Grid("grid_container", { columns: [ - { id: "country", header: [{ text: "Country" }] }, - { id: "population", header: [{ text: "Population" }] } + { id: "zone_name", header: [{ text: "Zone name" }] }, + { id: "temperature", header: [{ text: "Temperature" }] }, ], data: dataset, - dragMode: "source", - // dragItem: "column" - allows reordering columns one by one + subRowConfig: { + height: 200, + padding: 8, + fullWidth: true, + }, + subRow: ({ zone_name }) => `
Details for ${zone_name}
`, }); ~~~ -**Related sample**: [Grid. Drag-n-drop between grids](https://snippet.dhtmlx.com/qx9a86ax) - -### Drag-n-drop of multiple rows +**Related sample:** [Grid. Row expander. Full config](https://snippet.dhtmlx.com/xdw2037t) -:::tip Pro version only -This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. -::: +### Dynamic configuration of sub-rows -To allow a user to drag-n-drop multiple rows at once, you need to enable [multiselection](#multiple-selection-of-grid-cells) of rows when configuring drag-n-drop. For example: +You can dynamically expand/collapse certain sub-rows or adjust their appearance (specify the size of a cell, provide particular styles for sub-rows, etc.) on initialization of Grid depending on some conditions, using the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration property of Grid set as a callback function. Check the example below: -~~~jsx -const grid = new dhx.Grid("grid", { +~~~jsx {7-11} +const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { id: "zone_name", header: [{ text: "Zone name" }] }, + { id: "temperature", header: [{ text: "Temperature" }] }, ], - data: data, - selection: "row", - //drag-n-drop rows inside the grid - multiselection: true, - dragItem: "both" // or dragItem: "row" + data: dataset, + subRowConfig: (row) => ({ + height: 200, + expanded: row.temperature > 30, + css: row.temperature > 30 ? "hot-zone" : "cool-zone", + }), + subRow: ({ zone_name }) => `
Details for ${zone_name}
`, }); ~~~ -**Related sample**: [Grid. Drag-n-drop](https://snippet.dhtmlx.com/zwc91d50) +In the above example the sub-rows are dynamically configured depending on the value in the column with the "temperature" id. If the temperature value is more than 30, a sub-row will be expanded and gets the CSS "hot-zone" class (or "cool-zone", if the temperature value is less than 30). The height of an expanded sub-row cell will be 200px. -or +#### Adding sub-rows for specific rows -~~~jsx -const grid = new dhx.Grid("grid", { +You can define which row a sub-row should be created for with the help of the `height` property of the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration option. If you don't want to create sub-rows for particular rows, specify the `height:0` setting in the `subRowConfig` property. + +:::note +The described functionality works only if the `subRowConfig` property is initialized as a callback function. +::: + +~~~jsx {7-10} +const grid = new dhx.Grid("grid_container", { columns: [ // columns config ], data: dataset, - selection: "row", - //drag-n-drop rows between grids - multiselection: true, - dragMode: "both" // or dragMode: "source" + autoWidth: true, + subRowConfig: (row) => ({ + height: row.data.length ? 250 : 0, + expanded: true + }), + subRow: (row) => new dhx.Grid(null, { + columns: [ + // columns config + ], + data: row.data + }), }); ~~~ -## Keyboard Navigation +![](../assets/grid/subgrid_specific_rows.png) -DHTMLX Grid provides the keyboard navigation that will help you manipulate your grid faster. +In the above example the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) config set as a callback function defines that sub-rows with the height 250px will be created for rows that have some data. For rows without data the `height:0` setting is specified, so sub-rows won't be created for these rows. -### Default shortcut keys +**Related sample:** [Grid. Row expander. Subgrid only in specific rows](https://snippet.dhtmlx.com/03udbtmr) -There are four navigation keys that Grid enables by default: +### Saving state of nested components or data in sub-rows - - - - - - - - - - - - - - - - - - - - - - - -
PageUpscroll Grid up to the height of the visible content (without change of the selected cell)
PageDownscroll Grid down to the height of the visible content (without change of the selected cell)
Homenavigate to the beginning of the Grid content (without change of the selected cell)
Endnavigate to the end of the Grid content (without change of the selected cell)
Ctrl+Enterexpands/collapses the parent item in the TreeGrid mode
+You can save the state of the nested components or the data of sub-rows while updating data, scrolling or collapsing sub-rows by using the `preserve` property of the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration option of Grid. By default, sub-rows are destroyed when they are hidden (e.g. if a row leaves the visible area during scrolling) or collapsed, which leads to resetting of any changes made in the inner components. -If you need to disable this functionality, set the [`keyNavigation`](grid/api/grid_keynavigation_config.md) property to *false*. +When the `preserve: true` setting is specified, sub-rows aren't destroyed when hidden or collapsed and their content is saved. It means that any change (such as sorting, data input or state change) is saved and the sub-row is restored in the same state when displayed again. -~~~jsx -const grid = new dhx.Grid("grid_container", { - columns: [ - // columns config - ], - data: dataset, - keyNavigation: false -}); -~~~ +:::info note +It's important to take into account that the `preserve: true` setting increases the size of the used memory, since the sub-rows data are kept in the memory even when they aren't displayed. +::: -**Related sample**: [Grid. Key navigation](https://snippet.dhtmlx.com/y9kdk0md) +#### When using `preserve` is useful -### Arrow shortcut keys +- When the data of sub-rows should be interactive. It means when a sub-row contains a form or any other component the content of which can be changed by a user and the changes shouldn't be reset +- For complex sub-rows with a state. For example, if a sub-row renders a component with a dynamic content and a complex user interface -In case you want to enable the arrow keys that allow moving the selection between cells, you need to specify the [`selection`](grid/api/grid_selection_config.md) property for Grid. +#### When `preserve` shouldn't be used -~~~jsx {6} +- When sub-rows are used just for rendering static information. If a sub-row presents a simple text or a static HTML, the use of `preserve` is not rational +- In case a large amount of data is used. If a grid has a lot of rows and sub-rows, using `preserve` may increase the size of the used memory, which will affect the performance + +In the example below the `preserve` config is used to save the context of the Form nested in a sub-row: + +~~~jsx {7-9} const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { id: "name", header: [{ text: "Name" }] }, + { id: "age", header: [{ text: "Age" }] }, ], data: dataset, - selection: "complex", - keyNavigation: true // true - by default + subRowConfig: { + preserve: true, // saves the state of sub-rows + }, + subRow: (row) => { + return new dhx.Form(null, { + rows: [ + { type: "input", name: "details", label: "Details", value: row.details }, + ], + }); + }, }); ~~~ -**Related sample**: [Grid. Key navigation](https://snippet.dhtmlx.com/y9kdk0md) - -The list of the arrow shortcut keys: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ArrowUpmove selection to the previous vertical cell
ArrowDownmove selection to the next vertical cell
ArrowLeftmove selection to the previous horizontal cell
ArrowRightmove selection to the next horizontal cell
Ctrl+ArrowUpmove selection to the first vertical cell
Ctrl+ArrowDownmove selection to the last vertical cell
Ctrl+ArrowLeft move selection to the first horizontal cell
Ctrl+ArrowRight move selection to the last horizontal cell
Tab move selection to the next horizontal cell or the first cell of the next row
Shit+Tab move selection to the previous horizontal cell or to the first cell of the previous row
- -The arrow shortcut keys listed below do not work when the `selection` property is set to *"complex"*. Use another mode (*"cell" or "row"*) in case you want to activate these navigation keys: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Shift+ArrowUpmove selection to the previous vertical cell with the change of the selected cells
Shift+ArrowDownmove selection to the next vertical cell with the change of the selected cells
Shift+ArrowLeftmove selection to the previous horizontal cell with the change of the selected cells
Shift+ArrowRightmove selection to the next horizontal cell with the change of the selected cells
Ctrl+Shift+ArrowUpmove selection to the first vertical cell with the change of the selected cells
Ctrl+Shift+ArrowDownmove selection to the last vertical cell with the change of the selected cells
Ctrl+Shift+ArrowLeftmove selection to the first horizontal cell with the change of the selected cells
Ctrl+Shift+ArrowRightmove selection to the last horizontal cell with the change of the selected cells
- -### Shortcut keys for editing +### Loading data into a sub-row -It is also possible to use shortcut keys for editing a cell in Grid by setting [`editable:true`](grid/api/grid_editable_config.md) property in the configuration object of Grid. +You can dynamically load data into a sub-row using the `load()` method of [DataCollection](/data_collection/) or [TreeCollection](/tree_collection/), depending on the nested component: -~~~jsx {7} +~~~jsx {16-18} const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { id: "country", header: [{ text: "Country" }] }, + { id: "population", header: [{ text: "Population" }] }, ], data: dataset, - selection: "complex", - editable: true, - keyNavigation: true // true - by default + subRowConfig: { height: 400 }, + subRow: () => { + const subGrid = new dhx.Grid(null, { + columns: [ + { id: "title", header: [{ text: "Title" }] }, + { id: "authors", header: [{ text: "Authors" }] }, + ], + }); + + subGrid.data.load("https://some/dataset.json").then(() => { + subGrid.selection.setCell(subGrid.data.getId(0)); + }); + + return subGrid; + }, }); ~~~ -**Related sample**: [Grid. Key navigation](https://snippet.dhtmlx.com/y9kdk0md) - -The list of the shortcut keys for editing: +In the above example the `load()` method of [DataCollection](/data_collection/) is used for loading data into a nested Grid. - - - - - - - - - - - -
Enteropen the editor in the selected cell. If the editor is currently opened - close the editor and save changes
Escapeclose the editor of the selected cell without saving
+**Related sample:** [Grid. Row expander. Subgrid data loading](https://snippet.dhtmlx.com/03ndqrqt) -## Selection +### Handling events -DHTMLX Grid includes the selection feature that allows highlighting Grid elements depending on the chosen mode. The [`selection`](grid/api/grid_selection_config.md) property enables selection in a grid. It can take three values: +#### Grid event handlers - - - - - - - - - - - - - - - -
rowto move selection between Grid rows
cellto move selection between Grid cells
complexto highlight both a selected cell and the row it belongs to
-
+If a sub-row initializes a nested component (any Suite component), the sub-component's events can be set in the [`subRow`](grid/api/grid_subrow_config.md) callback function. It allows specifying event handlers directly for the nested component: -~~~jsx +~~~jsx {16-18} const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { width: 200, id: "zone_name", header: [{ text: "Zone Name" }] }, + { width: 150, id: "temperature", header: [{ text: "Temperature" }] }, ], - selection: "complex", - data: dataset + data: dataset, + subRow: ({ zone_name }) => { + const subGrid = new dhx.Grid(null, { + columns: [ + { id: "animal", header: [{ text: "Animal" }] }, + { id: "count", header: [{ text: "Count" }] }, + ], + data: zooMap[zone_name], + }); + + subGrid.events.on("cellClick", (row, column) => { + console.log(`${row} ${column}`); + }); + + return subGrid; + }, }); ~~~ -**Related sample**: [Grid. Selection](https://snippet.dhtmlx.com/ad6roqsx) +**Related sample:** [Grid. Row expander. Subgrid events handling](https://snippet.dhtmlx.com/3364si14) -### Multiple selection of Grid cells +#### HTML template event handlers -While setting the [`selection`](grid/configuration.md#selection) property to *"row"*, *"cell"*, or *"complex"* value, you can enable the [](grid/api/grid_multiselection_config.md) property to allow a user to select multiple Grid elements: +To specify the event handlers for a sub-row with an HTML content, use the [`eventHandlers`](grid/api/grid_eventhandlers_config.md) configuration option of Grid: -~~~jsx +~~~jsx {13-20} const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { width: 200, id: "name", header: [{ text: "Name" }] }, + { width: 150, id: "details", header: [{ text: "Details" }] }, ], - multiselection: true, - selection: "row", - data: dataset + data: dataset, + subRow: (row) => ` +
+

Details for ${row.name}

+ +
+ `, + eventHandlers: { + onclick: { + // the button click event in a sub-row + subrow_button: (event, data) => { + console.log(`A button click in the row ${data.row.id}`); // subRow id + } + }, + } }); ~~~ -**Related sample**: [Grid. Multiselection](https://snippet.dhtmlx.com/4nj0e9ye) +### Multi-level Grid nesting -Since the `multiselection` configuration option is set to *true*, using the "Ctrl + Click" combination allows selecting the desired cells or rows. -A range of Grid cells/rows can be selected by clicking the first element to select and then, while holding down the Shift key, clicking the last element to select. +It is possible to create as many levels of nested subgrids, as necessary. -## Spans +![](../assets/grid/multi_level_nesting.png) -The Grid component has the [spans](grid/api/grid_spans_config.md) property that allows you to specify all necessary columns and rows spans right through the initial configuration. It represents an array with spans objects. +To specify the structure of a multi-level Grid nesting, do the following: -~~~jsx -const grid = new dhx.Grid("grid_container", { - columns: [ - // columns config - ], - spans: [ - {row:"0", column:"a", rowspan:5 }, - {row:"0", column:"b", rowspan:9, text:"

Some content here

"}, - {row:"0", column:"c", colspan:2, text:"Some content"}, - {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"} +- create a Grid with columns and data +- in the Grid configuration specify the [`subRow`](grid/api/grid_subrow_config.md) option as a callback function, which: + - returns a nested Grid that contains the `subRow` config set as a callback function that may return: + - some Suite component + - HTML as string + - a subgrid instance for another nesting level (that contains the `subRow` config set as a callback function to return another subgrid, a Suite component, or HTML content) + +Check the example below: + +~~~jsx {12,24,36} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "col_1", header: [{ text: "Grid. Level 1" }] }, + { id: "col_2", header: [{ text: "Second Column" }] }, ], - data: dataset + data: dataset, + autoWidth: true, + subRowConfig: (row) => ({ + height: 300, + expanded: row.col_1 === "Row 1", + }), + subRow: ({ data }) => { + return new dhx.Grid(null, { + columns: [ + { id: "col_1", header: [{ text: "Grid. Level 2" }] }, + { id: "col_2", header: [{ text: "Second Column" }] }, + ], + data, + autoWidth: true, + subRowConfig: (row) => ({ + height: 300, + expanded: row.col_1 === "Row 1", + }), + subRow: ({ data }) => { + return new dhx.Grid(null, { + columns: [ + { id: "col_1", header: [{ text: "Grid. Level 3" }] }, + { id: "col_2", header: [{ text: "Second Column" }] }, + ], + data, + autoWidth: true, + subRowConfig: (row) => ({ + height: 300, + expanded: row.col_1 === "Row 1", + }), + subRow: () => (`Subrow. Level 4`), + }) + }, + }) + }, }); ~~~ -Each span object contains the following properties: +**Related sample:** [Grid. Row expander. Subgrid with rows expanded by criteria](https://snippet.dhtmlx.com/dih3z7cz) -- `row` - (*string | number*) obligatory, the id of a row -- `column` - (*string|number*) obligatory, the id of a column -- `rowspan` - (*number*) optional, the number of rows in a span -- `colspan` - (*number*) optional, the number of columns in a span -- `text` - (*string|number*) optional, the content of a span. You can specify the text of the column span via the `text` property. It can be set either as a *string* or a *callback function* which is called with the following parameter: - - `content` - an object with the content of the span tooltip that contains the calculated values of the `summary` property, set as *key:value* pairs where: - - the *key* is either the key defined in the list or the functor name - - the *value* can be a *string*, *number* or *null* +### Adjusting sub-row width -The calculated values are taken from the [`summary`](grid/api/grid_summary_config.md) config option of the component and the [`summary`](grid/api/api_gridcolumn_properties.md) config option of a column. +You can adjust the sub-row width depending on the width of its parent Grid via the `fullWidth` property of the [`subRowConfig`](grid/api/grid_subrowconfig_config.md) configuration object. -:::note -In case key names in the `summary` configs are the same, values are taken from the column's configuration option. +:::info note +The `fullWidth` property works only if the `subRowConfig` property is initialized as an object. ::: -:::info important -If the value of a spanned cell is initialized with the `text` property set as a *callback function*, the cell content can't be edited. -::: +If the `fullWidth: true` configuration option is specified, the sub-row width is the same as the full width of the Grid content, including the area outside the visible area borders (it means that the sub-row will be scrolled together with the horizontal scroll). By default, a sub-row takes just the width of the visible Grid area. -~~~jsx {17} +Check the example below: + +~~~jsx {12-14} const grid = new dhx.Grid("grid_container", { + width: 400, columns: [ - { width: 200, id: "country", header: [{ text: "Country" }] }, - { - width: 150, - id: "population", - header: [{ text: "Population" }], - summary: "count" - } - ], - summary: { totalPopulation: ["population", "sum"] }, - spans: [ - { - row: "rowid", - column: "population", - rowspan: 9, - text: ({ count }) => ("Count population:" + count) - }, + { id: "name", header: [{ text: "Name" }], width: 150 }, + { id: "value", header: [{ text: "Value" }], width: 150 }, + { id: "description", header: [{ text: "Description" }], width: 300 }, ], - data: dataset + data: dataset, + subRow: (row) => { + return `
Details for ${row.name}
`; + }, + subRowConfig: { + fullWidth: true, // makes the sub-row width equal to the Grid content width + }, }); ~~~ -- `css` - (*string*) optional, the name of a CSS class applied to a span -- [`tooltip`](#column-and-spans-tooltips) - (*boolean|object*) optional, enables a tooltip on hovering over the content of a span, or sets the configuration object with the tooltip settings; *true* by default. When set as an object, the `tooltip` config can have the following properties: - - `force` - (optional) forces opening of a tooltip; if set to true, the `showDelay` and `hideDelay` settings are ignored, *false* by default - - `showDelay` - (optional) the time period that should pass before showing a tooltip, in ms - - `hideDelay` - (optional) the time period that should pass before hiding a tooltip, in ms - - `margin` - (optional) the margin between the node and tooltip - - `position` - (optional) the position of a tooltip: *"right"*, *"bottom"*, *"center"*, *"left"*, *"top"*; *"bottom"* by default - - `css` - (optional) the style of a tooltip box +In the above example: -~~~jsx -const grid = new dhx.Grid("grid_container", { - columns: [ - // columns config - ], - spans: [ - {row:"0", column:"a", rowspan:5 }, - {row:"0", column:"b", rowspan:9, text:"

Some content here

"}, - {row:"0", column:"c", colspan:2, text:"Some content"}, - {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"} - ], - data: dataset -}); -~~~ +- the width of the Grid container is set as 400px +- if the `fullWidth` config isn't enabled, the sub-row width will be equal to the Grid width (400px) +- the common width of all the columns is 600px, thus if the `fullWidth: true` setting is specified, the sub-row width will be equal to 600px -- [`tooltipTemplate`](#adding-templates-for-column-and-spans-tooltip) - (*function*) sets a template for the span tooltip. The value of the `tooltipTemplate` property is a callback function which is called with the following parameters: - - `content` - an object with the content of the span tooltip. Contains two properties which are available either from the component's or from the column's configuration: - - `value` - the value rendered in a cell, including the applied templates - - an object with the calculated values of the `summary` property, set as *key:value* pairs where: - - the *key* is either the key defined in the list or the functor name - - the *value* can be a *string*, *number* or *null* - - `span` - the object of the column span +### Getting sub-row config and content -~~~jsx {17-18} -const grid = new dhx.Grid("grid_container", { - columns: [ - { width: 200, id: "country", header: [{ text: "Country" }] }, - { - width: 150, - id: "population", - header: [{ text: "Population" }], - summary: "count" - } - ], - summary: { totalPopulation: ["population", "sum"] }, - spans: [ - { - row: "rowid", - column: "population", - rowspan: 9, - text: "Some text", - tooltipTemplate: ({ value, count }) => (`value: ${value}; count: ${count}`), - }, - ], - data: dataset -}); -~~~ +You can get the configuration settings applied to a sub-row and the content inside it using the [`getSubRow()`](grid/api/grid_getsubrow_method.md) method. -**Related sample**: [Grid. Grouped cells (spans)](https://snippet.dhtmlx.com/1775dwbl) +:::info +Note that the method works if a sub-row is in the visible area or if the `preserve:true` property is specified in the `subRowConfig` object of the sub-row. +::: -**Note**, that if both the `spans` and [`leftSplit`](grid/api/grid_leftsplit_config.md) properties are set in the Grid config, the following rules will be applied: +The method takes as a parameter the id of a row and returns an object that includes the following properties: -- All necessary columns or rows will be in a span if the `spans` property is set for the columns located within the frozen area. -- If the `spans` property is set for a number of columns or rows placed as in the frozen part as in the movable one, then the columns remained in the movable part only will be in a span. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
css(string) user-defined CSS classes for a sub-row
element(HTMLElement | null) the parent container of the current sub-row
expanded(boolean) defines whether a sub-row is expanded by default, false by default
fullWidth(boolean) defines whether a sub-row will take all the width of Grid, false by default
height(number) the height of a sub-row in pixels, 200 by default
padding(string | number) the inner padding of a sub-row, 8 by default
preserve(boolean) saves the state of sub-rows while expanding/collapsing, disappearing from the visible area, data updating, false by default
toggleIcon(boolean) enables the icon for expanding/collapsing, true by default
view(string | object | null) that can be presented by:
  • a string, if the sub-row is set by the HTML content
  • an object instance to interact with, if a sub-row is an instance of a nested component (for example, Grid)
  • null, if the sub-row is unavailable (for example, it is hidden or placed outside the visible area and the `preserve` config is not specified)
-## Tooltip +## Drag-n-drop -### Grid tooltips +The drag-n-drop functionality allows you to reorder one or several rows or columns inside the grid or between several grids. -The default configuration of Grid provides tooltips that are rendered when a user hovers over the content of a column's cell. All the tooltips can be controlled via the [](grid/api/grid_tooltip_config.md) configuration property of Grid. By default, the tooltips are enabled. You can disable them, by setting the config to *false*: +:::tip Pro version only +If you use the GPL version of DHTMLX Grid (or DHTMLX Suite), you will be able to reorder only rows and only one by one. -~~~jsx +**Note**, to be able to drag-n-drop a column and (or) multiple rows, you need to use PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +### Drag-n-drop inside the grid + +It is possible to reorder a row or column of Grid by drag and drop. To enable the functionality, define the [`dragItem: "both"`](grid/api/grid_dragitem_config.md) property in the configuration object of Grid: + +~~~jsx {5} const grid = new dhx.Grid("grid_container", { columns: [ - //columns config + // columns config ], - data: dataset, - tooltip: false + dragItem: "both", + data: dataset }); ~~~ -**Related sample**: [Grid. Hiding tooltips](https://snippet.dhtmlx.com/mq4t3t3w) +**Related sample**: [Grid. Drag-n-drop](https://snippet.dhtmlx.com/zwc91d50) -The `tooltip` configuration option can be set as an object with the following properties: +:::note +To activate the functionality for columns or rows separately, use `dragItem: "column"` or `dragItem: "row"` respectively. +::: -- `force` - (optional) forces opening of a tooltip; if set to true, the `showDelay` and `hideDelay` settings are ignored, *false* by default -- `showDelay` - (optional) the time period that should pass before showing a tooltip, in ms -- `hideDelay` - (optional) the time period that should pass before hiding a tooltip, in ms -- `margin` - (optional) the margin between the node and tooltip -- `position` - (optional) the position of a tooltip: *"right"*, *"bottom"*, *"center"*, *"left"*, *"top"*; *"bottom"* by default -- `css` - (optional) the style of a tooltip box +If needed, you can disable the drag-n-drop functionality for a separate column via the `draggable` configuration option of the column: -~~~jsx {6-8} +~~~jsx {5,8} const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { width: 200, id: "country", header: [{ text: "Country" }]}, + { width: 150, id: "land", header: [{ text: "Land" }] }, + { width: 150, id: "density", header: [{ text: "Density" }], draggable: false } ], data: dataset, - tooltip: { - force: true - } + dragItem: "column", }); ~~~ -**Related sample**: [Grid. Tooltip config](https://snippet.dhtmlx.com/qpqnalyt) +:::tip +To make the process of work with drag and drop more flexible, you can apply the related drag-n-drop events of Grid for [columns](grid/api/api_overview.md#column-drag-and-drop) and [rows](grid/api/api_overview.md/#row-drag-and-drop). +::: -It is also possible to control the header and footer tooltips, independently. There are the [`headerTooltip`](grid/api/grid_headertooltip_config.md) and [`footerTooltip`](grid/api/grid_footertooltip_config.md) Grid configuration properties, that you can use for this purpose: +### Drag-n-drop between grids -~~~jsx {7-8} -const grid = new dhx.Grid("grid_container", { +DHTMLX Grid supports drag-n-drop of rows/columns between grids in several modes. To begin with, you should specify the [dragMode](grid/api/grid_dragmode_config.md) property in the configuration object of Grid. Then define which mode you need: + +- "target" - a grid takes a row/column from other grids, while its row/colmn can't be dragged out of it +- "source" - a grid allows dragging its row/column out and can't take a row/column from other grids +- "both" - a grid both takes a row/column from other grids and allows dragging its row/column out as well + +~~~jsx {7} +const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { id: "country", header: [{ text: "Country" }] }, + { id: "population", header: [{ text: "Population" }] } ], data: dataset, - tooltip: false, // Disable all tooltips - headerTooltip: true, // Enable all header tooltips - footerTooltip: true, // Enable all footer tooltips + dragMode: "source", + // dragItem: "column" - allows reordering columns one by one }); ~~~ -The `headerTooltip` and `footerTooltip` configs can be specified as objects the same as the main [`tooltip`](grid/configuration.md#grid-tooltips) config. +**Related sample**: [Grid. Drag-n-drop between grids](https://snippet.dhtmlx.com/qx9a86ax) -### Column and spans tooltips +### Drag-n-drop of multiple rows -There is a possibility to enable/disable tooltips for separate columns or spans by using the `tooltip` option in the configuration object of the [`columns`](grid/configuration.md#columns) or [`spans`](grid/configuration.md#spans) accordingly: +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: -~~~jsx {3,7,10} -const grid = new dhx.Grid("grid_container", { +To allow a user to drag-n-drop multiple rows at once, you need to enable [multiselection](#multiple-selection-of-grid-cells) of rows when configuring drag-n-drop. For example: + +~~~jsx +const grid = new dhx.Grid("grid", { columns: [ - { width: 200, id: "country", header: [{ text: "Country" }], tooltip: true }, - { width: 150, id: "population", header: [{ text: "Population" }] }, + // columns config ], - spans: [ - { row: "1", column: "country", rowspan: 5, tooltip: true }, + data: data, + selection: "row", + //drag-n-drop rows inside the grid + multiselection: true, + dragItem: "both" // or dragItem: "row" +}); +~~~ + +**Related sample**: [Grid. Drag-n-drop](https://snippet.dhtmlx.com/zwc91d50) + +or + +~~~jsx +const grid = new dhx.Grid("grid", { + columns: [ + // columns config ], data: dataset, - tooltip: false + selection: "row", + //drag-n-drop rows between grids + multiselection: true, + dragMode: "both" // or dragMode: "source" }); ~~~ -The same as with the common Grid tooltips, column and span tooltips can be set as objects with the following properties: +### Adjusting DragPanel module -- `force` - (optional) forces opening of a tooltip; if set to true, the `showDelay` and `hideDelay` settings are ignored, *false* by default -- `showDelay` - (optional) the time period that should pass before showing a tooltip, in ms -- `hideDelay` - (optional) the time period that should pass before hiding a tooltip, in ms -- `margin` - (optional) the margin between the node and tooltip; *8px* by default -- `position` - (optional) the position of a tooltip: *"right"*, *"bottom"*, *"center"*, *"left"*, *"top"*; *"bottom"* by default -- `css` - (optional) the style of a tooltip box +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: -~~~jsx {3,7,10} +The [`DragPanel`](grid/usage_dragpanel.md) module allows configuring the drag-n-drop functionality in Grid. It provides settings for adjusting the look and feel of the drag panel that appears when the drag-n-drop functionality is activated. Check the details below. + +![](../assets/grid/dragpanel_module.png) + +To initialize the `DragPanel` module, you should enable the [`dragPanel`](grid/api/grid_dragpanel_config.md) property in the Grid configuration together with the [row Drag-and-Drop](#drag-n-drop) functionality (e.g. via the `dragItem: "row"` or `dragItem: "both"` properties). For example: + +~~~jsx {10-11} const grid = new dhx.Grid("grid_container", { columns: [ - { width: 200, id: "country", header: [{ text: "Country" }], tooltip: { force: true } }, - { width: 150, id: "population", header: [{ text: "Population" }] }, + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, ], - spans: [ - { row: "1", column: "country", rowspan: 5, tooltip: { force: true } }, + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, ], - data: dataset, - tooltip: false + dragItem: "row", // enables row Drag-and-Drop + dragPanel: true // enables the DragPanel module }); ~~~ -#### Adding templates for column and spans tooltip - -You can add a template for a column or spans tooltip. +**Related sample**: [Grid (TreeGrid). DragPanel. Initialization](https://snippet.dhtmlx.com/uevdwjuo) -- to set a template for a column tooltip use a function which takes 3 parameters: - - `value` - (required) the value of a cell - - `row` - (required) an object with all cells in a row - - `column` - (required) an object with the configuration of a column +The module is also automatically enabled if the [row Drag-and-Drop](#drag-n-drop) functionality is activated +(e.g. via the `dragItem: "row"` or `dragItem: "both"` properties) and either the [`BlockSelection`](grid/usage_blockselection.md) or [`Clipboard`](grid/usage_clipboard.md) modules are enabled. -Returning *false* from the function will block showing of the tooltip. +The following example demonstrates enabling the `DragPanel` module with row Drag-and-Drop and the `BlockSelection` module: -~~~jsx {6-8} +~~~jsx {10-11} const grid = new dhx.Grid("grid_container", { columns: [ - { - width: 200, id: "country", header: [{ text: "Country" }], align: "left", - htmlEnable: true, - tooltipTemplate: function (value, row, column) { - // the template logic - } - }, - { width: 150, id: "population", header: [{ text: "Population" }] }, - { width: 150, id: "yearlyChange", header: [{ text: "Yearly Change" }] }, - // more options + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, ], - data: dataset + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + dragItem: "row", // enables row Drag-and-Drop + blockSelection: true // triggers DragPanel activation }); ~~~ -You can [check an example of applying a template for a column tooltip](grid/customization.md#adding-template-to-tooltip). +You can specify additional configuration options for the `DragPanel` module while initializing the component. For this, you need to set the `dragPanel` property as an *object*. The following options are available: + - `css` - (*string*) specifies a custom CSS class for styling the drag panel + - `icon` - (*string*) defines a custom icon for the drag handle + - `width` - (*number*) sets the width of the drag panel in pixels -- to set a template for a spans tooltip use the `tooltipTemplate` configuration property. The value of the `tooltipTemplate` property is a callback function which is called with the following parameters: - - `content` - an object with the content of the span tooltip. Contains two properties which are available either from the component's or from the column's configuration: - - `value` - the value rendered in a cell, including the applied templates - - an object with the calculated values of the `summary` property, set as *key:value* pairs where: - - the *key* is either the key defined in the list or the functor name - - the *value* can be a *string*, *number* or *null* - - `span` - the object of the column span +The following example demonstrates configuring the `DragPanel` module with custom styling and width: -~~~jsx {18} +~~~html + + + ~~~ -#### Column header/footer tooltip +## Selection -The tooltip set for a column enables/disables all its tooltips. However, you can control the tooltips of the column header/footer separately, by specifying the `tooltip` property in the corresponding header/footer object inside the column: +DHTMLX Grid includes the selection feature that allows highlighting Grid elements depending on the chosen mode. The [`selection`](grid/api/grid_selection_config.md) property enables selection in a grid. It can take three values: -~~~jsx {4} + + + + + + + + + + + + + + + +
rowto move selection between Grid rows
cellto move selection between Grid cells
complexto highlight both a selected cell and the row it belongs to
+
+ +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - // Enables a tooltip for the country title - { id: "country", header: [{ text: "Country", tooltip: true }] }, - { id: "population", header: [{ text: "Population" }] }, - // more columns + // columns config ], - data: dataset, - tooltip: false, + selection: "complex", + data: dataset }); ~~~ -What is more, you can specify a necessary template for the header/footer tooltip via the `tooltipTemplate` configuration property. The value of the `tooltipTemplate` property is a callback -function which is called with the following parameters: +**Related sample**: [Grid. Selection](https://snippet.dhtmlx.com/ad6roqsx) -- `content` - an object with the content of the header/footer tooltip. Contains two properties which are available either from the component's or from the column's configuration: - - `value` - (*string*) the value rendered in a cell, including the applied templates - - an object with the calculated values of the `summary` property, set as *key:value* pairs where: - - the *key* is either the key defined in the list or the functor name - - the *value* can be a *string*, *number* or *null* -- `header/footer` - (*object*) the object of the column header/footer -- `column` - (*object*) the object of a column +### Multiple selection of Grid cells -and returns a string with the tooltip template for the header/footer or *false* to disable a tooltip. +While setting the [`selection`](grid/configuration.md#selection) property to *"row"*, *"cell"*, or *"complex"* value, you can enable the [](grid/api/grid_multiselection_config.md) property to allow a user to select multiple Grid elements: -~~~jsx {9} +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - { - width: 150, - id: "population", - header: [ - { - text: "Population", - tooltipTemplate: ({ totalPopulation, count }) => `Total: ${totalPopulation}, Count: ${ count }` - } - ], - summary: "count" - } - // more columns + // columns config ], - summary: { totalPopulation: ["population", "sum"] }, + multiselection: true, + selection: "row", data: dataset +}); ~~~ -**Related sample**: [Grid. Header/footer tooltip](https://snippet.dhtmlx.com/fgstf2mq) +**Related sample**: [Grid. Multiselection](https://snippet.dhtmlx.com/4nj0e9ye) -#### Tooltips for filters +Since the `multiselection` configuration option is set to *true*, using the "Ctrl + Click" combination allows selecting the desired cells or rows. +A range of Grid cells/rows can be selected by clicking the first element to select and then, while holding down the Shift key, clicking the last element to select. -You can provide a tooltip template for the header content of any type, which allows showing tooltips for filters. +## Managing range selection in Grid -Check the example below: +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: -~~~jsx {14,26} -const balanceTemplate = value => { - return value > 0 - ? `
⬆ $${value}
` - : `
⬇ $${value}
`; -}; +The Grid functionality provides the [range selection management](grid/usage_rangeselection.md) feature for setting/resetting a range of cells, retrieving information about the current range, and checking whether specific cells belong to the selected range. +To enable [range selection management](grid/usage_rangeselection.md) within a grid, you should use the `RangeSelection` module. To initialize the module, enable the [`rangeSelection`](grid/api/grid_rangeselection_config.md) property in the Grid configuration: + +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - { - minWidth: 150, - id: "project", - header: [ - {text: "Project"}, - {content: "comboFilter", tooltipTemplate: () => "Select project"} - ], - footer: [{text: "Total"}], - resizable: true, - draggable: false - }, - { - width: 130, - id: "balance", - header: [{text: "Balance"}, {content: "inputFilter"}], - footer: [ - { - tooltipTemplate: balanceTemplate - }, - ], - template: balanceTemplate, - htmlEnable: true, - numberMask: { - prefix: "$" - } - }, + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true // enables the RangeSelection module }); ~~~ +The `rangeSelection` property can be set in two ways: + +- as a *boolean* value it enables or disables the range selection module upon the component initialization +- as an *object* it enables the module and allows setting additional configuration options during the component initialization. The following options are available: + - `disabled` - (*boolean*) makes the module inactive upon initialization of the component + +The example below demonstrates interaction with the RangeSelection module's API when range selection is configured to be inactive on the component initialization. + +~~~jsx {11,15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: { disabled: true } +}); + +console.log(grid.range.isDisabled()); // `true` - module is inactive +grid.range.setRange({ xStart: "a", yStart: "1" }); // the range will not be set +~~~ + +For information on using the Range Selection API, read the [Work with RangeSelection module](grid/usage_rangeselection.md) guide. + +## Managing block selection in Grid + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +The Grid functionality provides the [block selection management](grid/usage_blockselection.md) feature for selecting cells' ranges via the mouse pointer, touch input, and keyboard navigation, as well as adjusting the appearance of the selection and managing the behavior of the module, depending on the applied mode. + +To enable managing of the block selection within a grid, you should use the `BlockSelection` module. To initialize the module, enable the [`blockSelection`](grid/api/grid_blockselection_config.md) property in the Grid configuration: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true // enables the BlockSelection module +}); +~~~ + +The `blockSelection` property can be set in two ways: + +- as a *boolean* value it enables or disables the block selection module upon the component initialization +- as an *object* it enables the module and allows setting additional configuration options during the component initialization. The following options are available: + + + + + + + + + + + + + + + + + + + + +
disabled(boolean) disables the module on startup, `false` by default
mode(string) the operating mode of the module:
handle(boolean | object) enables the handle for resizing or provides additional configuration options, `true` by default. As an *object* can contain the following properties:
  • allowAxis - (string) restricts the handle movement: `"x"` (horizontal), `"y"` (vertical), `"xy"` (both directions). `"xy"` by default
  • handler - (function | boolean) a *function* to process the handle actions or *boolean* to enable/disable. As a *function*, the property takes the following parameters:
    • cell - (object) the object of the current cell. Contains the following properties:
      • *row* - the configuration object of a row
      • *column* - the configuration object of a column
    • array - (array) an array of all selected cells. Each cell object contains the following properties:
      • *row* - the configuration object of a row
      • *column* - the configuration object of a column
    • range - (array) an array of pre-selected cells. Each cell object contains the following properties:
      • *row* - the configuration object of a row
      • *column* - the configuration object of a column
    • dir - (string) the direction of cells selection: "up" | "down" | "right" | "left"
    • index - (number) the index of the iterated cell
    • grid - (object) the `dhx.Grid` component object
    The handler function may return an object with the history of Grid actions. The returned object contains the following properties:
    • prev - the previous cell value
    • current - the new cell value
area(boolean) enables the display of the selection area, `true` by default
+ +:::note +By default, the `blockSelection` property is set to `false`. When `blockSelection` is set to `true` or the module is set to the "range" mode, the [`RangeSelection`](grid/usage_rangeselection.md) module is initialized. +::: + +The example below demonstrates configuring the module with the handle disabled and the "range" mode enabled: + +~~~jsx {10-13} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { + mode: "range", // setting the "range" mode + handle: false // the handle is disabled + } +}); +~~~ + +The following example demonstrates configuring the handle: + +~~~jsx {10-13} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { + mode: "range", // setting the "range" mode + handle: { allowAxis: "y" } // restricts the handle movement to the vertical direction + } +}); +~~~ + +**Related sample:** [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) + +For information on using the Block Selection API, read the [Work with Block Selection module](grid/usage_blockselection.md) guide. + +## Clipboard + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +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. + +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. + +:::note +The `blockSelection: { mode: "range" }` property is automatically initialized in the Grid configuration when the `Clipboard` module is enabled. +::: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { mode: "range" }, // required for Clipboard to function (initializes automatically) + clipboard: true // enables the Clipboard module +}); +~~~ + +The `clipboard` property can be set in two ways: + +- as a *boolean* value it enables or disables the `clipboard` module upon the component initialization +- as an *object* it enables the module and allows defining [modifier functions](grid/usage_clipboard.md/#using-formatter-functions) for data processing. The following properties are available: + - `copyModifier` - (*function*) modifies data before copying to the clipboard. Accepts as parameters the cell value, the cell object, and the `cut` flag (set to `true`, if it's a cut operation) + - `cutModifier` - (*function*) modifies the cell data before cutting (before clearing the cell). Accepts as parameters the cell value and the cell object + - `pasteModifier` - (*function*) modifies data from the clipboard before pasting into a cell. Accepts as parameters the cell value and the cell object + +The example below demonstrates the clipboard configuration with all the modifiers in use: + +~~~jsx {10-15} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + clipboard: { + // adds a suffix based on the operation + copyModifier: (value, cell, cut) => `${value}${cut ? "-cut" : "-copied"}`, + cutModifier: (value, cell) => `${value}-removed`, // before cutting a value + pasteModifier: (value, cell) => value.replace("-copied", "") // removes the suffix on data pasting + } +}); +~~~ + +**Related sample**: [Grid. Clipboard. Custom copy/cut/paste for number and date columns](https://snippet.dhtmlx.com/dfj49xah) + +For information on working with Clipboard, read the [Work with Clipboard module](grid/usage_clipboard.md) guide. + +## History of Grid actions + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +DHTMLX Grid provides the [functionality for managing the history of actions in the component](grid/usage_history.md). + +To enable the history functionality within a grid, you should use the `History` module. To initialize the module, enable the [`history`](grid/api/grid_history_config.md) property in the Grid configuration. + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + history: true // enables the History module +}); +~~~ + +The `history` property can be set in two ways: +- as a *boolean* value it enables or disables the `History` module upon the component initialization +- as an *object* it enables the module and allows setting additional parameters: + - `limit` - (*number*) the maximum number of actions stored in the history. When the limit is exceeded, the oldest actions are removed + - `disabled` - (*boolean*) if `true`, the module is disabled on initialization, and no actions are recorded in the history + +The example below demonstrates configuring the module with a history limit of 10 actions. The module is disabled on initialization: + +~~~jsx {10-13} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + history: { + limit: 10, // limits history to 10 actions + disabled: true // the module is disabled on start + } +}); + +grid.history.enable(); // enabling the module +~~~ + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +For information on working with the History API, read the [Work with History module](grid/usage_history.md) guide. + +## Keyboard navigation + +DHTMLX Grid provides the keyboard navigation that will help you manipulate your grid faster. + +### Default shortcut keys + +The navigation shortcut keys and keys combinations that Grid enables by default are provided below: + + + + + + + + + + + + + + + + + + + + + + + + +
PageUpscrolls Grid up to the height of the visible content (without change of the selected cell)
PageDownscrolls Grid down to the height of the visible content (without change of the selected cell)
Homenavigates to the beginning of the Grid content (without change of the selected cell)
Endnavigates to the end of the Grid content (without change of the selected cell)
Ctrl+Enterexpands/collapses the parent item in the TreeGrid mode
+ +If you need to disable this functionality, set the [`keyNavigation`](grid/api/grid_keynavigation_config.md) property to *false*. + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + data: dataset, + keyNavigation: false +}); +~~~ + +**Related sample**: [Grid. Key navigation](https://snippet.dhtmlx.com/y9kdk0md) + +### Shortcut keys for moving selection between cells + +In case you want to enable the shortcut keys that allow moving the selection between cells, you need to specify the [`selection`](grid/api/grid_selection_config.md) property for Grid. + +~~~jsx {6} +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + data: dataset, + selection: "complex", + keyNavigation: true // true - by default +}); +~~~ + +**Related sample**: [Grid. Key navigation](https://snippet.dhtmlx.com/y9kdk0md) + +The list of the shortcut keys and their combinations used for moving selection between cells is the following: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArrowUpmoves selection to the previous vertical cell
ArrowDownmoves selection to the next vertical cell
ArrowLeftmoves selection to the previous horizontal cell
ArrowRightmoves selection to the next horizontal cell
Ctrl+ArrowUpmoves selection to the first vertical cell
Ctrl+ArrowDownmoves selection to the last vertical cell
Ctrl+ArrowLeft moves selection to the first horizontal cell
Ctrl+ArrowRight moves selection to the last horizontal cell
Tab moves selection to the next horizontal cell or the first cell of the next row
Shit+Tab moves selection to the previous horizontal cell or to the first cell of the previous row
+ +The combinations of the shortcut keys listed below do not work when the `selection` property is set to *"complex"*. Use another mode (*"cell" or "row"*) in case you want to activate these navigation keys: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Shift+ArrowUpmoves selection to the previous vertical cell with the change of the selected cells
Shift+ArrowDownmoves selection to the next vertical cell with the change of the selected cells
Shift+ArrowLeftmoves selection to the previous horizontal cell with the change of the selected cells
Shift+ArrowRightmoves selection to the next horizontal cell with the change of the selected cells
Ctrl+Shift+ArrowUpmoves selection to the first vertical cell with the change of the selected cells
Ctrl+Shift+ArrowDownmoves selection to the last vertical cell with the change of the selected cells
Ctrl+Shift+ArrowLeftmoves selection to the first horizontal cell with the change of the selected cells
Ctrl+Shift+ArrowRightmoves selection to the last horizontal cell with the change of the selected cells
+ +### Shortcut keys for editing + +It is possible to use shortcut keys for editing a cell in Grid by setting the [`editable:true`](grid/api/grid_editable_config.md) property in the configuration object of Grid. + +~~~jsx {7} +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + data: dataset, + selection: "complex", + editable: true, + keyNavigation: true // true - by default +}); +~~~ + +**Related sample**: [Grid. Key navigation](https://snippet.dhtmlx.com/y9kdk0md) + +The list of the shortcut keys for editing is given below: + + + + + + + + + + + + + + + + +
Enteropens the editor in the selected cell. If the editor is currently opened - closes the editor and saves changes
Escapecloses the editor of the selected cell without saving
Deleteclears data in the selected cells. Works only with the `BlockSelection` module in the "range" mode
+ +### Shortcut keys for selecting ranges of cells + +If you need to use the keyboard navigation for selecting ranges of cells via the user interface, you should enable the [`BlockSelection` module](grid/usage_blockselection.md) in the Grid configuration. + +:::note +Keyboard navigation works in both the `"range"` and `"manual"` modes. In the `"manual"` mode, applying the selection (e.g., after `Enter`) requires handling via the events, such as [`beforeBlockSelectionApply`](grid/api/blockselection/beforeblockselectionapply_event.md) and [`afterBlockSelectionApply`](grid/api/blockselection/afterblockselectionapply_event.md). +::: + +The module supports keyboard navigation for selecting and managing ranges, similar to keyboard navigation used in Google Spreadsheets. The following shortcut keys and their combinations are available: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArrowUpresets the selected range and moves the focus to the previous vertical cell, setting the initially selected cell if no selection is active
ArrowDownresets the selected range and moves the focus to the next vertical cell, setting the initially selected cell if no selection is active
ArrowLeftresets the selected range and moves the focus to the previous horizontal cell, setting the initially selected cell if no selection is active
ArrowRightresets the selected range and moves the focus to the next horizontal cell, setting the initially selected cell if no selection is active
Shift+ArrowUpextends the selected range from the current initial cell to the previous vertical cell
Shift+ArrowDownextends the selected range from the current initial cell to the next vertical cell
Shift+ArrowLeftextends the selected range from the current initial cell to the previous horizontal cell
Shift+ArrowRightextends the selected range from the current initial cell to the next horizontal cell
Ctrl+ArrowUpresets the selected range and moves the focus to the first vertical cell
Ctrl+ArrowDownresets the selected range and moves the focus to the last vertical cell
Ctrl+ArrowLeftresets the selected range and moves the focus to the first horizontal cell
Ctrl+ArrowRightresets the selected range and moves the focus to the last horizontal cell
Ctrl+Shift+ArrowUpextends the selected range to the first vertical cell
Ctrl+Shift+ArrowDownextends the selected range to the last vertical cell
Ctrl+Shift+ArrowLeft extends the selected range to the first horizontal cell
Ctrl+Shift+ArrowRight extends the selected range to the last horizontal cell
+ +The following shortcut key and mouse combination is available: + + + + + + + + +
Shift + clicksets the end cell of the range, extending the selection from the current initial cell
+ +The following shortcut key is available when the [`editable` mode](grid/api/grid_editable_config.md) is set for the Grid component and the `BlockSelection` module is used in the `"range"` mode: + + + + + + + + +
Deleteallows clearing the selected cells
\ No newline at end of file diff --git a/docs/grid/features.md b/docs/grid/features.md index 37716bf6..e05ae2d0 100644 --- a/docs/grid/features.md +++ b/docs/grid/features.md @@ -46,6 +46,17 @@ In this section you can find out how to initialize Grid, how to load data into t ## How to configure Grid +### How to work with TreeGrid mode + +In this section you will find the ways of working with the TreeGrid mode of Grid. + +| Topic | Description | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Enabling TreeGrid mode](../treegrid_mode/#initialization) | Learn how to enable the TreeGrid mode of Grid | +| [Configuring TreeGrid mode](../treegrid_mode/#configuration)| Learn how to configure the TreeGrid mode of Grid | +| [Data loading in TreeGrid mode](../treegrid_mode/#data-loading)| Learn how to load data in the TreeGrid mode of Grid | +| [Working with TreeGrid mode](../treegrid_mode/#work-with-grid-in-the-treegrid-mode) | Learn how to expand/collapse nodes | + ### How to configure columns In this section you will get to know how to configure Grid columns on Grid initialization. @@ -124,6 +135,7 @@ In this section you will get to know how to configure the drag-n-drop functional | [Drag-n-drop between grids](../configuration/#drag-n-drop-between-grids) | Learn how to configure drag-n-drop between grids ([Example](https://snippet.dhtmlx.com/qx9a86ax)) | | [Drag-n-drop of multiple rows](grid/configuration.md#drag-n-drop-of-multiple-rows) | Learn how to allow end users to drag-n-drop several rows at once | | [Copying of rows during drag-n-drop](../api/grid_dragcopy_config/) | Learn how to copy a row to a target during drag-n-drop ([Example](https://snippet.dhtmlx.com/23slivyz)) | +| [Using the DragPanel module](../usage_dragpanel/) | Learn how to use the DragPanel module that provides additional functionality for moving rows in the Grid ([Example](https://snippet.dhtmlx.com/uevdwjuo)) | ## How to render custom statistics in the column header/footer and in the spans @@ -281,18 +293,48 @@ In this section you will find the ways of working with selection functionality. | [Enabling multiselection](../configuration/#multiple-selection-of-grid-cells) | Learn how to enable multi-row/multi-cell selection in Grid ([Example](https://snippet.dhtmlx.com/4nj0e9ye)) | | [Working with selection](../usage_selection/) | Learn how to enable/disable selection, set selection to cells, remove selection, and get the object of a selected cell ([Example](https://snippet.dhtmlx.com/4nj0e9ye)) | | [Selection API](../../category/selection-api/) | Learn how to use the API of Selection to manage the selection of Grid cells | -| [Keyboard navigation](../configuration/#arrow-shortcut-keys) | Learn how to enable key navigation that allows moving the selection between cells ([Example](https://snippet.dhtmlx.com/y9kdk0md)) | +| [Keyboard navigation](../configuration/#shortcut-keys-for-moving-selection-between-cells) | Learn how to enable key navigation that allows moving the selection between cells ([Example](https://snippet.dhtmlx.com/y9kdk0md)) | -## How to work with TreeGrid mode +## How to work with range selection -In this section you will find the ways of working with the TreeGrid mode of Grid. +In this section you will get to know how to work with the range selection functionality. | Topic | Description | | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Enabling TreeGrid mode](../treegrid_mode/#initialization) | Learn how to enable the TreeGrid mode of Grid | -| [Configuring TreeGrid mode](../treegrid_mode/#configuration)| Learn how to configure the TreeGrid mode of Grid | -| [Data loading in TreeGrid mode](../treegrid_mode/#data-loading)| Learn how to load data in the TreeGrid mode of Grid | -| [Working with TreeGrid mode](../treegrid_mode/#work-with-grid-in-the-treegrid-mode) | Learn how to expand/collapse nodes | +| [Configuring range selection](../configuration/#managing-range-selection-in-grid) | Learn how to configure the range selection module within Grid | +| [Working with range selection](../usage_rangeselection/) | Learn how to enable/disable range selection, set/reset range selection, get the range selection object, and check whether a cell is in the range ([Example](https://snippet.dhtmlx.com/42fp5qvt)) | +| [Range Selection API](../../category/rangeselection-api/) | Learn how to use the API of the RangeSelection module to manage the range selection within Grid | + + +## How to work with block selection + +In this section you will get to know how to work with the block selection functionality. + +| Topic | Description | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Configuring block selection](../configuration/#managing-block-selection-in-grid) | Learn how to configure the block selection module within Grid ([Example](https://snippet.dhtmlx.com/sryiguxu)) | +| [Working with block selection](../usage_blockselection/) | Learn how to enable/disable block selection in Grid, check the main features of the BlockSelection module and explore how it interacts with other modules | +| [BlockSelection API](../../category/blockselection-api/) | Learn how to use API of the BlockSelection module to manage the block selection within Grid | + +## How to work with clipboard + +In this section you will get to know how to work with the clipboard functionality. + +| Topic | Description | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Configuring clipboard](../configuration/#clipboard) | Learn how to configure the Clipboard module within Grid ([Example](https://snippet.dhtmlx.com/dfj49xah)) | +| [Working with clipboard](../usage_clipboard/) | Learn how to enable the clipboard in Grid, check the main features and explore the peculiarities of using the Clipboard module | +| [Clipboard API](../../category/clipboard-events/) | Learn how to use API of the Clipboard module to manage the clipboard operations within Grid | + +## How to work with history of Grid actions + +In this section you will get to know how to work with the history of Grid actions. + +| Topic | Description | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Configuring history of Grid actions](../configuration/#history-of-grid-actions) | Learn how to configure the History module within Grid ([Example](https://snippet.dhtmlx.com/vznpyeit)) | +| [Working with history of actions](../usage_history/) | Learn how to enable the history of actions in Grid, check the main features and explore the peculiarities of using the History module | +| [History API](../../category/history-api/) | Learn how to use API of the History module to manage the history of operations within Grid | ## How to scroll Grid @@ -341,7 +383,14 @@ In this section you can find out corresponding references of Grid API. | [Grid properties](../api/api_overview/#grid-properties) | Check the list of Grid properties | | [Grid column properties](../api/api_gridcolumn_properties/) | Check the list of properties of a Grid column | | [DataCollection API](../../data_collection/) | Check the API of DataCollection to work with Grid data | -| [Selection API](../../category/selection-api/) | Check the API of Selection to manage the selection of Grid cells | +| [TreeCollection API](../../tree_collection/) | Check the API of TreeCollection to work with Grid data in the TreeGrid mode | +| [Selection API](../../category/selection-api/) | Check the API of the Selection object to manage the selection of Grid cells | +| [RangeSelection API](../../category/rangeselection-api/) | Check the API of the RangeSelection module to manage the range selection in Grid | +| [BlockSelection API](../../category/blockselection-api/) | Check the API of the BlockSelection module to manage the block selection in Grid | +| [Clipboard API](../../category/clipboard-events/) | Check the API of the Clipboard module to work with clipboard in Grid | +| [DragPanel API](../../category/dragpanel-events/) | Check the API of the DragPanel module to work with drag panel within Grid | +| [History API](../../category/history-api/) | Check the API of the History module to work with the history of Grid actions | +| [Export API](../../category/export-methods-1/) | Check the API of the Export module to export Grid data | ## Common functionality diff --git a/docs/grid/index.md b/docs/grid/index.md index ede57e1f..e95af17d 100644 --- a/docs/grid/index.md +++ b/docs/grid/index.md @@ -28,6 +28,7 @@ You can check the following page to learn how to build a full-featured DHTMLX Gr - To get the whole JavaScript library of UI components [download DHTMLX Suite](https://dhtmlx.com/docs/products/dhtmlxSuite/download.shtml) - There are also [online samples for DHTMLX Grid](https://snippet.dhtmlx.com/1mxmshax?tag=grid) - To work with data of Grid check [DataCollection API](data_collection.md) +- To work with data of Grid in the TreeGrid mode check [TreeCollection API](tree_collection.md) ## Guides @@ -35,10 +36,16 @@ Says how to build a standard grid on a page and bring it to life: configure with - [](grid/initialization.md) - [](grid/configuration.md) +- [](grid/localization.md) - [](grid/data_loading.md) - [](grid/usage.md) - [](grid/treegrid_mode.md) - [](grid/usage_selection.md) +- [](grid/usage_rangeselection.md) +- [](grid/usage_blockselection.md) +- [](grid/usage_clipboard.md) +- [](grid/usage_dragpanel.md) +- [](grid/usage_history.md) - [](grid/customization.md) - [](grid/events.md) diff --git a/docs/grid/usage.md b/docs/grid/usage.md index 8cf3b5f2..79227da8 100644 --- a/docs/grid/usage.md +++ b/docs/grid/usage.md @@ -6,6 +6,10 @@ description: You can explore how to work with Grid in the documentation of the D # Work with Grid +## Working with Grid in the TreeGrid mode + +For information on working with with Grid in the TreeGrid mode, read the [TreeGrid mode](grid/treegrid_mode.md#work-with-grid-in-the-treegrid-mode) guide. + ## Working with columns and cells The API of DHTMLX Grid allows setting configuration of columns, getting an object of a particular column as well as the parameters of a certain cell. @@ -473,26 +477,38 @@ You can easily export data of Grid into the Excel, CSV, PDF, or PNG format. #### Exporting data to Excel -DHTMLX Grid provides the possibility to export data from Grid into an Excel file by calling the [`xlsx()`](grid/api/export/grid_xlsx_method.md) method of the Export module. The method takes an object with export settings as a parameter. +DHTMLX Grid uses the WebAssembly-based library [Json2Excel](https://github.com/dhtmlx/json2excel) to enable the export to Excel functionality and the [`xlsx()`](grid/api/export/grid_xlsx_method.md) method of the `Export` module to export data from Grid into an Excel file. Thus, to have the possibility of exporting files you need to: -~~~js +- install the [Json2Excel](https://github.com/dhtmlx/json2excel) library +- if you need to set a local path to the export module on your computer, specify the `url` option in the configuration object of the [`xlsx()`](grid/api/export/grid_xlsx_method.md) method and set the path to the **worker.js** file like: `"../libs/json2excel/1.3/worker.js?vx"`. If the local path isn't set, the link to the file from CDN will be used +- call the [`xlsx()`](grid/api/export/grid_xlsx_method.md) method of the `Export` module. The method takes an [object with export settings](grid/api/export/grid_xlsx_method.md) as a parameter (all settings are optional) + +~~~jsx grid.export.xlsx({ - name:"grid_data", - url: "//export.dhtmlx.com/excel" + url: "../libs/json2excel/1.3/worker.js?vx", // a local path to the export module + name: "my_file", // the name of a ready Excel file, "grid" by default + tableName: "grid", // the name of a sheet with grid data in the Excel file, "data" by default + dateFormatMask: "mm.dd.yy" // the date format mask for Excel, "dd/mm/yy" by default }); ~~~ +:::note +You can check the latest version of the Json2Excel library at the [github repository](https://github.com/dhtmlx/json2excel). +::: + +Read the details on dates formatting in Excel in the [related Excel documentation](https://support.microsoft.com/en-us/office/format-a-date-the-way-you-want-in-excel-8e10019e-d5d8-47a1-ba95-db95123d273e). + **Related sample**: [Grid. Export to xlsx and csv](https://snippet.dhtmlx.com/58oqij47) #### Exporting data to CSV -You can export data from Grid to the CSV format with the [`csv()`](grid/api/export/grid_csv_method.md) method of the Export module. +You can export data from Grid to the CSV format with the [`csv()`](grid/api/export/grid_csv_method.md) method of the Export module. The method takes an [object with export settings](grid/api/export/grid_csv_method.md) as a parameter (all settings are optional). -~~~js +~~~jsx grid.export.csv({ - name:"grid_data", // grid data will be exported to a CSV file named "grid_data" - rowDelimiter: "\t", // the tab delimiter will be used to separate rows - columnDelimiter: ";" // the semicolon delimiter will be used to separate columns + name: "my_file", // the name of a ready CSV file, "grid" by default + rowDelimiter: "\t", // the delimiter used to separate rows, "\n" (newline) by default + columnDelimiter: ";" // the delimiter used to separate columns, "," (comma) by default }); ~~~ @@ -502,14 +518,14 @@ The `csv()` method returns a CSV string with Grid data. #### Exporting data to PDF -The [`pdf()`](grid/api/export/grid_pdf_method.md) method of the Export module allows you to export data from Grid into a PDF file. The method takes an object with export settings as a parameter. +The [`pdf()`](grid/api/export/grid_pdf_method.md) method of the Export module allows you to export data from Grid into a PDF file. The method takes an [object with export settings](grid/api/export/grid_pdf_method.md) as a parameter (all settings are optional). -~~~js +~~~jsx grid.export.pdf({ - format: "A4", - scale: 0.75, - displayHeaderFooter: true, - theme: "dark", + format: "A4", // the format of the output file, "A4" by default + scale: 0.75, // the scale of the grid rendering (between 0.1 and 2) + displayHeaderFooter: true, // defines whether to display the header and footer, false by default + theme: "dark" // the exported theme, "light" by default }); ~~~ @@ -517,11 +533,11 @@ grid.export.pdf({ #### Exporting data to PNG -The [`png()`](grid/api/export/grid_png_method.md) method of the Export module allows you to export data from Grid into a PNG file. The method takes an object with export settings as a parameter. +The [`png()`](grid/api/export/grid_png_method.md) method of the Export module allows you to export data from Grid into a PNG file. The method takes an [object with export settings](grid/api/export/grid_png_method.md) as a parameter (all settings are optional). -~~~js +~~~jsx grid.export.png({ - theme: "dark", + theme: "dark" // the exported theme, "light" by default }); ~~~ @@ -1198,8 +1214,25 @@ grid.destructor(); ## Using Selection API -For information on using Selection API, read [Work with Selection Object](grid/usage_selection.md). +For information on using Selection API, read [Work with Selection object](grid/usage_selection.md). -## Working with Grid in the TreeGrid mode +## Using RangeSelection API + +For information on using RangeSelection API, read [Work with RangeSelection Module](grid/usage_rangeselection.md). + +## Using BlockSelection API + +For information on using BlockSelection API, read [Work with BlockSelection module](grid/usage_blockselection.md). + +## Working with Clipboard + +For information on using the Clipboard module in Grid, read [Work with Clipboard module](grid/usage_clipboard.md). + +## Working with DragPanel + +For information on using the DragPanel module in Grid, read [Work with DragPanel module](grid/usage_dragpanel.md). + +## Working with History API + +For information on using the History API in Grid, read [Work with History module](grid/usage_history.md). -For information on working with with Grid in the TreeGrid mode, read the [TreeGrid mode](grid/treegrid_mode.md#work-with-grid-in-the-treegrid-mode) guide. diff --git a/docs/grid/usage_blockselection.md b/docs/grid/usage_blockselection.md new file mode 100644 index 00000000..1af99cca --- /dev/null +++ b/docs/grid/usage_blockselection.md @@ -0,0 +1,496 @@ +--- +sidebar_label: Work with BlockSelection module +title: JavaScript Grid - Work with BlockSelection module +description: You can explore how to work with BlockSelection module of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Work with BlockSelection module + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +You can manage block selection within a grid via the API of the [`BlockSelection`](grid/configuration.md/#managing-block-selection-in-grid) module. It allows selecting ranges of cells using the mouse pointer, touch input, or keyboard navigation, visualizing the selection, and controlling behavior through various modes and handlers. It also supports an [event system](grid/api/api_overview.md/#blockselection-events) to track user actions, including keyboard and mouse combinations. + +![](../assets/grid/blockselection_module.png) + +## Initializing the BlockSelection module + +To initialize the `BlockSelection` module, use the [`blockSelection`](grid/api/grid_blockselection_config.md) property in the configuration of the **dhx.Grid** component. Once the Grid is created, the module is accessible through the `grid.block` property. + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true // enables the BlockSelection module +}); +~~~ + +The `blockSelection` property can also be set as an *object* to enable the module and provide additional configuration options. +Learn about configuration possibilities of the `BlockSelection` module in the [Configuration](grid/configuration.md/#managing-block-selection-in-grid) guide. + +**Related sample:** [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) + +## Enabling/disabling BlockSelection module + +You can activate the block selection module via the [`enable()`](grid/api/blockselection/enable_method.md) method of the `block` object. +The following example shows how the module is enabled after deactivation on initialization: + +~~~jsx {13} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { disabled: true } // disabled on initialization +}); + +grid.block.enable(); // activating the module +console.log(grid.block.isDisabled()); // -> false +~~~ + +To disable the block selection in Grid, use the [`disable()`](grid/api/blockselection/disable_method.md) method of the `block` object. +The example below shows disabling of the `BlockSelection` module: + +~~~jsx {13} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true +}); + +grid.block.disable(); // disabling the module +console.log(grid.block.isDisabled()); // -> true +~~~ + +## Checking BlockSelection module state + +You can check whether the `BlockSelection` module is disabled, using the [`isDisabled()`](grid/api/blockselection/isdisabled_method.md) method of the `block` object. It returns `true`, if the module is disabled and `false`, if it is enabled. The following example shows checking of the module's activity status: + +~~~jsx {13,15} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: true +}); + +console.log(grid.block.isDisabled()); // -> false +grid.block.disable(); +console.log(grid.block.isDisabled()); // -> true +~~~ + +## Using events of the BlockSelection object + +To make the process of working with block selection more flexible, you can apply the [related events of the `block` object](grid/api/api_overview.md/#blockselection-events). + +## User-interface features + +This section describes the main UI features of the `BlockSelection` module: the way of selecting a range of cells, the available keyboard navigation combinations, as well as the appearance and behavior of the selection handle. + +### Cell selection + +The main points of cell selection while using the `BlockSelection` module are given below: + +- The user selects a range by dragging the mouse from the initial cell to the end cell. For example, dragging from **A1** to **B3** creates the range **A1:B3**, which is highlighted. +- The `Shift + click` combination allows extending the range from the current initial cell to the clicked cell. +- The cell selection behavior depends on the applied mode: + - the `"range"` mode uses the [**RangeSelection API**](grid/api/api_overview.md/#rangeselection-api) + - the `"manual"` mode requires specifying a custom logic via the [events](grid/api/api_overview.md/#blockselection-events) + +### Keyboard navigation + +:::note +Keyboard navigation works in both the `"range"` and `"manual"` modes. In the `"manual"` mode, applying the selection (e.g., after `Enter`) requires handling via the events, such as [`beforeBlockSelectionApply`](grid/api/blockselection/beforeblockselectionapply_event.md) and [`afterBlockSelectionApply`](grid/api/blockselection/afterblockselectionapply_event.md). +::: + +The module supports keyboard navigation for selecting and managing ranges, similar to keyboard navigation used in Google Spreadsheets. The following shortcut keys and their combinations are available: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArrowUpresets the selected range and moves the focus to the previous vertical cell, setting the initially selected cell if no selection is active
ArrowDownresets the selected range and moves the focus to the next vertical cell, setting the initially selected cell if no selection is active
ArrowLeftresets the selected range and moves the focus to the previous horizontal cell, setting the initially selected cell if no selection is active
ArrowRightresets the selected range and moves the focus to the next horizontal cell, setting the initially selected cell if no selection is active
Shift+ArrowUpextends the selected range from the current initial cell to the previous vertical cell
Shift+ArrowDownextends the selected range from the current initial cell to the next vertical cell
Shift+ArrowLeftextends the selected range from the current initial cell to the previous horizontal cell
Shift+ArrowRightextends the selected range from the current initial cell to the next horizontal cell
Ctrl+ArrowUpresets the selected range and moves the focus to the first vertical cell
Ctrl+ArrowDownresets the selected range and moves the focus to the last vertical cell
Ctrl+ArrowLeftresets the selected range and moves the focus to the first horizontal cell
Ctrl+ArrowRightresets the selected range and moves the focus to the last horizontal cell
Ctrl+Shift+ArrowUpextends the selected range to the first vertical cell
Ctrl+Shift+ArrowDownextends the selected range to the last vertical cell
Ctrl+Shift+ArrowLeft extends the selected range to the first horizontal cell
Ctrl+Shift+ArrowRight extends the selected range to the last horizontal cell
+ +The following shortcut key and mouse combination is available: + + + + + + + + +
Shift + clicksets the end cell of the range, extending the selection from the current initial cell
+ +The following shortcut key is available when the [`editable` mode](grid/api/grid_editable_config.md) is set for the Grid component and the `BlockSelection` module is used in the `"range"` mode: + + + + + + + + +
Deleteallows clearing the selected cells
+ +It is possible to cancel the cells clearing by using the [`beforeKeyDown`](grid/api/grid_beforekeydown_event.md) event: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "country", header: [{ text: "Country" }] }, + // The data of the cells in the "population" column will not be cleared + { id: "population", header: [{ text: "Population" }], editable: false }, + { id: "yearlyChange", header: [{ text: "Yearly Change" }] }, + ], + blockSelection: { + mode: "range" + }, + editable: true, + // other configuration +}); + +grid.events.on("beforeKeyDown", (event) => { + if (event.key === "Delete") { + return false; // cancel clearing all selected cells + } +}); +~~~ + +### Selection handle + +The peculiarities of the selection handle functionality are the following: + +- When the handle is enabled via [`blockSelection.handle`](grid/api/grid_blockselection_config.md/#parameters), it appears in the bottom-right corner of the range. +- When the handle is used with **default** settings (the `handler` property isn't specified in the `handle` object) and the `BlockSelection` module is used in the `"range"` mode, the behavior of the handle is the following: + - copies the value of the first cell of the selected range (or the entire range if selected) to new cells. For example, selecting **A1** (the value is "x") and dragging to **A3** fills **A2**, **A3** with "x". + - if the range **A1:B1** (the values are "x" and "y", correspondingly) is selected, dragging to **D1** copies "x" to **C1** and "y" to **D1**. +- A custom handler can be specified to modify the behavior (e.g., adding suffixes or other rules). +- In the `"manual"` mode, the handle and `handler` are ignored, and the built-in filling does not work. + +## Interaction with other modules + +The way of `BlockSelection` API interacting with other grid modules depends on which mode the module is used in: the `"range"` or the `"manual"` mode. + +#### Range mode + +- The `BlockSelection` module uses the [`RangeSelection` API](grid/api/api_overview.md/#rangeselection-api) to manage continuous rectangular ranges. +- The handle automatically fills data in the new range. +- The selected range will be reset during data grouping or ungrouping. +- The range will be reinstalled to a new one when moving columns or rows. + +#### Manual mode + +- The `BlockSelection` module does not use the `RangeSelection` API. The developer implements logic via the events such as [`blockSelectionValidate`](grid/api/blockselection/blockselectionvalidate_event.md), [`afterBlockSelectionApply`](grid/api/blockselection/afterblockselectionapply_event.md). +- The handle and built-in filling are unavailable. + +## Usage examples + +#### Restricting selection in the Range mode + +This example shows how to control the start of a block selection and programmatically set a range using the [`RangeSelection` API](grid/api/api_overview.md/#rangeselection-api). + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }], minWidth: 150 }, + { id: "b", header: [{ text: "B" }], minWidth: 150 }, + { id: "c", header: [{ text: "C" }], minWidth: 150 }, + { id: "d", header: [{ text: "D" }], minWidth: 150 }, + { id: "e", header: [{ text: "E" }], minWidth: 150 }, + { id: "f", header: [{ text: "F" }], minWidth: 150 }, + ], + data, + autoWidth: true, + blockSelection: { + mode: "range", // setting the "range" mode + handle: { allowAxis: "xy" } + } +}); + +// Controlling the block selection start via the event +grid.block.events.on("blockSelectionValidate", (cell, handle, event) => { + if (cell.column.id === "a") { + console.log("Selection cannot start from column A"); + return false; + } +}); + +// Setting a range via the `setRange()` method of the Range API +grid.range.setRange({ xStart: "b", xEnd: "d", yStart: "4", yEnd: "8" }); +~~~ + +**Related sample:** [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) + +#### Setting custom logic in the manual mode + +This example demonstrates the `"manual"` mode, providing full control and allowing the use of events for custom logic, such as styling. + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }], minWidth: 150 }, + { id: "b", header: [{ text: "B" }], minWidth: 150 }, + { id: "c", header: [{ text: "C" }], minWidth: 150 }, + { id: "d", header: [{ text: "D" }], minWidth: 150 }, + { id: "e", header: [{ text: "E" }], minWidth: 150 }, + { id: "f", header: [{ text: "F" }], minWidth: 150 }, + ], + data, + autoWidth: true, + blockSelection: { + mode: "manual", // Setting the manual mode + handle: false + }, + rangeSelection: true, +}); + +// Using an event for applying custom styling to a range of cells +grid.block.events.on("afterBlockSelectionApply", (startCell, endCell) => { + if ( + startCell.column.id === endCell.column.id && + startCell.row.id === endCell.row.id + ) { + return; + } + if (grid.range.getRange) { + grid.range.getRangedCells().forEach(cell => { + grid.removeCellCss(cell.row.id, cell.column.id, "custom-selected-cell"); + }); + } + + grid.range.setRange({ + xStart: startCell.column.id, + xEnd: endCell.column.id, + yStart: startCell.row.id, + yEnd: endCell.row.id, + }); + + grid.range.getRangedCells().forEach(cell => { + grid.addCellCss(cell.row.id, cell.column.id, "custom-selected-cell"); + }); +}); +~~~ + +#### Setting a custom handler for the handle + +This example shows how to override the handle behavior by adding a custom logic, such as modifying values based on the drag direction. + +~~~jsx +/* Define grid columns configuration */ +const columns = [ + { id: "productId", header: [{ text: "Product ID" }] }, // Column for the unique product identifier + { id: "productName", header: [{ text: "Product Name" }] }, // Column for the product name + { id: "category", header: [{ text: "Category" }] }, // Column for the product category + { id: "receivedDate", header: [{ text: "Received Date" }], type: "date", dateFormat: "%d.%m.%Y" }, // Date column with the specified format + { id: "stock", header: [{ text: "Stock" }], type: "number" }, // Numeric column for the stock quantity + { id: "price", header: [{ text: "Price" }], type: "number", numberMask: { prefix: "$" } } // Numeric column for the price with the dollar prefix +]; + +/* Initialize DHTMLX Grid with the specified configuration */ +const grid = new dhx.Grid("grid_container", { + columns, + data, + autoWidth: true, + history: true, // Enable history tracking for undo/redo + blockSelection: { + handle: { + allowAxis: "y", // Allow selection along the y-axis (rows) + handler: blockSelectionHandler, // Custom handler for block selection + }, + }, +}); + +/* Set initial selection range for the grid */ +grid.range.setRange({ + xStart: "productId", // Start selection at the "productId" column + yEnd: grid.data.getId(0), // End selection at the first row +}); + +/* Initialize objects to store initial values and column indices */ +let initValues = {}; // Store initial values for each column +let columnIndex = {}; // Track index increments for each column + +/* The handler function for block selection events */ +function blockSelectionHandler({ cell, array, index, grid }) { + // Reset tracking objects if this is the first cell in the selection + if (!index) { + initValues = {}; + columnIndex = {}; + } + const columnId = cell.column.id; + // Initialize values for a new column if not already set + if (!initValues[columnId]) { + initValues[columnId] = cell.row[columnId]; // Store the initial cell value + columnIndex[columnId] = 0; // Initialize the index counter + return { prev: initValues[columnId], current: initValues[columnId] }; // Return unchanged values + } + + // Increment column index for the current column + const colIndex = columnIndex[columnId] += 1; + const initValue = initValues[columnId]; // Get the initial value for a column + let prev = current = cell.row[columnId]; // Set the default previous and current values + + // Modify the current value based on the column type + switch (cell.column.type) { + case "number": + current = initValue + colIndex * 10; // Increment the number by 10 per row + break; + case "date": + // Parse ISO date and increment the day by colIndex + const [year, month, day] = initValue.split("-"); + current = new Date(Number(year), Number(month) - 1, Number(day) + colIndex).toISOString(); + break; + default: + current = initValue; // Keep the default value for other types + break; + } + + // Custom formatting for specific columns + if (columnId === "productId") { + // Generate a new product ID with the format P00N + current = `P00${parseInt(initValue.replace(/\D/g, "")) + colIndex}`; + } + if (columnId === "category") { + // Append the index in parentheses to the category + current = `${current} (${colIndex})`; + } + + // Create the history object for undo/redo + const history = { prev, current }; + // Update grid data with the new value + grid.data.update(cell.row.id, { [columnId]: current }, + index < array.length - 1 // Continue updating if it isn't the last cell in selection + ); + return history; // Return the history for tracking +} +~~~ + +**Related sample:** [Grid. BlockSelection. Work with the handle configuration](https://snippet.dhtmlx.com/sryiguxu) + +#### Selection styling + +This example demonstrates how to customize the appearance of the selected range and of the handle. + +~~~html + + + +~~~ + +**Related sample:** [Grid. BlockSelection. Styling (custom CSS)](https://snippet.dhtmlx.com/4k3x4bfm) \ No newline at end of file diff --git a/docs/grid/usage_clipboard.md b/docs/grid/usage_clipboard.md new file mode 100644 index 00000000..a02a9677 --- /dev/null +++ b/docs/grid/usage_clipboard.md @@ -0,0 +1,236 @@ +--- +sidebar_label: Work with Clipboard module +title: JavaScript Grid - Work with Clipboard module +description: You can explore how to work with Clipboard module of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Work with Clipboard module + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +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. + +## Initializing the Clipboard module + +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. + +:::note +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) +::: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + blockSelection: { mode: "range" }, // required for Clipboard to function (initializes automatically) + clipboard: true // enables the Clipboard module +}); +~~~ + +**Related sample**: [Grid. Clipboard with notifications (messages)](https://snippet.dhtmlx.com/2nar7ocd) + +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`. Check the details below. + +## Using events of the Clipboard object + +To make the process of working with clipboard more flexible, you can apply the related events of the `clipboard` object: +[`afterCopy`](grid/api/clipboard/aftercopy_event.md), [`afterPaste`](grid/api/clipboard/afterpaste_event.md), [`beforeCopy`](grid/api/clipboard/beforecopy_event.md), [`beforePaste`](grid/api/clipboard/beforepaste_event.md), [`copyError`](grid/api/clipboard/copyerror_event.md), [`pasteError`](grid/api/clipboard/pasteerror_event.md) + +## Interaction with cell selection + +### Automatic activation of BlockSelection module + +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. + +### Usage in other BlockSelection modes + +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 })`. + +:::note +Without a set range, copying and pasting will not work, as **Clipboard API** relies on data from the **RangeSelection API**. +::: + +### Data source for Clipboard + +The **Clipboard API** always uses data from the [`RangeSelection` API](grid/api/api_overview.md/#rangeselection-api) to determine the cells that will be copied or into which data will be pasted. + +:::note +The `cut`/`paste` operations will be blocked in the [*grouping*](grid/usage.md/#grouping-data) mode. +::: + +## Interaction between Grids and external widgets + +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. + +**Related sample**: [Grid. Clipboard. Copy/сut/paste between grids with validation](https://snippet.dhtmlx.com/q1wj772g) + +**Related sample**: [Grid. Clipboard between Grid and Spreadsheet](https://snippet.dhtmlx.com/hx69j42h) + +### Integration with Google Spreadsheets + +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). + +### Pasting from clipboard + +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: + +- **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. + +- **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". + +The repetition of elements follows the order of copying, starting from the first cell. + +### Copying/pasting cells depending on the column type + +Below you'll find the details on copying/pasting data depending on the type of a column. + +#### Columns with type "date" + +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. + +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. + +#### Columns with type "number" + +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. + +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. + +#### Columns with type "string" + +If `patternMask` is applied to a cell (e.g., for formatting phone numbers or currency), the *formatted* value is copied to the clipboard. +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. + +#### Templates + +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. + +#### Columns with editors "combobox", "multiselect", "select" + +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). + +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. + +## Using formatter functions + +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: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + clipboard: { + // adds a suffix based on the operation + copyModifier: (value, cell, cut) => `${value}${cut ? "-cut" : "-copied"}`, + cutModifier: (value, cell) => `${value}-removed`, // before cutting a value + pasteModifier: (value, cell) => value.replace("-copied", "") // removes the suffix on pasting + } +}); +~~~ + +**Related sample**: [Grid. Clipboard between two Grids with modifiers](https://snippet.dhtmlx.com/h3hxcpog) + +These functions provide flexible control over how data is processed before copying, cutting, or pasting, which is particularly useful in the scenarios described below. + +### Why formatters are needed + +- **Format control**: if the default behavior (e.g., copying numbers without a mask or `id` instead of text in a `combobox`) does not meet the requirements, formatters allow data to be transformed into the desired form. +- **Compatibility**: formatters help adapting data for specific external systems (e.g., preserving number masks or converting dates to a different format). +- **Customization**: you can add additional information (e.g., units of measurement) or remove unnecessary elements from the data. +- **Preprocessing before validation**: `pasteModifier` can preprocess data before it undergoes validation for `date`, `number`, or `boolean` types, ensuring compatibility with the grid's strict typing. + +### How to use formatters + +- **`copyModifier`** + - Applied before copying or cutting data to the clipboard. Allows overriding what is placed in the clipboard. + - Example: To copy the displayed text instead of the `id` for a `combobox`, you can use the cell object (`cell`) to retrieve the desired value. +- **`cutModifier`** + - Applied before cutting to modify the data that goes into the clipboard and leave the original cells in a desired state (e.g., not fully clearing them). + - Example: You can add a suffix to the cut value to indicate its origin. +- **`pasteModifier`** + - Applied before pasting data from the clipboard into cells. Allows transforming the incoming data into a format suitable for the grid, before validation for the `date`, `number`, or `boolean` types. + - Example: If the clipboard contains a formatted date (`"11/04/2025"`) but the data requires `"2025-04-11"`, `pasteModifier` can perform this conversion. + +### Examples + +**Copying numbers with a mask** + +This example demonstrates how to copy numbers while preserving the mask (e.g., `"1,234.56"` instead of `1234.56`). + +~~~jsx +copyModifier: (value, cell, cut) => { + if (cell.column.type === "number" && cell.column.numberMask) { + return new Intl.NumberFormat("en-US", { + minimumFractionDigits: 2 + }).format(value); + } + return value; +} +~~~ + +**Copying the displayed text of the Combobox option** + +This example shows how to copy the combobox option text (`"Option 1"`) instead of the `id` (`"1"`). + +~~~jsx +copyModifier: (value, cell, cut) => { + if (cell.column.editorType === "combobox") { + const options = cell.column.options; + const option = options.find(opt => opt.id === value); + return option ? option.value : value; + } + return value; +} +~~~ + +**Pasting dates with validation** + +This example demonstrates how to transform a date from `"11/04/2025"` to `"2025-04-11"` during pasting and ensure it is valid. + +~~~jsx +pasteModifier: (value, cell) => { + if (cell.column.type === "date") { + const dateFormat = cell.column.dateFormat || "dd/mm/yyyy"; + const regex = /^(\d{2})\/(\d{2})\/(\d{4})$/; // for dd/mm/yyyy + const match = value.match(regex); + if (match) { + const date = new Date(`${match[3]}-${match[2]}-${match[1]}`); + if (!isNaN(date.getTime())) { + return `${match[3]}-${match[2]}-${match[1]}`; // ISO format + } + } + return value; // validation will handle invalid cases + } + return value; +} +~~~ + +**Removing `patternMask` during copying** + +This example shows how to remove mask formatting (e.g., copy `"1234567890"` instead of `"+1 (234) 567-89-0"`). + +~~~jsx +copyModifier: (value, cell, cut) => { + if (cell.column.patternMask) { + return value.replace(/[^0-9]/g, ""); // remove all non-numeric characters + } + return value; +} +~~~ + +**Related sample**: [Grid. Clipboard. Custom copy/cut/paste for number and date columns](https://snippet.dhtmlx.com/dfj49xah) + diff --git a/docs/grid/usage_dragpanel.md b/docs/grid/usage_dragpanel.md new file mode 100644 index 00000000..c8a73173 --- /dev/null +++ b/docs/grid/usage_dragpanel.md @@ -0,0 +1,55 @@ +--- +sidebar_label: Work with DragPanel module +title: JavaScript Grid - Work with DragPanel module +description: You can explore how to work with DragPanel module of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Work with DragPanel module + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +The `DragPanel` module provides auxiliary functionality for moving rows in the **dhx.Grid** component. + +![](../assets/grid/dragpanel_module.png) + +The module is automatically activated when the [Drag-and-Drop functionality](grid/configuration.md/#drag-n-drop) for rows is enabled and conflicting configurations, such as the [`BlockSelection`](grid/usage_blockselection.md) or [`Clipboard`](grid/usage_clipboard.md) modules, are used. + +You can also adjust the appearance and behavior of the `DragPanel` module via the [configuration options](grid/configuration.md/#adjusting-dragpanel-module). + +## Initializing the DragPanel module + +To initialize the `DragPanel` module, use the [`dragPanel`](grid/api/grid_dragpanel_config.md) property in the configuration of the **dhx.Grid** component. The module is also automatically activated if: + +- The row Drag-and-Drop is enabled, e.g. via `dragItem: "row"` or `dragItem: "both"` +- The [`BlockSelection`](grid/usage_blockselection.md) or [`Clipboard`](grid/usage_clipboard.md) modules are enabled + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + dragItem: "both", // enables row Drag-and-Drop + blockSelection: true, // triggers `DragPanel` activation when `dragItem` is enabled + // or + dragPanel: true // enables the `DragPanel` module +}); +~~~ + +**Related sample**: [Grid (TreeGrid). DragPanel. Initialization](https://snippet.dhtmlx.com/uevdwjuo) + +The `dragPanel` property can also be set as an *object* to enable the module and provide additional configuration options. +Learn about configuration possibilities of the drag panel in the [Configuration](grid/configuration.md/#adjusting-dragpanel-module) guide. + +## Using events of the DragPanel module + +To make the process of working with the drag panel more flexible, you can apply the related events of the `DragPanel` module: + +- [`dragPanelItemClick`](grid/api/dragpanel/dragpanelitemclick_event.md) +- [`dragPanelItemMouseDown`](grid/api/dragpanel/dragpanelitemmousedown_event.md) \ No newline at end of file diff --git a/docs/grid/usage_history.md b/docs/grid/usage_history.md new file mode 100644 index 00000000..15cf5aa1 --- /dev/null +++ b/docs/grid/usage_history.md @@ -0,0 +1,453 @@ +--- +sidebar_label: Work with History module +title: JavaScript Grid - Work with History module +description: You can explore how to work with History module of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Work with History module + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +You can manage the history of actions in the Grid component via the API of the [`History`](grid/configuration.md/#history-of-grid-actions) module. It allows tracking changes made by the user through the user interface, such as editing cells using the editor, clearing cells, or applying modifications via the handle in the `BlockSelection` mode. The module supports the `undo` and `redo` operations, as well as allows managing the history stack with the ability to limit its size. + +## Initializing the History module + +To initialize the `History` module, use the [`history`](grid/api/grid_history_config.md) property in the configuration of the **dhx.Grid** component. When the Grid is created, the module is accessible through the `grid.history` property. + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + history: true // enables the History module +}); +~~~ + +The `history` property can also be set as an *object* to enable the module and provide additional configuration options. +Learn about configuration possibilities of the `History` module in the [Configuration](grid/configuration.md/#history-of-grid-actions) guide. + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +## Enabling/disabling History module + +You can activate the history module via the [`enable()`](grid/api/history/enable_method.md) method of the `history` object. The following example shows how the module is enabled after deactivation on initialization: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: { disabled: true } +}); + +// checking the state +console.log(grid.history.isDisabled()); // -> true + +// enabling the module +grid.history.enable(); +console.log(grid.history.isDisabled()); // -> false + +// adding an action +grid.history.add({ + type: "change", + batch: [{ id: "1", name: "Updated Item", value: 15 }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); +console.log(grid.history.getHistory().length); // -> 1 +~~~ + +To disable the management of the history of actions in Grid, use the [`disable()`](grid/api/rangeselection/disable_method.md) method of the `history` object. The following example shows disabling of the module after adding an action: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding an action +grid.history.add({ + type: "change", + batch: [{ id: "1", name: "Updated Item", value: 15 }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); + +// disabling the module +grid.history.disable(); +console.log(grid.history.isDisabled()); // -> true + +// attempting to add a new action +grid.history.add({ + type: "add", + batch: [{ id: "2", name: "New Item", value: 20 }], +}); +console.log(grid.history.getHistory().length); // -> 1 (the new action hasn't been added) +~~~ + +### Checking History module state + +You can check whether the `History` module is disabled, using the [`isDisabled()`](grid/api/history/isdisabled_method.md) method of the `history` object. It returns `true`, if the module is disabled and `false`, if it is enabled. The following example shows checking the module's state after disabling it: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +grid.history.disable(); +console.log(grid.history.isDisabled()); // -> true + +grid.history.enable(); +console.log(grid.history.isDisabled()); // -> false +~~~ + +## Adding/removing Grid history actions + +### Types of actions + +The `History` module supports the following action types within the Grid component: + +- **"add"** - adding rows to the table +- **"remove"** - removing rows from the table +- **"removeAll"** - clearing all the rows +- **"change"** - modifying cell values (requires specifying an inverse action) + +For the "change" and "removeAll" actions, an `inverse` action is mandatory. Otherwise, [adding the action to the history](#adding-a-new-action) will trigger an error. + +### Adding a new action + +You can add a new action into the history of actions within the grid by using the [`add()`](grid/api/history/add_method.md) method of the `history` object. The method takes the following parameters: + +- `action: IAction` - the action object containing: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (mandatory for the "change" and "removeAll" types, not required for other types) + +:::note +The `action` argument must conform to the `IAction` interface. If the module is disabled, the action type is invalid, or the `inverse` property is missing (for actions with the "change" and "removeAll" types), the [`error`](grid/api/history/error_event.md) event is triggered. +::: + +All the actions performed through the API (e.g., using `grid.data`) can be added to the history using the `add()` method. The following example shows adding a new row via `DataCollection`: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding a new row via DataCollection +const newItem = { id: "2", name: "New Item", value: 20 }; +grid.data.add(newItem); + +// recording the action in the history +grid.history.add({ + type: "add", + batch: [{ ...newItem }], +}); + +// checking the history +const history = grid.history.getHistory(); +console.log(history.length); // ->1 +~~~ + +**Related sample:** [Grid. History. Adding a custom action](https://snippet.dhtmlx.com/i9rm4vsd) + +To make the process of adding new actions into the Grid history more flexible, you can apply the related events of the `history` object: +- [`beforeAdd`](grid/api/history/beforeadd_event.md) +- [`afterAdd`](grid/api/history/afteradd_event.md) + +### Removing the last action + +You can remove the last action from the Grid history using the [`remove()`](grid/api/history/remove_method.md) method of the `history` object. Note that if the history is empty or the module is disabled, the operation is ignored and the [`error`](grid/api/history/error_event.md) event is triggered (for a disabled module). + +The following example shows removing the last action from the history after modifying a value: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// modifying a value via DataCollection +const updatedItem = { id: "1", name: "Updated Item", value: 15 }; +grid.data.update("1", updatedItem); + +// adding the action to history +grid.history.add({ + type: "change", + batch: [{ ...updatedItem }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); + +// removing the last action +grid.history.remove(); +console.log(grid.history.getHistory().length); // -> 0 +~~~ + +### Removing all the actions + +You can remove all the actions from the Grid history using the [`removeAll()`](grid/api/history/removeall_method.md) method of the `history` object. The method clears the entire history and the redo stack. Note that if the module is disabled, the operation is ignored and the [`error`](grid/api/history/error_event.md) event is triggered. + +The example below shows clearing the history after adding multiple rows: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding two actions +grid.history.add({ + type: "add", + batch: [{ id: "2", name: "New Item 1", value: 20 }], +}); +grid.history.add({ + type: "add", + batch: [{ id: "3", name: "New Item 2", value: 30 }], +}); + +// clearing the history +grid.history.removeAll(); +console.log(grid.history.getHistory().length); // -> 0 +console.log(grid.history.canRedo()); // -> false +~~~ + +## Applying undo/redo operations to Grid history actions + +### Applying the `undo` operation + +The Grid component allows applying the `undo` operation to the last action in the history via the [`undo()`](grid/api/history/undo_method.md) method of the `history` object. + +Depending on the [type of the action](#types-of-actions), the method either applies the inverse action (for the "change" and "removeAll" types) or restores data (for the "add" and "remove" types). Note that if the history is empty, the module is disabled, or no inverse action is available (for actions with the "change" and "removeAll" types), the [`error`](grid/api/history/error_event.md) event is triggered. + +The following example shows undoing the removal of all rows: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + { id: "2", name: "Item 2", value: 20 }, + ], + history: true +}); + +// removing all rows +const removedData = grid.data.serialize(); +grid.data.removeAll(); +grid.history.add({ + type: "removeAll", + batch: [], + inverse: { type: "add", batch: removedData }, +}); + +// undoing the action +grid.history.undo(); +console.log(grid.history.getHistory().length); // -> 0 +console.log(grid.history.canRedo()); // -> true +~~~ + +### Applying the `redo` operation + +You can reapply the last undone action in the Grid history using the [`redo()`](grid/api/history/redo_method.md) method of the `history` object. Note that if the redo stack is empty or the module is disabled, the [`error`](grid/api/history/error_event.md) event is triggered. + +The example below shows how the undone row addition can be re-applied: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding a new row +const newItem = { id: "2", name: "New Item", value: 20 }; +grid.data.add(newItem); +grid.history.add({ + type: "add", + batch: [{ ...newItem }], +}); + +// undoing and redoing +grid.history.undo(); +grid.history.redo(); +console.log(grid.history.getHistory().length); // -> 1 +console.log(grid.history.canUndo()); // -> true +~~~ + +### Checking whether an action can be undone + +You can check whether an action in the Grid history can be undone using the [`canUndo()`](grid/api/history/canundo_method.md) method of the `history` object. The method returns `true` if the history contains actions and the module is not disabled. + +The following example shows checking whether undo is possible after removing a row: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// removing a row +const removedItem = { id: "1", name: "Item 1", value: 10 }; +grid.data.remove("1"); +grid.history.add({ + type: "remove", + batch: [{ ...removedItem }], +}); + +// checking +if (grid.history.canUndo()) { + console.log("Undo is possible"); + grid.history.undo(); +} +~~~ + +### Checking whether an action can be reapplied + +It is possible to check whether an action in the Grid history can be reapplied using the [`canRedo()`](grid/api/history/canredo_method.md) method of the `history` object. The method returns `true` if the redo stack contains actions and the module is not disabled. + +The following example shows checking whether it is possible to redo an undone action: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// modifying data +const updatedItem = { id: "1", name: "Updated Item", value: 15 }; +grid.data.update("1", updatedItem); +grid.history.add({ + type: "change", + batch: [{ ...updatedItem }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); + +// undoing and checking +grid.history.undo(); +if (grid.history.canRedo()) { + console.log("Redo is possible"); + grid.history.redo(); +} +~~~ + +To make the process of working with the undo/redo operations more flexible, you can apply the related events of the `history` object: [`beforeUndo`](grid/api/history/beforeundo_event.md), [`afterUndo`](grid/api/history/afterundo_event.md), [`beforeRedo`](grid/api/history/beforeredo_event.md), [`afterRedo`](grid/api/history/afterredo_event.md). + +## Getting the history of Grid actions + +You can get a copy of the array of all actions in the Grid history using the [`getHistory()`](grid/api/history/gethistory_method.md) method of the `history` object to prevent accidental modification of the internal structure. + +Each `action` object in the returned array may contain the following properties: + - `type: ActionType` - the type of action: "add", "remove", "removeAll", or "change" + - `batch: IRow[]` - an array of rows representing the data affected by the action (e.g., added, removed, or modified rows) + - `inverse?: IAction` - the inverse action required for undoing (for the "change" and "removeAll" types) + +The example below shows retrieving the history: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "value", header: [{ text: "Value" }] }, + ], + data: [ + { id: "1", name: "Item 1", value: 10 }, + ], + history: true +}); + +// adding actions +grid.history.add({ + type: "change", + batch: [{ id: "1", name: "Updated Item", value: 15 }], + inverse: { type: "change", batch: [{ id: "1", name: "Item 1", value: 10 }] }, +}); +grid.history.add({ + type: "add", + batch: [{ id: "2", name: "New Item", value: 20 }], +}); + +// retrieving the history +const history = grid.history.getHistory(); +console.log(history.length); // -> 2 +~~~ + +## User interface interaction + +The `History` module records actions performed through the user interface, including: + +- cells editing: changes made using the cell editor +- cells clearing: clearing the contents of cells using keyboard navigation +- handle modifications: if the handle is used in the [`BlockSelection` mode](grid/configuration.md/#managing-block-selection-in-grid) and the [`handler`](grid/api/grid_blockselection_config.md/#parameters) function returns an object with the `prev` (the previous cell value) and `current` (the new cell value) fields, these changes are added to the history + +The actions not related to the UI (e.g., programmatic changes via `grid.data`) are not automatically recorded, but can be manually added using the [`add()`](grid/api/history/add_method.md) method. + +## History stack limitation + +If the `limit` parameter is set in the [configuration of the `History` module](grid/api/grid_history_config.md), the history is limited to the specified number of actions. When the limit is exceeded, the oldest actions are automatically removed. + +**Related sample:** [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) + +## Module disabling + +If the module is disabled (via [`disabled: true`](grid/api/grid_history_config.md) in the module configuration or the [`disable()`](grid/api/rangeselection/disable_method.md) method), all the operations ("add", "remove", "removeAll", "change", undo", "redo") are blocked, and the [`error`](grid/api/history/error_event.md) event is triggered. diff --git a/docs/grid/usage_rangeselection.md b/docs/grid/usage_rangeselection.md new file mode 100644 index 00000000..74884ed5 --- /dev/null +++ b/docs/grid/usage_rangeselection.md @@ -0,0 +1,325 @@ +--- +sidebar_label: Work with RangeSelection module +title: JavaScript Grid - Work with RangeSelection module +description: You can explore how to work with RangeSelection module of Grid in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Work with RangeSelection module + +:::tip Pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +You can manage range selection within a grid via the API of the [`RangeSelection`](grid/configuration.md/#managing-range-selection-in-grid) module. It provides methods for setting and resetting a range of cells, getting information about the current range, and checking whether specific cells belong to the selected range. It also supports an [event system](grid/api/api_overview.md/#rangeselection-events) to track changes. + +## Initializing the RangeSelection module + +To initialize the `RangeSelection` module, use the [`rangeSelection`](grid/api/grid_rangeselection_config.md) property in the Grid configuration. Once the Grid is created, the module is accessible through the `grid.range` property. + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true // enables the RangeSelection module +}); +~~~ + +The `rangeSelection` property can also be set as an *object* to enable the module and provide additional configuration options. +Learn about configuration possibilities of the `RangeSelection` module in the [Configuration](grid/configuration.md/#managing-range-selection-in-grid) guide. + +## Enabling/disabling RangeSelection module + +You can activate the range selection module via the [`enable()`](grid/api/rangeselection/enable_method.md) method of the `range` object. +The following example shows how the module is enabled after deactivation on initialization: + +~~~jsx {14} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: { disabled: true } // disabled on initialization +}); + +grid.range.enable(); // activating the module +grid.range.setRange({ xStart: "a", yStart: "1" }); // the range will be set +~~~ + +To disable the range selection in Grid, use the [`disable()`](grid/api/rangeselection/disable_method.md) method of the `range` object. +The example below shows disabling of the `range` module: + +~~~jsx {15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.disable(); // disabling the module +console.log(grid.range.getRange()); // -> null +grid.range.setRange({ xStart: "a", yStart: "1" }); // the range won't be set +~~~ + +## Checking RangeSelection module state + +You can check whether the RangeSelection module is disabled, using the [`isDisabled()`](grid/api/rangeselection/isdisabled_method.md) method of the `range` object. It returns `true`, if the module is disabled and `false`, if it is enabled. The following example shows checking of the module's activity status: + +~~~jsx {15,17} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.disable(); +console.log(grid.range.isDisabled()); // -> true +grid.range.enable(); +console.log(grid.range.isDisabled()); // -> false +~~~ + +## Setting a range selection + +You can set a range selection using the [`setRange()`](grid/api/rangeselection/setrange_method.md) method of the `range` object. The method takes the following parameters: + + + + + + + + + + + + +
range(object) an object with the range coordinates that contains the following options:
  • `xStart` - (string | number) the starting column id
  • `xEnd` - (string | number) the ending column id
  • `yStart` - (string | number) the starting row id
  • `yEnd` - (string | number) the ending row id
join(boolean) defines whether a new range is merged with the current one: +
  • if `join: true` is set, the method merges the new range with the current one. In this case, you can specify just the ending ids of the range, while the starting ids are optional
  • if the `join: false` setting is specified, the method resets the previous range
+ +If not all coordinates are provided, the missing ones are automatically filled (e.g., the last visible column for `xEnd`). The starting id for at least one coordinate is required. The method returns `true` - on success or `false` - on error, event cancellation, or if the module is disabled. + +The following example shows setting of a range with omitted ending coordinates: + +~~~jsx {14} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); // sets range from "a1" to the end +console.log(grid.range.getRange()); // -> { xStart: "a", xEnd: "b", yStart: "1", yEnd: "2" } +~~~ + +The example below demonstrates merging of a new range with the current one: + +~~~jsx {14,15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.setRange({ xEnd: "b", yEnd: "2" }, true); // merges with the current range +console.log(grid.range.getRange()); // -> { xStart: "a", xEnd: "b", yStart: "1", yEnd: "2" } +~~~ + +To make the process of selecting a range more flexible, you can apply the related events of the `range` object: + +- [`afterSetRange`](grid/api/rangeselection/aftersetrange_event.md) +- [`beforeSetRange`](grid/api/rangeselection/beforesetrange_event.md) + +**Related sample**: [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) + +## Resetting the range selection + +You can reset the applied range selection using the [`resetRange()`](grid/api/rangeselection/resetrange_method.md) method of the `range` object. The method returns `true` - on success, `false`, if the module is disabled, or if reset is canceled by an event. + +The following example shows resetting of the current range: + +~~~jsx {15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1" }); +grid.range.resetRange(); +console.log(grid.range.getRange()); // -> null +~~~ + +To make the process of unselecting a range more flexible, you can apply the related events of the `range` object: + +- [`afterResetRange`](grid/api/rangeselection/afterresetrange_event.md) +- [`beforeResetRange`](grid/api/rangeselection/beforeresetrange_event.md) + +## Getting the range selection + +You can get the current selection range. For this, use the [`getRange()`](grid/api/rangeselection/getrange_method.md) method of the `range` object. It returns the object of selection range or `null` if no range is set. The following example shows retrieving of the current range: + +~~~jsx {15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1", xEnd: "b", yEnd: "2" }); +console.log(grid.range.getRange()); // -> { xStart: "a", xEnd: "b", yStart: "1", yEnd: "2" } +~~~ + +The returned object with the current selection range contains the following properties: + + + + + + + + + + + + + + + + + + + + +
xStart(string | number) the starting column id
xEnd(string | number) the ending column id
yStart(string | number) the starting row id
yEnd(string | number) the ending row id
+ +### Getting an array of cells within the range + +It is also possible to get an array of cells within the range selection by using the [`getRangedCells()`](grid/api/rangeselection/getrangedcells_method.md) method of the `range` object. It returns an array of objects where: + + + + + + + + + + + + +
row(object) the row object
column(object) the column object
+ +This example shows retrieving of the range of selected cells: + +~~~jsx {15} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1", xEnd: "b", yEnd: "1" }); +console.log(grid.range.getRangedCells()); // -> [{ row: { id: "1", ... }, column: { id: "a", ... }}, ...] +~~~ + +## Checking whether a cell is in the range + +You can check whether a cell is within the current range using the [`isRanged()`](grid/api/rangeselection/isranged_method.md) method of the `range` object. The method takes the following parameter: + + + + + + + + +
cell(object) - an object with the `x` and `y` coordinates of a cell, where:
  • `x` - (*string | number*) - the column id
  • `y` - (*string | number*) - the row id
+ +:::note +You can specify just `x` or `y` to check a column or a row, correspondingly. +::: + +The method returns `true`, if the cell is within the current range and `false` if it isn't. + +The example below shows checking whether an ID belongs to the selected range of cells: + +~~~jsx {15-17} +const grid = new dhx.Grid("grid_container", { + // other configuration + columns: [ + { id: "a", header: [{ text: "A" }] }, + { id: "b", header: [{ text: "B" }] }, + ], + data: [ + { id: "1", a: "A1", b: "B1" }, + { id: "2", a: "A2", b: "B2" }, + ], + rangeSelection: true +}); + +grid.range.setRange({ xStart: "a", yStart: "1", xEnd: "b", yEnd: "2" }); +console.log(grid.range.isRanged({ x: "a", y: "1" })); // -> true +console.log(grid.range.isRanged({ x: "a" })); // -> true +console.log(grid.range.isRanged({ y: "3" })); // -> false +~~~ \ No newline at end of file diff --git a/docs/grid/usage_selection.md b/docs/grid/usage_selection.md index 58b73efe..329b2d40 100644 --- a/docs/grid/usage_selection.md +++ b/docs/grid/usage_selection.md @@ -6,43 +6,43 @@ description: You can explore how to work with Selection Object of Grid in the do # Work with Selection object -You can manipulate with Grid cells via the API of the selection object. It is possible to get the object of one or more selected cells or rows, to set selection as to a single row or cell as to multiple rows or cells. The selection object also allows removing selection from previously selected cells. +You can manipulate with Grid cells via the API of the `selection` object. It is possible to get the object of one or more selected cells or rows, to set selection both to a single row or cell and to multiple rows or cells. The `selection` object also allows removing selection from previously selected cells. -## Enabling/Disabling Selection object +## Enabling/disabling Selection object -Starting from v7.0, you can activate selection of cells via the [](grid/api/selection/selection_enable_method.md) method of the selection object. +Starting from v7.0, you can activate selection of cells via the [`enable`](grid/api/selection/selection_enable_method.md) method of the `selection` object. -~~~js +~~~jsx grid.selection.enable(); ~~~ -To disable selection of cells in Grid, make use of the [](grid/api/selection/selection_disable_method.md) method of the selection object: +To disable selection of cells in Grid, make use of the [`disable`](grid/api/selection/selection_disable_method.md) method of the `selection` object: -~~~js +~~~jsx grid.selection.disable(); ~~~ ## Setting selection to cells -You can set selection to one or more rows or cells using the [setCell()](grid/api/selection/selection_setcell_method.md) method of the selection object. The method takes the following parameters: +You can set selection to one or more rows or cells using the [`setCell()`](grid/api/selection/selection_setcell_method.md) method of the `selection` object. The method takes the following parameters: - + - + - + - +
row(object|string) an object with a cell to be selected or the id of a row(object | string) an object with a cell to be selected or the id of a row
column(object|string) the config of a column or its id(object | string) the config of a column or its id
ctrlUp(boolean) true - to select the desired rows or cells, otherwise - false (for multiselection mode)(boolean) true - to select the desired rows or cells, otherwise - false (for the `multiselection` mode)
shiftUp(boolean) true - to select a range of rows or cells, otherwise - false (for multiselection mode)(boolean) true - to select a range of rows or cells, otherwise - false (for the `multiselection` mode)
@@ -53,7 +53,7 @@ You can set selection to one or more rows or cells using the [setCell()](grid/ap The example below shows how to highlight the first cell in the "Yearly Change" column: -~~~js {6} +~~~jsx {6} const grid = new dhx.Grid("grid_container", { columns: [ // columns config @@ -70,15 +70,17 @@ grid.selection.setCell(row, column); **Related sample**: [Grid. Multiselection](https://snippet.dhtmlx.com/4nj0e9ye) -{{note The **multiselection** property is disabled.}} +:::note +The `multiselection` property is disabled. +::: ### Setting selection to multiple cells/rows -You can highlight the desired cells when the [multiselection:true](grid/api/grid_multiselection_config.md) and the [selection:"cell"](grid/api/grid_selection_config.md) properties are set: +You can highlight the desired cells when the [`multiselection:true`](grid/api/grid_multiselection_config.md) and the [`selection:"cell"`](grid/api/grid_selection_config.md) properties are set: ![](../assets/grid/desired_setcell.png) -~~~js {5,6} +~~~jsx {5,6} const grid = new dhx.Grid("grid_container", { columns: [ // columns config @@ -99,40 +101,77 @@ It is also possible to select a range of cells at once: ![](../assets/grid/range_setcell.png) -For that, manipulate the **ctrlUp** and **shiftUp** parameters accordingly: +For that, manipulate the `ctrlUp` and `shiftUp` parameters accordingly: -~~~js +~~~jsx grid.selection.setCell(grid.data.getId(1),"yearlyChange"); grid.selection.setCell(grid.data.getId(3),"density", false, true); ~~~ **Related sample**: [Grid. Multiselection](https://snippet.dhtmlx.com/4nj0e9ye) -{{note Use the **selection:"rows"** property to be able to operate rows. }} +:::note +Use the `selection:"rows"` property to be able to operate rows. +::: -To make the process of selecting cells more flexible, you can apply the related events of the selection object: +To make the process of selecting cells more flexible, you can apply the related events of the `selection` object: -- [afterSelect](grid/api/selection/selection_afterselect_event.md) -- [beforeSelect](grid/api/selection/selection_beforeselect_event.md) +- [`afterSelect`](grid/api/selection/selection_afterselect_event.md) +- [`beforeSelect`](grid/api/selection/selection_beforeselect_event.md) + +## Checking whether a cell is selected + +You can check whether a particular cell is selected using the [`isSelectedCell()`](grid/api/selection/selection_isselectedcell_method.md) method of the `selection` object. The method takes the following parameters: + + + + + + + + + + + + +
row(IRow | Id) an object with a cell to be checked or the id of a row
column(ICol | Id) the config of a column or its id
+ +~~~jsx {14} +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + selection:"cell", + multiselection: false, + data: dataset +}); + +const row = grid.data.getItem(grid.data.getId(0)); +const column = grid.getColumn("project"); +grid.selection.setCell(row,column); + +const selectedCell = grid.selection.isSelectedCell(row,column); +console.log(selectedCell); // -> true +~~~ ## Removing selection -Starting from v7.0, you can remove selection from a selected cell/row or from highlighted cells/rows using the [](grid/api/selection/selection_removecell_method.md) method of the selection object. The method takes two parameters: +Starting from v7.0, you can remove selection from a selected cell/row or from highlighted cells/rows using the [`removeCell`](grid/api/selection/selection_removecell_method.md) method of the `selection` object. The method takes two parameters: - + - +
rowId(string|number) optional, the id of a row(string | number) optional, the id of a row
colId(string|number) optional, the id of a column(string | number) optional, the id of a column
-~~~js +~~~jsx // unselects all previously selected cells grid.selection.removeCell(); @@ -143,23 +182,23 @@ grid.selection.removeCell(rowId); grid.selection.removeCell(rowId, colId); ~~~ -To make the process of unselecting cells more flexible, you can apply the related events of the selection object: +To make the process of unselecting cells more flexible, you can apply the related events of the `selection` object: -- [afterUnSelect](grid/api/selection/selection_afterunselect_event.md) -- [beforeUnSelect](grid/api/selection/selection_beforeunselect_event.md) +- [`afterUnSelect`](grid/api/selection/selection_afterunselect_event.md) +- [`beforeUnSelect`](grid/api/selection/selection_beforeunselect_event.md) ## Getting object of selected cells -To get the object of a selected Grid cell, use the [getCell()](grid/api/selection/selection_getcell_method.md) method of the selection object: +To get the object of a selected Grid cell, use the [`getCell()`](grid/api/selection/selection_getcell_method.md) method of the `selection` object: -~~~js +~~~jsx const selectedCell = grid.selection.getCell(); // -> {row: {…}, column: {…}} ~~~ -To get the object of multiple selected cells, use the [getCells()](grid/api/selection/selection_getcells_method.md) method of the selection object: +To get the object of multiple selected cells, use the [`getCells()`](grid/api/selection/selection_getcells_method.md) method of the `selection` object: -~~~js +~~~jsx const selectedCells = grid.selection.getCells(); // -> [{…}, {…}, {…}] 0: {row: {…}, column: {…}} diff --git a/docs/menu/creating_context_menu.md b/docs/menu/creating_context_menu.md index 7e2714ce..3db94f18 100644 --- a/docs/menu/creating_context_menu.md +++ b/docs/menu/creating_context_menu.md @@ -16,22 +16,28 @@ dhtmlxContextMenu is a component that provides an easy way to add a contextual m You can initialize dhtmlxContextMenu with the constructor: -~~~js +~~~jsx const cmenu = new dhx.ContextMenu(null, {css: "dhx_widget--bg_gray"}); ~~~ It takes two parameters: -- *container* - optional, set it to *null*, since ContentMenu is created inside a popup -- *config* - optional, a configuration object. You can set the CSS classes to style a context menu here +- `container` - optional, set it to *null*, since ContextMenu is created inside a popup +- `config` - optional, a configuration object. It may contain the following properties: + - `css` - adds style classes to ContextMenu + - `data` - specifies an array of data objects to set into ContextMenu + - `navigationType` - defines the action that opens context menu options: + - "click" - displays the context menu option when a user clicks on it + - "pointer" - displays the context menu option when a user hovers the mouse pointer over it ## Loading menu options -Like with DHTMLX Menu, options can be either parsed from a JSON array: +dhtmlxContextMenu expects loaded data in the JSON format. Here is an example of an appropriate data set: -~~~js -const data = [ - { value: "File", +~~~jsx +const dataset = [ + { + value: "File", items: [ { value: "New File", icon: "dxi dxi-file-outline"}, { value: "Remove File", icon: "dxi dxi-delete"} @@ -40,7 +46,8 @@ const data = [ { type: "separator" }, - { value: "Edit", + { + value: "Edit", items: [ { value: "Undo", icon: "dxi dxi-undo"}, { value: "Redo", icon: "dxi dxi-redo"} @@ -50,19 +57,36 @@ const data = [ type: "spacer" } ]; +~~~ + +A data set consists of objects with configurations of context menu controls. + +Like with [DHTMLX Menu](menu/data_loading.md), options can be: + +- either loaded into the ContextMenu on initialization via the `data` configuration property: + +~~~jsx +const cmenu = new dhx.ContextMenu(null, { + css: "dhx_widget--bg_gray" + data: dataset +}); +~~~ + +- or parsed from a JSON array: -cmenu.data.parse(data); +~~~jsx +cmenu.data.parse(dataset); ~~~ -or loaded from a JSON file: +- or loaded from a JSON file: -~~~js +~~~jsx cmenu.data.load("[path_to_file]/file.json"); ~~~ ## Showing dhtmlxContextMenu -dhtmlxContextMenu is attached to a context zone, and can be shown with the **showAt()** method. It takes two parameters: +dhtmlxContextMenu is attached to a context zone, and can be shown with the `showAt()` method. It takes two parameters: @@ -85,7 +109,7 @@ This is how you can attach dhtmlxContextMenu to an HTML element: ~~~ -~~~js +~~~jsx const cmenu = new dhx.ContextMenu(null, {css: "dhx_widget--bg_gray"}); document.querySelector('#menu').oncontextmenu = function(e) { @@ -100,7 +124,7 @@ document.querySelector('#menu').oncontextmenu = function(e) { This is how you can attach dhtmlxContextMenu to a mouse event: -~~~js +~~~jsx const cmenu = new dhx.ContextMenu(null, {css: "dhx_widget--bg_gray"}); document.querySelector('#menu').oncontextmenu = function(e) { diff --git a/docs/migration.md b/docs/migration.md index b38e6cd7..c1a4dfb5 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -6,6 +6,33 @@ description: You can explore how to migrate to newer versions in the documentati # Migration to newer versions +9.1 -> 9.2 +----------- + +### Grid + +Since v9.2 the Grid component uses the WebAssembly-based library [Json2Excel](https://github.com/dhtmlx/json2excel) for [exporting Grid data to an Excel file](grid/usage.md/#exporting-data-to-excel). By default, you don't need to specify the link to the export module. + +However, if you use your own export server, you need to install the **Json2Excel** library and provide the local path to the export module on your computer by setting the path to the **worker.js** file as `"../libs/json2excel/1.3/worker.js?vx"`: + +~~~jsx title="Before v9.2" +grid.export.xlsx({ + url: "https://export.dhtmlx.com/excel", // optional, the link to the export module + // more export settings +}); +~~~ + +~~~jsx title="From v9.2" +grid.export.xlsx({ + url: "../libs/json2excel/1.3/worker.js?vx", // optional, a local path to the export module + // more export settings +}); +~~~ + +:::info +The previously used export module server is still available for the Suite versions up to v9.1. +::: + 9.0 -> 9.1 ----------- diff --git a/docs/whatsnew.md b/docs/whatsnew.md index 58be8e0c..bec86fcb 100644 --- a/docs/whatsnew.md +++ b/docs/whatsnew.md @@ -8,6 +8,170 @@ description: You can explore what's new in DHTMLX Suite and its release history Before updating DHTMLX to the latest version, please check the [Migration to Newer Versions](migration.md) guide to avoid possible breakdowns. +## Version 9.2 + +Released on July X, 2025 + +Review of the release on the blog + +### Breaking changes + +This version brings some updates in the use of the export module used for [exporting Grid data to an Excel file](grid/usage.md/#exporting-data-to-excel). Check the [Migration](migration.md#91---92) guide to keep in step with the latest updates. + +### New functionality + +- Grid. The [`RangeSelection` module](grid/usage_rangeselection.md) is added to provide functionality for managing range selection in Grid (PRO version) + - new Grid configuration property: [`rangeSelection`](grid/api/grid_rangeselection_config.md) + - new methods of the `range` object: [`disable()`](grid/api/rangeselection/disable_method.md), [`enable()`](grid/api/rangeselection/enable_method.md), [`getRange()`](grid/api/rangeselection/getrange_method.md), [`getRangedCells()`](grid/api/rangeselection/getrangedcells_method.md), [`isDisabled()`](grid/api/rangeselection/isdisabled_method.md), [`isRanged()`](grid/api/rangeselection/isranged_method.md), [`resetRange()`](grid/api/rangeselection/resetrange_method.md), [`setRange()`](grid/api/rangeselection/setrange_method.md) + - new events of the `range` object: [`afterResetRange`](grid/api/rangeselection/afterresetrange_event.md), [`afterSetRange`](grid/api/rangeselection/aftersetrange_event.md), [`beforeResetRange`](grid/api/rangeselection/beforeresetrange_event.md), [`beforeSetRange`](grid/api/rangeselection/beforesetrange_event.md) +- Grid. The [`BlockSelection` module](grid/usage_blockselection.md) is added to provide functionality for managing block selection in Grid (PRO version) + - new Grid configuration property: [`blockSelection`](grid/api/grid_blockselection_config.md) + - new methods of the `block` object: [`disable()`](grid/api/blockselection/disable_method.md), [`enable()`](grid/api/blockselection/enable_method.md), [`isDisabled()`](grid/api/blockselection/isdisabled_method.md) + - new events of the `block` object: [`afterBlockHandleApply`](grid/api/blockselection/afterblockhandleapply_event.md), [`afterBlockSelectionApply`](grid/api/blockselection/afterblockselectionapply_event.md), [`afterBlockSelectionMove`](grid/api/blockselection/afterblockselectionmove_event.md), [`beforeBlockHandleApply`](grid/api/blockselection/beforeblockhandleapply_event.md), [`beforeBlockSelectionApply`](grid/api/blockselection/beforeblockselectionapply_event.md), [`beforeBlockSelectionMove`](grid/api/blockselection/beforeblockselectionmove_event.md), [`blockHandleMouseDown`](grid/api/blockselection/blockhandlemousedown_event.md), [`blockSelectionEnd`](grid/api/blockselection/blockselectionend_event.md), [`blockSelectionStart`](grid/api/blockselection/blockselectionstart_event.md), [`blockSelectionValidate`](grid/api/blockselection/blockselectionvalidate_event.md) +- Grid. The [`Clipboard` module](grid/usage_clipboard.md) is added to provide functionality for interacting with the clipboard in Grid (PRO version) + - new Grid configuration property: [`clipboard`](grid/api/grid_clipboard_config.md) + - new events of the `clipboard` object: [`afterCopy`](grid/api/clipboard/aftercopy_event.md), [`afterPaste`](grid/api/clipboard/afterpaste_event.md), [`beforeCopy`](grid/api/clipboard/beforecopy_event.md), [`beforePaste`](grid/api/clipboard/beforepaste_event.md), [`copyError`](grid/api/clipboard/copyerror_event.md), [`pasteError`](grid/api/clipboard/pasteerror_event.md) +- Grid. The [`DragPanel` module](grid/usage_dragpanel.md) is added to provide auxiliary functionality for moving rows in Grid and improve the drag-n-drop visualization (PRO version) + - new Grid configuration property: [`dragPanel`](grid/api/grid_dragpanel_config.md) + - new events: [`dragPanelItemClick`](grid/api/dragpanel/dragpanelitemclick_event.md), [`dragPanelItemMouseDown`](grid/api/dragpanel/dragpanelitemmousedown_event.md) +- Grid. The [`History` module](grid/usage_history.md) is added to provide functionality for managing the history of actions in Grid, including the [Undo/Redo functionality](grid/usage_history.md/#applying-undoredo-operations-to-grid-history-actions) (PRO version) + - new Grid configuration property: [`history`](grid/api/grid_history_config.md) + - new methods of the `history` object: [`add()`](grid/api/history/add_method.md), [`canRedo()`](grid/api/history/canredo_method.md), [`canUndo()`](grid/api/history/canundo_method.md), [`disable()`](grid/api/history/disable_method.md), [`enable()`](grid/api/history/enable_method.md), [`isDisabled()`](grid/api/history/isdisabled_method.md), [`getHistory()`](grid/api/history/gethistory_method.md), [`redo()`](grid/api/history/redo_method.md), [`remove()`](grid/api/history/remove_method.md), [`removeAll()`](grid/api/history/removeall_method.md), [`undo()`](grid/api/history/undo_method.md) + - new events of the `history` object: [`afterAdd`](grid/api/history/afteradd_event.md), [`afterRedo`](grid/api/history/afterredo_event.md), [`afterUndo`](grid/api/history/afterundo_event.md), [`beforeAdd`](grid/api/history/beforeadd_event.md), [`beforeRedo`](grid/api/history/beforeredo_event.md), [`beforeUndo`](grid/api/history/beforeundo_event.md), [`error`](grid/api/history/error_event.md) +- Grid. The [`isSelected()`](grid/api/selection/selection_isselectedcell_method.md) method is added for the [`Selection` module](grid/usage_selection.md) to check whether the specified cell is selected + +### Updates + +- Grid. The logic and appearance of the [drag-n-drop functionality](grid/configuration.md/#drag-n-drop) is improved. Check the [related sample](https://snippet.dhtmlx.com/uevdwjuo) +- Grid. The [export to Excel](grid/usage.md/#exporting-data-to-excel) functionality is updated. The [Json2Excel](https://github.com/dhtmlx/json2excel) module is now used for exporting Grid data to Excel. Check the [Migration guide](migration.md/#91---92) for details +- Grid. The [`xlsx()`](grid/api/export/grid_xlsx_method.md) method of the Export module gets two new configuration settings: + - `tableName`- to set the name of a sheet with grid data in the Excel file + - `dateFormatMask` - to set the date format mask for Excel +- Grid. The possibility to use keyboard navigation for [selecting ranges of cells](grid/configuration.md/#shortcut-keys-for-selecting-ranges-of-cells). The following shortcut keys and their combinations are available: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArrowUpresets the selected range and moves the focus to the previous vertical cell, setting the initially selected cell if no selection is active
ArrowDownresets the selected range and moves the focus to the next vertical cell, setting the initially selected cell if no selection is active
ArrowLeftresets the selected range and moves the focus to the previous horizontal cell, setting the initially selected cell if no selection is active
ArrowRightresets the selected range and moves the focus to the next horizontal cell, setting the initially selected cell if no selection is active
Shift+ArrowUpextends the selected range from the current initial cell to the previous vertical cell
Shift+ArrowDownextends the selected range from the current initial cell to the next vertical cell
Shift+ArrowLeftextends the selected range from the current initial cell to the previous horizontal cell
Shift+ArrowRightextends the selected range from the current initial cell to the next horizontal cell
Ctrl+ArrowUpresets the selected range and moves the focus to the first vertical cell
Ctrl+ArrowDownresets the selected range and moves the focus to the last vertical cell
Ctrl+ArrowLeftresets the selected range and moves the focus to the first horizontal cell
Ctrl+ArrowRightresets the selected range and moves the focus to the last horizontal cell
Ctrl+Shift+ArrowUpextends the selected range to the first vertical cell
Ctrl+Shift+ArrowDownextends the selected range to the last vertical cell
Ctrl+Shift+ArrowLeft extends the selected range to the first horizontal cell
Ctrl+Shift+ArrowRight extends the selected range to the last horizontal cell
+ +The following shortcut key and mouse combination is available: + + + + + + + + +
Shift + clicksets the end cell of the range, extending the selection from the current initial cell
+ +The following shortcut key is available when the [`editable` mode](grid/api/grid_editable_config.md) is set for the Grid component and the `BlockSelection` module is used in the `"range"` mode: + + + + + + + + +
Deleteallows clearing the selected cells
+ +### Fixes + +- DragManager. Incorrect determining the position for dropping an element during the Drag&Drop operation (child elements) in the TreeGrid mode +- DragManager. The issue with moving a line to the header/footer area +- DragManager. The problem with determining the position for dropping above the first element +- DragManager. The issue associated with the absence or incorrect definition of the drop position for the default mode +- DragManager. The issue with the `dragIn` event (the previous reset state was transmitted) +- DragManager. The `dragIn/dragOut` events are optimized (false positives are removed) +- Grid. The issue with falsy selection of fixed cells while selecting unfrozen cells +- Grid. The issue with dragging unselected items +- Grid. Sorting of the Date string (ISO) values results in the invalid format error +- Grid. Export. Double quotes in the cell value are escaped in the exported Excel +- Grid. The issue with editor closing and saving the entered value on scrolling the grid +- Grid. The `draggable:false` setting of a column affects the drag-n-drop of rows + +### New samples + +#### Grid + +- [Grid (TreeGrid). DragPanel. Initialization](https://snippet.dhtmlx.com/uevdwjuo) +- [Grid. BlockSelection in the "range" mode. Selection with restricted columns](https://snippet.dhtmlx.com/42fp5qvt) +- [Grid. BlockSelection. Work with the handle configuration](https://snippet.dhtmlx.com/sryiguxu) +- [Grid. BlockSelection. Styling (custom CSS)](https://snippet.dhtmlx.com/4k3x4bfm) +- [Grid. Clipboard with notifications (messages)](https://snippet.dhtmlx.com/2nar7ocd) +- [Grid. Clipboard. Custom copy/cut/paste for number and date columns](https://snippet.dhtmlx.com/dfj49xah) +- [Grid. Clipboard. Copy/сut/paste between grids with validation](https://snippet.dhtmlx.com/q1wj772g) +- [Grid. Clipboard between two Grids with modifiers](https://snippet.dhtmlx.com/h3hxcpog) +- [Grid. Clipboard between Grid and Spreadsheet](https://snippet.dhtmlx.com/hx69j42h) +- [Grid. History. Configuration](https://snippet.dhtmlx.com/vznpyeit) +- [Grid. History. Adding a custom action](https://snippet.dhtmlx.com/i9rm4vsd) + + ## Version 9.1.6 Released on June 23, 2025 @@ -98,10 +262,18 @@ This version brings some updates in the API methods. Check the [Migration](migra ### New functionality +#### DataCollection/TreeCollection + +- The new [`getSortingStates()`](data_collection/api/datacollection_getsortingstates_method.md) method to get the current state of data sorting (including sorting by multiple columns) + #### Grid - [Row expander](grid/configuration.md#row-expander) with the possibility to insert any Suite widget or HTML content (PRO version) + - new Grid configuration property: [`subRow`](grid/api/grid_subrow_config.md) + - new Grid configuration property: [`subRowConfig`](grid/api/grid_subrowconfig_config.md) + - new method: [`getSubRow()`](grid/api/grid_getsubrow_method.md) - [Multi-sorting](grid/usage.md#sorting-by-multiple-columns) functionality that allows sorting Grid by several columns (PRO version) + - new Grid configuration property: [`multiSort`](grid/api/grid_multisort_config.md) ### Fixes diff --git a/sidebars.js b/sidebars.js index 08066c69..d6626e1a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -2615,7 +2615,9 @@ module.exports = { "grid/api/grid_autoemptyrow_config", "grid/api/grid_autoheight_config", "grid/api/grid_autowidth_config", + "grid/api/grid_blockselection_config", "grid/api/grid_bottomsplit_config", + "grid/api/grid_clipboard_config", "grid/api/grid_closable_config", "grid/api/grid_collapsed_config", "grid/api/grid_columns_config", @@ -2625,6 +2627,7 @@ module.exports = { "grid/api/grid_dragexpand_config", "grid/api/grid_dragitem_config", "grid/api/grid_dragmode_config", + "grid/api/grid_dragpanel_config", "grid/api/grid_editable_config", "grid/api/grid_eventhandlers_config", "grid/api/grid_exportstyles_config", @@ -2637,11 +2640,13 @@ module.exports = { "grid/api/grid_headerrowheight_config", "grid/api/grid_headertooltip_config", "grid/api/grid_height_config", + "grid/api/grid_history_config", "grid/api/grid_htmlenable_config", "grid/api/grid_keynavigation_config", "grid/api/grid_leftsplit_config", "grid/api/grid_multiselection_config", "grid/api/grid_multisort_config", + "grid/api/grid_rangeselection_config", "grid/api/grid_resizable_config", "grid/api/grid_rightsplit_config", "grid/api/grid_rootparent_config", @@ -2736,6 +2741,7 @@ module.exports = { "grid/api/selection/selection_enable_method", "grid/api/selection/selection_getcell_method", "grid/api/selection/selection_getcells_method", + "grid/api/selection/selection_isselectedcell_method", "grid/api/selection/selection_removecell_method", "grid/api/selection/selection_setcell_method", ], @@ -2763,6 +2769,103 @@ module.exports = { }, ], }, + { + type: "category", + label: "RangeSelection API", + link: { + type: 'generated-index', + title: "RangeSelection API", + keywords: ['rangeselection API'], + image: '/img/docusaurus.png' + }, + items: [{ + type: "category", + label: "Grid RangeSelection methods", + link: { + type: 'generated-index', + title: "Grid RangeSelection methods", + keywords: ['grid range selection methods'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/rangeselection/disable_method", + "grid/api/rangeselection/enable_method", + "grid/api/rangeselection/getrange_method", + "grid/api/rangeselection/getrangedcells_method", + "grid/api/rangeselection/isdisabled_method", + "grid/api/rangeselection/isranged_method", + "grid/api/rangeselection/resetrange_method", + "grid/api/rangeselection/setrange_method", + ], + }, + + { + type: "category", + label: "Grid RangeSelection events", + link: { + type: 'generated-index', + title: "Grid RangeSelection events", + keywords: ['grid range selection events'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/rangeselection/afterresetrange_event", + "grid/api/rangeselection/aftersetrange_event", + "grid/api/rangeselection/beforeresetrange_event", + "grid/api/rangeselection/beforesetrange_event", + ], + }, + ], + }, + { + type: "category", + label: "BlockSelection API", + link: { + type: 'generated-index', + title: "BlockSelection API", + keywords: ['block selection API'], + image: '/img/docusaurus.png' + }, + items: [{ + type: "category", + label: "Grid BlockSelection methods", + link: { + type: 'generated-index', + title: "Grid BlockSelection methods", + keywords: ['grid block selection methods'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/blockselection/disable_method", + "grid/api/blockselection/enable_method", + "grid/api/blockselection/isdisabled_method" + ], + }, + + { + type: "category", + label: "Grid BlockSelection events", + link: { + type: 'generated-index', + title: "Grid BlockSelection events", + keywords: ['grid block selection events'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/blockselection/afterblockhandleapply_event", + "grid/api/blockselection/afterblockselectionapply_event", + "grid/api/blockselection/afterblockselectionmove_event", + "grid/api/blockselection/beforeblockhandleapply_event", + "grid/api/blockselection/beforeblockselectionapply_event", + "grid/api/blockselection/beforeblockselectionmove_event", + "grid/api/blockselection/blockhandlemousedown_event", + "grid/api/blockselection/blockselectionend_event", + "grid/api/blockselection/blockselectionstart_event", + "grid/api/blockselection/blockselectionvalidate_event" + ], + } + ], + }, { type: "category", label: "Export methods", @@ -2780,6 +2883,92 @@ module.exports = { "grid/api/export/grid_xlsx_method" ], }, + { + type: "category", + label: "Clipboard events", + collapsed: true, + link: { + type: 'generated-index', + title: "Clipboard events", + keywords: ['clipboard events'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/clipboard/aftercopy_event", + "grid/api/clipboard/afterpaste_event", + "grid/api/clipboard/beforecopy_event", + "grid/api/clipboard/beforepaste_event", + "grid/api/clipboard/copyerror_event", + "grid/api/clipboard/pasteerror_event" + ], + }, + { + type: "category", + label: "DragPanel events", + collapsed: true, + link: { + type: 'generated-index', + title: "DragPanel events", + keywords: ['drag panel events'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/dragpanel/dragpanelitemclick_event", + "grid/api/dragpanel/dragpanelitemmousedown_event" + ], + }, + { + type: "category", + label: "History API", + link: { + type: 'generated-index', + title: "History API", + keywords: ['history API'], + image: '/img/docusaurus.png' + }, + items: [{ + type: "category", + label: "Grid History methods", + link: { + type: 'generated-index', + title: "Grid History methods", + keywords: ['grid history methods'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/history/add_method", + "grid/api/history/canredo_method", + "grid/api/history/canundo_method", + "grid/api/history/disable_method", + "grid/api/history/enable_method", + "grid/api/history/isdisabled_method", + "grid/api/history/gethistory_method", + "grid/api/history/redo_method", + "grid/api/history/remove_method", + "grid/api/history/removeall_method", + "grid/api/history/undo_method" + ], + }, + { + type: "category", + label: "Grid History events", + link: { + type: 'generated-index', + title: "Grid History events", + keywords: ['grid history events'], + image: '/img/docusaurus.png' + }, + items: [ + "grid/api/history/afteradd_event", + "grid/api/history/afterredo_event", + "grid/api/history/afterundo_event", + "grid/api/history/beforeadd_event", + "grid/api/history/beforeredo_event", + "grid/api/history/beforeundo_event", + "grid/api/history/error_event" + ], + }], + }, ], }, "grid/features", @@ -2790,8 +2979,13 @@ module.exports = { "grid/usage", "grid/treegrid_mode", "grid/usage_selection", + "grid/usage_rangeselection", + "grid/usage_blockselection", + "grid/usage_clipboard", + "grid/usage_dragpanel", + "grid/usage_history", "grid/customization", - "grid/events", + "grid/events" ], }, // end Grid