source: Dev/branches/rest-dojo-ui/client/dojo/dom-attr.js @ 256

define(["exports", "./_base/sniff", "./_base/lang", "./dom", "./dom-style", "./dom-prop"],
                function(exports, has, lang, dom, style, prop){
        // module:
        //              dojo/dom-attr
        // summary:
        //              This module defines the core dojo DOM attributes API.

        // =============================
        // Element attribute Functions
        // =============================

        // This module will be obsolete soon. Use dojo.prop instead.

        // dojo.attr() should conform to http://www.w3.org/TR/DOM-Level-2-Core/

        // attribute-related functions (to be obsolete soon)

        /*=====
        dojo.hasAttr = function(node, name){
                // summary:
                //              Returns true if the requested attribute is specified on the
                //              given element, and false otherwise.
                // node: DOMNode|String
                //              id or reference to the element to check
                // name: String
                //              the name of the attribute
                // returns: Boolean
                //              true if the requested attribute is specified on the
                //              given element, and false otherwise
        };
        =====*/

        /*=====
        dojo.getAttr = function(node, name){
                // summary:
                //              Gets an attribute on an HTML element.
                // description:
                //              Handles normalized getting of attributes on DOM Nodes.
                // node: DOMNode|String
                //              id or reference to the element to get the attribute on
                // name: String
                //              the name of the attribute to get.
                // returns:
                //              the value of the requested attribute or null if that attribute does not have a specified or
                //              default value;
                //
                // example:
                //      |       // get the current value of the "foo" attribute on a node
                //      |       dojo.getAttr(dojo.byId("nodeId"), "foo");
                //      |       // or we can just pass the id:
                //      |       dojo.getAttr("nodeId", "foo");
        };
        =====*/

        /*=====
        dojo.setAttr = function(node, name, value){
                // summary:
                //              Sets an attribute on an HTML element.
                // description:
                //              Handles normalized setting of attributes on DOM Nodes.
                //
                //              When passing functions as values, note that they will not be
                //              directly assigned to slots on the node, but rather the default
                //              behavior will be removed and the new behavior will be added
                //              using `dojo.connect()`, meaning that event handler properties
                //              will be normalized and that some caveats with regards to
                //              non-standard behaviors for onsubmit apply. Namely that you
                //              should cancel form submission using `dojo.stopEvent()` on the
                //              passed event object instead of returning a boolean value from
                //              the handler itself.
                // node: DOMNode|String
                //              id or reference to the element to set the attribute on
                // name: String|Object
                //              the name of the attribute to set, or a hash of key-value pairs to set.
                // value: String?
                //              the value to set for the attribute, if the name is a string.
                // returns:
                //              the DOM node
                //
                // example:
                //      |       // use attr() to set the tab index
                //      |       dojo.setAttr("nodeId", "tabIndex", 3);
                //
                // example:
                //      Set multiple values at once, including event handlers:
                //      |       dojo.setAttr("formId", {
                //      |               "foo": "bar",
                //      |               "tabIndex": -1,
                //      |               "method": "POST",
                //      |               "onsubmit": function(e){
                //      |                       // stop submitting the form. Note that the IE behavior
                //      |                       // of returning true or false will have no effect here
                //      |                       // since our handler is connect()ed to the built-in
                //      |                       // onsubmit behavior and so we need to use
                //      |                       // dojo.stopEvent() to ensure that the submission
                //      |                       // doesn't proceed.
                //      |                       dojo.stopEvent(e);
                //      |
                //      |                       // submit the form with Ajax
                //      |                       dojo.xhrPost({ form: "formId" });
                //      |               }
                //      |       });
                //
                // example:
                //      Style is s special case: Only set with an object hash of styles
                //      |       dojo.setAttr("someNode",{
                //      |               id:"bar",
                //      |               style:{
                //      |                       width:"200px", height:"100px", color:"#000"
                //      |               }
                //      |       });
                //
                // example:
                //      Again, only set style as an object hash of styles:
                //      |       var obj = { color:"#fff", backgroundColor:"#000" };
                //      |       dojo.setAttr("someNode", "style", obj);
                //      |
                //      |       // though shorter to use `dojo.style()` in this case:
                //      |       dojo.setStyle("someNode", obj);
        };
        =====*/

        /*=====
        dojo.removeAttr = function(node, name){
                // summary:
                //              Removes an attribute from an HTML element.
                // node: DOMNode|String
                //              id or reference to the element to remove the attribute from
                // name: String
                //              the name of the attribute to remove
        };
        =====*/

        /*=====
        dojo.getNodeProp = function(node, name){
                // summary:
                //              Returns an effective value of a property or an attribute.
                // node: DOMNode|String
                //              id or reference to the element to remove the attribute from
                // name: String
                //              the name of the attribute
                // returns:
                //      the value of the attribute
        };
        =====*/

        var forcePropNames = {
                        innerHTML:      1,
                        className:      1,
                        htmlFor:        has("ie"),
                        value:          1
                },
                attrNames = {
                        // original attribute names
                        classname: "class",
                        htmlfor: "for",
                        // for IE
                        tabindex: "tabIndex",
                        readonly: "readOnly"
                };

        function _hasAttr(node, name){
                var attr = node.getAttributeNode && node.getAttributeNode(name);
                return attr && attr.specified; // Boolean
        }

        // There is a difference in the presence of certain properties and their default values
        // between browsers. For example, on IE "disabled" is present on all elements,
        // but it is value is "false"; "tabIndex" of <div> returns 0 by default on IE, yet other browsers
        // can return -1.

        exports.has = function hasAttr(/*DOMNode|String*/node, /*String*/name){
                var lc = name.toLowerCase();
                return forcePropNames[prop.names[lc] || name] || _hasAttr(dom.byId(node), attrNames[lc] || name);       // Boolean
        };

        exports.get = function getAttr(/*DOMNode|String*/node, /*String*/name){
                node = dom.byId(node);
                var lc = name.toLowerCase(),
                        propName = prop.names[lc] || name,
                        forceProp = forcePropNames[propName];
                // should we access this attribute via a property or via getAttribute()?
                value = node[propName];
                if(forceProp && typeof value != "undefined"){
                        // node's property
                        return value;   // Anything
                }
                if(propName != "href" && (typeof value == "boolean" || lang.isFunction(value))){
                        // node's property
                        return value;   // Anything
                }
                // node's attribute
                // we need _hasAttr() here to guard against IE returning a default value
                var attrName = attrNames[lc] || name;
                return _hasAttr(node, attrName) ? node.getAttribute(attrName) : null; // Anything
        };

        exports.set = function setAttr(/*DOMNode|String*/node, /*String|Object*/name, /*String?*/value){
                node = dom.byId(node);
                if(arguments.length == 2){ // inline'd type check
                        // the object form of setter: the 2nd argument is a dictionary
                        for(var x in name){
                                exports.set(node, x, name[x]);
                        }
                        return node; // DomNode
                }
                var lc = name.toLowerCase(),
                        propName = prop.names[lc] || name,
                        forceProp = forcePropNames[propName];
                if(propName == "style" && typeof value != "string"){ // inline'd type check
                        // special case: setting a style
                        style.set(node, value);
                        return node; // DomNode
                }
                if(forceProp || typeof value == "boolean" || lang.isFunction(value)){
                        return prop.set(node, name, value)
                }
                // node's attribute
                node.setAttribute(attrNames[lc] || name, value);
                return node; // DomNode
        };

        exports.remove = function removeAttr(/*DOMNode|String*/ node, /*String*/ name){
                dom.byId(node).removeAttribute(attrNames[name.toLowerCase()] || name);
        };

        exports.getNodeProp = function getNodeProp(/*DomNode|String*/ node, /*String*/ name){
                node = dom.byId(node);
                var lc = name.toLowerCase(), propName = prop.names[lc] || name;
                if((propName in node) && propName != "href"){
                        // node's property
                        return node[propName];  // Anything
                }
                // node's attribute
                var attrName = attrNames[lc] || name;
                return _hasAttr(node, attrName) ? node.getAttribute(attrName) : null; // Anything
        };
});