Canvas Data Grid

• Demo

• High performance lightweight hierarchal canvas based data grid.

• Support for millions of rows and columns.

• Extensible styling, filtering, formatting, resizing, selecting, and ordering.

• Rich API of events, methods and properties optimized for CRUD, reporting and work flow applications.

• Zero dependencies, very small code base, a single 94k (16k gziped) file.

• Installation

• Instantiation

• Extending

• Attributes

• Properties

• Methods

• Events

• Common Objects

• Styles

Installation

You can install canvas-datagrid one of three ways:

1. Download the source file from github.

2. Use bower

   bower install canvas-datagrid

3. Use npm

   npm install canvas-datagrid

Place the single source file ./lib/main.js in your web page using a script tag that points to the source or use a require framework.

If you do not use a require framework a function will be added to the global scope of the web page called canvasDatagrid.

Instantiation

Works with require framework or without. If used without require, canvasDataGrid is declared in the global scope.

Simple creation and data set.

var grid = canvasDataGrid({
    parentNode: document.getElementById('myHtmlElement'),
    data: [
        {col1: 'row 1 column 1', col2: 'row 1 column 2', col3: 'row 1 column 3'},
        {col1: 'row 2 column 1', col2: 'row 2 column 2', col3: 'row 2 column 3'}
    ]
});

Check which cell the user clicked on.

grid.addEventListener('click', function (e, cell) {
    console.log(cell.value);
});

Check values when the selection has changed.

grid.addEventListener('selectionchanged', function (data, matrix, bounds) {
    console.log(data);
});

You can alter the data after instantiation.

grid.data[0].col1 = 'blah';
// gota call draw after setting data this way.
grid.draw();

Change the color of a cell based on value.

grid.addEventListener('rendercell', function (ctx, cell) {
    if (cell.value === 'blah') {
        ctx.fillStyle = 'red';
    }
});

Alter the format (appearance only) of a data based on type.

grid.formatters.date = function (ctx, cell) {
    return new Date(cell.value).toISOString();
};

Add a tree view.

grid.attributes.tree = true;
grid.addEventListener('expandtree', function (grid, data, rowIndex) {
    grid.data = [{My: 'Other Data'}];
});

Change all the data!

grid.data = [{other: 'data'}];

Extending

canvas-datagrid can be extended in many ways. This section covers all of the methods of extending the canvas.

Extending the visual appearance

All visual elements of the canvas are dependent on the values of the style object. You can change the dimensions and appearance of any element of the grid.

This example changes the fill style of the cell when the cell is a certain value.

grid.addEventListener('rendercell', function (ctx, cell) {
    if (cell.header.name === 'MyStatusCell' && /blah/.test(cell.value)) {
        ctx.fillStyle = '#AEEDCF';
    }
});

For a complete list of all style properties visit the styles section.

Extending behavior by drawing on the canvas

Extending behavior is done using event handlers just like a regular HTML element. You can alter the content of a rendered cell by attaching to such an event handler. Below is an example of drawing an image into a cell:

This example attaches to two events. rendertext to prevent the rendering of text into the cell...

grid.addEventListener('rendertext', function (ctx, cell) {
    if (cell.rowIndex > -1) {
        if (cell.header.name === 'MyImageColumnName') {
            cell.formattedValue = cell.value ? '' : 'No Image';
        }
    }
});

... and afterrendercell to draw an image into the cell after the background and borders are drawn. Because the image is loaded asynchronously, you need to attach to the load even to actually draw the image.

var imgs = {};
grid.addEventListener('afterrendercell', function (ctx, cell) {
    var i, contextGrid = this;
    if (cell.header.name === 'MyImageColumnName'
            && cell.value && cell.rowIndex > -1) {
        if (!imgs[cell.value]) {
            i = imgs[cell.value] = new Image();
            i.src = cell.value;
            i.onload = function () {
                i.targetHeight = cell.height;
                i.targetWidth = cell.height * (i.width / i.height);
                contextGrid.draw();
            };
            return;
        }
        i = imgs[cell.value];
        if (i.width !== 0) {
            ctx.drawImage(i, cell.x, cell.y, i.targetWidth, i.targetHeight);
        }
    }
});

Extending the context menu

You can add or remove items from the context menu, or stop it from appearing. In the following example, a context menu item is added:

    grid.addEventListener('contextmenu', function (e, cell, items) {
        items.push({
            title: 'Process selected row(s)',
            click: function () {
                // cell.value contains the cell's value
                // cell.data contains the row values
                myProcess(cell.value, cell.data);
            }
        });
    });

The title property can be an HTML node reference instead of a string. The click property is optional. See contextmenu complete information.

Extending the behavior of the canvas by formatting data

You can format the data in your cells without altering the data in two ways.

The first and fastest method is grid formatters. Grid formatters allow you to define what happens to a type of data. Data type is defined in the schema that you can optionally pass to describe your data.

This method is slightly faster due to the O(1) hash map employed in the value formatters.

In the following example the type date is given a formatter function.

grid.formatters.date = function (ctx, cell) {
    return new Date(cell.value).toISOString();
};

The return value of the formatter function will be displayed in the cell instead of the value in the data without altering the data.

The second method is the rendertext event. By subscribing to the rendertext event listener we can intercept the value in the context of the cell being drawn and alter it.

This method is slightly slower due to the O(n) loop employed in the event handler class.

This method is not dependent on values in the schema. This methods overrides grid.formatters.

grid.addEventListener('rendertext', function (ctx, cell) {
    if (cell.rowIndex > -1) {
        if (cell.header.name === 'MyDateColumnName') {
            cell.formattedValue = new Date(cell.value).toISOString();
        }
    }
});

Attributes

Attributes are the basic properties set during instantiation. Think of HTML attributes. Attributes can be set during instantiation or after by setting grid.attributes. Setting an attribute will automatically call draw.

var grid = canvasDataGrid({
        // Every value here is an attribute
    });

// all attributes can be accessed here after instantiation
grid.attributes

parentNode

HTML element that will hold the grid.

name

Optional value that will allow the saving of column height and row width settings to the browser's local store. This name should be unique to this grid.

tree: false

When true, an arrow will be drawn on each row that when clicked raises the expandtree event for that row and creates an inner grid.

treeHorizontalScroll: false

When true, expanded child grids will scroll horizontally with the parent columns. When false, when scrolling horizontally child grids will remain stationary. This does not impact vertical scrolling behavior.

childGridAttributes

Attributes used for cell grids. These child grids are different than the tree grids. See the data property for more information about cell grids.

showNewRow: true

When true, a row will appear at the bottom of the data set. schema[].defaultValue will define a default value for each cell. defaultValue can be a string or a function. When a function is used, the arguments header and index will be passed to the function. The value returned by the function will be the value in the new cell.

saveAppearance: true

When true, and the attribute name is set, column and row sizes will be saved to the browser's localStore.

selectionFollowsActiveCell: false

When true, moving the active cell with keystrokes will also change the selection.

multiLine: true

When true, edit cells will be textareas, when false edit cells will be inputs.

globalRowResize: false

When true, resizing a row will resize all rows to the same height. Questionable compatibility with hierarchical views.

editable: true

When true cells can be edited. When false, grid is read only to the user.

allowColumnReordering: true

When true columns can be reordered. NOT IMPLEMENTED.

showFilter: true

When true, filter will be an option in the context menu.

pageUpDownOverlap: 1

Amount of rows to overlap when pageup/pagedown is used.

persistantSelectionMode: false

When true, selections will behave as if the command/control key is held down at all times.

rowSelectionMode: false

When true, clicking on any cell will select the entire row that cell belongs to.

autoResizeColumns: false

When true, all columns will be automatically resized to fit the data in them. Warning! Expensive for large (>100k ~2 seconds) datasets.

allowRowHeaderResize: true

When true, the user can resize the width of the row headers.

allowColumnResize: true

When true, the user can resize the width of the columns.

allowRowResize: true

When true, the user can resize the row headers increasing the height of the row.

allowRowResizeFromCell: false

When true, the user can resize the height of the row from the border of the cell.

allowColumnResizeFromCell: false

When true, the user can resize the width of the column from the border of the cell.

showPerformance: false

When true, the amount of time taken to draw the grid is shown.

borderResizeZone: 10

Number of pixels in total around a border that count as resize zones.

showHeaders: true

When true, headers are shown.

showRowNumbers: true

When true, row numbers are shown in the row headers.

showRowHeaders: true

When true, row headers are shown.

schema

Sets the schema. See schema property below.

data: []

Sets the data. See data property below.

style

Sets all style values overriding all defaults. Unless you're replacing 100% of the styles, don't use this property. See style property below.

Properties

The difference between attributes and properties is that attributes are always getter/setters attached to the attributes property. Attributes are the values that can be passed during instantiation. Setting an attribute will call draw.

Properties are references to internal objects and function maps like filters. You can change the sub-properties of the various properties, but the base properties, with a few exceptions are immutable.

