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

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