CustomBorders

Plugin: CustomBorders

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.

When a border property is set to an empty object {} or an empty string '', the default style is applied: 1px solid black.

The plugin also integrates with the [[ContextMenu]] plugin. Adding 'borders' to the contextMenu items enables users to apply or remove borders on selected cells directly from the right-click menu.

See customBorders configuration option or go to Custom cell borders demo for more examples.

Example

1
// Enable custom borders with context menu integration.
2
// When a border property is an empty object, the default style (1px solid black) is applied.
3
new Handsontable(container, {
4
  customBorders: [
5
    {
6
      range: {
7
        from: { row: 1, col: 1 },
8
        to: { row: 3, col: 4 },
9
      },
10
      top: {},    // default: 1px solid black
11
      bottom: {}, // default: 1px solid black
12
      start: {},  // default: 1px solid black
13
      end: {},    // default: 1px solid black
14
    },
15
    {
16
      row: 2,
17
      col: 2,
18
      start: { width: 2, color: 'red', style: 'dotted' },
19
      end: { width: 1, color: 'green', style: 'dashed' },
20
      top: '',    // default: 1px solid black
21
      bottom: '', // default: 1px solid black
22
    },
23
  ],
24
  // Enable the 'borders' item in the context menu so users can
25
  // apply or remove borders from the right-click menu.
26
  contextMenu: ['borders'],
27
});

Options

customBorders

Source code

customBorders.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` `style`	`width`: Number `color`: String `style`: String	If the layout direction is LTR (default): `start` sets the width (`width`), color (`color`) and style (`style`) of the left-hand border. If the layout direction is RTL: `start` sets the width (`width`), color (`color`) and style (`style`) of the right-hand border.
`end`	`width` `color` `style`	`width`: Number `color`: String `style`: String	If the layout direction is LTR (default): `end` sets the width (`width`), color (`color`) and style (`style`) of the right-hand border. If the layout direction is RTL: `end` sets the width (`width`), color (`color`) and style (`style`) of the left-hand border.
`top`	`width` `color` `style`	`width`: Number `color`: String `style`: String	Sets the width (`width`), color (`color`) and style (`style`) of the top border.
`bottom`	`width` `color` `style`	`width`: Number `color`: String `style`: String	Sets the width (`width`), color (`color`) and style (`style`) 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`: Object `to`: Object `row`: Number `col`: 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` `style`	`width`: Number `color`: String `style`: String	If the layout direction is LTR (default): `start` sets the width (`width`), color (`color`) and style (`style`) of the left-hand border. If the layout direction is RTL: `start` sets the width (`width`), color (`color`) and style (`style`) of the right-hand border.
`end`	`width` `color` `style`	`width`: Number `color`: String `style`: String	If the layout direction is LTR (default): `end` sets the width (`width`), color (`color`) and style (`style`) of the right-hand border. If the layout direction is RTL: `end` sets the width (`width`), color (`color`) and style (`style`) of the left-hand border.
`top`	`width` `color` `style`	`width`: Number `color`: String `style`: String	Sets the width (`width`), color (`color`) and style (`style`) of the top border.
`bottom`	`width` `color` `style`	`width`: Number `color`: String `style`: String	Sets the width (`width`), color (`color`) and style (`style`) of the bottom border.

Default: false
Example

1
// enable the `CustomBorders` plugin
2
customBorders: true,
3

4
// enable the `CustomBorders` plugin
5
// and add a predefined border for a particular cell
6
customBorders: [
7
  // add an object with a border configuration for one cell
8
  {
9
    // set the cell's row coordinate
10
    row: 2,
11
    // set the cell's column coordinate
12
    col: 2,
13
    // set the left/right border's width and color
14
    start: {
15
      width: 2,
16
      color: 'red'
17
    },
18
    // set the right/left border's width, color and style
19
    end: {
20
      width: 1,
21
      color: 'green',
22
      style: 'dashed'
23
    },
24
    // set the top border's width and color
25
    top: '',
26
    // set the bottom border's width and color
27
    bottom: ''
28
  }
29
],
30

31
// enable the `CustomBorders` plugin
32
// and add a predefined border for a range of cells
33
customBorders: [
34
  // add an object with a border configuration for one range of cells
35
  {
36
    // select a range of cells
37
    range: {
38
      // set the range's top-left corner
39
      from: {
40
        row: 1,
41
        col: 1
42
      },
43
      // set the range's bottom-right corner
44
      to: {
45
        row: 3,
46
        col: 4
47
      }
48
    },
49
    // set the left/right border's width, color and style
50
    start: {
51
      width: 2,
52
      color: 'red',
53
      style: 'dashed'
54
    },
55
    // set the right/left border's width and color
56
    end: {},
57
    // set the top border's width and color
58
    top: {},
59
    // set the bottom border's width and color
60
    bottom: {}
61
  }
62
],

Methods

clearBorders

Source code

customBorders.clearBorders(selectionRanges)

Clear custom borders.

Example

1
const customBordersPlugin = hot.getPlugin('customBorders');
2

3
// Using an array of arrays (produced by `.getSelected()` method).
4
customBordersPlugin.clearBorders([[1, 1, 2, 2], [6, 2, 0, 2]]);
5
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
6
customBordersPlugin.clearBorders(hot.getSelectedRange());
7
// Using without param - clear all customBorders.
8
customBordersPlugin.clearBorders();

Param	Type	Description
selectionRanges	`Array<Array>` `Array<CellRange>`	Array of selection ranges.

destroy

Source code

customBorders.destroy()

Destroys the plugin instance.

disablePlugin

Source code

customBorders.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Source code

customBorders.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

getBorders

Source code

customBorders.getBorders(selectionRanges) ⇒ Array<object>

Get custom borders.

Example

1
const customBordersPlugin = hot.getPlugin('customBorders');
2

3
// Using an array of arrays (produced by `.getSelected()` method).
4
customBordersPlugin.getBorders([[1, 1, 2, 2], [6, 2, 0, 2]]);
5
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
6
customBordersPlugin.getBorders(hot.getSelectedRange());
7
// Using without param - return all customBorders.
8
customBordersPlugin.getBorders();

Param	Type	Description
selectionRanges	`Array<Array>` `Array<CellRange>`	Array of selection ranges.

Returns: Array<object> - Returns array of border objects.

isEnabled

Source code

customBorders.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 code

customBorders.setBorders(selectionRanges, borderObject)

Set custom borders.

Example

1
const customBordersPlugin = hot.getPlugin('customBorders');
2

3
// Using an array of arrays (produced by `.getSelected()` method).
4
customBordersPlugin.setBorders([[1, 1, 2, 2], [6, 2, 0, 2]], {start: {width: 2, color: 'blue'}});
5

6
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
7
//  Selecting a cell range.
8
hot.selectCell(0, 0, 2, 2);
9
// Returning selected cells' range with the getSelectedRange method.
10
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 code

customBorders.updatePlugin()

Updates the plugin’s state.

This method is executed when updateSettings() is invoked with any of the following configuration options:

customBorders