Writing custom cell editors

Basic interface

function IEditor(args) {

    // initialize the UI


    /*********** REQUIRED METHODS ***********/

    this.destroy = function() {
        // remove all data, events & dom elements created in the constructor
    };

    this.focus = function() {
        // set the focus on the main input control (if any)
    };

    this.isValueChanged = function() {
        // return true if the value(s) being edited by the user has/have been changed
        return false;
    };

    this.serializeValue = function() {
        // return the value(s) being edited by the user in a serialized form
        // can be an arbitrary object
        // the only restriction is that it must be a simple object that can be passed around even
        // when the editor itself has been destroyed
        return "";
    };

    this.loadValue = function(item) {
        // load the value(s) from the data item and update the UI
        // this method will be called immediately after the editor is initialized
        // it may also be called by the grid if if the row/cell being edited is updated via grid.updateRow/updateCell
    };

    this.applyValue = function(item,state) {
        // deserialize the value(s) saved to "state" and apply them to the data item
        // this method may get called after the editor itself has been destroyed
        // treat it as an equivalent of a Java/C# "static" method - no instance variables should be accessed
    };

    this.validate = function() {
        // validate user input and return the result along with the validation message, if any
        // if the input is valid, return {valid:true,msg:null}
        return { valid: false, msg: "This field is required" };        
    };


    /*********** OPTIONAL METHODS***********/

    this.hide = function() {
        // if implemented, this will be called if the cell being edited is scrolled out of the view
        // implement this is your UI is not appended to the cell itself or if you open any secondary
        // selector controls (like a calendar for a datepicker input)
    };

    this.show = function() {
        // pretty much the opposite of hide
    };

    this.position = function(cellBox) {
        // if implemented, this will be called by the grid if any of the cell containers are scrolled
        // and the absolute position of the edited cell is changed
        // if your UI is constructed as a child of document BODY, implement this to update the
        // position of the elements as the position of the cell changes
        // 
        // the cellBox: { top, left, bottom, right, width, height, visible }
    };
}

Compound editors

In most cases, there will be a one-to-one relationship between the fields of your data objects and cells in the grid.
Occasionally, though, you may want to combine several fields into one cell in order to improve the usability of your application. A custom formatter can easily pull information from multiple fields of your data object and present it in one cell. SlickGrid handles edition those cells by using the loadValue(), serializeValue() and applyValue() methods of your editor. While it may seem more complicated than a simple getValue() and setValue(), without them, compound editors would not have been possible.