SlickGrid资料

SlickGrid简单介绍 : https://github.com/mleibman/SlickGrid/wiki

快速入门 : https://github.com/mleibman/SlickGrid/wiki/Getting-Started

使用示例 : https://github.com/mleibman/SlickGrid/wiki/Examples

API文档: https://github.com/mleibman/SlickGrid/wiki/API-Reference

处理选择模式: https://github.com/mleibman/SlickGrid/wiki/Handling-selection

Welcome to the SlickGrid!

UPDATE: March 5th, 2014 – I have too many things going on in my life right now to really give SlickGrid support and development the time and attention it deserves. I am not stopping it, but I will most likely be unresponsive for some time. Sorry.

UPDATE: This repo hasn’t been updated in a while. https://github.com/6pac/SlickGrid/wikiseems to be the most active fork at the moment.

Do you use SlickGrid? Add your site to the Used By!

Want to show your appreciation? Hit Donate! :)

What it is

Quite simply, SlickGrid is a JavaScript grid/spreadsheet component.
It is an advanced component and is going to be a bit more difficult to learn and configure, but once you realize its full potential, it will blow your mind!

Some highlights:

• Adaptive virtual scrolling (handle hundreds of thousands of rows with extreme responsiveness)
• Extremely fast rendering speed
• Supports jQuery UI Themes
• Background post-rendering for richer cells
• Configurable & customizable
• Column resize/reorder/show/hide
• Column autosizing & force-fit
• Pluggable cell formatters & editors
• Support for editing and creating new rows.
• Grouping, filtering, custom aggregators, and more!
• Advanced detached & multi-field editors with undo/redo support.
• “GlobalEditorLock” to manage concurrent edits in cases where multiple Views on a page can edit the same data.

Resources

Dependencies

• jQuery
• jQueryUI Sortable (optional, only if column reordering is enabled)
• jquery.event.drag – http://threedubmedia.com/code/event/drag
• jquery.event.drop – http://threedubmedia.com/code/event/drop

Documentation

• Getting Started – A brief introduction to some of SlickGrid’s basic concepts.
• Examples – A broad set of examples that demonstrate the most effective ways of using SlickGrid (probably the best place to learn how to use it).
• API Reference
• Handling selection
• All pages on this wiki

Contact/Support

GitHub Issues are for bug reports only. Please use the appropriate forum.
Please see Rules of conduct

• Asking questions
• SlickGrid questions on StackOverflow
• SlickGrid Google Group – For support requests and conversation about SlickGrid.
• @slickgrid on Twitter

• Reporting bugs
• SlickGrid GitHub issues page

When reporting bugs, please be specific (details are described in the above “Rules of conduct”):

1. Include the version of SlickGrid.
2. Include the reproduction steps. Describe about expected behavior & actual behavior.
(If possible, post code on jsfiddle.net).
3. Use proper English that everybody can understand.

What makes it different

Virtual rendering

SlickGrid utilizes virtual rendering to enable you to easily work with hundreds of thousands of items without any drop in performance. In fact, there is no difference in performance between working with a grid with 10 rows versus a 100’000 rows. This is achieved through virtual rendering where only what’s visible on the screen plus a small buffer is rendered. As the user scrolls, DOM nodes are continuously being created and removed. These operations are highly tuned to provide optimal performance under all browsers. The grid also adapts to the direction and speed of scroll to minimize the number of rows that need to be swapped out and to dynamically switch between synchronous and asynchronous rendering.

It does a few other things to maximize performance, such as dynamically generating and updatingCSS rules, so that resizing a column does not change the grid DOM tree and only causes one reflow, and loading cell editors asynchronously to maximize keyboard navigation speed.

Grid vs Data

The key difference is between SlickGrid and other grid implementation I have seen is that they focus too much on being able to understand and work with data (search, sort, parse, ajax load, etc.) and not enough on being a better “grid” (or, in case of editable grids, a spreadsheet). It’s great if all you want to do is “spruce up” an HTML TABLE or slap a front end onto a simple list, but too inflexible for anything else.

Data is complicated. It has business rules. It has non-intrinsic properties. Editing one property of an element can lead to cascading changes modifying other properties or even other elements. It has dependencies. What I’m saying, is that dealing with data is best left to the developer using the grid control. Trying to fit all of that into the grid implementation and API will only limit its applicability and add considerable bloat.

SlickGrid takes a different approach. In the simplest scenario, it accesses data through an array interface (i.e. using “dataitem” to get to an item at a given position and “data.length” to determine the number of items), but the API is structured in such a way that it is very easy to make the grid react to any possible changes to the underlying data.

Responding to data source changes

While this may not be immediately obvious from what you see in the examples and in the code, the key use of the grid is in MVC applications where the grid is wired to respond to events in the Model. In our application we have spreadsheet component of a Gantt chart, and the Model is a “filtered” view of the tasks (rows) in the original datasource. Suppose you collapse or expand a parent task or enter some text in a Quick Filter textbox. The Model then recalculates which rows are now visible, compares that with what was visible before and fires two events – onRowCountChanged & onRowsChanged. The latter one tells all subscribed Views, such as the grid, that the rows in specific positions changed. The grid then only has to invalidate/remove those rows and call grid.renderViewport() to make sure that whatever is in the viewport is visible. The onRowCountChanged event triggers the recalculation of the virtual canvas – grid.resizeCanvas(). Together, this pattern makes for an incredibly efficient, flexible and, most importantly, scalable implementation.

Unsupported browsers

