File: datatable/js/table.js

            /**
            View class responsible for rendering a `<table>` from provided data.  Used as
            the default `view` for `Y.DataTable.Base` and `Y.DataTable` classes.
            
            @module datatable
            @submodule datatable-table
            @since 3.6.0
            **/
            var toArray = Y.Array,
                YLang   = Y.Lang,
                fromTemplate = YLang.sub,
            
                isArray    = YLang.isArray,
                isFunction = YLang.isFunction;
            
            /**
            View class responsible for rendering a `<table>` from provided data.  Used as
            the default `view` for `Y.DataTable.Base` and `Y.DataTable` classes.
            
            
            
            @class TableView
            @namespace DataTable
            @extends View
            @since 3.6.0
            **/
            Y.namespace('DataTable').TableView = Y.Base.create('table', Y.View, [], {
            
                /**
                The HTML template used to create the caption Node if the `caption`
                attribute is set.
            
                @property CAPTION_TEMPLATE
                @type {String}
                @default '<caption class="{className}"></caption>'
                @since 3.6.0
                **/
                CAPTION_TEMPLATE: '<caption class="{className}"></caption>',
            
                /**
                The HTML template used to create the table Node.
            
                @property TABLE_TEMPLATE
                @type {String}
                @default '<table cellspacing="0" class="{className}"></table>'
                @since 3.6.0
                **/
                TABLE_TEMPLATE  : '<table cellspacing="0" class="{className}"></table>',
            
                /**
                The object or instance of the class assigned to `bodyView` that is
                responsible for rendering and managing the table's `<tbody>`(s) and its
                content.
            
                @property body
                @type {Object}
                @default undefined (initially unset)
                @since 3.5.0
                **/
                //body: null,
            
                /**
                The object or instance of the class assigned to `footerView` that is
                responsible for rendering and managing the table's `<tfoot>` and its
                content.
            
                @property foot
                @type {Object}
                @default undefined (initially unset)
                @since 3.5.0
                **/
                //foot: null,
            
                /**
                The object or instance of the class assigned to `headerView` that is
                responsible for rendering and managing the table's `<thead>` and its
                content.
            
                @property head
                @type {Object}
                @default undefined (initially unset)
                @since 3.5.0
                **/
                //head: null,
            
                //-----------------------------------------------------------------------//
                // Public methods
                //-----------------------------------------------------------------------//
            
                /**
                Returns the `<td>` Node from the given row and column index.  Alternately,
                the `seed` can be a Node.  If so, the nearest ancestor cell is returned.
                If the `seed` is a cell, it is returned.  If there is no cell at the given
                coordinates, `null` is returned.
            
                Optionally, include an offset array or string to return a cell near the
                cell identified by the `seed`.  The offset can be an array containing the
                number of rows to shift followed by the number of columns to shift, or one
                of "above", "below", "next", or "previous".
            
                <pre><code>// Previous cell in the previous row
                var cell = table.getCell(e.target, [-1, -1]);
            
                // Next cell
                var cell = table.getCell(e.target, 'next');
                var cell = table.getCell(e.taregt, [0, 1];</pre></code>
            
                This is actually just a pass through to the `bodyView` instance's method
                by the same name.
            
                @method getCell
                @param {Number[]|Node} seed Array of row and column indexes, or a Node that
                    is either the cell itself or a descendant of one.
                @param {Number[]|String} [shift] Offset by which to identify the returned
                    cell Node
                @return {Node}
                @since 3.5.0
                **/
                getCell: function (/* seed, shift */) {
                    return this.body && this.body.getCell &&
                        this.body.getCell.apply(this.body, arguments);
                },
            
                /**
                Returns the generated CSS classname based on the input.  If the `host`
                attribute is configured, it will attempt to relay to its `getClassName`
                or use its static `NAME` property as a string base.
            
                If `host` is absent or has neither method nor `NAME`, a CSS classname
                will be generated using this class's `NAME`.
            
                @method getClassName
                @param {String} token* Any number of token strings to assemble the
                    classname from.
                @return {String}
                @protected
                **/
                getClassName: function () {
                    // TODO: add attr with setter for host?
                    var host = this.host,
                        NAME = (host && host.constructor.NAME) ||
                                this.constructor.NAME;
            
                    if (host && host.getClassName) {
                        return host.getClassName.apply(host, arguments);
                    } else {
                        return Y.ClassNameManager.getClassName
                            .apply(Y.ClassNameManager,
                                   [NAME].concat(toArray(arguments, 0, true)));
                    }
                },
            
                /**
                Relays call to the `bodyView`'s `getRecord` method if it has one.
            
                @method getRecord
                @param {String|Node} seed Node or identifier for a row or child element
                @return {Model}
                @since 3.6.0
                **/
                getRecord: function () {
                    return this.body && this.body.getRecord &&
                        this.body.getRecord.apply(this.body, arguments);
                },
            
                /**
                Returns the `<tr>` Node from the given row index, Model, or Model's
                `clientId`.  If the rows haven't been rendered yet, or if the row can't be
                found by the input, `null` is returned.
            
                This is actually just a pass through to the `bodyView` instance's method
                by the same name.
            
                @method getRow
                @param {Number|String|Model} id Row index, Model instance, or clientId
                @return {Node}
                @since 3.5.0
                **/
                getRow: function (/* id */) {
                    return this.body && this.body.getRow &&
                        this.body.getRow.apply(this.body, arguments);
                },
            
            
                //-----------------------------------------------------------------------//
                // Protected and private methods
                //-----------------------------------------------------------------------//
                /**
                Updates the table's `summary` attribute.
            
                @method _afterSummaryChange
                @param {EventHandle} e The change event
                @protected
                @since 3.6.0
                **/
                _afterSummaryChange: function (e) {
                    this._uiSetSummary(e.newVal);
                },
            
                /**
                Updates the table's `<caption>`.
            
                @method _afterCaptionChange
                @param {EventHandle} e The change event
                @protected
                @since 3.6.0
                **/
                _afterCaptionChange: function (e) {
                    this._uiSetCaption(e.newVal);
                },
            
                /**
                Updates the table's width.
            
                @method _afterWidthChange
                @param {EventHandle} e The change event
                @protected
                @since 3.6.0
                **/
                _afterWidthChange: function (e) {
                    this._uiSetWidth(e.newVal);
                },
            
                /**
                Attaches event subscriptions to relay attribute changes to the child Views.
            
                @method _bindUI
                @protected
                @since 3.6.0
                **/
                _bindUI: function () {
                    var relay;
            
                    if (!this._eventHandles) {
                        relay = Y.bind('_relayAttrChange', this);
            
                        this._eventHandles = this.after({
                            columnsChange  : relay,
                            modelListChange: relay,
                            summaryChange  : Y.bind('_afterSummaryChange', this),
                            captionChange  : Y.bind('_afterCaptionChange', this),
                            widthChange    : Y.bind('_afterWidthChange', this)
                        });
                    }
                },
            
                /**
                Creates the `<table>`.
            
                @method _createTable
                @return {Node} The `<table>` node
                @protected
                @since 3.5.0
                **/
                _createTable: function () {
                    return Y.Node.create(fromTemplate(this.TABLE_TEMPLATE, {
                        className: this.getClassName('table')
                    })).empty();
                },
            
                /**
                Calls `render()` on the `bodyView` class instance.
            
                @method _defRenderBodyFn
                @param {EventFacade} e The renderBody event
                @protected
                @since 3.5.0
                **/
                _defRenderBodyFn: function (e) {
                    e.view.render();
                },
            
                /**
                Calls `render()` on the `footerView` class instance.
            
                @method _defRenderFooterFn
                @param {EventFacade} e The renderFooter event
                @protected
                @since 3.5.0
                **/
                _defRenderFooterFn: function (e) {
                    e.view.render();
                },
            
                /**
                Calls `render()` on the `headerView` class instance.
            
                @method _defRenderHeaderFn
                @param {EventFacade} e The renderHeader event
                @protected
                @since 3.5.0
                **/
                _defRenderHeaderFn: function (e) {
                    e.view.render();
                },
            
                /**
                Renders the `<table>` and, if there are associated Views, the `<thead>`,
                `<tfoot>`, and `<tbody>` (empty until `syncUI`).
            
                Assigns the generated table nodes to the `tableNode`, `_theadNode`,
                `_tfootNode`, and `_tbodyNode` properties.  Assigns the instantiated Views
                to the `head`, `foot`, and `body` properties.
            
            
                @method _defRenderTableFn
                @param {EventFacade} e The renderTable event
                @protected
                @since 3.5.0
                **/
                _defRenderTableFn: function (e) {
                    var container = this.get('container'),
                        attrs = this.getAttrs();
            
                    if (!this.tableNode) {
                        this.tableNode = this._createTable();
                    }
            
                    attrs.host  = this.get('host') || this;
                    attrs.table = this;
                    attrs.container = this.tableNode;
            
                    this._uiSetCaption(this.get('caption'));
                    this._uiSetSummary(this.get('summary'));
                    this._uiSetWidth(this.get('width'));
            
                    if (this.head || e.headerView) {
                        if (!this.head) {
                            this.head = new e.headerView(Y.merge(attrs, e.headerConfig));
                        }
            
                        this.fire('renderHeader', { view: this.head });
                    }
            
                    if (this.foot || e.footerView) {
                        if (!this.foot) {
                            this.foot = new e.footerView(Y.merge(attrs, e.footerConfig));
                        }
            
                        this.fire('renderFooter', { view: this.foot });
                    }
            
                    attrs.columns = this.displayColumns;
            
                    if (this.body || e.bodyView) {
                        if (!this.body) {
                            this.body = new e.bodyView(Y.merge(attrs, e.bodyConfig));
                        }
            
                        this.fire('renderBody', { view: this.body });
                    }
            
                    if (!container.contains(this.tableNode)) {
                        container.append(this.tableNode);
                    }
            
                    this._bindUI();
                },
            
                /**
                Cleans up state, destroys child views, etc.
            
                @method destructor
                @protected
                **/
                destructor: function () {
                    if (this.head && this.head.destroy) {
                        this.head.destroy();
                    }
                    delete this.head;
            
                    if (this.foot && this.foot.destroy) {
                        this.foot.destroy();
                    }
                    delete this.foot;
            
                    if (this.body && this.body.destroy) {
                        this.body.destroy();
                    }
                    delete this.body;
            
                    if (this._eventHandles) {
                        this._eventHandles.detach();
                        delete this._eventHandles;
                    }
            
                    if (this.tableNode) {
                        this.tableNode.remove().destroy(true);
                    }
                },
            
                /**
                Processes the full column array, distilling the columns down to those that
                correspond to cell data columns.
            
                @method _extractDisplayColumns
                @protected
                **/
                _extractDisplayColumns: function () {
                    var columns = this.get('columns'),
                        displayColumns = [];
            
                    function process(cols) {
                        var i, len, col;
            
                        for (i = 0, len = cols.length; i < len; ++i) {
                            col = cols[i];
            
                            if (isArray(col.children)) {
                                process(col.children);
                            } else {
                                displayColumns.push(col);
                            }
                        }
                    }
            
                    if (columns) {
                        process(columns);
                    }
            
                    /**
                    Array of the columns that correspond to those with value cells in the
                    data rows. Excludes colspan header columns (configured with `children`).
            
                    @property displayColumns
                    @type {Object[]}
                    @since 3.6.0
                    **/
                    this.displayColumns = displayColumns;
                },
            
                /**
                Publishes core events.
            
                @method _initEvents
                @protected
                @since 3.5.0
                **/
                _initEvents: function () {
                    this.publish({
                        // Y.bind used to allow late binding for method override support
                        renderTable : { defaultFn: Y.bind('_defRenderTableFn', this) },
                        renderHeader: { defaultFn: Y.bind('_defRenderHeaderFn', this) },
                        renderBody  : { defaultFn: Y.bind('_defRenderBodyFn', this) },
                        renderFooter: { defaultFn: Y.bind('_defRenderFooterFn', this) }
                    });
                },
            
                /**
                Constructor logic.
            
                @method intializer
                @param {Object} config Configuration object passed to the constructor
                @protected
                @since 3.6.0
                **/
                initializer: function (config) {
                    this.host = config.host;
            
                    this._initEvents();
            
                    this._extractDisplayColumns();
            
                    this.after('columnsChange', this._extractDisplayColumns, this);
                },
            
                /**
                Relays attribute changes to the child Views.
            
                @method _relayAttrChange
                @param {EventHandle} e The change event
                @protected
                @since 3.6.0
                **/
                _relayAttrChange: function (e) {
                    var attr = e.attrName,
                        val  = e.newVal;
            
                    if (this.head) {
                        this.head.set(attr, val);
                    }
            
                    if (this.foot) {
                        this.foot.set(attr, val);
                    }
            
                    if (this.body) {
                        if (attr === 'columns') {
                            val = this.displayColumns;
                        }
            
                        this.body.set(attr, val);
                    }
                },
            
                /**
                Creates the UI in the configured `container`.
            
                @method render
                @chainable
                **/
                render: function () {
                    if (this.get('container')) {
                        this.fire('renderTable', {
                            headerView  : this.get('headerView'),
                            headerConfig: this.get('headerConfig'),
            
                            bodyView    : this.get('bodyView'),
                            bodyConfig  : this.get('bodyConfig'),
            
                            footerView  : this.get('footerView'),
                            footerConfig: this.get('footerConfig')
                        });
                    }
            
                    return this;
                },
            
                /**
                Creates, removes, or updates the table's `<caption>` element per the input
                value.  Empty values result in the caption being removed.
            
                @method _uiSetCaption
                @param {String} htmlContent The content to populate the table caption
                @protected
                @since 3.5.0
                **/
                _uiSetCaption: function (htmlContent) {
                    var table   = this.tableNode,
                        caption = this.captionNode;
            
                    if (htmlContent) {
                        if (!caption) {
                            this.captionNode = caption = Y.Node.create(
                                fromTemplate(this.CAPTION_TEMPLATE, {
                                    className: this.getClassName('caption')
                                }));
            
                            table.prepend(this.captionNode);
                        }
            
                        caption.setHTML(htmlContent);
            
                    } else if (caption) {
                        caption.remove(true);
            
                        delete this.captionNode;
                    }
                },
            
                /**
                Updates the table's `summary` attribute with the input value.
            
                @method _uiSetSummary
                @protected
                @since 3.5.0
                **/
                _uiSetSummary: function (summary) {
                    if (summary) {
                        this.tableNode.setAttribute('summary', summary);
                    } else {
                        this.tableNode.removeAttribute('summary');
                    }
                },
            
                /**
                Sets the `boundingBox` and table width per the input value.
            
                @method _uiSetWidth
                @param {Number|String} width The width to make the table
                @protected
                @since 3.5.0
                **/
                _uiSetWidth: function (width) {
                    var table = this.tableNode;
            
                    // Table width needs to account for borders
                    table.setStyle('width', !width ? '' :
                        (this.get('container').get('offsetWidth') -
                         (parseInt(table.getComputedStyle('borderLeftWidth'), 10)||0) -
                         (parseInt(table.getComputedStyle('borderLeftWidth'), 10)||0)) +
                         'px');
            
                    table.setStyle('width', width);
                },
            
                /**
                Ensures that the input is a View class or at least has a `render` method.
            
                @method _validateView
                @param {View|Function} val The View class
                @return {Boolean}
                @protected
                **/
                _validateView: function (val) {
                    return isFunction(val) && val.prototype.render;
                }
            }, {
                ATTRS: {
                    /**
                    Content for the `<table summary="ATTRIBUTE VALUE HERE">`.  Values
                    assigned to this attribute will be HTML escaped for security.
            
                    @attribute summary
                    @type {String}
                    @default '' (empty string)
                    @since 3.5.0
                    **/
                    //summary: {},
            
                    /**
                    HTML content of an optional `<caption>` element to appear above the
                    table.  Leave this config unset or set to a falsy value to remove the
                    caption.
            
                    @attribute caption
                    @type HTML
                    @default undefined (initially unset)
                    @since 3.6.0
                    **/
                    //caption: {},
            
                    /**
                    Columns to include in the rendered table.
            
                    This attribute takes an array of objects. Each object is considered a
                    data column or header cell to be rendered.  How the objects are
                    translated into markup is delegated to the `headerView`, `bodyView`,
                    and `footerView`.
            
                    The raw value is passed to the `headerView` and `footerView`.  The
                    `bodyView` receives the instance's `displayColumns` array, which is
                    parsed from the columns array.  If there are no nested columns (columns
                    configured with a `children` array), the `displayColumns` is the same
                    as the raw value.
            
                    @attribute columns
                    @type {Object[]}
                    @since 3.6.0
                    **/
                    columns: {
                        validator: isArray
                    },
            
                    /**
                    Width of the table including borders.  This value requires units, so
                    `200` is invalid, but `'200px'` is valid.  Setting the empty string
                    (the default) will allow the browser to set the table width.
            
                    @attribute width
                    @type {String}
                    @default ''
                    @since 3.6.0
                    **/
                    width: {
                        value: '',
                        validator: YLang.isString
                    },
            
                    /**
                    An instance of this class is used to render the contents of the
                    `<thead>`&mdash;the column headers for the table.
            
                    The instance of this View will be assigned to the instance's `head`
                    property.
            
                    It is not strictly necessary that the class function assigned here be
                    a View subclass.  It must however have a `render()` method.
            
                    @attribute headerView
                    @type {Function|Object}
                    @default Y.DataTable.HeaderView
                    @since 3.6.0
                    **/
                    headerView: {
                        value: Y.DataTable.HeaderView,
                        validator: '_validateView'
                    },
            
                    /**
                    Configuration overrides used when instantiating the `headerView`
                    instance.
            
                    @attribute headerConfig
                    @type {Object}
                    @since 3.6.0
                    **/
                    //headerConfig: {},
            
                    /**
                    An instance of this class is used to render the contents of the
                    `<tfoot>` (if appropriate).
            
                    The instance of this View will be assigned to the instance's `foot`
                    property.
            
                    It is not strictly necessary that the class function assigned here be
                    a View subclass.  It must however have a `render()` method.
            
                    @attribute footerView
                    @type {Function|Object}
                    @since 3.6.0
                    **/
                    footerView: {
                        validator: '_validateView'
                    },
            
                    /**
                    Configuration overrides used when instantiating the `footerView`
                    instance.
            
                    @attribute footerConfig
                    @type {Object}
                    @since 3.6.0
                    **/
                    //footerConfig: {},
            
                    /**
                    An instance of this class is used to render the contents of the table's
                    `<tbody>`&mdash;the data cells in the table.
            
                    The instance of this View will be assigned to the instance's `body`
                    property.
            
                    It is not strictly necessary that the class function assigned here be
                    a View subclass.  It must however have a `render()` method.
            
                    @attribute bodyView
                    @type {Function|Object}
                    @default Y.DataTable.BodyView
                    @since 3.6.0
                    **/
                    bodyView: {
                        value: Y.DataTable.BodyView,
                        validator: '_validateView'
                    }
            
                    /**
                    Configuration overrides used when instantiating the `bodyView`
                    instance.
            
                    @attribute bodyConfig
                    @type {Object}
                    @since 3.6.0
                    **/
                    //bodyConfig: {}
                }
            });