lib/dojo/dom-attr.js.uncompressed.js

   1 define("dojo/dom-attr", ["exports", "./sniff", "./_base/lang", "./dom", "./dom-style", "./dom-prop"],
   2                 function(exports, has, lang, dom, style, prop){
   3         // module:
   4         //              dojo/dom-attr
   5         // summary:
   6         //              This module defines the core dojo DOM attributes API.
   7
   8         // TODOC: summary not showing up in output see https://github.com/csnover/js-doc-parse/issues/42
   9
  10         // =============================
  11         // Element attribute Functions
  12         // =============================
  13
  14         // This module will be obsolete soon. Use dojo/prop instead.
  15
  16         // dojo.attr() should conform to http://www.w3.org/TR/DOM-Level-2-Core/
  17
  18         // attribute-related functions (to be obsolete soon)
  19
  20         var forcePropNames = {
  21                         innerHTML:      1,
  22                         className:      1,
  23                         htmlFor:        has("ie"),
  24                         value:          1
  25                 },
  26                 attrNames = {
  27                         // original attribute names
  28                         classname: "class",
  29                         htmlfor: "for",
  30                         // for IE
  31                         tabindex: "tabIndex",
  32                         readonly: "readOnly"
  33                 };
  34
  35         function _hasAttr(node, name){
  36                 var attr = node.getAttributeNode && node.getAttributeNode(name);
  37                 return attr && attr.specified; // Boolean
  38         }
  39
  40         // There is a difference in the presence of certain properties and their default values
  41         // between browsers. For example, on IE "disabled" is present on all elements,
  42         // but it is value is "false"; "tabIndex" of <div> returns 0 by default on IE, yet other browsers
  43         // can return -1.
  44
  45         exports.has = function hasAttr(/*DOMNode|String*/ node, /*String*/ name){
  46                 // summary:
  47                 //              Returns true if the requested attribute is specified on the
  48                 //              given element, and false otherwise.
  49                 // node: DOMNode|String
  50                 //              id or reference to the element to check
  51                 // name: String
  52                 //              the name of the attribute
  53                 // returns: Boolean
  54                 //              true if the requested attribute is specified on the
  55                 //              given element, and false otherwise
  56
  57                 var lc = name.toLowerCase();
  58                 return forcePropNames[prop.names[lc] || name] || _hasAttr(dom.byId(node), attrNames[lc] || name);       // Boolean
  59         };
  60
  61         exports.get = function getAttr(/*DOMNode|String*/ node, /*String*/ name){
  62                 // summary:
  63                 //              Gets an attribute on an HTML element.
  64                 // description:
  65                 //              Handles normalized getting of attributes on DOM Nodes.
  66                 // node: DOMNode|String
  67                 //              id or reference to the element to get the attribute on
  68                 // name: String
  69                 //              the name of the attribute to get.
  70                 // returns:
  71                 //              the value of the requested attribute or null if that attribute does not have a specified or
  72                 //              default value;
  73                 //
  74                 // example:
  75                 //      |       // get the current value of the "foo" attribute on a node
  76                 //      |       dojo.getAttr(dojo.byId("nodeId"), "foo");
  77                 //      |       // or we can just pass the id:
  78                 //      |       dojo.getAttr("nodeId", "foo");
  79
  80                 node = dom.byId(node);
  81                 var lc = name.toLowerCase(),
  82                         propName = prop.names[lc] || name,
  83                         forceProp = forcePropNames[propName],
  84                         value = node[propName];         // should we access this attribute via a property or via getAttribute()?
  85
  86                 if(forceProp && typeof value != "undefined"){
  87                         // node's property
  88                         return value;   // Anything
  89                 }
  90                 if(propName != "href" && (typeof value == "boolean" || lang.isFunction(value))){
  91                         // node's property
  92                         return value;   // Anything
  93                 }
  94                 // node's attribute
  95                 // we need _hasAttr() here to guard against IE returning a default value
  96                 var attrName = attrNames[lc] || name;
  97                 return _hasAttr(node, attrName) ? node.getAttribute(attrName) : null; // Anything
  98         };
  99
 100         exports.set = function setAttr(/*DOMNode|String*/ node, /*String|Object*/ name, /*String?*/ value){
 101                 // summary:
 102                 //              Sets an attribute on an HTML element.
 103                 // description:
 104                 //              Handles normalized setting of attributes on DOM Nodes.
 105                 //
 106                 //              When passing functions as values, note that they will not be
 107                 //              directly assigned to slots on the node, but rather the default
 108                 //              behavior will be removed and the new behavior will be added
 109                 //              using `dojo.connect()`, meaning that event handler properties
 110                 //              will be normalized and that some caveats with regards to
 111                 //              non-standard behaviors for onsubmit apply. Namely that you
 112                 //              should cancel form submission using `dojo.stopEvent()` on the
 113                 //              passed event object instead of returning a boolean value from
 114                 //              the handler itself.
 115                 // node: DOMNode|String
 116                 //              id or reference to the element to set the attribute on
 117                 // name: String|Object
 118                 //              the name of the attribute to set, or a hash of key-value pairs to set.
 119                 // value: String?
 120                 //              the value to set for the attribute, if the name is a string.
 121                 // returns:
 122                 //              the DOM node
 123                 //
 124                 // example:
 125                 //      |       // use attr() to set the tab index
 126                 //      |       dojo.setAttr("nodeId", "tabIndex", 3);
 127                 //
 128                 // example:
 129                 //      Set multiple values at once, including event handlers:
 130                 //      |       dojo.setAttr("formId", {
 131                 //      |               "foo": "bar",
 132                 //      |               "tabIndex": -1,
 133                 //      |               "method": "POST",
 134                 //      |               "onsubmit": function(e){
 135                 //      |                       // stop submitting the form. Note that the IE behavior
 136                 //      |                       // of returning true or false will have no effect here
 137                 //      |                       // since our handler is connect()ed to the built-in
 138                 //      |                       // onsubmit behavior and so we need to use
 139                 //      |                       // dojo.stopEvent() to ensure that the submission
 140                 //      |                       // doesn't proceed.
 141                 //      |                       dojo.stopEvent(e);
 142                 //      |
 143                 //      |                       // submit the form with Ajax
 144                 //      |                       dojo.xhrPost({ form: "formId" });
 145                 //      |               }
 146                 //      |       });
 147                 //
 148                 // example:
 149                 //      Style is s special case: Only set with an object hash of styles
 150                 //      |       dojo.setAttr("someNode",{
 151                 //      |               id:"bar",
 152                 //      |               style:{
 153                 //      |                       width:"200px", height:"100px", color:"#000"
 154                 //      |               }
 155                 //      |       });
 156                 //
 157                 // example:
 158                 //      Again, only set style as an object hash of styles:
 159                 //      |       var obj = { color:"#fff", backgroundColor:"#000" };
 160                 //      |       dojo.setAttr("someNode", "style", obj);
 161                 //      |
 162                 //      |       // though shorter to use `dojo.style()` in this case:
 163                 //      |       dojo.setStyle("someNode", obj);
 164
 165                 node = dom.byId(node);
 166                 if(arguments.length == 2){ // inline'd type check
 167                         // the object form of setter: the 2nd argument is a dictionary
 168                         for(var x in name){
 169                                 exports.set(node, x, name[x]);
 170                         }
 171                         return node; // DomNode
 172                 }
 173                 var lc = name.toLowerCase(),
 174                         propName = prop.names[lc] || name,
 175                         forceProp = forcePropNames[propName];
 176                 if(propName == "style" && typeof value != "string"){ // inline'd type check
 177                         // special case: setting a style
 178                         style.set(node, value);
 179                         return node; // DomNode
 180                 }
 181                 if(forceProp || typeof value == "boolean" || lang.isFunction(value)){
 182                         return prop.set(node, name, value);
 183                 }
 184                 // node's attribute
 185                 node.setAttribute(attrNames[lc] || name, value);
 186                 return node; // DomNode
 187         };
 188
 189         exports.remove = function removeAttr(/*DOMNode|String*/ node, /*String*/ name){
 190                 // summary:
 191                 //              Removes an attribute from an HTML element.
 192                 // node: DOMNode|String
 193                 //              id or reference to the element to remove the attribute from
 194                 // name: String
 195                 //              the name of the attribute to remove
 196
 197                 dom.byId(node).removeAttribute(attrNames[name.toLowerCase()] || name);
 198         };
 199
 200         exports.getNodeProp = function getNodeProp(/*DomNode|String*/ node, /*String*/ name){
 201                 // summary:
 202                 //              Returns an effective value of a property or an attribute.
 203                 // node: DOMNode|String
 204                 //              id or reference to the element to remove the attribute from
 205                 // name: String
 206                 //              the name of the attribute
 207                 // returns:
 208                 //              the value of the attribute
 209
 210                 node = dom.byId(node);
 211                 var lc = name.toLowerCase(), propName = prop.names[lc] || name;
 212                 if((propName in node) && propName != "href"){
 213                         // node's property
 214                         return node[propName];  // Anything
 215                 }
 216                 // node's attribute
 217                 var attrName = attrNames[lc] || name;
 218                 return _hasAttr(node, attrName) ? node.getAttribute(attrName) : null; // Anything
 219         };
 220 });