JavaScript Data GridCustomBorders
Description
This plugin enables an option to apply custom borders through the context menu (configurable with context menu key
borders
).
To initialize Handsontable with predefined custom borders, provide cell coordinates and border styles in a form of an array.
See customBorders
configuration option or go to
Custom cell borders demo for more examples.
Example
customBorders: [
{
range: {
from: {
row: 1,
col: 1
},
to: {
row: 3,
col: 4
},
},
start: {},
end: {},
top: {},
bottom: {},
},
],
// or
customBorders: [
{ row: 2,
col: 2,
start: {
width: 2,
color: 'red',
},
end: {
width: 1,
color: 'green',
},
top: '',
bottom: '',
}
],
Options
customBorders
Source codecustomBorders.customBorders : boolean | Array<object>
The customBorders
option configures the CustomBorders
plugin.
To enable the CustomBorders
plugin
(and add its menu items to the context menu),
set the customBorders
option to true
.
To enable the CustomBorders
plugin
and add a predefined border around a particular cell,
set the customBorders
option to an array of objects.
Each object represents a border configuration for one cell, and has the following properties:
Property | Sub-properties | Types | Description |
---|---|---|---|
row | - | row : Number | The cell's row coordinate. |
col | - | col : Number | The cell's column coordinate. |
start | width color | width : Numbercolor : String | If the layout direction is LTR (default): start sets the width (width ) and color (color ) of the left-hand border.If the layout direction is RTL: start sets the width (width ) and color (color ) of the right-hand border. |
end | width color | width : Numbercolor : String | If the layout direction is LTR (default): end sets the width (width ) and color (color ) of the right-hand border.If the layout direction is RTL: end sets the width (width ) and color (color ) of the left-hand border. |
top | width color | width : Numbercolor : String | Sets the width (width ) and color (color ) of the top border. |
bottom | width color | width : Numbercolor : String | Sets the width (width ) and color (color ) of the bottom border. |
To enable the CustomBorders
plugin
and add a predefined border around a range of cells,
set the customBorders
option to an array of objects.
Each object represents a border configuration for a single range of cells, and has the following properties:
Property | Sub-properties | Types | Description |
---|---|---|---|
range | from {row , col }to {row , col } | from : Objectto : Objectrow : Numbercol : Number | If the layout direction is LTR (default): - from selects the range's top-left corner.- to selects the range's bottom-right corner.If the layout direction is RTL: - from selects the range's top-right corner.- to selects the range's bottom-left corner. |
start | width color | width : Numbercolor : String | If the layout direction is LTR (default): start sets the width (width ) and color (color ) of the left-hand border.If the layout direction is RTL: start sets the width (width ) and color (color ) of the right-hand border. |
end | width color | width : Numbercolor : String | If the layout direction is LTR (default): end sets the width (width ) and color (color ) of the right-hand border.If the layout direction is RTL: end sets the width (width ) and color (color ) of the left-hand border. |
top | width color | width : Numbercolor : String | Sets the width (width ) and color (color ) of the top border. |
bottom | width color | width : Numbercolor : String | Sets the width (width ) and color (color ) of the bottom border. |
Read more:
- Formatting cells: Custom cell borders
- Context menu
- Plugins:
CustomBorders
- Layout direction
layoutDirection
Default: false
Example
// enable the `CustomBorders` plugin
customBorders: true,
// enable the `CustomBorders` plugin
// and add a predefined border for a particular cell
customBorders: [
// add an object with a border configuration for one cell
{
// set the cell's row coordinate
row: 2,
// set the cell's column coordinate
col: 2,
// set the left/right border's width and color
start: {
width: 2,
color: 'red'
},
// set the right/left border's width and color
end: {
width: 1,
color: 'green'
},
// set the top border's width and color
top: '',
// set the bottom border's width and color
bottom: ''
}
],
// enable the `CustomBorders` plugin
// and add a predefined border for a range of cells
customBorders: [
// add an object with a border configuration for one range of cells
{
// select a range of cells
range: {
// set the range's top-left corner
from: {
row: 1,
col: 1
},
// set the range's bottom-right corner
to: {
row: 3,
col: 4
}
},
// set the left/right border's width and color
start: {
width: 2,
color: 'red'
},
// set the right/left border's width and color
end: {},
// set the top border's width and color
top: {},
// set the bottom border's width and color
bottom: {}
}
],
Methods
clearBorders
Source codecustomBorders.clearBorders(selectionRanges)
Clear custom borders.
Example
const customBordersPlugin = hot.getPlugin('customBorders');
// Using an array of arrays (produced by `.getSelected()` method).
customBordersPlugin.clearBorders([[1, 1, 2, 2], [6, 2, 0, 2]]);
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
customBordersPlugin.clearBorders(hot.getSelectedRange());
// Using without param - clear all customBorders.
customBordersPlugin.clearBorders();
Param | Type | Description |
---|---|---|
selectionRanges | Array<Array> Array<CellRange> | Array of selection ranges. |
destroy
Source codecustomBorders.destroy()
Destroys the plugin instance.
disablePlugin
Source codecustomBorders.disablePlugin()
Disables the plugin functionality for this Handsontable instance.
enablePlugin
Source codecustomBorders.enablePlugin()
Enables the plugin functionality for this Handsontable instance.
getBorders
Source codecustomBorders.getBorders(selectionRanges) ⇒ Array<object>
Get custom borders.
Example
const customBordersPlugin = hot.getPlugin('customBorders');
// Using an array of arrays (produced by `.getSelected()` method).
customBordersPlugin.getBorders([[1, 1, 2, 2], [6, 2, 0, 2]]);
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
customBordersPlugin.getBorders(hot.getSelectedRange());
// Using without param - return all customBorders.
customBordersPlugin.getBorders();
Param | Type | Description |
---|---|---|
selectionRanges | Array<Array> Array<CellRange> | Array of selection ranges. |
Returns: Array<object>
- Returns array of border objects.
isEnabled
Source codecustomBorders.isEnabled() ⇒ boolean
Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit
hook and if it returns true
then the CustomBorders#enablePlugin method is called.
setBorders
Source codecustomBorders.setBorders(selectionRanges, borderObject)
Set custom borders.
Example
const customBordersPlugin = hot.getPlugin('customBorders');
// Using an array of arrays (produced by `.getSelected()` method).
customBordersPlugin.setBorders([[1, 1, 2, 2], [6, 2, 0, 2]], {start: {width: 2, color: 'blue'}});
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
// Selecting a cell range.
hot.selectCell(0, 0, 2, 2);
// Returning selected cells' range with the getSelectedRange method.
customBordersPlugin.setBorders(hot.getSelectedRange(), {start: {hide: false, width: 2, color: 'blue'}});
Param | Type | Description |
---|---|---|
selectionRanges | Array<Array> Array<CellRange> | Array of selection ranges. |
borderObject | object | Object with top , right , bottom and start properties. |
updatePlugin
Source codecustomBorders.updatePlugin()
Updates the plugin's state.
This method is executed when updateSettings()
is invoked with any of the following configuration options: