Canvas Data Grid

Lightweight canvas based data grid.

Demo

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('blockElement'),
    data: data
});

Attributes

Attributes can be set during instantiation or after by accessing grid.attributes. If changed after instantiation some attributes require calling grid.draw() to see changes.

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.

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 (>10k ~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.

Properties

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.

resizeMode

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

cellFormaters

Object that contains a list of formatters 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 cellFormatters.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.

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

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

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'}
]

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:

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

Methods

beginEditAt(x, y)

Begins editing at cell x, row y

endEdit(abort)

Ends editing, optionally aborting the edit.

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.

gotoToCell(x, y)

Scrolls to the cell at cell x, row y.

gotoToRow(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

selectionchanged

Fires when the selection changes.

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

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, add content, etc. this is the event to attach to. Altering what is drawn by changing the cell object's height and width is allowed. Drawing on the canvas is allowed. Altering the context of the canvas is allowed.

grid.addEventListener('rendercell', 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) { });

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 rect. This object is returned by a number of events, methods and properties, and is passed to the selectArea method.

Styles