#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: node/js/node-data.js

    /**
     * Provides methods for managing custom Node data.
     *
     * @module node
     * @main node
     * @submodule node-data
     */

    Y.mix(Y.Node.prototype, {
        _initData: function() {
            if (! ('_data' in this)) {
                this._data = {};
            }
        },

        /**
        * @method getData
        * @for Node
        * @description Retrieves arbitrary data stored on a Node instance.
        * If no data is associated with the Node, it will attempt to retrieve
        * a value from the corresponding HTML data attribute. (e.g. node.getData('foo')
        * will check node.getAttribute('data-foo')).
        * @param {string} name Optional name of the data field to retrieve.
        * If no name is given, all data is returned.
        * @return {any | Object} Whatever is stored at the given field,
        * or an object hash of all fields.
        */
        getData: function(name) {
            this._initData();
            var data = this._data,
                ret = data;

            if (arguments.length) { // single field
                if (name in data) {
                    ret = data[name];
                } else { // initialize from HTML attribute
                    ret = this._getDataAttribute(name);
                }
            } else if (typeof data == 'object' && data !== null) { // all fields
                ret = {};
                Y.Object.each(data, function(v, n) {
                    ret[n] = v;
                });

                ret = this._getDataAttributes(ret);
            }

            return ret;

        },

        _getDataAttributes: function(ret) {
            ret = ret || {};
            var i = 0,
                attrs = this._node.attributes,
                len = attrs.length,
                prefix = this.DATA_PREFIX,
                prefixLength = prefix.length,
                name;

            while (i < len) {
                name = attrs[i].name;
                if (name.indexOf(prefix) === 0) {
                    name = name.substr(prefixLength);
                    if (!(name in ret)) { // only merge if not already stored
                        ret[name] = this._getDataAttribute(name);
                    }
                }

                i += 1;
            }

            return ret;
        },

        _getDataAttribute: function(name) {
            name = this.DATA_PREFIX + name;

            var node = this._node,
                attrs = node.attributes,
                data = attrs && attrs[name] && attrs[name].value;

            return data;
        },

        /**
        * @method setData
        * @for Node
        * @description Stores arbitrary data on a Node instance.
        * This is not stored with the DOM node.
        * @param {string} name The name of the field to set. If no val
        * is given, name is treated as the data and overrides any existing data.
        * @param {any} val The value to be assigned to the field.
        * @chainable
        */
        setData: function(name, val) {
            this._initData();
            if (arguments.length > 1) {
                this._data[name] = val;
            } else {
                this._data = name;
            }

           return this;
        },

        /**
        * @method clearData
        * @for Node
        * @description Clears internally stored data.
        * @param {string} name The name of the field to clear. If no name
        * is given, all data is cleared.
        * @chainable
        */
        clearData: function(name) {
            if ('_data' in this) {
                if (typeof name != 'undefined') {
                    delete this._data[name];
                } else {
                    delete this._data;
                }
            }

            return this;
        }
    });

    Y.mix(Y.NodeList.prototype, {
        /**
        * @method getData
        * @for NodeList
        * @description Retrieves arbitrary data stored on each Node instance
        * bound to the NodeList.
        * @see Node
        * @param {string} name Optional name of the data field to retrieve.
        * If no name is given, all data is returned.
        * @return {Array} An array containing all of the data for each Node instance.
        * or an object hash of all fields.
        */
        getData: function(name) {
            var args = (arguments.length) ? [name] : [];
            return this._invoke('getData', args, true);
        },

        /**
        * @method setData
        * @for NodeList
        * @description Stores arbitrary data on each Node instance bound to the
        *  NodeList. This is not stored with the DOM node.
        * @param {string} name The name of the field to set. If no name
        * is given, name is treated as the data and overrides any existing data.
        * @param {any} val The value to be assigned to the field.
        * @chainable
        */
        setData: function(name, val) {
            var args = (arguments.length > 1) ? [name, val] : [name];
            return this._invoke('setData', args);
        },

        /**
        * @method clearData
        * @for NodeList
        * @description Clears data on all Node instances bound to the NodeList.
        * @param {string} name The name of the field to clear. If no name
        * is given, all data is cleared.
        * @chainable
        */
        clearData: function(name) {
            var args = (arguments.length) ? [name] : [];
            return this._invoke('clearData', [name]);
        }
    });