YUI Library Examples: DataTable Control: Quick Edit

DataTable Quick Edit was developed by John Lindal. This was originally a concept for Yahoo! APT by Neal Sainani.

Custom CSS for this Example

DataTable Quick Edit extension code:

Also available here.

/* This code should not be modified */
(function(){
/**********
* Quick Edit extension to YUI 2 DataTable
* Author: lindalj@yahoo-inc.com / John Lindal
* @submodule Quick Edit
* @class YAHOO.widget.QuickEditDataTable
***********/
(function(){

var lang = YAHOO.lang,
        Dom = YAHOO.util.Dom;

/**
     * The QuickEditDataTable class extends the DataTable class to provide
     * Quick Edit mode.  (It could just as easily extend
     * ScrollingDataTable.)  QuickEdit mode allows the user to edit all the
     * values that are visible in the table, controlled by the column
     * configuration.  Each editable cell contains an input field.  If the
     * user decides to save the changes, then you can extract the changes
     * by calling <code>getQuickEditChanges()</code>.
     * 
     * For a column to be editable in QuickEdit mode, the column
     * configuration must include <code>quickEdit</code>.  The contents of
     * this object define the column's behavior in QuickEdit mode.
     * 
     * If a column should not be editable, but needs to be formatted
     * differently in QuickEdit mode, then you must define qeFormatter in
     * the column configuration. This is simply a normal cell formatter
     * function that will be used in QuickEdit mode.  The static functions
     * <code>readonly*QuickEditFormatter</code> provide examples.
     * 
     * The following configuration can be provided as part of quickEdit:
     * 
     * <dl>
     * 
     * <dt>copyDown</dt><dd>If true, the top cell in the column will have a
     * button to copy the value down to the rest of the rows.</dd>
     * 
     * <dt>formatter</dt><dd>The cell formatter which will render an
     * appropriate form field: <input type="text">, <textarea>,
     * or <select>.</dd>
     * 
     * <dt>validation</dt><dd>Validation configuration for every field in
     * the column.</dd>
     * 
     * </dl>
     * 
     * The following configuration can be provided as part of
     * quickEdit.validation:
     * 
     * <dl>
     * 
     * <dt>css</dt><dd>CSS classes encoding basic validation rules.  Note
     * that this will only work if you uncomment the call to
     * <code>validateFromCSSData()</code> inside
     * <code>_validateElements()</code>.</dd>
     * 
     * <dt>fn</dt><dd>A function that will be called with the DataTable as
     * its scope and the cell's form element as the argument. Return true
     * if the value is valid. Otherwise, call this.displayMessage(...) to
     * display an error and return false.</dd>
     * 
     * <dt>msg</dt><dd>A map of types to messages that will be displayed
     * when a basic or regex validation rule fails. Currently, the only
     * valid type is regex.  If you copy the implementation of
     * validateFromCSSData(), from FormManager in the YUI 3 Gallery, then
     * you will be able to specify more types:  required, min_length,
     * max_length, integer, and decimal.</dd>
     * 
     * <dt>regex</dt><dd>Regular expression that the value must satisfy in
     * order to be considered valid.</dd>
     * 
     * </dl>
     * 
     * Custom QuickEdit Formatters
     * 
     * To write a custom cell formatter for QuickEdit mode, you must
     * structure the function as follows:
     * 
     * function myQuickEditFormatter(el, oRecord, oColumn, oData) {
     *   var markup =
     *     '<input type="text" class="{yiv} yui-quick-edit yui-quick-edit-key:{key}"/>' +
     *     YAHOO.widget.QuickEditDataTable.MARKUP_QE_ERROR_DISPLAY;
     *     
     *     el.innerHTML = lang.substitute(markup, {
     *       key: oColumn.key,
     *       yiv: oColumn.quickEdit.validation ? (oColumn.quickEdit.validation.css || '') : ''
     *     });
     *     
     *     el.firstChild.value = extractMyEditableValue(oData);
     *     
     *     YAHOO.widget.QuickEditDataTable.copyDownFormatter.apply(this, arguments);
     * };
     * 
     * You can use textarea or select instead of input, but you can only
     * create a single field.
     * 
     * <code>extractMyEditableValue</code> does not have to be a separate
     * function nor must it be limited to using only oData. The work should
     * normally be done inline in the formatter function, but the name of
     * the sample function makes the point clear.
     *
     * @module QuickEdit
     * @namespace YAHOO.widget
     * @class QuickEditDataTable
     * @extends YAHOO.widget.DataTable
     * @constructor
     * @param elContainer {HTMLElement} Container element for the TABLE.
     * @param aColumnDefs {Object[]} Array of object literal Column definitions.
     * @param oDataSource {YAHOO.util.DataSource} DataSource instance.
     * @param oConfigs {object} (optional) Object literal of configuration values.
     */
    YAHOO.widget.QuickEditDataTable = function(elContainer,aColumnDefs,oDataSource,oConfigs)
    {
        YAHOO.widget.QuickEditDataTable.superclass.constructor.call(this, elContainer,aColumnDefs,oDataSource,oConfigs);

this.hasQEMessages = false;

};

var QEDT = YAHOO.widget.QuickEditDataTable,
        quick_edit_re             = /yui-quick-edit-key:([^\s]+)/,
        qe_row_status_even_prefix = 'yui-quick-edit-even-has',
        qe_row_status_odd_prefix  = 'yui-quick-edit-odd-has',
        qe_row_status_pattern     = '(?:^|\\s)(?:yui-quick-edit-(even|odd)-has([a-z]+))(?= |$)',
        qe_row_status_re          = new RegExp(qe_row_status_pattern),
        qe_cell_status_prefix     = 'yui-quick-edit-has',
        qe_cell_status_pattern    = '(?:^|\\s)(?:' + qe_cell_status_prefix + '([a-z]+))(?= |$)',
        qe_cell_status_re         = new RegExp(qe_cell_status_pattern);

QEDT.status_order =
    [
        'error',
        'warn',
        'success',
        'info'
    ];

getStatusPrecedence = function(
        /* string */    status)
    {
        for (var i=0; i<QEDT.status_order.length; i++)
        {
            if (status == QEDT.status_order[i])
            {
                return i;
            }
        }

return QEDT.status_order.length;
    };

statusTakesPrecendence = function(
        /* string */    orig_status,
        /* string */    new_status)
    {
        return (!orig_status || getStatusPrecedence(new_status) < getStatusPrecedence(orig_status));
    };

YAHOO.lang.extend( 
        YAHOO.widget.QuickEditDataTable,
        YAHOO.widget.DataTable, 
    {
        /**
         * Switch to Quick Edit mode.  Columns that have quickEdit defined will
         * be editable.
         *
         * @method startQuickEdit
         */
        startQuickEdit : function() {

this.fireEvent('clearErrorNotification');

if (YAHOO.lang.isFunction(this.collapseAllRows)) {
                this.collapseAllRows();
            }

var cols        = this.getColumnSet().keys;
            this.qeSaveSort = [];
            this.qeSaveEdit = {};
            this.qeSaveFmt  = {};
            var sortable    = false;
            for (var i=0; i<cols.length; i++) {
                var col  = cols[i];
                sortable = sortable || col.sortable;
                this.qeSaveSort.push(col.sortable);
                col.sortable = false;

this.qeSaveEdit[ col.key ] = col.editor;
                col.editor                 = null;

if (!col.hidden && (col.quickEdit || col.qeFormatter)) {
                    var fn;
                    if (col.quickEdit && lang.isFunction(col.quickEdit.formatter)) {
                        fn = col.quickEdit.formatter;
                    }
                    else if (lang.isFunction(col.qeFormatter)) {
                        fn = col.qeFormatter;
                    }
                    else {
                        fn = QEDT.textQuickEditFormatter;
                    }

if (fn) {
                        var fmt                 = this._wrapFormatter(fn, col.formatter);
                        this.qeSaveFmt[col.key] = col.formatter;
                        col.formatter           = fmt;
                    }
                }
            }

Dom.addClass(this.getContainerEl(), 'yui-dt-quick-edit');
            this.subscribe('tbodyKeyEvent', this._moveFocus, null, this);

if (sortable) {
                this._initTheadEl();
            }
            this.render();
        },

_wrapFormatter : function(editFmt, origFmt) {

return function(el, oRecord, oColumn, oData) {
                if (oRecord) {
                    editFmt.apply(this, arguments);
                }
                else {
                    origFmt.apply(this, arguments);
                }
            };
        },

/**
         * Switch out of Quick Edit mode.  THIS DISCARDS ALL DATA!  If you
         * want to save the data, call getQuickEditChanges() BEFORE calling
         * this function.
         *
         * @method cancelQuickEdit
         */
        cancelQuickEdit : function() {

this.fireEvent('clearErrorNotification');

var cols     = this.getColumnSet().keys;
            var sortable = false;
            for (var i=0; i<cols.length; i++) {
                var col      = cols[i];
                col.sortable = this.qeSaveSort[i];
                sortable     = sortable || col.sortable;
                col.editor   = this.qeSaveEdit[ col.key ];
            }
            delete this.qeSaveSort;
            delete this.qeSaveEdit;

for (var key in this.qeSaveFmt) {
                if (lang.hasOwnProperty(this.qeSaveFmt, key)) {
                    var col       = this.getColumn(key);
                    col.formatter = this.qeSaveFmt[key];
                }
            }
            delete this.qeSaveFmt;

Dom.removeClass(this.getContainerEl(), 'yui-dt-quick-edit');
            this.unsubscribe('tbodyKeyEvent', this._moveFocus);

if (sortable) {
                this._initTheadEl();
            }
            this.render();
        },

/**
         * Return the changed values.  For each row, an object is created
         * with only the changed values.  The object keys are the column keys.
         *
         * @method getQuickEditChanges
         * @return {mixed} array if all validation passed, false otherwise
         */
        getQuickEditChanges : function() {

if (!this.validateQuickEdit()) {
                return false;
            }

var changes = [];

var tr = this.getFirstTrEl();
            while (tr) {
                var rec  = this.getRecord(tr);
                var list = Dom.getElementsByClassName(quick_edit_re, null, tr);

var change = {};
                changes.push(change);

for (var i=0; i<list.length; i++) {
                    var m    = quick_edit_re.exec(list[i].className);
                    var key  = m[1];
                    var col  = this.getColumn(key);
                    var prev = rec.getData(key);

var val = list[i].value;
                    if (col.parser) {
                        val = col.parser.call(this, val);
                    }

if (col.quickEditChanged ? col.quickEditChanged(prev, val) :
                            val !== (prev ? prev.toString() : '')) {
                        change[key] = val;
                    }
                }

tr = this.getNextTrEl(tr);
            }

return changes;
        },

/**
         * Copy value from first cell to all other cells in the column.
         *
         * @method _quickEditCopyDown
         * @param e {Event} triggering event
         * @param cell {Element} cell from which to copy
         * @private
         */
        _quickEditCopyDown : function(
            /* event */     e,
            /* element */   cell) {

var list = Dom.getElementsByClassName(quick_edit_re, null, cell);
            if (!list || !list.length) {
                return;
            }

var value = list[0].value;
            while (1) {
                cell = this.getBelowTdEl(cell);
                if (!cell) {
                    break;
                }

list = Dom.getElementsByClassName(quick_edit_re, null, cell);
                if (list && list.length) {
                    list[0].value = value;
                }
            }
        },

/**
         * Validate the quick edit data.
         *
         * @method validateQuickEdit
         * @return {boolean} true if all validation checks pass
         */
        validateQuickEdit : function() {

this.clearMessages();
            var status = true;

var e1 = this.getTbodyEl().getElementsByTagName('input');
            var e2 = this.getTbodyEl().getElementsByTagName('textarea');

status = this._validateElements(e1) && status;	// status last to guarantee call
            status = this._validateElements(e2) && status;

if (!status) {
                this.fireEvent('notifyErrors');
            }

return status;
        },

/**
         * Validate the given form fields.
         *
         * @method _validateElements
         * @param e {Array} Array of form fields.
         * @return {boolean} true if all validation checks pass
         * @private
         */
        _validateElements : function(
            /* array */ e) {

var status = true;
            for (var i=0; i<e.length; i++) {
                var col = this.getColumn(e[i]);
                if (!col.quickEdit) {
                    continue;
                }
                var msg_list = col.quickEdit.validation ? col.quickEdit.validation.msg : null;
/*
                // see yui3-gallery:gallery-formmgr for an example of validateFromCSSData()

if (col.quickEdit.validation
                        && lang.isFunction(col.quickEdit.validation.fn)
                        && !col.quickEdit.validation.fn.call(this, e[i])) {
                    status = false;
                    continue;
                }
            }

return status;
        },

/**
         * Clear all validation messages in quick edit mode.
         *
         * @method clearMessages
         */
        clearMessages : function() {

this.hasQEMessages = false;

this.fireEvent('clearErrorNotification');

var list = Dom.getElementsByClassName(qe_row_status_re, null, this.getTbodyEl());
            Dom.removeClass(list, qe_row_status_re);

list = Dom.getElementsByClassName(qe_cell_status_re, null, this.getTbodyEl());
            Dom.removeClass(list, qe_cell_status_re);

for (var i=0; i<list.length; i++) {
                var m = Dom.getElementsByClassName(QEDT.CLASS_QE_ERROR_TEXT, null, list[i]);
                if (m && m.length > 0) {
                    m[0].innerHTML = '';
                }
            }
        },

/**
         * Display a message for a quick edit field.  If an existing message with
         * a higher precedence is already visible, it will not be replaced.
         *
         * @method displayMessage
         * @param e {Element} form field
         * @param msg {String} message to display
         * @param type {String} message type: error, warn, success, info
         * @param scroll {boolean} If false, does not scroll, even if this is the first message to display.
         */
        displayMessage : function(
            /* element */   e,
            /* string */    msg,
            /* string */    type,
            /* boolean */   scroll) {

if (lang.isUndefined(scroll)) {
                scroll = true;
            }

var row = this.getTrEl(e);
            if (statusTakesPrecendence(this._getElementStatus(row, qe_row_status_re), type)) {
                if (!this.hasQEMessages && scroll) {
                    this.getFirstTdEl(row).scrollIntoView();
                }

if (Dom.hasClass(row, 'yui-dt-even')) {
                    Dom.replaceClass(row, qe_row_status_re, qe_row_status_even_prefix + type);
                }
                else {
                    Dom.replaceClass(row, qe_row_status_re, qe_row_status_odd_prefix + type);
                }
                this.hasQEMessages = true;
            }

var cell = this.getTdEl(e);
            if (statusTakesPrecendence(this._getElementStatus(cell, qe_cell_status_re), type)) {
                if (msg) {
                    var m = Dom.getElementsByClassName(QEDT.CLASS_QE_ERROR_TEXT, null, cell);
                    if (m && m.length > 0) {
                        m[0].innerHTML = msg;
                    }
                }

Dom.replaceClass(cell, qe_cell_status_re, qe_cell_status_prefix + type);
                this.hasQEMessages = true;
            }
        },

/**
         * Return the status of the field.
         *
         * @method _getElementStatus
         * @param e {Element} form field
         * @param r {RegExp} regex to match against className
         * @private
         */
        _getElementStatus : function(
            /* string/object */ e,
            /* regex */         r) {

var m = e.className.match(r);
            return ((m && m.length) ? m[1] : false);
        },

/**
         * Shift the focus up/down within a column.
         *
         * @method _moveFocus
         * @param cssClass {String} Extra class to apply to the row.
         * @return {Element} reference to the new row
         * @private
         */
        _moveFocus : function(data) {
            var e   = data.event;
            var key = YAHOO.util.Event.getCharCode(e);
            if (e.ctrlKey && (key == 38 || key == 40)) {    // Ctrl-up/down
                var target = YAHOO.util.Event.getTarget(e);
                var cell   = (key == 38 ? this.getAboveTdEl(target) : this.getBelowTdEl(target));
                if (cell) {
                    var input = Dom.getElementsByClassName(quick_edit_re, null, cell)[0];
                    if (input) {
                        input.focus();
                        input.select();
                        YAHOO.util.Event.stopEvent(e);
                    }
                }
            }
        }
    });

YAHOO.lang.augmentObject(YAHOO.widget.QuickEditDataTable,
    {
        CLASS_QE_ERROR_TEXT     : 'yui-quick-edit-message-text',
        MARKUP_QE_ERROR_DISPLAY : '<div class="yui-quick-edit-message-text"></div>',

/**
         * Called with exactly the same arguments as any other cell
         * formatter, this function displays an input field.
         *
         * @method textQuickEditFormatter
         * @static
         */
        textQuickEditFormatter : function(el, oRecord, oColumn, oData)
        {
            var markup =
                '<input type="text" class="{yiv} yui-quick-edit yui-quick-edit-key:{key}"/>' +
                QEDT.MARKUP_QE_ERROR_DISPLAY;

el.innerHTML = lang.substitute(markup,
            {
                key: oColumn.key,
                yiv: oColumn.quickEdit.validation ? (oColumn.quickEdit.validation.css || '') : ''
            });

el.firstChild.value = oData;

QEDT.copyDownFormatter.apply(this, arguments);
        },

/**
         * Called with exactly the same arguments as any other cell
         * formatter, this function displays a textarea field.
         *
         * @method textareaQuickEditFormatter
         * @static
         */
        textareaQuickEditFormatter : function(el, oRecord, oColumn, oData) {

var markup =
                '<textarea class="{yiv} yui-quick-edit yui-quick-edit-key:{key}"/>' +
                QEDT.MARKUP_QE_ERROR_DISPLAY;

el.firstChild.value = oData;

QEDT.copyDownFormatter.apply(this, arguments);
        },

/**
         * Called with exactly the same arguments as any other cell
         * formatter, this function displays an email address without the
         * anchor tag.  Use this as the column's qeFormatter if the column
         * should not be editable in Quick Edit mode.
         *
         * @method readonlyLinkQuickEditFormatter
         * @static
         */
        readonlyEmailQuickEditFormatter : function(el, oRecord, oColumn, oData)
        {
            el.innerHTML = (oData ? oData : '');
        },

/**
         * Called with exactly the same arguments as any other cell
         * formatter, this function displays a link without the anchor tag.
         * Use this as the column's qeFormatter if the column should not be
         * editable in Quick Edit mode.
         *
         * @method readonlyLinkQuickEditFormatter
         * @static
         */
         readonlyLinkQuickEditFormatter : function(el, oRecord, oColumn, oData)
         {
            el.innerHTML = oData;
        },

/**
         * Called with exactly the same arguments as a normal cell
         * formatter, this function inserts a "Copy down" button if the
         * cell is in the first row of the DataTable.  Call this at the end
         * of your QuickEdit formatter.
         *
         * @method copyDownFormatter
         * @static
         */
        copyDownFormatter : function(el, oRecord, oColumn, oData)
        {
            if (oColumn.quickEdit.copyDown &&
                this.getRecordSet().getRecordIndex(oRecord) ==
                    this.getState().pagination.recordOffset)
            {
                var button       = document.createElement('button');
                button.title     = 'Copy down';
                button.innerHTML = '↓'

var msg = Dom.getElementsByClassName(QEDT.CLASS_QE_ERROR_TEXT, null, el)[0];
                el.insertBefore(button, msg);

YAHOO.util.Event.on(button, 'click', this._quickEditCopyDown, el, this);
            }
        }
    });

})();
})();

JavaScript to run this example

/* Modify as needed */
YAHOO.util.Event.onDOMReady( function() {

YAHOO.example.Data = {
        bookorders: [
            {author:"C.S. Lewis", year:1950, quantity:10, title:"The Lion, the Witch and the Wardrobe"},
            {author:"C.S. Lewis", year:1951, quantity:5, title:"Prince Caspian: The Return to Narnia"},
            {author:"C.S. Lewis", year:1952, quantity:2, title:"The Voyage of the Dawn Treader"},
            {author:"C.S. Lewis", year:1953, quantity:6, title:"The Silver Chair"},
            {author:"C.S. Lewis", year:1954, quantity:9, title:"The Horse and His Boy"},
            {author:"C.S. Lewis", year:1955, quantity:4, title:"The Magician's Nephew"},
            {author:"C.S. Lewis", year:1956, quantity:8, title:"The Last Battle"},
            {author:"C.S. Lewis", year:1938, quantity:10, title:"Out of the Silent Planet"},
            {author:"C.S. Lewis", year:1943, quantity:5, title:"Perelandra"},
            {author:"C.S. Lewis", year:1945, quantity:2, title:"That Hideous Strength"},
            {author:"Philip Pullman", year:1995, quantity:7, title:"Northern Lights"},
            {author:"Philip Pullman", year:1997, quantity:5, title:"The Subtle Knife"},
            {author:"Philip Pullman", year:2000, quantity:8, title:"The Amber Spyglass"},
            {author:"J. R. R. Tolkien", year:1937, quantity:5, title:"The Hobbit"},
            {author:"J. R. R. Tolkien", year:1955, quantity:12, title:"The Fellowship of the Ring"},
            {author:"J. R. R. Tolkien", year:1955, quantity:0, title:"The Two Towers"},
            {author:"J. R. R. Tolkien", year:1955, quantity:8, title:"The Return of the King"},
            {author:"Philip K. Dick", year:1966, quantity:5, title:"Do Androids Dream of Electric Sheep?"},
            {author:"Robert A. Heinlein", year:1959, quantity:4, title:"Starship Troopers"},
            {author:"Robert A. Heinlein", year:1961, quantity:7, title:"Stranger in a Strange Land"},
            {author:"Robert A. Heinlein", year:1966, quantity:3, title:"The Moon Is a Harsh Mistress"},
            {author:"A. E. van Vogt", year:1946, quantity:3, title:"Slan"},
            {author:"A. E. van Vogt", year:1950, quantity:5, title:"The Voyage of the Space Beagle"},
            {author:"A. E. van Vogt", year:1970, quantity:8, title:"Quest for the Future"}
        ]
    };

/**
    *
    * Create a YUI DataSource instance. This will create an XHR datasource and will use YQL 
    * to query the Flickr web service.
    *
    **/
    var myDataSource = new YAHOO.util.DataSource(YAHOO.example.Data.bookorders, {

responseType: YAHOO.util.DataSource.TYPE_JSARRAY,
        responseSchema: {
            fields: [ 'author', 'year', 'quantity', 'title' ]
        }
    });

/**
    *
    * Create a YUI DataTable instance.
    *
    **/
    var myDataTable = new YAHOO.widget.QuickEditDataTable(
        "quickedit_table",
        [
            {
                key:"title",
                label:"Title",
                resizeable: true,
                sortable: true
            },
            {
                key:"author",
                label:"Author",
                resizeable: true,
                sortable: true,
                quickEdit: {
                    validation: {
                        fn: function(e) {
                            if (e.value == "John Lindal") {
                                this.displayMessage(e, 'He has never been published!', 'error');
                                return false;
                            }
                            else {
                                return true;
                            }
                        }
                    }
                }
            },
            {
                key:"year",
                label:"Publication Date",
                resizeable: true,
                sortable: true,
                quickEdit: {
                    validation: {
                        regex: /^[0-9]{4}$/,
                        msg: {
                            regex: 'Please enter a four digit year.'
                        }
                    }
                }
            },
            {
                key:"quantity",
                label:"Quantity",
                resizeable: true,
                sortable: true,
                quickEdit: {
                    copyDown: true,
                    validation: {
//                          css: "yiv-integer:[0,]"
                        regex: /^[0-9]+$/,
                        msg: {
                            regex: 'Please enter a positive integer.'
                        }
                    }
                }
            },
        ],
        myDataSource,
        { 
            paginator: new YAHOO.widget.Paginator({
                rowsPerPage:5,
                containers:'pagination'
            })
        }
    );

/**
    * Quick Edit controls
    **/
    YAHOO.util.Event.on('start-quick-edit', 'click', function()
    {
        document.getElementById('start-quick-edit').disabled = true;
        YAHOO.util.Dom.setStyle('quick-edit-controls', 'display', 'inline');
        myDataTable.startQuickEdit();
    });

YAHOO.util.Event.on('save-quick-edit', 'click', function()
    {
        stopQuickEdit(true);
    });

YAHOO.util.Event.on('cancel-quick-edit', 'click', function()
    {
        stopQuickEdit(false);
    });

function stopQuickEdit(save)
    {
        if (save)
        {
            var changes = myDataTable.getQuickEditChanges();
            if (changes === false)
            {
                return false;
            }

document.getElementById('start-quick-edit').disabled = false;
        YAHOO.util.Dom.setStyle('quick-edit-controls', 'display', 'none');
        myDataTable.cancelQuickEdit();
        return true;
    }
});

YUI Logger Output:

Note: Logging and debugging is currently turned off for this example.

Reload with logging
and debugging enabled.

DataTable Control Examples:

More DataTable Control Resources:

All YUI 2.x users should review the YUI 2.8.2 security bulletin, which discusses a vulnerability present in YUI 2.4.0-2.8.1.