blockSelection
pro version only
This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.
Optional. Enables/disables the BlockSelection module during the Grid initialization
Usage
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 value: 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
});
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:
|
| 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 module is initialized.
This example demonstrates configuring the module with the handle disabled and the "range" mode enabled:
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:
/* 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
Related articles:
Change log:
added in v9.2