lib/dojo/NodeList-traverse.js.uncompressed.js

   1 define("dojo/NodeList-traverse", ["./query", "./_base/lang", "./_base/array"], function(dquery, lang, array) {
   2         // module:
   3         //              dojo/NodeList-traverse
   4         // summary:
   5         //              TODOC
   6
   7 var NodeList = dquery.NodeList;
   8
   9 /*=====
  10 dojo["NodeList-traverse"] = {
  11         // summary: Adds a chainable methods to dojo.query() / Nodelist instances for traversing the DOM
  12 };
  13
  14 // doc alias helpers:
  15 NodeList = dojo.NodeList;
  16 =====*/
  17
  18 lang.extend(NodeList, {
  19         _buildArrayFromCallback: function(/*Function*/callback){
  20                 // summary:
  21                 //              builds a new array of possibly differing size based on the input list.
  22                 //              Since the returned array is likely of different size than the input array,
  23                 //              the array's map function cannot be used.
  24                 var ary = [];
  25                 for(var i = 0; i < this.length; i++){
  26                         var items = callback.call(this[i], this[i], ary);
  27                         if(items){
  28                                 ary = ary.concat(items);
  29                         }
  30                 }
  31                 return ary;     //Array
  32         },
  33
  34         _getUniqueAsNodeList: function(/*Array*/ nodes){
  35                 // summary:
  36                 //              given a list of nodes, make sure only unique
  37                 //              elements are returned as our NodeList object.
  38                 //              Does not call _stash().
  39                 var ary = [];
  40                 //Using for loop for better speed.
  41                 for(var i = 0, node; node = nodes[i]; i++){
  42                         //Should be a faster way to do this. dojo.query has a private
  43                         //_zip function that may be inspirational, but there are pathways
  44                         //in query that force nozip?
  45                         if(node.nodeType == 1 && array.indexOf(ary, node) == -1){
  46                                 ary.push(node);
  47                         }
  48                 }
  49                 return this._wrap(ary, null, this._NodeListCtor);        //dojo.NodeList
  50         },
  51
  52         _getUniqueNodeListWithParent: function(/*Array*/ nodes, /*String*/ query){
  53                 // summary:
  54                 //              gets unique element nodes, filters them further
  55                 //              with an optional query and then calls _stash to track parent NodeList.
  56                 var ary = this._getUniqueAsNodeList(nodes);
  57                 ary = (query ? dquery._filterResult(ary, query) : ary);
  58                 return ary._stash(this);  //dojo.NodeList
  59         },
  60
  61         _getRelatedUniqueNodes: function(/*String?*/ query, /*Function*/ callback){
  62                 // summary:
  63                 //              cycles over all the nodes and calls a callback
  64                 //              to collect nodes for a possible inclusion in a result.
  65                 //              The callback will get two args: callback(node, ary),
  66                 //              where ary is the array being used to collect the nodes.
  67                 return this._getUniqueNodeListWithParent(this._buildArrayFromCallback(callback), query);  //dojo.NodeList
  68         },
  69
  70         children: function(/*String?*/ query){
  71                 // summary:
  72                 //              Returns all immediate child elements for nodes in this dojo.NodeList.
  73                 //              Optionally takes a query to filter the child elements.
  74                 // description:
  75                 //              .end() can be used on the returned dojo.NodeList to get back to the
  76                 //              original dojo.NodeList.
  77                 // query:
  78                 //              a CSS selector.
  79                 // returns:
  80                 //              dojo.NodeList, all immediate child elements for the nodes in this dojo.NodeList.
  81                 //      example:
  82                 //              assume a DOM created by this markup:
  83                 //      |       <div class="container">
  84                 //      |               <div class="red">Red One</div>
  85                 //      |               Some Text
  86                 //      |               <div class="blue">Blue One</div>
  87                 //      |               <div class="red">Red Two</div>
  88                 //      |               <div class="blue">Blue Two</div>
  89                 //      |       </div>
  90                 //              Running this code:
  91                 //      |       dojo.query(".container").children();
  92                 //              returns the four divs that are children of the container div.
  93                 //              Running this code:
  94                 //      |       dojo.query(".container").children(".red");
  95                 //              returns the two divs that have the class "red".
  96                 return this._getRelatedUniqueNodes(query, function(node, ary){
  97                         return lang._toArray(node.childNodes);
  98                 }); //dojo.NodeList
  99         },
 100
 101         closest: function(/*String*/ query, /*String|DOMNode?*/ root){
 102                 // summary:
 103                 //              Returns closest parent that matches query, including current node in this
 104                 //              dojo.NodeList if it matches the query.
 105                 // description:
 106                 //              .end() can be used on the returned dojo.NodeList to get back to the
 107                 //              original dojo.NodeList.
 108                 // query:
 109                 //              a CSS selector.
 110                 // root:
 111                 //              If specified, query is relative to "root" rather than document body.
 112                 // returns:
 113                 //              dojo.NodeList, the closest parent that matches the query, including the current
 114                 //              node in this dojo.NodeList if it matches the query.
 115                 // example:
 116                 //              assume a DOM created by this markup:
 117                 //      |       <div class="container">
 118                 //      |               <div class="red">Red One</div>
 119                 //      |               Some Text
 120                 //      |               <div class="blue">Blue One</div>
 121                 //      |               <div class="red">Red Two</div>
 122                 //      |               <div class="blue">Blue Two</div>
 123                 //      |       </div>
 124                 //              Running this code:
 125                 //      |       dojo.query(".red").closest(".container");
 126                 //              returns the div with class "container".
 127                 return this._getRelatedUniqueNodes(null, function(node, ary){
 128                         do{
 129                                 if(dquery._filterResult([node], query, root).length){
 130                                         return node;
 131                                 }
 132                         }while(node != root && (node = node.parentNode) && node.nodeType == 1);
 133                         return null; //To make rhino strict checking happy.
 134                 }); //dojo.NodeList
 135         },
 136
 137         parent: function(/*String?*/ query){
 138                 // summary:
 139                 //              Returns immediate parent elements for nodes in this dojo.NodeList.
 140                 //              Optionally takes a query to filter the parent elements.
 141                 // description:
 142                 //              .end() can be used on the returned dojo.NodeList to get back to the
 143                 //              original dojo.NodeList.
 144                 //      query:
 145                 //              a CSS selector.
 146                 // returns:
 147                 //              dojo.NodeList, immediate parent elements for nodes in this dojo.NodeList.
 148                 //      example:
 149                 //              assume a DOM created by this markup:
 150                 //      |       <div class="container">
 151                 //      |               <div class="red">Red One</div>
 152                 //      |               <div class="blue first"><span class="text">Blue One</span></div>
 153                 //      |               <div class="red">Red Two</div>
 154                 //      |               <div class="blue"><span class="text">Blue Two</span></div>
 155                 //      |       </div>
 156                 //              Running this code:
 157                 //      |       dojo.query(".text").parent();
 158                 //              returns the two divs with class "blue".
 159                 //              Running this code:
 160                 //      |       dojo.query(".text").parent(".first");
 161                 //              returns the one div with class "blue" and "first".
 162                 return this._getRelatedUniqueNodes(query, function(node, ary){
 163                         return node.parentNode;
 164                 }); //dojo.NodeList
 165         },
 166
 167         parents: function(/*String?*/ query){
 168                 // summary:
 169                 //              Returns all parent elements for nodes in this dojo.NodeList.
 170                 //              Optionally takes a query to filter the child elements.
 171                 // description:
 172                 //              .end() can be used on the returned dojo.NodeList to get back to the
 173                 //              original dojo.NodeList.
 174                 //      query:
 175                 //              a CSS selector.
 176                 // returns:
 177                 //              dojo.NodeList, all parent elements for nodes in this dojo.NodeList.
 178                 //      example:
 179                 //              assume a DOM created by this markup:
 180                 //      |       <div class="container">
 181                 //      |               <div class="red">Red One</div>
 182                 //      |               <div class="blue first"><span class="text">Blue One</span></div>
 183                 //      |               <div class="red">Red Two</div>
 184                 //      |               <div class="blue"><span class="text">Blue Two</span></div>
 185                 //      |       </div>
 186                 //              Running this code:
 187                 //      |       dojo.query(".text").parents();
 188                 //              returns the two divs with class "blue", the div with class "container",
 189                 //      |       the body element and the html element.
 190                 //              Running this code:
 191                 //      |       dojo.query(".text").parents(".container");
 192                 //              returns the one div with class "container".
 193                 return this._getRelatedUniqueNodes(query, function(node, ary){
 194                         var pary = [];
 195                         while(node.parentNode){
 196                                 node = node.parentNode;
 197                                 pary.push(node);
 198                         }
 199                         return pary;
 200                 }); //dojo.NodeList
 201         },
 202
 203         siblings: function(/*String?*/ query){
 204                 // summary:
 205                 //              Returns all sibling elements for nodes in this dojo.NodeList.
 206                 //              Optionally takes a query to filter the sibling elements.
 207                 // description:
 208                 //              .end() can be used on the returned dojo.NodeList to get back to the
 209                 //              original dojo.NodeList.
 210                 //      query:
 211                 //              a CSS selector.
 212                 // returns:
 213                 //              dojo.NodeList, all sibling elements for nodes in this dojo.NodeList.
 214                 //      example:
 215                 //              assume a DOM created by this markup:
 216                 //      |       <div class="container">
 217                 //      |               <div class="red">Red One</div>
 218                 //      |               Some Text
 219                 //      |               <div class="blue first">Blue One</div>
 220                 //      |               <div class="red">Red Two</div>
 221                 //      |               <div class="blue">Blue Two</div>
 222                 //      |       </div>
 223                 //              Running this code:
 224                 //      |       dojo.query(".first").siblings();
 225                 //              returns the two divs with class "red" and the other div
 226                 //      |       with class "blue" that does not have "first".
 227                 //              Running this code:
 228                 //      |       dojo.query(".first").siblings(".red");
 229                 //              returns the two div with class "red".
 230                 return this._getRelatedUniqueNodes(query, function(node, ary){
 231                         var pary = [];
 232                         var nodes = (node.parentNode && node.parentNode.childNodes);
 233                         for(var i = 0; i < nodes.length; i++){
 234                                 if(nodes[i] != node){
 235                                         pary.push(nodes[i]);
 236                                 }
 237                         }
 238                         return pary;
 239                 }); //dojo.NodeList
 240         },
 241
 242         next: function(/*String?*/ query){
 243                 // summary:
 244                 //              Returns the next element for nodes in this dojo.NodeList.
 245                 //              Optionally takes a query to filter the next elements.
 246                 // description:
 247                 //              .end() can be used on the returned dojo.NodeList to get back to the
 248                 //              original dojo.NodeList.
 249                 //      query:
 250                 //              a CSS selector.
 251                 // returns:
 252                 //              dojo.NodeList, the next element for nodes in this dojo.NodeList.
 253                 //      example:
 254                 //              assume a DOM created by this markup:
 255                 //      |       <div class="container">
 256                 //      |               <div class="red">Red One</div>
 257                 //      |               Some Text
 258                 //      |               <div class="blue first">Blue One</div>
 259                 //      |               <div class="red">Red Two</div>
 260                 //      |               <div class="blue last">Blue Two</div>
 261                 //      |       </div>
 262                 //              Running this code:
 263                 //      |       dojo.query(".first").next();
 264                 //              returns the div with class "red" and has innerHTML of "Red Two".
 265                 //              Running this code:
 266                 //      |       dojo.query(".last").next(".red");
 267                 //              does not return any elements.
 268                 return this._getRelatedUniqueNodes(query, function(node, ary){
 269                         var next = node.nextSibling;
 270                         while(next && next.nodeType != 1){
 271                                 next = next.nextSibling;
 272                         }
 273                         return next;
 274                 }); //dojo.NodeList
 275         },
 276
 277         nextAll: function(/*String?*/ query){
 278                 // summary:
 279                 //              Returns all sibling elements that come after the nodes in this dojo.NodeList.
 280                 //              Optionally takes a query to filter the sibling elements.
 281                 // description:
 282                 //              .end() can be used on the returned dojo.NodeList to get back to the
 283                 //              original dojo.NodeList.
 284                 //      query:
 285                 //              a CSS selector.
 286                 // returns:
 287                 //              dojo.NodeList, all sibling elements that come after the nodes in this dojo.NodeList.
 288                 //      example:
 289                 //              assume a DOM created by this markup:
 290                 //      |       <div class="container">
 291                 //      |               <div class="red">Red One</div>
 292                 //      |               Some Text
 293                 //      |               <div class="blue first">Blue One</div>
 294                 //      |               <div class="red next">Red Two</div>
 295                 //      |               <div class="blue next">Blue Two</div>
 296                 //      |       </div>
 297                 //              Running this code:
 298                 //      |       dojo.query(".first").nextAll();
 299                 //              returns the two divs with class of "next".
 300                 //              Running this code:
 301                 //      |       dojo.query(".first").nextAll(".red");
 302                 //              returns the one div with class "red" and innerHTML "Red Two".
 303                 return this._getRelatedUniqueNodes(query, function(node, ary){
 304                         var pary = [];
 305                         var next = node;
 306                         while((next = next.nextSibling)){
 307                                 if(next.nodeType == 1){
 308                                         pary.push(next);
 309                                 }
 310                         }
 311                         return pary;
 312                 }); //dojo.NodeList
 313         },
 314
 315         prev: function(/*String?*/ query){
 316                 // summary:
 317                 //              Returns the previous element for nodes in this dojo.NodeList.
 318                 //              Optionally takes a query to filter the previous elements.
 319                 // description:
 320                 //              .end() can be used on the returned dojo.NodeList to get back to the
 321                 //              original dojo.NodeList.
 322                 //      query:
 323                 //              a CSS selector.
 324                 // returns:
 325                 //              dojo.NodeList, the previous element for nodes in this dojo.NodeList.
 326                 //      example:
 327                 //              assume a DOM created by this markup:
 328                 //      |       <div class="container">
 329                 //      |               <div class="red">Red One</div>
 330                 //      |               Some Text
 331                 //      |               <div class="blue first">Blue One</div>
 332                 //      |               <div class="red">Red Two</div>
 333                 //      |               <div class="blue">Blue Two</div>
 334                 //      |       </div>
 335                 //              Running this code:
 336                 //      |       dojo.query(".first").prev();
 337                 //              returns the div with class "red" and has innerHTML of "Red One".
 338                 //              Running this code:
 339                 //      |       dojo.query(".first").prev(".blue");
 340                 //              does not return any elements.
 341                 return this._getRelatedUniqueNodes(query, function(node, ary){
 342                         var prev = node.previousSibling;
 343                         while(prev && prev.nodeType != 1){
 344                                 prev = prev.previousSibling;
 345                         }
 346                         return prev;
 347                 }); //dojo.NodeList
 348         },
 349
 350         prevAll: function(/*String?*/ query){
 351                 // summary:
 352                 //              Returns all sibling elements that come before the nodes in this dojo.NodeList.
 353                 //              Optionally takes a query to filter the sibling elements.
 354                 // description:
 355                 //              The returned nodes will be in reverse DOM order -- the first node in the list will
 356                 //              be the node closest to the original node/NodeList.
 357                 //              .end() can be used on the returned dojo.NodeList to get back to the
 358                 //              original dojo.NodeList.
 359                 //      query:
 360                 //              a CSS selector.
 361                 // returns:
 362                 //              dojo.NodeList, all sibling elements that come before the nodes in this dojo.NodeList.
 363                 //      example:
 364                 //              assume a DOM created by this markup:
 365                 //      |       <div class="container">
 366                 //      |               <div class="red prev">Red One</div>
 367                 //      |               Some Text
 368                 //      |               <div class="blue prev">Blue One</div>
 369                 //      |               <div class="red second">Red Two</div>
 370                 //      |               <div class="blue">Blue Two</div>
 371                 //      |       </div>
 372                 //              Running this code:
 373                 //      |       dojo.query(".second").prevAll();
 374                 //              returns the two divs with class of "prev".
 375                 //              Running this code:
 376                 //      |       dojo.query(".first").prevAll(".red");
 377                 //              returns the one div with class "red prev" and innerHTML "Red One".
 378                 return this._getRelatedUniqueNodes(query, function(node, ary){
 379                         var pary = [];
 380                         var prev = node;
 381                         while((prev = prev.previousSibling)){
 382                                 if(prev.nodeType == 1){
 383                                         pary.push(prev);
 384                                 }
 385                         }
 386                         return pary;
 387                 }); //dojo.NodeList
 388         },
 389
 390         andSelf: function(){
 391                 // summary:
 392                 //              Adds the nodes from the previous dojo.NodeList to the current dojo.NodeList.
 393                 // description:
 394                 //              .end() can be used on the returned dojo.NodeList to get back to the
 395                 //              original dojo.NodeList.
 396                 // returns:
 397                 //              dojo.NodeList
 398                 //      example:
 399                 //              assume a DOM created by this markup:
 400                 //      |       <div class="container">
 401                 //      |               <div class="red prev">Red One</div>
 402                 //      |               Some Text
 403                 //      |               <div class="blue prev">Blue One</div>
 404                 //      |               <div class="red second">Red Two</div>
 405                 //      |               <div class="blue">Blue Two</div>
 406                 //      |       </div>
 407                 //              Running this code:
 408                 //      |       dojo.query(".second").prevAll().andSelf();
 409                 //              returns the two divs with class of "prev", as well as the div with class "second".
 410                 return this.concat(this._parent);       //dojo.NodeList
 411         },
 412
 413         //Alternate methods for the :first/:last/:even/:odd pseudos.
 414         first: function(){
 415                 // summary:
 416                 //              Returns the first node in this dojo.NodeList as a dojo.NodeList.
 417                 // description:
 418                 //              .end() can be used on the returned dojo.NodeList to get back to the
 419                 //              original dojo.NodeList.
 420                 // returns:
 421                 //              dojo.NodeList, with the first node in this dojo.NodeList
 422                 //      example:
 423                 //              assume a DOM created by this markup:
 424                 //      |       <div class="container">
 425                 //      |               <div class="red">Red One</div>
 426                 //      |               <div class="blue first">Blue One</div>
 427                 //      |               <div class="red">Red Two</div>
 428                 //      |               <div class="blue last">Blue Two</div>
 429                 //      |       </div>
 430                 //              Running this code:
 431                 //      |       dojo.query(".blue").first();
 432                 //              returns the div with class "blue" and "first".
 433                 return this._wrap(((this[0] && [this[0]]) || []), this); //dojo.NodeList
 434         },
 435
 436         last: function(){
 437                 // summary:
 438                 //              Returns the last node in this dojo.NodeList as a dojo.NodeList.
 439                 // description:
 440                 //              .end() can be used on the returned dojo.NodeList to get back to the
 441                 //              original dojo.NodeList.
 442                 // returns:
 443                 //              dojo.NodeList, with the last node in this dojo.NodeList
 444                 //      example:
 445                 //              assume a DOM created by this markup:
 446                 //      |       <div class="container">
 447                 //      |               <div class="red">Red One</div>
 448                 //      |               <div class="blue first">Blue One</div>
 449                 //      |               <div class="red">Red Two</div>
 450                 //      |               <div class="blue last">Blue Two</div>
 451                 //      |       </div>
 452                 //              Running this code:
 453                 //      |       dojo.query(".blue").last();
 454                 //              returns the last div with class "blue",
 455                 return this._wrap((this.length ? [this[this.length - 1]] : []), this); //dojo.NodeList
 456         },
 457
 458         even: function(){
 459                 // summary:
 460                 //              Returns the even nodes in this dojo.NodeList as a dojo.NodeList.
 461                 // description:
 462                 //              .end() can be used on the returned dojo.NodeList to get back to the
 463                 //              original dojo.NodeList.
 464                 // returns:
 465                 //              dojo.NodeList, with the even nodes in this dojo.NodeList
 466                 //      example:
 467                 //              assume a DOM created by this markup:
 468                 //      |       <div class="container">
 469                 //      |               <div class="interior red">Red One</div>
 470                 //      |               <div class="interior blue">Blue One</div>
 471                 //      |               <div class="interior red">Red Two</div>
 472                 //      |               <div class="interior blue">Blue Two</div>
 473                 //      |       </div>
 474                 //              Running this code:
 475                 //      |       dojo.query(".interior").even();
 476                 //              returns the two divs with class "blue"
 477                 return this.filter(function(item, i){
 478                         return i % 2 != 0;
 479                 }); //dojo.NodeList
 480         },
 481
 482         odd: function(){
 483                 // summary:
 484                 //              Returns the odd nodes in this dojo.NodeList as a dojo.NodeList.
 485                 // description:
 486                 //              .end() can be used on the returned dojo.NodeList to get back to the
 487                 //              original dojo.NodeList.
 488                 // returns:
 489                 //              dojo.NodeList, with the odd nodes in this dojo.NodeList
 490                 //      example:
 491                 //              assume a DOM created by this markup:
 492                 //      |       <div class="container">
 493                 //      |               <div class="interior red">Red One</div>
 494                 //      |               <div class="interior blue">Blue One</div>
 495                 //      |               <div class="interior red">Red Two</div>
 496                 //      |               <div class="interior blue">Blue Two</div>
 497                 //      |       </div>
 498                 //              Running this code:
 499                 //      |       dojo.query(".interior").odd();
 500                 //              returns the two divs with class "red"
 501                 return this.filter(function(item, i){
 502                         return i % 2 == 0;
 503                 }); //dojo.NodeList
 504         }
 505 });
 506
 507 return NodeList;
 508 });