selectedRows

Array of selected rows. Looks just like the data you passed in, but filtered for the rows the user has cells selected in. If any cell in the row is selected, all data for that row will appear in this array.

selectedCells

Jagged array of cells that the user has selected. Beware that because this is a jagged array, some indexes will be null. Besides the nulls this data looks just like the data you passed in, but just the cells the user has selected. So if the user has selected cell 10 in a 10 column row, there will be 9 nulls followed by the data from column 10.

changes

Array of changes and additions made to the grid since last time data was loaded. The data property will change with changes as well, but this is a convince list of all the changes in one spot. Calling clearChangeLog will clear this list.

input

Reference to the the edit cell when editing. Undefined when not editing.

controlInput

Input used for key controls on the grid. Any clicks on the grid will cause this input to be focused. This input is hidden behind the canvas.

currentCell

Convenience object that represents the object that the mouse moved over last.

height

Height of the grid.

width

Width of the grid.

visibleCells

Array of cell drawn.

visibleRows

Array of visible row indexes.

selections

Matrix array of selected cells.

selectionBounds

rect object, bounds of current selection.

attributes

Object that contains the properties listed in the attributes section.

sizes

Mutable object that contains sizes.columns and sizes.rows arrays. These arrays control the sizes of the columns and rows. If there is not an entry for the row or column index it will fall back to the style default.

style

Object that contains the properties listed in the style section. Changing a style will automatically call draw.

resizeMode

Represents the currently displayed resize cursor. Can be ns-resize, ew-resize, pointer, or inherit.

formatters

Object that contains a list of formatting functions for displaying text. The properties in this object match the schema[].type property. For example, if the schema for a given column was of the type date the grid would look for a formatter called formatters.date if a formatter cannot be found for a given data type a warning will be logged and the string formatter will be used.

Cell formatter function should contain the following arguments.

grid.formatters.date = function (ctx, cell) { return new Date(cell.value).toISOString(); }

Formatters must return a string value to be displayed in the cell.

sorters

Object that contains a list of sorting functions for sorting columns.

Sorter function must return a sort function. This function will be used in the native sort method.

Example sorter:

grid.sorters.number = function (columnName, direction) {
    var asc = direction === 'asc';
    return function (a, b) {
        if (asc) {
            return a[columnName] - b[columnName];
        }
        return b[columnName] - a[columnName];
    };
};

filters

Object that contains a list of filters for filtering data. The properties in this object match the schema[].type property. For example, if the schema for a given column was of the type date the grid would look for a filter called filters.date if a filter cannot be found for a given data type a warning will be logged and the string/RegExp filter will be used.

filters.number = function (value, filterFor) {
    if (!filterFor) { return true; }
    return value === filterFor;
};

data

This is how data is set in the grid. Data must be an array of objects that conform to a schema.

[
    {col1: 'row 1 column 1', col2: 'row 1 column 2', col3: 'row 1 column 3'},
    {col1: 'row 2 column 1', col2: 'row 2 column 2', col3: 'row 2 column 3'}
]

Data values can be any primitive type. However if a cell value is another data array, a child grid will be rendered into the cell. This child grid is different than a tree view grid and uses the childGridAttributes attribute for properties and styling.

schema

Schema is optional. Schema is an array of column objects. If no schema is provided one will be generated from the data, in that case all data will be assumed to be string data.

Each column object can have the following properties:

Example schema:

[
    {
        name: 'col1'
    },
    {
        name: 'col2'
    },
    {
        name: 'col3'
    }
]

scrollHeight

The total number of pixels that can be scrolled down.

scrollWidth

The total number of pixels that can be scrolled to the left.

scrollTop

The number of pixels that have been scrolled down.

scrollLeft

The number of pixels that have been scrolled to the left.

offsetTop

The offset top of the grid.

offsetLeft

The offset left of the grid.

parentNode

The grid's parent HTML node.

isChildGrid

When true, this grid is a child grid of another grid.

openChildren

List of open child grids by internal unique row id.

childGrids

Child grids in this grid organized by internal unique row id.

height

Gets or sets the height of the grid.

width

Gets or sets the width of the grid.

parentGrid

If this grid is a child grid, this is the grids parent.

canvas

The canvas element drawn onto for this grid.

Methods

setRowHeight(index, height)

Sets the height of the given row index.

setColumnWidth(index, width)

Sets the column width of the given column index.

resetColumnWidths()

Removes any changes to the width of the columns due to user or api interaction, setting them back to the schema or style default.

