source: Dev/trunk/src/client/dojo/NodeList-dom.js @ 501

define(["./_base/kernel", "./query", "./_base/array", "./_base/lang", "./dom-class", "./dom-construct", "./dom-geometry", "./dom-attr", "./dom-style"], function(dojo, query, array, lang, domCls, domCtr, domGeom, domAttr, domStyle){

        // module:
        //              dojo/NodeList-dom.js

        /*=====
         return function(){
                 // summary:
                 //             Adds DOM related methods to NodeList, and returns NodeList constructor.
         };
         =====*/

        var magicGuard = function(a){
                // summary:
                //              the guard function for dojo/dom-attr() and dojo/dom-style()
                return a.length == 1 && (typeof a[0] == "string"); // inline'd type check
        };

        var orphan = function(node){
                // summary:
                //              function to orphan nodes
                var p = node.parentNode;
                if(p){
                        p.removeChild(node);
                }
        };
        // FIXME: should we move orphan() to dojo/_base/html?

        var NodeList = query.NodeList,
                awc = NodeList._adaptWithCondition,
                aafe = NodeList._adaptAsForEach,
                aam = NodeList._adaptAsMap;

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

        lang.extend(NodeList, {
                _normalize: function(/*String||Element||Object||NodeList*/content, /*DOMNode?*/refNode){
                        // summary:
                        //              normalizes data to an array of items to insert.
                        // description:
                        //              If content is an object, it can have special properties "template" and
                        //              "parse". If "template" is defined, then the template value is run through
                        //              dojo/string.substitute (if dojo/string.substitute() has been required elsewhere),
                        //              or if templateFunc is a function on the content, that function will be used to
                        //              transform the template into a final string to be used for for passing to dojo/dom-construct.toDom().
                        //              If content.parse is true, then it is remembered for later, for when the content
                        //              nodes are inserted into the DOM. At that point, the nodes will be parsed for widgets
                        //              (if dojo/parser has been required elsewhere).

                        //Wanted to just use a DocumentFragment, but for the array/NodeList
                        //case that meant using cloneNode, but we may not want that.
                        //Cloning should only happen if the node operations span
                        //multiple refNodes. Also, need a real array, not a NodeList from the
                        //DOM since the node movements could change those NodeLists.

                        var parse = content.parse === true;

                        //Do we have an object that needs to be run through a template?
                        if(typeof content.template == "string"){
                                var templateFunc = content.templateFunc || (dojo.string && dojo.string.substitute);
                                content = templateFunc ? templateFunc(content.template, content) : content;
                        }

                        var type = (typeof content);
                        if(type == "string" || type == "number"){
                                content = domCtr.toDom(content, (refNode && refNode.ownerDocument));
                                if(content.nodeType == 11){
                                        //DocumentFragment. It cannot handle cloneNode calls, so pull out the children.
                                        content = lang._toArray(content.childNodes);
                                }else{
                                        content = [content];
                                }
                        }else if(!lang.isArrayLike(content)){
                                content = [content];
                        }else if(!lang.isArray(content)){
                                //To get to this point, content is array-like, but
                                //not an array, which likely means a DOM NodeList. Convert it now.
                                content = lang._toArray(content);
                        }

                        //Pass around the parse info
                        if(parse){
                                content._runParse = true;
                        }
                        return content; //Array
                },

                _cloneNode: function(/*DOMNode*/ node){
                        // summary:
                        //              private utility to clone a node. Not very interesting in the vanilla
                        //              dojo/NodeList case, but delegates could do interesting things like
                        //              clone event handlers if that is derivable from the node.
                        return node.cloneNode(true);
                },

                _place: function(/*Array*/ary, /*DOMNode*/refNode, /*String*/position, /*Boolean*/useClone){
                        // summary:
                        //              private utility to handle placing an array of nodes relative to another node.
                        // description:
                        //              Allows for cloning the nodes in the array, and for
                        //              optionally parsing widgets, if ary._runParse is true.

                        //Avoid a disallowed operation if trying to do an innerHTML on a non-element node.
                        if(refNode.nodeType != 1 && position == "only"){
                                return;
                        }
                        var rNode = refNode, tempNode;

                        //Always cycle backwards in case the array is really a
                        //DOM NodeList and the DOM operations take it out of the live collection.
                        var length = ary.length;
                        for(var i = length - 1; i >= 0; i--){
                                var node = (useClone ? this._cloneNode(ary[i]) : ary[i]);

                                //If need widget parsing, use a temp node, instead of waiting after inserting into
                                //real DOM because we need to start widget parsing at one node up from current node,
                                //which could cause some already parsed widgets to be parsed again.
                                if(ary._runParse && dojo.parser && dojo.parser.parse){
                                        if(!tempNode){
                                                tempNode = rNode.ownerDocument.createElement("div");
                                        }
                                        tempNode.appendChild(node);
                                        dojo.parser.parse(tempNode);
                                        node = tempNode.firstChild;
                                        while(tempNode.firstChild){
                                                tempNode.removeChild(tempNode.firstChild);
                                        }
                                }

                                if(i == length - 1){
                                        domCtr.place(node, rNode, position);
                                }else{
                                        rNode.parentNode.insertBefore(node, rNode);
                                }
                                rNode = node;
                        }
                },


                position: aam(domGeom.position),
                /*=====
                position: function(){
                        // summary:
                        //              Returns border-box objects (x/y/w/h) of all elements in a node list
                        //              as an Array (*not* a NodeList). Acts like `dojo/dom-geometry-position`, though
                        //              assumes the node passed is each node in this list.

                        return dojo.map(this, dojo.position); // Array
                },
                =====*/

                attr: awc(getSet(domAttr), magicGuard),
                /*=====
                attr: function(property, value){
                        // summary:
                        //              gets or sets the DOM attribute for every element in the
                        //              NodeList. See also `dojo/dom-attr`
                        // property: String
                        //              the attribute to get/set
                        // value: String?
                        //              optional. The value to set the property to
                        // returns:
                        //              if no value is passed, the result is an array of attribute values
                        //              If a value is passed, the return is this NodeList
                        // example:
                        //              Make all nodes with a particular class focusable:
                        //      |       require(["dojo/query", "dojo/NodeList-dom"], function(query){
                        //      |               query(".focusable").attr("tabIndex", -1);
                        //      |       });
                        // example:
                        //              Disable a group of buttons:
                        //      |       require(["dojo/query", "dojo/NodeList-dom"], function(query){
                        //      |               query("button.group").attr("disabled", true);
                        //      |       });
                        // example:
                        //              innerHTML can be assigned or retrieved as well:
                        //      |       // get the innerHTML (as an array) for each list item
                        //      |       require(["dojo/query", "dojo/NodeList-dom"], function(query){
                        //      |               var ih = query("li.replaceable").attr("innerHTML");
                        //      |       });
                        return; // dojo/NodeList|Array
                },
                =====*/

                style: awc(getSet(domStyle), magicGuard),
                /*=====
                style: function(property, value){
                        // summary:
                        //              gets or sets the CSS property for every element in the NodeList
                        // property: String
                        //              the CSS property to get/set, in JavaScript notation
                        //              ("lineHieght" instead of "line-height")
                        // value: String?
                        //              optional. The value to set the property to
                        // returns:
                        //              if no value is passed, the result is an array of strings.
                        //              If a value is passed, the return is this NodeList
                        return; // dojo/NodeList
                        return; // Array
                },
                =====*/

                addClass: aafe(domCls.add),
                /*=====
                addClass: function(className){
                        // summary:
                        //              adds the specified class to every node in the list
                        // className: String|Array
                        //              A String class name to add, or several space-separated class names,
                        //              or an array of class names.
                        return; // dojo/NodeList
                },
                =====*/

                removeClass: aafe(domCls.remove),
                /*=====
                removeClass: function(className){
                        // summary:
                        //              removes the specified class from every node in the list
                        // className: String|Array?
                        //              An optional String class name to remove, or several space-separated
                        //              class names, or an array of class names. If omitted, all class names
                        //              will be deleted.
                        // returns:
                        //              this list
                        return; // dojo/NodeList
                },
                =====*/

                toggleClass: aafe(domCls.toggle),
                /*=====
                toggleClass: function(className, condition){
                        // summary:
                        //              Adds a class to node if not present, or removes if present.
                        //              Pass a boolean condition if you want to explicitly add or remove.
                        // condition: Boolean?
                        //              If passed, true means to add the class, false means to remove.
                        // className: String
                        //              the CSS class to add
                        return; // dojo/NodeList
                },
                =====*/

                replaceClass: aafe(domCls.replace),
                /*=====
                replaceClass: function(addClassStr, removeClassStr){
                        // summary:
                        //              Replaces one or more classes on a node if not present.
                        //              Operates more quickly than calling `removeClass()` and `addClass()`
                        // addClassStr: String|Array
                        //              A String class name to add, or several space-separated class names,
                        //              or an array of class names.
                        // removeClassStr: String|Array?
                        //              A String class name to remove, or several space-separated class names,
                        //              or an array of class names.
                        return; // dojo/NodeList
                 },
                 =====*/

                empty: aafe(domCtr.empty),
                /*=====
                empty: function(){
                        // summary:
                        //              clears all content from each node in the list. Effectively
                        //              equivalent to removing all child nodes from every item in
                        //              the list.
                        return this.forEach("item.innerHTML='';"); // dojo/NodeList
                        // FIXME: should we be checking for and/or disposing of widgets below these nodes?
                },
                =====*/

                removeAttr: aafe(domAttr.remove),
                /*=====
                 removeAttr: function(name){
                        // summary:
                        //              Removes an attribute from each node in the list.
                        // name: String
                        //              the name of the attribute to remove
                        return;         // dojo/NodeList
                },
                =====*/

                marginBox: aam(domGeom.getMarginBox),
                /*=====
                marginBox: function(){
                        // summary:
                        //              Returns margin-box size of nodes
                        return; // dojo/NodeList
                 },
                 =====*/

                // FIXME: connectPublisher()? connectRunOnce()?

                /*
                destroy: function(){
                        // summary:
                        //              destroys every item in the list.
                        this.forEach(d.destroy);
                        // FIXME: should we be checking for and/or disposing of widgets below these nodes?
                },
                */

                place: function(/*String||Node*/ queryOrNode, /*String*/ position){
                        // summary:
                        //              places elements of this node list relative to the first element matched
                        //              by queryOrNode. Returns the original NodeList. See: `dojo/dom-construct.place`
                        // queryOrNode:
                        //              may be a string representing any valid CSS3 selector or a DOM node.
                        //              In the selector case, only the first matching element will be used
                        //              for relative positioning.
                        // position:
                        //              can be one of:
                        //
                        //              -       "last" (default)
                        //              -       "first"
                        //              -       "before"
                        //              -       "after"
                        //              -       "only"
                        //              -       "replace"
                        //
                        //              or an offset in the childNodes property
                        var item = query(queryOrNode)[0];
                        return this.forEach(function(node){ domCtr.place(node, item, position); }); // dojo/NodeList
                },

                orphan: function(/*String?*/ filter){
                        // summary:
                        //              removes elements in this list that match the filter
                        //              from their parents and returns them as a new NodeList.
                        // filter:
                        //              CSS selector like ".foo" or "div > span"
                        // returns:
                        //              NodeList containing the orphaned elements
                        return (filter ? query._filterResult(this, filter) : this).forEach(orphan); // dojo/NodeList
                },

                adopt: function(/*String||Array||DomNode*/ queryOrListOrNode, /*String?*/ position){
                        // summary:
                        //              places any/all elements in queryOrListOrNode at a
                        //              position relative to the first element in this list.
                        //              Returns a dojo/NodeList of the adopted elements.
                        // queryOrListOrNode:
                        //              a DOM node or a query string or a query result.
                        //              Represents the nodes to be adopted relative to the
                        //              first element of this NodeList.
                        // position:
                        //              can be one of:
                        //
                        //              -       "last" (default)
                        //              -       "first"
                        //              -       "before"
                        //              -       "after"
                        //              -       "only"
                        //              -       "replace"
                        //
                        //              or an offset in the childNodes property
                        return query(queryOrListOrNode).place(this[0], position)._stash(this);  // dojo/NodeList
                },

                // FIXME: do we need this?
                query: function(/*String*/ queryStr){
                        // summary:
                        //              Returns a new list whose members match the passed query,
                        //              assuming elements of the current NodeList as the root for
                        //              each search.
                        // example:
                        //              assume a DOM created by this markup:
                        //      |       <div id="foo">
                        //      |               <p>
                        //      |                       bacon is tasty, <span>dontcha think?</span>
                        //      |               </p>
                        //      |       </div>
                        //      |       <div id="bar">
                        //      |               <p>great comedians may not be funny <span>in person</span></p>
                        //      |       </div>
                        //              If we are presented with the following definition for a NodeList:
                        //      |       require(["dojo/dom", "dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(dom, query){
                        //      |               var l = new NodeList(dom.byId("foo"), dom.byId("bar"));
                        //              it's possible to find all span elements under paragraphs
                        //              contained by these elements with this sub-query:
                        //      |               var spans = l.query("p span");
                        //      |       });

                        // FIXME: probably slow
                        if(!queryStr){ return this; }
                        var ret = new NodeList;
                        this.map(function(node){
                                // FIXME: why would we ever get undefined here?
                                query(queryStr, node).forEach(function(subNode){
                                        if(subNode !== undefined){
                                                ret.push(subNode);
                                        }
                                });
                        });
                        return ret._stash(this);        // dojo/NodeList
                },

                filter: function(/*String|Function*/ filter){
                        // summary:
                        //              "masks" the built-in javascript filter() method (supported
                        //              in Dojo via `dojo.filter`) to support passing a simple
                        //              string filter in addition to supporting filtering function
                        //              objects.
                        // filter:
                        //              If a string, a CSS rule like ".thinger" or "div > span".
                        // example:
                        //              "regular" JS filter syntax as exposed in dojo.filter:
                        //      |       require(["dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(query){
                        //      |               query("*").filter(function(item){
                        //      |                       // highlight every paragraph
                        //      |                       return (item.nodeName == "p");
                        //      |               }).style("backgroundColor", "yellow");
                        //      |       });
                        // example:
                        //      the same filtering using a CSS selector
                        //      |       require(["dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(query){
                        //      |               query("*").filter("p").styles("backgroundColor", "yellow");
                        //      |       });
                        var a = arguments, items = this, start = 0;
                        if(typeof filter == "string"){ // inline'd type check
                                items = query._filterResult(this, a[0]);
                                if(a.length == 1){
                                        // if we only got a string query, pass back the filtered results
                                        return items._stash(this); // dojo/NodeList
                                }
                                // if we got a callback, run it over the filtered items
                                start = 1;
                        }
                        return this._wrap(array.filter(items, a[start], a[start + 1]), this);   // dojo/NodeList
                },

                /*
                // FIXME: should this be "copyTo" and include parenting info?
                clone: function(){
                        // summary:
                        //              creates node clones of each element of this list
                        //              and returns a new list containing the clones
                },
                */

                addContent: function(/*String||DomNode||Object||dojo/NodeList*/ content, /*String||Integer?*/ position){
                        // summary:
                        //              add a node, NodeList or some HTML as a string to every item in the
                        //              list.  Returns the original list.
                        // description:
                        //              a copy of the HTML content is added to each item in the
                        //              list, with an optional position argument. If no position
                        //              argument is provided, the content is appended to the end of
                        //              each item.
                        // content:
                        //              DOM node, HTML in string format, a NodeList or an Object. If a DOM node or
                        //              NodeList, the content will be cloned if the current NodeList has more than one
                        //              element. Only the DOM nodes are cloned, no event handlers. If it is an Object,
                        //              it should be an object with at "template" String property that has the HTML string
                        //              to insert. If dojo.string has already been dojo.required, then dojo.string.substitute
                        //              will be used on the "template" to generate the final HTML string. Other allowed
                        //              properties on the object are: "parse" if the HTML
                        //              string should be parsed for widgets (dojo.require("dojo.parser") to get that
                        //              option to work), and "templateFunc" if a template function besides dojo.string.substitute
                        //              should be used to transform the "template".
                        // position:
                        //              can be one of:
                        //
                        //              -       "last"||"end" (default)
                        //              -       "first||"start"
                        //              -       "before"
                        //              -       "after"
                        //              -       "replace" (replaces nodes in this NodeList with new content)
                        //              -       "only" (removes other children of the nodes so new content is the only child)
                        //
                        //              or an offset in the childNodes property
                        // example:
                        //              appends content to the end if the position is omitted
                        //      |       require(["dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(query){
                        //      |               query("h3 > p").addContent("hey there!");
                        //      |       });
                        // example:
                        //              add something to the front of each element that has a
                        //              "thinger" property:
                        //      |       require(["dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(query){
                        //      |               query("[thinger]").addContent("...", "first");
                        //      |       });
                        // example:
                        //              adds a header before each element of the list
                        //      |       require(["dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(query){
                        //      |               query(".note").addContent("<h4>NOTE:</h4>", "before");
                        //      |       });
                        // example:
                        //              add a clone of a DOM node to the end of every element in
                        //              the list, removing it from its existing parent.
                        //      |       require(["dojo/dom", "dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(dom, query){
                        //      |               query(".note").addContent(dom.byId("foo"));
                        //      |       });
                        // example:
                        //              Append nodes from a templatized string.
                        //      |       require(["dojo/string", "dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(string, query){
                        //      |               query(".note").addContent({
                        //      |                       template: '<b>${id}: </b><span>${name}</span>',
                        //      |                       id: "user332",
                        //      |                       name: "Mr. Anderson"
                        //      |               });
                        //      |       });
                        // example:
                        //              Append nodes from a templatized string that also has widgets parsed.
                        //      |       require(["dojo/string", "dojo/parser", "dojo/query", "dojo/NodeList-dom"
                        //      |       ], function(string, parser, query){
                        //      |               var notes = query(".note").addContent({
                        //      |                       template: '<button dojoType="dijit/form/Button">${text}</button>',
                        //      |                       parse: true,
                        //      |                       text: "Send"
                        //      |               });
                        //      |       });
                        content = this._normalize(content, this[0]);
                        for(var i = 0, node; (node = this[i]); i++){
                                if(content.length){
                                        this._place(content, node, position, i > 0);
                                }else{
                                        // if it is an empty array, we empty the target node
                                        domCtr.empty(node);
                                }
                        }
                        return this; // dojo/NodeList
                }
        });

        return NodeList;
});