source: Dev/branches/rest-dojo-ui/client/dojo/_base/html.js @ 256

define(["./kernel", "../dom", "../dom-style", "../dom-attr", "../dom-prop", "../dom-class", "../dom-construct", "../dom-geometry"], function(dojo, dom, style, attr, prop, cls, ctr, geom){
        // module:
        //              dojo/dom
        // summary:
        //              This module is a stub for the core dojo DOM API.

        // mix-in dom
        dojo.byId = dom.byId;
        dojo.isDescendant = dom.isDescendant;
        dojo.setSelectable = dom.setSelectable;

        // mix-in dom-attr
        dojo.getAttr = attr.get;
        dojo.setAttr = attr.set;
        dojo.hasAttr = attr.has;
        dojo.removeAttr = attr.remove;
        dojo.getNodeProp = attr.getNodeProp;

        dojo.attr = function(node, name, value){
                // summary:
                //              Gets or sets an attribute on an HTML element.
                // description:
                //              Handles normalized getting and setting of attributes on DOM
                //              Nodes. If 2 arguments are passed, and a the second argument is a
                //              string, acts as a getter.
                //
                //              If a third argument is passed, or if the second argument is a
                //              map of attributes, acts as a setter.
                //
                //              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 get or set the attribute on
                // name: String|Object
                //              the name of the attribute to get or set.
                // value: String?
                //              The value to set for the attribute
                // returns:
                //              when used as a getter, the value of the requested attribute
                //              or null if that attribute does not have a specified or
                //              default value;
                //
                //              when used as a setter, the DOM node
                //
                // example:
                //      |       // get the current value of the "foo" attribute on a node
                //      |       dojo.attr(dojo.byId("nodeId"), "foo");
                //      |       // or we can just pass the id:
                //      |       dojo.attr("nodeId", "foo");
                //
                // example:
                //      |       // use attr() to set the tab index
                //      |       dojo.attr("nodeId", "tabIndex", 3);
                //      |
                //
                // example:
                //      Set multiple values at once, including event handlers:
                //      |       dojo.attr("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.attr("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.attr("someNode", "style", obj);
                //      |
                //      |       // though shorter to use `dojo.style()` in this case:
                //      |       dojo.style("someNode", obj);

                if(arguments.length == 2){
                        return attr[typeof name == "string" ? "get" : "set"](node, name);
                }
                return attr.set(node, name, value);
        };

        // mix-in dom-class
        dojo.hasClass = cls.contains;
        dojo.addClass = cls.add;
        dojo.removeClass = cls.remove;
        dojo.toggleClass = cls.toggle;
        dojo.replaceClass = cls.replace;

        // mix-in dom-construct
        dojo._toDom = dojo.toDom = ctr.toDom;
        dojo.place = ctr.place;
        dojo.create = ctr.create;
        dojo.empty = function(node){ ctr.empty(node); };
        dojo._destroyElement = dojo.destroy = function(node){ ctr.destroy(node); };

        // mix-in dom-geometry
        dojo._getPadExtents = dojo.getPadExtents = geom.getPadExtents;
        dojo._getBorderExtents = dojo.getBorderExtents = geom.getBorderExtents;
        dojo._getPadBorderExtents = dojo.getPadBorderExtents = geom.getPadBorderExtents;
        dojo._getMarginExtents = dojo.getMarginExtents = geom.getMarginExtents;
        dojo._getMarginSize = dojo.getMarginSize = geom.getMarginSize;
        dojo._getMarginBox = dojo.getMarginBox = geom.getMarginBox;
        dojo.setMarginBox = geom.setMarginBox;
        dojo._getContentBox = dojo.getContentBox = geom.getContentBox;
        dojo.setContentSize = geom.setContentSize;
        dojo._isBodyLtr = dojo.isBodyLtr = geom.isBodyLtr;
        dojo._docScroll = dojo.docScroll = geom.docScroll;
        dojo._getIeDocumentElementOffset = dojo.getIeDocumentElementOffset = geom.getIeDocumentElementOffset;
        dojo._fixIeBiDiScrollLeft = dojo.fixIeBiDiScrollLeft = geom.fixIeBiDiScrollLeft;
        dojo.position = geom.position;

        dojo.marginBox = function marginBox(/*DomNode|String*/node, /*Object?*/box){
                // summary:
                //              Getter/setter for the margin-box of node.
                // description:
                //              Getter/setter for the margin-box of node.
                //              Returns an object in the expected format of box (regardless
                //              if box is passed). The object might look like:
                //                      `{ l: 50, t: 200, w: 300: h: 150 }`
                //              for a node offset from its parent 50px to the left, 200px from
                //              the top with a margin width of 300px and a margin-height of
                //              150px.
                // node:
                //              id or reference to DOM Node to get/set box for
                // box:
                //              If passed, denotes that dojo.marginBox() should
                //              update/set the margin box for node. Box is an object in the
                //              above format. All properties are optional if passed.
                // example:
                //              Retrieve the margin box of a passed node
                //      |       var box = dojo.marginBox("someNodeId");
                //      |       console.dir(box);
                //
                // example:
                //              Set a node's margin box to the size of another node
                //      |       var box = dojo.marginBox("someNodeId");
                //      |       dojo.marginBox("someOtherNode", box);
                return box ? geom.setMarginBox(node, box) : geom.getMarginBox(node); // Object
        };

        dojo.contentBox = function contentBox(/*DomNode|String*/node, /*Object?*/box){
                // summary:
                //              Getter/setter for the content-box of node.
                // description:
                //              Returns an object in the expected format of box (regardless if box is passed).
                //              The object might look like:
                //                      `{ l: 50, t: 200, w: 300: h: 150 }`
                //              for a node offset from its parent 50px to the left, 200px from
                //              the top with a content width of 300px and a content-height of
                //              150px. Note that the content box may have a much larger border
                //              or margin box, depending on the box model currently in use and
                //              CSS values set/inherited for node.
                //              While the getter will return top and left values, the
                //              setter only accepts setting the width and height.
                // node:
                //              id or reference to DOM Node to get/set box for
                // box:
                //              If passed, denotes that dojo.contentBox() should
                //              update/set the content box for node. Box is an object in the
                //              above format, but only w (width) and h (height) are supported.
                //              All properties are optional if passed.
                return box ? geom.setContentSize(node, box) : geom.getContentBox(node); // Object
        };

        dojo.coords = function(/*DomNode|String*/node, /*Boolean?*/includeScroll){
                // summary:
                //              Deprecated: Use position() for border-box x/y/w/h
                //              or marginBox() for margin-box w/h/l/t.
                //              Returns an object representing a node's size and position.
                //
                // description:
                //              Returns an object that measures margin-box (w)idth/(h)eight
                //              and absolute position x/y of the border-box. Also returned
                //              is computed (l)eft and (t)op values in pixels from the
                //              node's offsetParent as returned from marginBox().
                //              Return value will be in the form:
                //|                     { l: 50, t: 200, w: 300: h: 150, x: 100, y: 300 }
                //              Does not act as a setter. If includeScroll is passed, the x and
                //              y params are affected as one would expect in dojo.position().
                dojo.deprecated("dojo.coords()", "Use dojo.position() or dojo.marginBox().");
                node = dom.byId(node);
                var s = style.getComputedStyle(node), mb = geom.getMarginBox(node, s);
                var abs = geom.position(node, includeScroll);
                mb.x = abs.x;
                mb.y = abs.y;
                return mb;      // Object
        };

        // mix-in dom-prop
        dojo.getProp = prop.get;
        dojo.setProp = prop.set;

        dojo.prop = function(/*DomNode|String*/node, /*String|Object*/name, /*String?*/value){
                // summary:
                //              Gets or sets a property on an HTML element.
                // description:
                //              Handles normalized getting and setting of properties on DOM
                //              Nodes. If 2 arguments are passed, and a the second argument is a
                //              string, acts as a getter.
                //
                //              If a third argument is passed, or if the second argument is a
                //              map of attributes, acts as a setter.
                //
                //              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:
                //              id or reference to the element to get or set the property on
                // name:
                //              the name of the property to get or set.
                // value:
                //              The value to set for the property
                // returns:
                //              when used as a getter, the value of the requested property
                //              or null if that attribute does not have a specified or
                //              default value;
                //
                //              when used as a setter, the DOM node
                //
                // example:
                //      |       // get the current value of the "foo" property on a node
                //      |       dojo.prop(dojo.byId("nodeId"), "foo");
                //      |       // or we can just pass the id:
                //      |       dojo.prop("nodeId", "foo");
                //
                // example:
                //      |       // use prop() to set the tab index
                //      |       dojo.prop("nodeId", "tabIndex", 3);
                //      |
                //
                // example:
                //      Set multiple values at once, including event handlers:
                //      |       dojo.prop("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.prop("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.prop("someNode", "style", obj);
                //      |
                //      |       // though shorter to use `dojo.style()` in this case:
                //      |       dojo.style("someNode", obj);

                if(arguments.length == 2){
                        return prop[typeof name == "string" ? "get" : "set"](node, name);
                }
                // setter
                return prop.set(node, name, value);
        };

        // mix-in dom-style
        dojo.getStyle = style.get;
        dojo.setStyle = style.set;
        dojo.getComputedStyle = style.getComputedStyle;
        dojo.__toPixelValue = dojo.toPixelValue = style.toPixelValue;

        dojo.style = function(node, name, value){
                // summary:
                //              Accesses styles on a node. If 2 arguments are
                //              passed, acts as a getter. If 3 arguments are passed, acts
                //              as a setter.
                // description:
                //              Getting the style value uses the computed style for the node, so the value
                //              will be a calculated value, not just the immediate node.style value.
                //              Also when getting values, use specific style names,
                //              like "borderBottomWidth" instead of "border" since compound values like
                //              "border" are not necessarily reflected as expected.
                //              If you want to get node dimensions, use `dojo.marginBox()`,
                //              `dojo.contentBox()` or `dojo.position()`.
                // node: DOMNode|String
                //              id or reference to node to get/set style for
                // name: String?|Object?
                //              the style property to set in DOM-accessor format
                //              ("borderWidth", not "border-width") or an object with key/value
                //              pairs suitable for setting each property.
                // value: String?
                //              If passed, sets value on the node for style, handling
                //              cross-browser concerns.  When setting a pixel value,
                //              be sure to include "px" in the value. For instance, top: "200px".
                //              Otherwise, in some cases, some browsers will not apply the style.
                // returns:
                //              when used as a getter, return the computed style of the node if passing in an ID or node,
                //              or return the normalized, computed value for the property when passing in a node and a style property
                // example:
                //              Passing only an ID or node returns the computed style object of
                //              the node:
                //      |       dojo.style("thinger");
                // example:
                //              Passing a node and a style property returns the current
                //              normalized, computed value for that property:
                //      |       dojo.style("thinger", "opacity"); // 1 by default
                //
                // example:
                //              Passing a node, a style property, and a value changes the
                //              current display of the node and returns the new computed value
                //      |       dojo.style("thinger", "opacity", 0.5); // == 0.5
                //
                // example:
                //              Passing a node, an object-style style property sets each of the values in turn and returns the computed style object of the node:
                //      |       dojo.style("thinger", {
                //      |               "opacity": 0.5,
                //      |               "border": "3px solid black",
                //      |               "height": "300px"
                //      |       });
                //
                // example:
                //              When the CSS style property is hyphenated, the JavaScript property is camelCased.
                //              font-size becomes fontSize, and so on.
                //      |       dojo.style("thinger",{
                //      |               fontSize:"14pt",
                //      |               letterSpacing:"1.2em"
                //      |       });
                //
                // example:
                //              dojo.NodeList implements .style() using the same syntax, omitting the "node" parameter, calling
                //              dojo.style() on every element of the list. See: `dojo.query()` and `dojo.NodeList()`
                //      |       dojo.query(".someClassName").style("visibility","hidden");
                //      |       // or
                //      |       dojo.query("#baz > div").style({
                //      |               opacity:0.75,
                //      |               fontSize:"13pt"
                //      |       });

                switch(arguments.length){
                        case 1:
                                return style.get(node);
                        case 2:
                                return style[typeof name == "string" ? "get" : "set"](node, name);
                }
                // setter
                return style.set(node, name, value);
        };

        return dojo;
});