resetRowHeights()

Removes any changes to the height of the rows due to user or api interaction, setting them back to the schema or style default.

insertColumn(column, index)

Inserts a new column before the specified index into the schema. See schema.

deleteColumn(index)

Deletes a column from the schema at the specified index.

addColumn(column)

Adds a new column into the schema. See schema.

addRow(data)

Adds a new row of data to the grid. Row data should probably look somewhat like the schema.

insertRow(data, index)

Inserts a new row of data to the grid before the specified index. Row data should probably look somewhat like the schema.

deleteRow(index)

Deletes the row at the specified index.

toggleTree(rowIndex)

Toggles the given row index's child table on/off.

expandTree(rowIndex)

Expands the given row index's child table.

collapseTree(rowIndex)

Collapses the given row index's child table.

beginEditAt(x, y)

Begins editing at cell x, row y

endEdit(abort)

Ends editing, optionally aborting the edit.

selectRow(rowIndex, toggleSelectMode, supressSelectionchangedEvent)

Selects a row. toggleSelectMode behaves as if you were holding control/command when you clicked the row. supressSelectionchangedEvent will prevent the selectionchanged event from firing.

clearChangeLog()

Clears the change log grid.changes that keeps track of changes to the data set. This does not undo changes or alter grid.data it is simply a convince array to keep track of changes made to the data.

setActiveCell(x, y)

Sets the active cell. Requires redrawing.

scrollIntoView(x, y)

Scrolls the cell at cell x, row y into view if it is not already.

gotoCell(x, y)

Scrolls to the cell at cell x, row y.

gotoRow(y)

Scrolls to the row y.

findColumnScrollLeft(columnIndex)

Returns the number of pixels to scroll to the left to line up with column columnIndex.

findRowScrollTop(rowIndex)

Returns the number of pixels to scroll down to line up with row rowIndex.

getSelectionBounds()

Gets the bounds of current selection. Returns a rect object.

fitColumnToValues(name)

Resizes a column to fit the longest value in the column. Call without a value to resize all columns. Warning, can be slow on very large record sets (100k records ~3-5 seconds on an i7).

getHeaderByName(name)

Returns a header from the schema by name.

findColumnMaxTextLength(name)

Returns the maximum text width for a given column by column name.

disposeContextMenu()

Removes the context menu if it is present.

getCellAt(x, y)

Gets the cell at grid pixel coordinate x and y.

order(columnName, direction)

Sets the order of the data.

draw()

Redraws the grid. No matter what the change, this is the only method required to refresh everything.

selectArea()

Accepts a rect object that defines the desired selected area.

getSchemaFromData()

Returns schema with auto generated schema based on data structure.

setFilterValue(column, value)

Sets the value of the filter.

Events

Events are subscribed to using addEventListener and unsubscribed from using removeEventListener. Some events have a first argument with the method preventDefault. Calling preventDefault will prevent the default behavior from occurring. For example, if you wanted to prevent the edit cell from appearing for some cells you can subscribe to the beforebeginedit event and call e.preventDefault when you want the cell to be read only. Using events will give you the most granular control of appearance and behavior.

selectionchanged

Fires when the selection changes.

grid.addEventListener('selectionchanged', function (data, matrix, bounds) { });

expandtree

Fires when the user clicks on the "drill in" arrow. When the arrow is clicked a new grid is created and nested inside of the row. The grid, the row data and row index are passed to the event listener. From here you can manipulate the inner grid. A grid is not disposed when the tree is collapsed, just hidden, but grids are not created until the arrow is clicked.

grid.addEventListener('expandtree', function (grid, data, rowIndex) { });

collapsetree

Fires when the user click the "drill in" arrow on a row that is already expanded.

grid.addEventListener('collapsetree', function (grid, data, rowIndex) { });

scroll

Fires when the user scrolls the grid.

datachanged

Fires when the data setter is set.

schemachanged

Fires when the schema setter is set.

beforerendercell

Fired just before a cell is drawn onto the canvas. e.preventDefault(); prevents the cell from being drawn. You would only use this if you want to completely stop the cell from being drawn and generally muck up everything.

grid.addEventListener('beforerendercell', function (ctx, value, row, header, x, y) { });

rendercell

Fires when a cell is drawn. If you want to change colors, sizes this is the event to attach to. Changing the cell object's height and width is allowed. Altering the context of the canvas is allowed. Drawing on the canvas will probably be drawn over by the cell.

grid.addEventListener('rendercell', function (ctx, cell) { });

afterrendercell