Rather than listing all the browsers that SlickGrid works on, I will concentrate on the ones that don’t.

IE6 is explicitly NOT supported. While some people have made SlickGrid work with IE6, I am not going to merge those changes in or spend any time testing on IE6 and trying to make it work. If you have to support it, I feel your pain, but I don’t want to share it.

Opera seems to be having some issues with synchronized scrolling of column headers and a vertical page scrollbar appearing when scrolling the grid content vertically. I haven’t been able to figure out why in the amount of time I was willing to spend on it. If you have an idea, let me know.

Thanks

Big thanks to JetBrains who have supported SlickGrid and other open-source projects by providing a free license for their awesome WebStorm IDE.

This is the API reference for SlickGrid.

Slick.Grid

• Constructor - Slick.Grid constructor
• Core - Core grid functionality
• Columns - Initializing and customizing columns
• Cells - Manipulating cell data and styling
• Rendering - Rendering methods
• Headers - Column header methods

DataView

Slick.Data.RemoteModel

Slick.Event

Slick.EventData

Slick.EditorLock

Slick.GlobalEditorLock

Slick.Range

Slick.CellRangeDecorator

Slick.CellRangeSelector

Table of Contents

• Constructor
• new Slick.Grid
• Core
• init
• getData
• setData
• getDataItem
• getSelectionModel
• setOptions
• Columns
• autosizeColumns
• getColumnIndex
• getColumns
• setColumns
• setSortColumn
• setSortColumns
• updateColumnHeader
• Cells
• addCellCssStyles
• canCellBeActive
• canCellBeSelected
• editActiveCell
• getActiveCell
• getCellEditor
• getCellFromEvent
• getCellFromPoint
• getCellNode
• getCellNodeBox
• gotoCell
• navigateDown
• navigateLeft
• navigateNext
• navigatePrev
• navigateRight
• navigateUp
• removeCellCssStyles
• resetActiveCell
• setActiveCell
• setCellCssStyles
• Rendering
• getCanvasNode
• getRenderedRange
• getViewport
• invalidate
• invalidateRow
• invalidateRows
• resizeCanvas
• scrollCellIntoView
• scrollRowIntoView
• scrollRowToTop
• updateCell
• updateRow
• updateRowCount
• Headers
• getHeaderRow
• getHeaderRowColumn
• getSortColumns
• setHeaderRowVisibility

# Constructor

# var grid = new Slick.Grid(container, data, columns, options);

container - Container node to create the grid in. This can be a DOM Element, a jQuery node, or a jQuery selector.

data - Databinding source. This can either be a regular JavaScript array or a custom object exposing getItem(index) and getLength() functions.

columns - An array of column definition objects. See Column Options for a list of options that can be included on each column definition object.

options - Additional options. See Grid Options for a list of options that can be included.

Create an instance of the grid.

