lib/dojo/_base/html.js.uncompressed.js

   1 define("dojo/_base/html", ["./kernel", "../dom", "../dom-style", "../dom-attr", "../dom-prop", "../dom-class", "../dom-construct", "../dom-geometry"], function(dojo, dom, style, attr, prop, cls, ctr, geom){
   2         // module:
   3         //              dojo/dom
   4         // summary:
   5         //              This module is a stub for the core dojo DOM API.
   6
   7         // mix-in dom
   8         dojo.byId = dom.byId;
   9         dojo.isDescendant = dom.isDescendant;
  10         dojo.setSelectable = dom.setSelectable;
  11
  12         // mix-in dom-attr
  13         dojo.getAttr = attr.get;
  14         dojo.setAttr = attr.set;
  15         dojo.hasAttr = attr.has;
  16         dojo.removeAttr = attr.remove;
  17         dojo.getNodeProp = attr.getNodeProp;
  18
  19         dojo.attr = function(node, name, value){
  20                 // summary:
  21                 //              Gets or sets an attribute on an HTML element.
  22                 // description:
  23                 //              Handles normalized getting and setting of attributes on DOM
  24                 //              Nodes. If 2 arguments are passed, and a the second argument is a
  25                 //              string, acts as a getter.
  26                 //
  27                 //              If a third argument is passed, or if the second argument is a
  28                 //              map of attributes, acts as a setter.
  29                 //
  30                 //              When passing functions as values, note that they will not be
  31                 //              directly assigned to slots on the node, but rather the default
  32                 //              behavior will be removed and the new behavior will be added
  33                 //              using `dojo.connect()`, meaning that event handler properties
  34                 //              will be normalized and that some caveats with regards to
  35                 //              non-standard behaviors for onsubmit apply. Namely that you
  36                 //              should cancel form submission using `dojo.stopEvent()` on the
  37                 //              passed event object instead of returning a boolean value from
  38                 //              the handler itself.
  39                 // node: DOMNode|String
  40                 //              id or reference to the element to get or set the attribute on
  41                 // name: String|Object
  42                 //              the name of the attribute to get or set.
  43                 // value: String?
  44                 //              The value to set for the attribute
  45                 // returns:
  46                 //              when used as a getter, the value of the requested attribute
  47                 //              or null if that attribute does not have a specified or
  48                 //              default value;
  49                 //
  50                 //              when used as a setter, the DOM node
  51                 //
  52                 // example:
  53                 //      |       // get the current value of the "foo" attribute on a node
  54                 //      |       dojo.attr(dojo.byId("nodeId"), "foo");
  55                 //      |       // or we can just pass the id:
  56                 //      |       dojo.attr("nodeId", "foo");
  57                 //
  58                 // example:
  59                 //      |       // use attr() to set the tab index
  60                 //      |       dojo.attr("nodeId", "tabIndex", 3);
  61                 //      |
  62                 //
  63                 // example:
  64                 //      Set multiple values at once, including event handlers:
  65                 //      |       dojo.attr("formId", {
  66                 //      |               "foo": "bar",
  67                 //      |               "tabIndex": -1,
  68                 //      |               "method": "POST",
  69                 //      |               "onsubmit": function(e){
  70                 //      |                       // stop submitting the form. Note that the IE behavior
  71                 //      |                       // of returning true or false will have no effect here
  72                 //      |                       // since our handler is connect()ed to the built-in
  73                 //      |                       // onsubmit behavior and so we need to use
  74                 //      |                       // dojo.stopEvent() to ensure that the submission
  75                 //      |                       // doesn't proceed.
  76                 //      |                       dojo.stopEvent(e);
  77                 //      |
  78                 //      |                       // submit the form with Ajax
  79                 //      |                       dojo.xhrPost({ form: "formId" });
  80                 //      |               }
  81                 //      |       });
  82                 //
  83                 // example:
  84                 //      Style is s special case: Only set with an object hash of styles
  85                 //      |       dojo.attr("someNode",{
  86                 //      |               id:"bar",
  87                 //      |               style:{
  88                 //      |                       width:"200px", height:"100px", color:"#000"
  89                 //      |               }
  90                 //      |       });
  91                 //
  92                 // example:
  93                 //      Again, only set style as an object hash of styles:
  94                 //      |       var obj = { color:"#fff", backgroundColor:"#000" };
  95                 //      |       dojo.attr("someNode", "style", obj);
  96                 //      |
  97                 //      |       // though shorter to use `dojo.style()` in this case:
  98                 //      |       dojo.style("someNode", obj);
  99
 100                 if(arguments.length == 2){
 101                         return attr[typeof name == "string" ? "get" : "set"](node, name);
 102                 }
 103                 return attr.set(node, name, value);
 104         };
 105
 106         // mix-in dom-class
 107         dojo.hasClass = cls.contains;
 108         dojo.addClass = cls.add;
 109         dojo.removeClass = cls.remove;
 110         dojo.toggleClass = cls.toggle;
 111         dojo.replaceClass = cls.replace;
 112
 113         // mix-in dom-construct
 114         dojo._toDom = dojo.toDom = ctr.toDom;
 115         dojo.place = ctr.place;
 116         dojo.create = ctr.create;
 117         dojo.empty = function(node){ ctr.empty(node); };
 118         dojo._destroyElement = dojo.destroy = function(node){ ctr.destroy(node); };
 119
 120         // mix-in dom-geometry
 121         dojo._getPadExtents = dojo.getPadExtents = geom.getPadExtents;
 122         dojo._getBorderExtents = dojo.getBorderExtents = geom.getBorderExtents;
 123         dojo._getPadBorderExtents = dojo.getPadBorderExtents = geom.getPadBorderExtents;
 124         dojo._getMarginExtents = dojo.getMarginExtents = geom.getMarginExtents;
 125         dojo._getMarginSize = dojo.getMarginSize = geom.getMarginSize;
 126         dojo._getMarginBox = dojo.getMarginBox = geom.getMarginBox;
 127         dojo.setMarginBox = geom.setMarginBox;
 128         dojo._getContentBox = dojo.getContentBox = geom.getContentBox;
 129         dojo.setContentSize = geom.setContentSize;
 130         dojo._isBodyLtr = dojo.isBodyLtr = geom.isBodyLtr;
 131         dojo._docScroll = dojo.docScroll = geom.docScroll;
 132         dojo._getIeDocumentElementOffset = dojo.getIeDocumentElementOffset = geom.getIeDocumentElementOffset;
 133         dojo._fixIeBiDiScrollLeft = dojo.fixIeBiDiScrollLeft = geom.fixIeBiDiScrollLeft;
 134         dojo.position = geom.position;
 135
 136         dojo.marginBox = function marginBox(/*DomNode|String*/node, /*Object?*/box){
 137                 // summary:
 138                 //              Getter/setter for the margin-box of node.
 139                 // description:
 140                 //              Getter/setter for the margin-box of node.
 141                 //              Returns an object in the expected format of box (regardless
 142                 //              if box is passed). The object might look like:
 143                 //                      `{ l: 50, t: 200, w: 300: h: 150 }`
 144                 //              for a node offset from its parent 50px to the left, 200px from
 145                 //              the top with a margin width of 300px and a margin-height of
 146                 //              150px.
 147                 // node:
 148                 //              id or reference to DOM Node to get/set box for
 149                 // box:
 150                 //              If passed, denotes that dojo.marginBox() should
 151                 //              update/set the margin box for node. Box is an object in the
 152                 //              above format. All properties are optional if passed.
 153                 // example:
 154                 //              Retrieve the margin box of a passed node
 155                 //      |       var box = dojo.marginBox("someNodeId");
 156                 //      |       console.dir(box);
 157                 //
 158                 // example:
 159                 //              Set a node's margin box to the size of another node
 160                 //      |       var box = dojo.marginBox("someNodeId");
 161                 //      |       dojo.marginBox("someOtherNode", box);
 162                 return box ? geom.setMarginBox(node, box) : geom.getMarginBox(node); // Object
 163         };
 164
 165         dojo.contentBox = function contentBox(/*DomNode|String*/node, /*Object?*/box){
 166                 // summary:
 167                 //              Getter/setter for the content-box of node.
 168                 // description:
 169                 //              Returns an object in the expected format of box (regardless if box is passed).
 170                 //              The object might look like:
 171                 //                      `{ l: 50, t: 200, w: 300: h: 150 }`
 172                 //              for a node offset from its parent 50px to the left, 200px from
 173                 //              the top with a content width of 300px and a content-height of
 174                 //              150px. Note that the content box may have a much larger border
 175                 //              or margin box, depending on the box model currently in use and
 176                 //              CSS values set/inherited for node.
 177                 //              While the getter will return top and left values, the
 178                 //              setter only accepts setting the width and height.
 179                 // node:
 180                 //              id or reference to DOM Node to get/set box for
 181                 // box:
 182                 //              If passed, denotes that dojo.contentBox() should
 183                 //              update/set the content box for node. Box is an object in the
 184                 //              above format, but only w (width) and h (height) are supported.
 185                 //              All properties are optional if passed.
 186                 return box ? geom.setContentSize(node, box) : geom.getContentBox(node); // Object
 187         };
 188
 189         dojo.coords = function(/*DomNode|String*/node, /*Boolean?*/includeScroll){
 190                 // summary:
 191                 //              Deprecated: Use position() for border-box x/y/w/h
 192                 //              or marginBox() for margin-box w/h/l/t.
 193                 //              Returns an object representing a node's size and position.
 194                 //
 195                 // description:
 196                 //              Returns an object that measures margin-box (w)idth/(h)eight
 197                 //              and absolute position x/y of the border-box. Also returned
 198                 //              is computed (l)eft and (t)op values in pixels from the
 199                 //              node's offsetParent as returned from marginBox().
 200                 //              Return value will be in the form:
 201                 //|                     { l: 50, t: 200, w: 300: h: 150, x: 100, y: 300 }
 202                 //              Does not act as a setter. If includeScroll is passed, the x and
 203                 //              y params are affected as one would expect in dojo.position().
 204                 dojo.deprecated("dojo.coords()", "Use dojo.position() or dojo.marginBox().");
 205                 node = dom.byId(node);
 206                 var s = style.getComputedStyle(node), mb = geom.getMarginBox(node, s);
 207                 var abs = geom.position(node, includeScroll);
 208                 mb.x = abs.x;
 209                 mb.y = abs.y;
 210                 return mb;      // Object
 211         };
 212
 213         // mix-in dom-prop
 214         dojo.getProp = prop.get;
 215         dojo.setProp = prop.set;
 216
 217         dojo.prop = function(/*DomNode|String*/node, /*String|Object*/name, /*String?*/value){
 218                 // summary:
 219                 //              Gets or sets a property on an HTML element.
 220                 // description:
 221                 //              Handles normalized getting and setting of properties on DOM
 222                 //              Nodes. If 2 arguments are passed, and a the second argument is a
 223                 //              string, acts as a getter.
 224                 //
 225                 //              If a third argument is passed, or if the second argument is a
 226                 //              map of attributes, acts as a setter.
 227                 //
 228                 //              When passing functions as values, note that they will not be
 229                 //              directly assigned to slots on the node, but rather the default
 230                 //              behavior will be removed and the new behavior will be added
 231                 //              using `dojo.connect()`, meaning that event handler properties
 232                 //              will be normalized and that some caveats with regards to
 233                 //              non-standard behaviors for onsubmit apply. Namely that you
 234                 //              should cancel form submission using `dojo.stopEvent()` on the
 235                 //              passed event object instead of returning a boolean value from
 236                 //              the handler itself.
 237                 // node:
 238                 //              id or reference to the element to get or set the property on
 239                 // name:
 240                 //              the name of the property to get or set.
 241                 // value:
 242                 //              The value to set for the property
 243                 // returns:
 244                 //              when used as a getter, the value of the requested property
 245                 //              or null if that attribute does not have a specified or
 246                 //              default value;
 247                 //
 248                 //              when used as a setter, the DOM node
 249                 //
 250                 // example:
 251                 //      |       // get the current value of the "foo" property on a node
 252                 //      |       dojo.prop(dojo.byId("nodeId"), "foo");
 253                 //      |       // or we can just pass the id:
 254                 //      |       dojo.prop("nodeId", "foo");
 255                 //
 256                 // example:
 257                 //      |       // use prop() to set the tab index
 258                 //      |       dojo.prop("nodeId", "tabIndex", 3);
 259                 //      |
 260                 //
 261                 // example:
 262                 //      Set multiple values at once, including event handlers:
 263                 //      |       dojo.prop("formId", {
 264                 //      |               "foo": "bar",
 265                 //      |               "tabIndex": -1,
 266                 //      |               "method": "POST",
 267                 //      |               "onsubmit": function(e){
 268                 //      |                       // stop submitting the form. Note that the IE behavior
 269                 //      |                       // of returning true or false will have no effect here
 270                 //      |                       // since our handler is connect()ed to the built-in
 271                 //      |                       // onsubmit behavior and so we need to use
 272                 //      |                       // dojo.stopEvent() to ensure that the submission
 273                 //      |                       // doesn't proceed.
 274                 //      |                       dojo.stopEvent(e);
 275                 //      |
 276                 //      |                       // submit the form with Ajax
 277                 //      |                       dojo.xhrPost({ form: "formId" });
 278                 //      |               }
 279                 //      |       });
 280                 //
 281                 // example:
 282                 //      Style is s special case: Only set with an object hash of styles
 283                 //      |       dojo.prop("someNode",{
 284                 //      |               id:"bar",
 285                 //      |               style:{
 286                 //      |                       width:"200px", height:"100px", color:"#000"
 287                 //      |               }
 288                 //      |       });
 289                 //
 290                 // example:
 291                 //      Again, only set style as an object hash of styles:
 292                 //      |       var obj = { color:"#fff", backgroundColor:"#000" };
 293                 //      |       dojo.prop("someNode", "style", obj);
 294                 //      |
 295                 //      |       // though shorter to use `dojo.style()` in this case:
 296                 //      |       dojo.style("someNode", obj);
 297
 298                 if(arguments.length == 2){
 299                         return prop[typeof name == "string" ? "get" : "set"](node, name);
 300                 }
 301                 // setter
 302                 return prop.set(node, name, value);
 303         };
 304
 305         // mix-in dom-style
 306         dojo.getStyle = style.get;
 307         dojo.setStyle = style.set;
 308         dojo.getComputedStyle = style.getComputedStyle;
 309         dojo.__toPixelValue = dojo.toPixelValue = style.toPixelValue;
 310
 311         dojo.style = function(node, name, value){
 312                 // summary:
 313                 //              Accesses styles on a node. If 2 arguments are
 314                 //              passed, acts as a getter. If 3 arguments are passed, acts
 315                 //              as a setter.
 316                 // description:
 317                 //              Getting the style value uses the computed style for the node, so the value
 318                 //              will be a calculated value, not just the immediate node.style value.
 319                 //              Also when getting values, use specific style names,
 320                 //              like "borderBottomWidth" instead of "border" since compound values like
 321                 //              "border" are not necessarily reflected as expected.
 322                 //              If you want to get node dimensions, use `dojo.marginBox()`,
 323                 //              `dojo.contentBox()` or `dojo.position()`.
 324                 // node: DOMNode|String
 325                 //              id or reference to node to get/set style for
 326                 // name: String?|Object?
 327                 //              the style property to set in DOM-accessor format
 328                 //              ("borderWidth", not "border-width") or an object with key/value
 329                 //              pairs suitable for setting each property.
 330                 // value: String?
 331                 //              If passed, sets value on the node for style, handling
 332                 //              cross-browser concerns.  When setting a pixel value,
 333                 //              be sure to include "px" in the value. For instance, top: "200px".
 334                 //              Otherwise, in some cases, some browsers will not apply the style.
 335                 // returns:
 336                 //              when used as a getter, return the computed style of the node if passing in an ID or node,
 337                 //              or return the normalized, computed value for the property when passing in a node and a style property
 338                 // example:
 339                 //              Passing only an ID or node returns the computed style object of
 340                 //              the node:
 341                 //      |       dojo.style("thinger");
 342                 // example:
 343                 //              Passing a node and a style property returns the current
 344                 //              normalized, computed value for that property:
 345                 //      |       dojo.style("thinger", "opacity"); // 1 by default
 346                 //
 347                 // example:
 348                 //              Passing a node, a style property, and a value changes the
 349                 //              current display of the node and returns the new computed value
 350                 //      |       dojo.style("thinger", "opacity", 0.5); // == 0.5
 351                 //
 352                 // example:
 353                 //              Passing a node, an object-style style property sets each of the values in turn and returns the computed style object of the node:
 354                 //      |       dojo.style("thinger", {
 355                 //      |               "opacity": 0.5,
 356                 //      |               "border": "3px solid black",
 357                 //      |               "height": "300px"
 358                 //      |       });
 359                 //
 360                 // example:
 361                 //              When the CSS style property is hyphenated, the JavaScript property is camelCased.
 362                 //              font-size becomes fontSize, and so on.
 363                 //      |       dojo.style("thinger",{
 364                 //      |               fontSize:"14pt",
 365                 //      |               letterSpacing:"1.2em"
 366                 //      |       });
 367                 //
 368                 // example:
 369                 //              dojo.NodeList implements .style() using the same syntax, omitting the "node" parameter, calling
 370                 //              dojo.style() on every element of the list. See: `dojo.query()` and `dojo.NodeList()`
 371                 //      |       dojo.query(".someClassName").style("visibility","hidden");
 372                 //      |       // or
 373                 //      |       dojo.query("#baz > div").style({
 374                 //      |               opacity:0.75,
 375                 //      |               fontSize:"13pt"
 376                 //      |       });
 377
 378                 switch(arguments.length){
 379                         case 1:
 380                                 return style.get(node);
 381                         case 2:
 382                                 return style[typeof name == "string" ? "get" : "set"](node, name);
 383                 }
 384                 // setter
 385                 return style.set(node, name, value);
 386         };
 387
 388         return dojo;
 389 });