Fires just after a cell is drawn. If you want to draw things in the cell, this is the event to attach to. Drawing on the canvas is allowed. Altering the context of the canvas is allowed.

grid.addEventListener('afterrendercell', function (ctx, cell) { });

rendertext

Fires when text is drawn into a cell. If you want to change the color of the text, this is the event to attach to. To alter what text finally appears in the cell, change the value of cell.formattedValue. Keep in mind this text will still be subject to the ellipsis function that truncates text when the width is too long for the cell.

You cannot alter the cell's height or width from this event, use rendercell event instead.

grid.addEventListener('rendertext', function (ctx, cell) { });

renderorderbyarrow

Fires when the order by arrow is drawn onto the canvas. This is the only way to completely replace the order arrow graphic. Call e.preventDefault() to stop the default arrow from being drawn.

grid.addEventListener('renderorderbyarrow', function (ctx, cell) { });

rendertreearrow

Fires when the tree arrow is drawn onto the canvas. This is the only way to completely replace the tree arrow graphic. Call e.preventDefault() to stop the default arrow from being drawn.

grid.addEventListener('rendertreearrow', function (ctx, cell) { });

rendercellgrid

Fires when a cell grid is instantiated. Allows you to alter the cell data grid. Only fires once per grid.

grid.addEventListener('rendercellgrid', function (ctx, cell) { });

ordercolumn

Fires when a column is reordered.

grid.addEventListener('rendercellgrid', function (columnName, direction) { });

mousemove

Fires when the mouse moves over the grid.

grid.addEventListener('mousemove', function (e, cell) { });

contextmenu

Fires when a context menu is requested. The menu item array can be altered to change what items appear on the menu.

grid.addEventListener('contextmenu', function (e, cell, menuItems, contextMenu) { });

You can add items to the context menu but they must conform to this object type.

Removing all items from the list of menu items will cause the context menu to not appear. Calling e.preventDefault(); will cause the context menu to not appear as well.

beforeendedit

Fires just before edit is complete giving you a chance to validate the input. e.preventDefault(); will cause the edit to not end and row data will not be written back to the data array.

grid.addEventListener('beforeendedit', function (value, originalValue, abort, cell, textarea) { });

endedit

Fires when the edit has ended. This event gives you a chance to abort the edit preserving original row data, or modify the value of the row data prior to being written.

grid.addEventListener('endedit', function (value, abort, cell, textarea) { });

beforebeginedit

Fires before a edit cell has been created giving you a chance to abort it. e.preventDefault(); will abort the edit cell from being created.

grid.addEventListener('beforebeginedit', function (cell) { });

beginedit

Fires when an editor textarea (or input) has been created.

grid.addEventListener('beginedit', function (cell, textarea) { });

click

Fires when the grid is clicked.

grid.addEventListener('click', function (e, cell) { });

resizecolumn

Fires when a column is about to be resized. e.preventDefault(); will abort the resize.

grid.addEventListener('resizecolumn', function (x, y, cell) { });

mousedown

Fires when the mouse button is pressed down on the grid. e.preventDefault(); will abort the default grid event.

grid.addEventListener('mousedown', function (e, cell) { });

mouseup

Fires when the mouse button is pressed down on the grid. e.preventDefault(); will abort the default grid event.

grid.addEventListener('mouseup', function (e, cell) { });

dblclick

Fires when the mouse button is double clicked on the grid. e.preventDefault(); will abort the default grid event. Note that this will necessarily require 2*mousedown, 2*mouseup and 2*click events to fire prior to the double click.

grid.addEventListener('dblclick', function (e, cell) { });

keydown

Fires when the keyboard button is pressed down on the grid. e.preventDefault(); will abort the default grid event.

grid.addEventListener('keydown', function (e, cell) { });

keyup

Fires when the keyboard button is released on the grid. e.preventDefault(); will abort the default grid event.

grid.addEventListener('keyup', function (e, cell) { });

keypress

Fires when the keyboard press is completed on the grid. e.preventDefault(); will abort the default grid event.

grid.addEventListener('keypress', function (e, cell) { });

resize

Fires when grid is being resized. e.preventDefault(); will abort the resizing.

grid.addEventListener('resize', function (e, cell) { });

Common Objects

cell

A cell on the grid and all data associated with it.

rect

A selection area represented by a rectangle. This object is returned by a number of events, methods and properties, and is passed to the selectArea method.

Styles

Styles can be passed during instantiation or after. Changing a style will automatically call draw.

grid.style.cellBackgroundColor = 'burlywood';