Example usage, taken from the basic Slickgrid example:

  var grid;

  var columns = [

    {id: "title", name: "Title", field: "title"},

    {id: "duration", name: "Duration", field: "duration"},

    {id: "%", name: "% Complete", field: "percentComplete"},

    {id: "start", name: "Start", field: "start"},

    {id: "finish", name: "Finish", field: "finish"},

    {id: "effort-driven", name: "Effort Driven", field: "effortDriven"}

  ];

 

  var options = {

    enableCellNavigation: true,

    enableColumnReorder: false

  };

 

  $(function () {

    var data = [];

    for (var i = 0; i < 500; i++) {

      data[i] = {

        title: "Task " + i,

        duration: "5 days",

        percentComplete: Math.round(Math.random() * 100),

        start: "01/01/2009",

        finish: "01/05/2009",

        effortDriven: (i % 5 == 0)

      };

    }

 

    grid = new Slick.Grid("#myGrid", data, columns, options);

# Core

# grid.init()

Initializes the grid. Called after plugins are registered. Normally, this is called by the constructor, so you don't need to call it. However, in certain cases you may need to delay the initialization until some other process has finished. In that case, set the explicitInitialization option to true and call the grid.init() manually.

# grid.getData()

Returns an array of every data object, unless you're using DataView in which case it returns a DataView object.

# grid.getDataItem(index)

index - Item index.

Returns the databinding item at a given position.

// Get the id of the 15th item

var id15 = grid.getDataItem(14).id;

# grid.setData(newData, scrollToTop)

data - New databinding source. This can either be a regular JavaScript array or a custom object exposing getItem(index) and getLength() functions.

scrollToTop - If true, the grid will reset the vertical scroll position to the top of the grid.

Sets a new source for databinding and removes all rendered rows. Note that this doesn't render the new rows - you can follow it with a call to render() to do that.

# grid.getDataLength()

Returns the size of the databinding source.

// Create an array of just the ids from every data item

var ids = [];

for (var i=0; i<grid.getDataLength() ; i++) {

  ids.push(grid.getDataItem(i).id);

}

# grid.getOptions()

Returns an object containing all of the Grid options set on the grid. See a list of Grid Options here.

// Find all elements that are currently selected

var $selectedCells = $('.' + grid.getOptions().selectedCellCssClass);

# grid.getSelectedRows()

Returns an array of row indices corresponding to the currently selected rows.

# grid.getSelectionModel()

Returns the current SelectionModel. See here for more information about SelectionModels.

# grid.setOptions(options)

options - An object with configuration options.

Extends grid options with a given hash. If there is an active edit, the grid will attempt to commit the changes and only continue if the attempt succeeds.

// set a new CSS class for selected cells

grid.setOptions( { selectedCellCssClass: "newSelection" } );

 

// Select the first row

grid.setSelectedRows([0]);

 

// get the elements for the selected cells

$('.newSelection');

# grid.setSelectedRows(rowsArray)

rowsArray - An array of row numbers.

Accepts an array of row indices and applies the current selectedCellCssClass to the cells in the row, respecting whether cells have been flagged as selectable.

// Select the first three rows

grid.setSelectedRows([0, 1, 2]);

# grid.setSelectionModel(selectionModel)

selectionModel - A SelectionModel.

Unregisters a current selection model and registers a new one. See the definition of SelectionModelfor more information.

# Columns

# grid.autosizeColumns()

Proportionately resizes all columns to fill available horizontal space. This does not take the cell contents into consideration.

# grid.getColumnIndex(id)

id - A column id.

Returns the index of a column with a given id. Since columns can be reordered by the user, this can be used to get the column definition independent of the order:

var column = grid.getColumns()[grid.getColumnIndex("title")]

# grid.getColumns()

Returns an array of column definitions, containing the option settings for each individual column.

// Log to console whether the first column is sortable

var cols = grid.getColumns();

var sortable = cols[0].sortable;

sortable ? console.log("It's sortable!") : console.log("It's not sortable!");

# grid.setColumns(columnDefinitions)

columnDefinitions - An array of column definitions.

Sets grid columns. Column headers will be recreated and all rendered rows will be removed. To re-render the grid (if necessary), call render().

// Change the name of the first column to "First"

var data = grid.getColumns();

data[0].name = "First";

grid.setColumns(data);

# grid.setSortColumn(columnId, ascending)

Accepts a columnId string and an ascending boolean. Applies a sort glyph in either ascending or descending form to the header of the column. Note that this does not actually sort the column. It only adds the sort glyph to the header.

# grid.setSortColumns(cols)

Accepts an array of objects in the form [ { columnId: [string], sortAsc: [boolean] }, ... ]. When called, this will apply a sort glyph in either ascending or descending form to the header of each column specified in the array. Note that this does not actually sort the column. It only adds the sort glyph to the header

# grid.updateColumnHeader(columnId, title, toolTip)

id - Column id.

title - New column name.

toolTip - New column tooltip.

Updates an existing column definition and a corresponding header DOM element with the new title and tooltip.

// Change the column with an id of 'FirstName' to have the name "A First Name", and no tooltip.

grid.updateColumnHeader("FirstName", "A First Name");

# Cells

# grid.addCellCssStyles(key, hash)

key - A unique key you can use in calls to setCellCssStyles and removeCellCssStyles. If a hash with that key has already been set, an exception will be thrown.

hash - A hash of additional cell CSS classes keyed by row number and then by column id. Multiple CSS classes can be specified and separated by space.

Example:

{

    0:    {

        "number_column":    "cell-bold",

        "title_column":     "cell-title cell-highlighted"

    },

    4:    {

        "percent_column":    "cell-highlighted"

    }

}

Adds an "overlay" of CSS classes to cell DOM elements. SlickGrid can have many such overlays associated with different keys and they are frequently used by plugins. For example, SlickGrid uses this method internally to decorate selected cells with selectedCellCssClass (see options).

# grid.canCellBeActive(row, col)

row - A row index.

col - A column index.

Returns true if you can click on a given cell and make it the active focus.

# grid.canCellBeSelected(row, col)

row - A row index.

col - A column index.

Returns true if selecting the row causes this particular cell to have the selectedCellCssClassapplied to it. A cell can be selected if it exists and if it isn't on an empty / "Add New" row and if it is not marked as "unselectable" in the column definition.

# grid.editActiveCell(editor)

editor - A SlickGrid editor (see examples in slick.editors.js).

Attempts to switch the active cell into edit mode. Will throw an error if the cell is set to be not editable. Uses the specified editor, otherwise defaults to any default editor for that given cell.

// Assuming slick.editors.js is included...

// Set the first cell in the first row to be active

grid.setActiveCell(0,0);

 

// Invoke the Date editor on that cell

grid.editActiveCell(Slick.Editors.Date);

# grid.flashCell(row, cell, speed)

row - A row index.

cell - A column index.

speed (optional) - The milliseconds delay between the toggling calls. Defaults to 100 ms.

Flashes the cell twice by toggling the CSS class 4 times.

# grid.getActiveCell()

Returns an object representing the coordinates of the currently active cell:

{

  row: activeRow,

  cell: activeCell

}

# grid.getActiveCellNode()

Returns the DOM element containing the currently active cell. If no cell is active, null is returned.

// Get the element for the active cell

var $active = $(grid.getActiveCellNode())

 

// Add a new class to the active cell

$active.addClass('myClass');

# grid.getActiveCellPosition()

Returns an object representing information about the active cell's position. All coordinates are absolute and take into consideration the visibility and scrolling position of all ancestors. The object takes the form:

{

  bottom:  [numPixels],

  height:  [numPixels],

  left:    [numPixels],

  right:   [numPixels],

  top:     [numPixels],

  visible: [boolean],

     [numPixels]

}

# grid.getCellCssStyles(key)

key - A string.

Accepts a key name, returns the group of CSS styles defined under that name. SeesetCellCssStyles for more info.

# grid.getCellEditor()

Returns the active cell editor. If there is no actively edited cell, null is returned.

# grid.getCellFromEvent(e)

e - A standard W3C/jQuery event.

Returns a hash containing row and cell indexes from a standard W3C/jQuery event.

# grid.getCellFromPoint(x, y)

x - An x coordinate.

y - A y coordinate.

Returns a hash containing row and cell indexes. Coordinates are relative to the top left corner of the grid beginning with the first row (not including the column headers).

# grid.getCellNode(row, cell)

row - A row index.

cell - A column index.

Returns a DOM element containing a cell at a given row and cell.

# grid.getCellNodeBox(row, cell)

row - A row index.

cell - A column index.

Returns an object representing information about a cell's position. All coordinates are absolute and take into consideration the visibility and scrolling position of all ancestors. The object takes the form:

{

  bottom:  [numPixels],

  height:  [numPixels],

  left:    [numPixels],

  right:   [numPixels],

  top:     [numPixels],

  visible: [boolean],

     [numPixels]

}

# grid.gotoCell(row, cell, forceEdit)

Accepts a row integer and a cell integer, scrolling the view to the row where row is its row index, and cell is its cell index. Optionally accepts a forceEdit boolean which, if true, will attempt to initiate the edit dialogue for the field in the specified cell.

Unlike setActiveCell, this scrolls the row into the viewport and sets the keyboard focus.

# grid.navigateDown()

Switches the active cell one row down skipping unselectable cells. Returns a boolean saying whether it was able to complete or not.

# grid.navigateLeft()

Switches the active cell one cell left skipping unselectable cells. Unline navigatePrev,navigateLeft stops at the first cell of the row. Returns a boolean saying whether it was able to complete or not.

# grid.navigateNext()

Tabs over active cell to the next selectable cell. Returns a boolean saying whether it was able to complete or not.

# grid.navigatePrev()

Tabs over active cell to the previous selectable cell. Returns a boolean saying whether it was able to complete or not.

# grid.navigateRight()

Switches the active cell one cell right skipping unselectable cells. Unline navigateNext,navigateRight stops at the last cell of the row. Returns a boolean saying whether it was able to complete or not.

# grid.navigateUp()

Switches the active cell one row up skipping unselectable cells. Returns a boolean saying whether it was able to complete or not.

# grid.removeCellCssStyles(key)

key - A string key.

Removes an "overlay" of CSS classes from cell DOM elements. See setCellCssStyles for more.

# grid.resetActiveCell()

Resets active cell.

# grid.setActiveCell(row, cell)

row - A row index.

cell - A column index.

Sets an active cell.

# grid.setCellCssStyles(key, hash)

key - A string key. Will overwrite any data already associated with this key.

hash - A hash of additional cell CSS classes keyed by row number and then by column id. Multiple CSS classes can be specified and separated by space.

Example:

{

    0:    {

        "number_column":    "cell-bold",

        "title_column":     "cell-title cell-highlighted"

    },

    4:    {

        "percent_column":    "cell-highlighted"

    }

}

Sets CSS classes to specific grid cells by calling removeCellCssStyles(key) followed byaddCellCssStyles(key, hash). key is name for this set of styles so you can reference it later - to modify it or remove it, for example. hash is a per-row-index, per-column-name nested hash of CSS classes to apply.

Suppose you have a grid with columns:

["login", "name", "birthday", "age", "likes_icecream", "favorite_cake"]

...and you'd like to highlight the "birthday" and "age" columns for people whose birthday is today, in this case, rows at index 0 and 9. (The first and tenth row in the grid).

   .highlight{ background: yellow }

grid.setCellCssStyles("birthday_highlight", {

   0: {

        birthday: "highlight",

        age: "highlight"

       },

 

   9: {

         birthday: "highlight",

         age: "highlight"

       }

})

# Rendering

# grid.getCanvasNode()

Returns the DIV element matching class grid-canvas, which contains every data row currently being rendered in the DOM.

// Get the total number of data rows being rendered in the DOM.

var numRenderedRows = $(grid.getCanvasNode()).children().length;

# grid.getGridPosition()

Returns an object representing information about the grid's position on the page. The object takes the form:

{

  bottom:  [numPixels],

  height:  [numPixels],

  left:    [numPixels],

  right:   [numPixels],

  top:     [numPixels],

  visible: [boolean],

     [numPixels]

}

# grid.getRenderedRange(viewportTop, viewportLeft)

viewportTop (optional) - The number of pixels offset from the top of the grid.

viewportLeft (optional) - The number of pixels offset from the left of the grid.

If passed no arguments, returns an object that tells you the range of rows (by row number) currently being rendered, as well as the left/right range of pixels currently rendered. { top: [rowIndex], bottom: [rowIndex], leftPx: [numPixels], rightPx: [numPixels] }

The options viewportTop and viewportLeft are optional, and tell what what would be rendered at a certain scroll top/left offset. For example, grid.getRenderedRange(1000) would essentially be asking: "if I were to scroll 1000 pixels down, what rows would be rendered?"

# grid.getViewport(viewportTop, viewportLeft)

viewportTop (optional) - The number of pixels offset from the top of the grid.

viewportLeft (optional) - The number of pixels offset from the left of the grid.

Returns an object telling you which rows are currently being displayed on the screen, and also the pixel offsets for left/right scrolling. { top: [rowIndex], bottom: [rowIndex], leftPx: [numPixels], rightPx: [numPixels] }

Also accepts viewportTop and viewportLeft offsets to tell you what would be shown to the user if you were to scroll to that point.

# grid.invalidate()

Redraws the grid. Invalidates all rows and calls render().

// Change the name property of the first row

var data = grid.getData();

data[0].name = "New name!"

 

// Call invalidate to render the data again. No need to call render, as this calls it for you.

grid.invalidate();

# grid.invalidateAllRows()

Tells the grid that all rows in the table are invalid. (If render() is called after this, it will redraw the entire grid.)

# grid.invalidateRow(row)

row - A row index.

Tells the grid that the row specified by row is invalid. (If render() is called after this, it will redraw the contents of that row.)

# grid.invalidateRows(rows)

rows - An array of row indices.

Accepts an array of row indices, and tells the grid that those rows are invalid. (If render() is called after this, it will redraw the contents of those rows.)

// Change the name property of the first row

var data = grid.getData();

data[0].name = "New name!"

data[1].name = "Another new name!"

 

// Call invalidateRows to invalidate the first two rows

grid.invalidateRows([0,1]);

 

// Call render to render them again

grid.render();

# grid.render()

Rerenders rows in the DOM.

# grid.resizeCanvas()

Resizes the canvas to fit the current DIV container. (For example, to resize the grid, you would first change the size of the div, then call resizeCanvas().)

# grid.scrollCellIntoView(row, cell)

row - A row index.

cell - A column index.

Scrolls the indicated cell into view.

Note that this does nothing unless the indicated column is already not in view. For example, if the grid is scrolled to the far left and you were looking at row 0, calling scrollCellIntoView(100,0) would not simply scroll you to row 100. But if column 8 were out of view and you calledscrollCellIntoView(100,8), then it would scroll down and to the right.

# grid.scrollRowIntoView(row, doPaging)

row - A row index.

doPaging - A boolean. If false, the grid will scroll so the indicated row is at the top of the view. If true, the grid will scroll so the indicated row is at the bottom of the view. Defaults to false.

Scrolls the view to the indicated row.

# grid.scrollRowToTop(row)

row - A row index.

Scrolls the view to the indicated row, placing the row at the top of the view.

# grid.updateCell(row, cell)

TODO

// put stuff here

# grid.updateRow(row)

TODO

// put stuff here

# grid.updateRowCount()

TODO

// put stuff here

# Headers

# grid.getHeaderRow()

Returns the element of a DIV row beneath the actual column headers. For an example of how you might use this, see the header row quick filter example, which grabs the element, appends inputs, and delegates events to the inputs.

# grid.getHeaderRowColumn(columnId)

columnId - The id string of a column.

If a header row is implemented and has one child for each column, as seen in the header row quick filter example, you may use this function to pass a columnId and get the individual cell from that header row. Returns a DIV element.

# grid.getSortColumns()

Returns an array of objects representing columns that have a sort glyph in the header:

{

  columnId: [string],

  sortAsc:  [boolean]

}

# grid.getTopPanel()

Returns the DIV element of the top panel. The panel is hidden by default, but you can show it by initializing the grid with showTopPanel set to true, or by callinggrid.setTopPanelVisibility(true).

// Create a subheader and attach it to the top panel

$("<div>Here is a subheader!</div>")

  .appendTo(grid.getTopPanel());

// Show the top panel

grid.setTopPanelVisibility(true);

# grid.setHeaderRowVisibility(visible)

Note: Earlier Versions used grid.showTopPanel() and grid.hideTopPanel() these have now been replaced with grid.setTopPanelVisibility(true) andgrid.setTopPanelVisibility(false); TODO

// put stuff here

 

DataView

Core concepts

SlickGrid is very flexible in how it consumes the data. The data is passed to the grid via the constructor and can also be accessed using the setData(data) and getData() methods. Data itself can be either an array-like object with a length property and an indexer (data[index]) or a custom data provider implementing the following interface:

• getLength() - returns the number of data items in the set
• getItem(index) - returns the item at a given index
• getItemMetadata(index) - returns the metadata for the item at a given index (optional)

DataView (Slick.Data.DataView included in slick.dataview.js) is one such data provider and it is part of the SlickGrid package.

If all of the data is available on the client (i.e. in a JavaScript array), DataView can provide many useful features that the grid itself doesn't have. (This fact that the grid lacks these features is by design - SlickGrid tries to keep the core lean and simple while encouraging modular design and data abstraction in its API.)

DataView works by taking in your data and acting as a data provider that you pass to SlickGrid instead of your original data array. For example, if you make DataView group data, it makes the grid think that the "group" rows are just regular data items, so the grid doesn't need to be aware of them. DataView tells the grid that those items have a custom display and behavior and provides implementations of both. You then wire up DataView's onRowCountChanged and onRowsChangedevents to update the grid and voila.

Here's a rough list of features that DataView adds to the grid:

• Paging.
• Multi-column sorting.
• Search.
• Multi-level grouping with totals.
• Expand/collapse groups.

DataView also enables very efficient updates in response to the changing data. Whenever something changes, it detects which rows need updating, and passes them in the onRowCountChanged andonRowsChanged events that it fires, so instead of rerendering the entire grid, you can simply invalidate the updated rows.

Getting started

To use the DataView, include slick.dataview.js:

// Create the DataView.

var dataView = new Slick.Data.DataView();

 

//Create columns

var columns = [

  {id: "column1", name: "ID", field: "id"},

  {id: "column2", name: "Language", field: "lang"},

  {id: "column3", name: "Year", field: "year"}

];

 

// Pass it as a data provider to SlickGrid.

var grid = new Slick.Grid(containerEl, dataView, columns, options);

 

// Make the grid respond to DataView change events.

dataView.onRowCountChanged.subscribe(function (e, args) {

  grid.updateRowCount();

  grid.render();

});

 

dataView.onRowsChanged.subscribe(function (e, args) {

  grid.invalidateRows(args.rows);

  grid.render();

});

Now we're ready to initialize it with some data. One important requirement that DataView imposes on the data it consumes is that every item has a unique identifier. DataView uses it to uniquely identify items and compare them to each other. By default, DataView uses the id property of the data item, but you can specify a different one by passing it in via an optional second argument in thesetItems(data, [objectIdProperty]). The id value must be serializable to a string.

var data = [

  {'id': 'l1', 'lang': 'Java', 'year': 1995},

  {'id': 'l2', 'lang': 'JavaScript', 'year': 1995},

  {'id': 'l3', 'lang': 'C#', 'year': 2000},

  {'id': 'l4', 'lang': 'Python', 'year': 1991}];

 

// This will fire the change events and update the grid.

dataView.setItems(data);

You can call getItems() to get the data array back.

Mapping rows vs items

Ok, let's reiterate - DataView takes in a data array as an input, manipulates it, and presents the results to the grid by acting as a data provider, i.e. exposing the data provider methods getItem(index),getLength() and getItemMetadata(index). In handling grid events, it's important to always keep in mind that the row indexes the grid refers to are, in fact, the indexes into the output of the DataView! For example, if you're handling a grid onClick event and it's giving you a row index, to look up the data item, you need to call dataView.getItem(rowIndex) and not data[rowIndex].

In general, whenever we talk about rows, we mean the data as the grid sees it, so, if you're using a DataView, that would be the output of the DataView (dataView.getItem(index)). Whenever we talk about items, we mean the input of the DataView (data[index] or dataView.getItems()[index]). You'll notice that it is somewhat confusing that getItem(index) returns a row while getItems()returns items. Unfortunately, it's this way for historical reasons. getItem(index) is part of the data provider interface. In retrospect, it would be better if the DataView exposed a getDataProvider()method.

DataView Methods

Since each item has a unique id, they are often used to keep track of ids/items/rows/indices and to map one to another.

These methods are exposed by the DataView as part of the data provider interface:

• getItems() - Returns the original data array.
• getItem(row) - With a row index of an item in the grid, return the item.
• getItemMetadata(idx) - Returns the item metadata at a given index.
• getLength() - Returns the number of rows in the grid.

DataView exposes several methods in order to map ids to items to rows in the grid to indices in the original data array:

• getItemById(id) - With an item's id, return the item.
• getIdxById(id) - With an item's id, return the index of the item in the original data array.
• getRowById(id) - With an item's id, return the row of the item in the grid.
• getItemByIdx(idx) - With an index of an item in the original data array, return the item. Equivalent to getItems()[index].
• mapIdsToRows(idArray) - Maps an array of item ids into rows in the grid.
• mapRowsToIds(rowArray) - Maps an array of rows in the grid into item ids.

Synchronizing selection & cell CSS styles

One of the most common questions about DataView is how to synchronize the selection or cell CSS styles state on DataView changes. Let's say that the user selected a row. If they then change the filter on the DataView to hide some items, the grid gets a call to invalidate all changed rows, including the selected one, but it doesn't know that the item that was displayed there has moved somewhere else. What we need to do, is to store the ids of items that were selected, and to update the selection on the grid any time the DataView is modified.

Luckily, there is a helper method on the DataView that can take care of that:

• syncGridSelection(grid, preserveHidden) - Synchronizes grid's selected rows with the DataView by subscribing to the grid's onSelectedRowsChanged event as well as the DataView'sonRowsChanged & onRowCountChanged events. If preserveHidden is true, it will preserve selected items even if they are not visible as rows. For example, if you select an item, change the DataView filter so that that item is no longer presented to the grid and then change it back, the item will remain selected. If preserveHidden is false, all selected items that can't be mapped onto rows are dropped.

The implementation is really simple, and I'll include it here for the reference:

function syncGridSelection(grid, preserveHidden) {

  var self = this;

  var selectedRowIds = self.mapRowsToIds(grid.getSelectedRows());;

  var inHandler;

 

  function update() {

    if (selectedRowIds.length > 0) {

      inHandler = true;

      var selectedRows = self.mapIdsToRows(selectedRowIds);

      if (!preserveHidden) {

        selectedRowIds = self.mapRowsToIds(selectedRows);

      }

      grid.setSelectedRows(selectedRows);

      inHandler = false;

    }

  }

 

  grid.onSelectedRowsChanged.subscribe(function(e, args) {

    if (inHandler) { return; }

    selectedRowIds = self.mapRowsToIds(grid.getSelectedRows());

  });

 

  this.onRowsChanged.subscribe(update);

 

  this.onRowCountChanged.subscribe(update);

}

NOTE: This only works with the RowSelectionModel. CellSelectionModel isn't supported yet (I'm open to pull requests!).

There is a similar helper method to synchronize the cell CSS styles:

function syncGridCellCssStyles(grid, key) {

  var hashById;

  var inHandler;

 

  // since this method can be called after the cell styles have been set,

  // get the existing ones right away

  storeCellCssStyles(grid.getCellCssStyles(key));

 

  function storeCellCssStyles(hash) {

    hashById = {};

    for (var row in hash) {

      var id = rows[row][idProperty];

      hashById[id] = hash[row];

    }

  }

 

  function update() {

    if (hashById) {

      inHandler = true;

      ensureRowsByIdCache();

      var newHash = {};

      for (var id in hashById) {

        var row = rowsById[id];

        if (row != undefined) {

          newHash[row] = hashById[id];

        }

      }

      grid.setCellCssStyles(key, newHash);

      inHandler = false;

    }

  }

 

  grid.onCellCssStylesChanged.subscribe(function(e, args) {

    if (inHandler) { return; }

    if (key != args.key) { return; }

    if (args.hash) {

      storeCellCssStyles(args.hash);

    }

  });

 

  this.onRowsChanged.subscribe(update);

 

  this.onRowCountChanged.subscribe(update);

}

Sorting

Sorting is pretty simple:

// Subscribe to the grid's onSort event.

// It only gets fired for sortable columns, so make sure your column definition has `sortable = true`.

grid.onSort.subscribe(function(e, args) {

  // args.multiColumnSort indicates whether or not this is a multi-column sort.

  // If it is, args.sortCols will have an array of {sortCol:..., sortAsc:...} objects.

  // If not, the sort column and direction will be in args.sortCol & args.sortAsc.

 

  // We'll use a simple comparer function here.

  var comparer = function(a, b) {

    return (a[args.sortCol.field] > b[args.sortCol.field]) ? 1 : -1;

  }

 

  // Delegate the sorting to DataView.

  // This will fire the change events and update the grid.

  dataView.sort(comparer, args.sortAsc);

});

Note that calling sort() on the DataView modifies the original data array that was passed in tosetItems(data)!

There's also a fastSort(field, isAscending) method on the DataView to do a fast lexicographic search that is especially handy for older versions of IE.

Updating data

Since DataView can't automatically detect when you're changing the data, you'll need to make these updates via the DataView. These updates will be applied directly to the original data array.

// Delete item with id 'l3' ('C#').

dataView.deleteItem('l3');

 

// Append item to the end.

dataView.addItem({'id': 'l5', 'lang': 'CoffeeScript'});

 

// Insert item at the beginning.

dataView.insertItem(0, {'id': 'l6', 'lang': 'TypeScript'});

 

// Update an existing item.

var item = dataView.getItemById('l4');

item['lang'] = 'Clojure';

dataView.updateItem('l4', item);

Each one of these updates will fire change events and the grid will get updated automatically.

Batching updates

Notice that in the example above, each update will result in the DataView recalculating its data and firing change events, resulting in the grid rerendering affected rows. If you need to make multiple changes, you should batch them up to avoid unnecessary operations:

// Suspend recalculations until endUpdate() is called.

dataView.beginUpdate();

 

dataView.addItem(...);

dataView.addItem(...);

dataView.sort(...);

 

// Indicate that we're done updating.

dataView.endUpdate();

Filtering

Paging

Grouping

Advanced topics

API reference

Grid Options

As included in the examples or described in stable releases:

Option	Default	Description
asyncEditorLoading	false	Makes cell editors load asynchronously after a small delay. This greatly increases keyboard navigation speed.
asyncEditorLoadDelay	100	Delay after which cell editor is loaded. Ignored unless asyncEditorLoading is true.
asyncPostRenderDelay	50
autoEdit	true	Cell will not automatically go into edit mode when selected.
autoHeight	false	This disables vertical scrolling.
cellFlashingCssClass	“flashing”	A CSS class to apply to flashing cells via flashCell().
cellHighlightCssClass	“selected”	A CSS class to apply to cells highlighted via setHighlightedCells().
dataItemColumnValueExtractor	null
defaultColumnWidth	80
defaultFormatter	defaultFormatter
editable	false
editCommandHandler	queueAndExecuteCommand	Not listed as a default under options in slick.grid.js
editorFactory	null	A factory object responsible to creating an editor for a given cell. Must implement getEditor(column).
editorLock	Slick.GlobalEditorLock	A Slick.EditorLock instance to use for controlling concurrent data edits.
enableAddRow	false	If true, a blank row will be displayed at the bottom - typing values in that row will add a new one. Must subscribe to onAddNewRow to save values.
enableAsyncPostRender	false	If true, async post rendering will occur and asyncPostRender delegates on columns will be called.
enableCellRangeSelection	null	**WARNING**: Not contained in SlickGrid 2.1, may be deprecated
enableCellNavigation	true	Appears to enable cell virtualisation for optimised speed with large datasets
enableColumnReorder	true
enableRowReordering	null	**WARNING**: Not contained in SlickGrid 2.1, may be deprecated
enableTextSelectionOnCells	false
explicitInitialization	false	See: Example: Explicit Initialization
forceFitColumns	false	Force column sizes to fit into the container (preventing horizontal scrolling). Effectively sets column width to be 1/Number of Columns which on small containers may not be desirable
forceSyncScrolling	false
formatterFactory	null	A factory object responsible to creating a formatter for a given cell. Must implement getFormatter(column).
fullWidthRows	false	Will expand the table row divs to the full width of the container, table cell divs will remain aligned to the left
headerRowHeight	25
leaveSpaceForNewRows	false
multiColumnSort	false	See: Example: Multi-Column Sort
multiSelect	true
rowHeight	25
selectedCellCssClass	“selected”
showHeaderRow	false
syncColumnCellResize	false	If true, the column being resized will change its width as the mouse is dragging the resize handle. If false, the column will resize after mouse drag ends.
topPanelHeight	25

Column Options

Options which you can apply to the columns objects.

Option	Default	Description
asyncPostRender	null	This accepts a function of the form function(cellNode, row, dataContext, colDef) and is used to post-process the cell’s DOM node / nodes
behavior	null	Used by the the slick.rowMoveManager.js plugin for moving rows. Has no effect without the plugin installed.
cannotTriggerInsert	null	In the “Add New” row, determines whether clicking cells in this column can trigger row addition. If true, clicking on the cell in this column in the “Add New” row will not trigger row addition.
cssClass	””	Accepts a string as a class name, applies that class to every row cell in the column.
defaultSortAsc	true	When set to true, the first user click on the header will do a ascending sort. When set to false, the first user click on the header will do an descending sort.
editor	null	The editor for cell edits {TextEditor, IntegerEditor, DateEditor…} See slick.editors.js
field	””	The property name in the data object to pull content from. (This is assumed to be on the root of the data object.)
focusable	true	When set to false, clicking on a cell in this column will not select the row for that cell. The cells in this column will also be skipped during tab navigation.
formatter	null	This accepts a function of the form function(row, cell, value, columnDef, dataContext) and returns a formatted version of the data in each cell of this column. For example, settingformatter to function(r, c, v, cd, dc) { return “Hello!”; } would overwrite every value in the column with “Hello!” SeedefaultFormatter in slick.grid.js for an example formatter.
headerCssClass	null	Accepts a string as a class name, applies that class to the cell for the column header.
id	””	A unique identifier for the column within the grid.
maxWidth	null	Set the maximum allowable width of this column, in pixels.
minWidth	30	Set the minimum allowable width of this column, in pixels.
name	””	The text to display on the column heading.
rerenderOnResize	false	If set to true, whenever this column is resized, the entire table view will rerender.
resizable	true	If false, column can no longer be resized.
selectable	true	If false, when a row is selected, the CSS class for selected cells (“selected” by default) is not applied to the cell in this column.
sortable	false	If true, the column will be sortable by clicking on the header.
toolTip	””	If set to a non-empty string, a tooltip will appear on hover containing the string.
width		Width of the column in pixels. (May often be overridden by things like minWidth, maxWidth, forceFitColumns, etc.)

Grid Events

SlickGrid exposes the following events:

• onScroll ({ scrollLeft: number, scrollTop: number })
• onSort ({ multiColumnSort: boolean, sortCol: Object, sortCols: Object[], sortAsc: boolean })
• onHeaderContextMenu ({ column: Object })
• onHeaderClick ({ column: Object })
• onMouseEnter ({})
• onMouseLeave ({})
• onClick ({ row: number, cell: number })
• onDblClick ({ row: number, cell: number })
• onContextMenu ({})
• onKeyDown ({ row: number, cell: number })
• onAddNewRow ({ item: any, column: Object })
• onValidationError ({ editor: Object, cellNode: Object, validationResult: Object, row: number, cell: number, column: Object })
• onViewportChanged ({})
• onColumnsReordered ({})
• onColumnsResized ({})
• onCellChange ({ row: number, cell: number, item: any })
• onBeforeEditCell ({ row: number, cell: number, item: any, column: Object })
• onBeforeCellEditorDestroy ({ editor: Object })
• onHeaderCellRendered ({ node: Object, column: Object })
• onBeforeHeaderCellDestroy ({ node: Object, column: Object })
• onBeforeDestroy ({})
• onActiveCellChanged ({ row: number, cell: number }|null)
• onActiveCellPositionChanged ({})
• onDragInit
• onDragStart
• onDrag
• onDragEnd
• onSelectedRowsChanged ({ rows: number[] })
• onCellCssStylesChanged ({ key: string, hash: Object })

You can subscribe to the above events using a syntax similar to:

gridInstance.onXYZEvent.subscribe(function(e, args){

    //event handling code.

});

The handler is called with these arguments:
e: Slick.EventData, which mimics the jQuery EventData.
args: event specific data

Event handlers can also be removed with

gridInstance.onXYZEvent.unsubscribe(fn);

Providing data to the grid

Overview

The data is passed to the grid via the constructor and can also be accessed using thesetData(data) and getData() methods. Data itself can be either an array-like object with alength property and an indexer (data[index]) or a custom data provider implementing the following interface:

• getLength() - returns the number of data items in the set
• getItem(index) - returns the item at a given index
• getItemMetadata(index) - returns the metadata for the item at a given index (optional)

Item Metadata

getItemMetadata provides a powerful way of specifying additional information about a data item that let the grid customize the appearance and handling of a particular data item. The method should returnnull if the item requires no special handling, or an object in the following general format:

{

  // properties describing metadata related to the item (i.e. grid row) itself

  "<property>": value,

  "<property>": value,

 

  // properties describing metadata related to individual columns

  "columns":  {

    "<column index>":  {

      // metadata indexed by column index

      "<property>": value,

      "<property>": value

    },

 

    "<column id>":  {

      // metadata indexed by column id

      "<property>": value,

      "<property>": value

    }

  }

}

Row-level properties

• cssClasses (string) - One or more (space-separated) CSS classes to be added to the entire row.
• focusable (boolean) - Whether or not any cells in the row can be set as "active".
• selectable (boolean) - Whether or not a row or any cells in it can be selected.

Column-level properties

• focusable (boolean) - Whether or not a cell can be set as "active".
• selectable (boolean) - Whether or not a cell can be selected.
• formatter (Function) - A custom cell formatter.
• editor (Function) - A custom cell editor.
• colspan (number|string) - Number of columns this cell will span. Can also contain "*" to indicate that the cell should span the rest of the row.

Order of checks

When looking up a property, the grid checks in the following order:

1. Row-level item metadata.
2. Column-level item metadata by column id.
3. Column-level item metadata by column index.
4. Column definition.
5. Grid options.
6. Grid defaults.

Examples

See colspan example.