sproutcore 0.9.0

data/frameworks/sproutcore/foundation/path_module.js

@@ -0,0 +1,413 @@
+// ==========================================================================
+// SC.PathModule
+// Author: Charles Jolley
+//
+// When creating a web app, you often need to find elements in your page to
+// configure them on load.  These elements are often marked with a class or
+// id.  General purpose methods such as $$() or getElementsByClassName are
+// not very good for this because they search entire trees of nodes.
+//
+// These methods are much faster because they make some assumptions about 
+// how your elements are structured.
+//
+// ==========================================================================
+
+require('Core') ;
+require('foundation/benchmark') ;
+
+// Constants
+SC.BENCHMARK_SELECTOR = NO ;
+NO_LIMIT = 10000 ;
+
+// PathModule is high-performance API for locating DOM nodes in your HTML
+// document.  It's designed to be used by searching elements from a parent
+// node.  
+//
+// PathModule is patched into Prototypes Element.Methods, which means that 
+// you can automatically access this API for any DOM element retrieved via
+// the $() operator.  You can also mixin the PathModule api to your own 
+// objects.  Be sure to also have a property called rootElement that points to 
+// the root DOM element you want to search.
+//
+SC.PathModule = {
+
+    $$func: function(func, levels, max, nest) {
+      return SC._PathModule.$$func(this.rootElement,func,levels,max,nest);
+    },
+
+    $$C: function(className, levels, max, nest) {
+      return SC._PathModule.$$C(this.rootElement,className,levels,max,nest);
+    },
+
+    $$T: function(tagName, levels, max, nest) {
+      return SC._PathModule.$$T(this.rootElement,tagName,levels,max,nest);
+    },
+
+    $$P: function(property, value, levels, max, nest) {
+      return SC._PathModule.$$P(this.rootElement, property, value, levels, max, nest);
+    },
+
+    $$S: function(selector, levels, max, nest) {
+      return SC._PathModule.$$S(this.rootElement, selector, levels, max, nest);
+    },
+
+    // finds the first node for which func returns true.
+    $func: function(func, levels) {
+      return SC._PathModule.$func(this.rootElement, func, levels);
+    },
+
+    // finds the first node with class name.  returns element, not array.
+    $C: function(className, levels) {
+      return SC._PathModule.$C(this.rootElement, className, levels);
+    },
+
+    // finds the first node with tag name.  returns element, not array.
+    $T: function(tagName, levels) {
+      return SC._PathModule.$T(this.rootElement, tagName, levels);
+    },
+
+    // find first node with an attribute matching then named value.
+    $P: function(attr, value, levels) {
+      return SC._PathModule.$P(this.rootElement, attr, value, levels);
+    },
+
+    // find first node matching the specified class selector.
+    $S: function(selector, levels) {
+      return SC._PathModule.$S(this.rootElement, selector, levels);
+    },
+    
+    // find an element and configure it as the named view if it is not already
+    // configured.
+    $$view: function(selector, viewClass, levels, max, nest) {
+      return SC._PathModule.$$view(this.rootElement, selector, viewClass, levels, max, nest) ;
+    },
+
+    // find the first element matching the selector and create a view if it is
+    // not already configured.
+    $view: function(selector, viewClass, levels) {
+      return SC._PathModule.$view(this.rootElement, selector, viewClass, levels) ;
+    }
+    
+};
+
+// This version of PathModule can be added to Element.Methods among others.
+// It is the same API except that it passes the element as the first parameter.
+SC._PathModule = {
+
+  // this is the core method that needs to be implemented for each object.
+  // this method will search the receiver (up to _levels_ deep) for _max_
+  // elements for which the function func() returns true. 
+  //
+  // el:     (req) the root element.  If you pass null, document will be used. 
+  // func:   (req) the function to be used to check each element.
+  // levels: (opt) the max levels deep in nested elements. defaults: NO_LIMIT
+  // max:    (opt) the maximum number of elements to return. defaults: 
+  //         NO_LIMIT
+  // nest:   (opt) if true, then the children of matched elements will also be
+  //         searched.  if your element matches will never be nested, setting
+  //         this to false can be much faster.  defaults: false
+  $$func: function(el, func, levels, max, nest) {
+    // defaults
+    levels = levels || NO_LIMIT ; max = max || NO_LIMIT; nest = nest || false;
+    
+    // function to search this node.
+    var searchNode = function(node, depth, remain, includeThisNode) {
+      var ret = [] ;
+      
+      // does this node match?
+      // we extend any returned elements so you can chain these methods. 
+      // on browsers that support HTMLElement.prototype, this will do nothing.
+      var match = (includeThisNode) ? func(node) : false ;
+      if (match) { ret.push(node); remain--; }
+
+      // can we search children?
+      depth-- ;
+      if ((match && !nest) || (remain<=0) || (depth<=0)) return ret;
+
+      // search children.
+      node = node.firstChild ;
+      while(node && (remain > 0)) {
+        var found = searchNode(node,depth,remain,true) ;
+        remain -= found.length ;
+        ret = ret.concat(found) ;
+        node = node.nextSibling ;
+      }
+      return ret ;
+    } ;
+    
+    return searchNode(el || document, levels+1, max, false) ;
+  },
+  
+  // finds all nodes with class name.
+  $$C: function(el, className, levels, max, nest) {
+    return SC._PathModule.$$func(el, function(node) {
+      return Element.hasClassName(node, className) ; 
+    }, levels, max, nest) ;
+  },
+  
+  // find all nodes with tag name
+  $$T: function(el, tagName, levels, max, nest) {
+    tagName = tagName.toUpperCase() ;
+    return SC._PathModule.$$func(el, function(node) { 
+      return node.tagName == tagName; 
+    }, levels, max, nest) ;
+  },
+
+  // find all nodes with an attribute matching then named value.
+  $$P: function(el, property, value, levels, max, nest) {
+    return SC._PathModule.$$func(el, function(node) { 
+      var pvalue = (node.getAttribute) ? node.getAttribute(property) : node[property] ;
+      return pvalue == value; 
+    }, levels, max, nest) ;
+  },
+
+  // this will parse the selector and then execute the selectors to return
+  // the result.  this understands a very simple form for selectors. the 
+  // parts are split by spaces. and treated like so:
+  // '.classname' = class name
+  // 'tag' = tag
+  // '#id' = an id. (this will bypass the normal selector methods) 
+  // 'attr=value' = find an attr with the value.
+  //
+  // understands the following qualifiers:
+  // .selector:3   => find .selector at most 3 levels deep
+  // .selector:3:4 => find at most 4 .selectors at most 3 levels deep
+  // .selector?    => find at most 1 .selector, any depth.
+  // .selector?3   => find at most 3 .selectors, any depth
+  // .selector:*:4 => find at more 4 .selectors at any depth.
+  // 
+  // You can also directly access child nodes by doing:
+  // .selector[0][1][3] -> get child 3 of child 1 of child 0.
+  // or:
+  // [0][2][3] -> search base.
+  //
+  $$S: function(el,selector, levels, max, nest) {
+    var parts = selector.split(' ') ;
+    var ret = [el] ; var nextMax = null ; var bits ;
+    var blevels; var bmax; var q; var indicies ;
+
+    parts.each(function(part) {
+      // this is included for compatibility with earlier changes I made to
+      // prototype.  the preferred way to do this in the future is with with
+      // the colon format.
+      if (part == '?') { nextMax = 1; return ; }
+
+      // get defaults
+      blevels = levels; bmax = (nextMax) ? nextMax : max ;
+      nextMax = null ;
+
+      // if there are indexes, find those and save them.
+      if (part.slice(part.length-1,part.length) == ']') {
+        bits = part.split('[') ;
+        part = bits.shift();
+        indicies = bits.map(function(b) {return parseInt(b.slice(0,-1),0);});
+      } else indicies = null ;
+
+      // find found modifiers
+      bits = part.split('?') ;
+      part = bits[0] ;
+      if (bits.length > 1) {
+        bmax = (bits[1].length == 0) ? 1 : parseInt(bits[1],0) ;
+      }
+
+      // find level modifiers
+      bits = part.split(':') ;
+      part = bits[0] ;
+      if (bits.length > 1) blevels = (bits[1] == '*') ? '*' : parseInt(bits[1],0) ;
+      if (bits.length > 2) bmax = (bits[2] == '*') ? '*' : parseInt(bits[2],0) ;
+
+      // convert star to NO_LIMIT
+      if (blevels == '*') blevels = NO_LIMIT ;
+      if (bmax == '*') bmac = NO_LIMIT ;
+
+      // prepare the selector info.
+      // q tells us how to process the first part.
+      // part is the first part of the selector
+      // bits are any extra css selectors.
+      if (part && part.length > 0) {
+        q = part.slice(0,1) ; 
+        if (['.','#'].indexOf(q) >= 0) { 
+          part = part.slice(1,part.length) ; 
+        }
+        
+        bits = part.split('.') ;
+        part = bits[0] ;
+        bits = bits.slice(1,bits.length) ;
+
+        // optimization for # types.
+        var fret = null ;
+        if (q == '#') {
+          fret = $(part) ;
+          fret = (fret) ? [fret] : null ;
+          if (fret) ret = fret ;
+        }
+        
+        // otherwise pass this off to $$func to actually search.
+        if (fret == null) {
+          fret = [] ;
+          for(var i=0;i<ret.length;i++) {
+            var found = SC._PathModule.$$func(ret[i],function(node) {
+              var match ;
+              switch(q) {
+                case '.':
+                  NODE = node ;
+                  var elementClassName = node.className;
+                  if (elementClassName && (elementClassName.length > 0)) {
+                    match = (elementClassName == part ||
+                      elementClassName.match( new RegExp("(^|\\s)" + part + 
+                        "(\\s|$)"))) ;
+                  } else match = false ;
+                  break ;
+                case '#':
+                  match = node.id == part ;
+                  break ;
+                default:
+                  if (node.tagName) {
+                    match = (node.tagName.toLowerCase() == part.toLowerCase()) ;
+                  } else { match = false; }
+              }
+
+              // if the first item matched, verify that the others match as well.
+              for(var i=0; match && i < bits.length; i++) {
+                if (!Element.hasClassName(node,bits[i])) match = false ; 
+              }
+              return match ; 
+            }, blevels, bmax, nest) ;
+            fret = fret.concat(found) ;
+          }
+          ret = fret ;
+        }
+      } else if ($type(ret) != T_ARRAY) ret = [ret] ;
+
+      // now follow indicies, if there are any
+      if (indicies && indicies.length > 0 && ret) {
+        ret = ret.map(function(el){
+          for(var iloc=0; el && (iloc < indicies.length); iloc++) {
+            el = el.childNodes[indicies[iloc]] ;
+          }
+          return el;
+        }) ;
+      }
+    }) ;
+    return ret ;
+  },
+
+  // finds the first node for which func returns true.
+  $func: function(el,func, levels) {
+    var ret = SC._PathModule.$$func(el,func,levels,1,false) ;
+    return (ret.length>0) ? ret[0] : null ;
+  },
+
+  // finds the first node with class name.  returns element, not array.
+  $C: function(el, className, levels) {
+    var ret = SC._PathModule.$$C(el, className,levels,1,false) ;
+    return (ret.length>0) ? ret[0] : null ;
+  },
+
+  // finds the first node with tag name.  returns element, not array.
+  $T: function(el, tagName, levels) {
+    var ret = SC._PathModule.$$T(el, tagName,levels,1,false) ;
+    return (ret.length>0) ? ret[0] : null ;
+  },
+
+  // find first node with an attribute matching then named value.
+  $P: function(el, attr, value, levels) {
+    var ret = SC._PathModule.$$A(el, attr, value,levels,1,false) ;
+    return (ret.length>0) ? ret[0] : null ;
+  },
+
+  // find first node matching the specified class selector.
+  $S: function(el, selector, levels) {
+    var ret = SC._PathModule.$$S(el, selector,levels,1,false) ;
+    return (ret.length>0) ? ret[0] : null ;
+  },
+  
+  // find an element and configure it as the named view if it is not already
+  // configured.
+  $$view: function(el, selector, viewClass, levels, max, nest) {
+    //if (!viewClass) viewClass = SC.View;
+    var ret ;
+    if (selector && (typeof(selector) != 'string')) {
+      ret = [selector] ;
+    } else {
+      ret = SC._PathModule.$$S(el,selector,levels,max,nest) ;
+    }
+    if (ret) ret = ret.map(function(x) { return (viewClass) ? viewClass.viewFor(x) : SC.View.findViewForElement(x); }) ;
+    return ret ;
+  },
+
+  // find the first element matching the selector and create a view if it is
+  // not already configured.
+  $view: function(el, selector, viewClass, levels) {
+    var ret = SC._PathModule.$$view(el, selector, viewClass, levels, 1, false) ;
+    return (ret.length>0) ? ret[0] : null ;
+  }
+  
+} ;
+
+// Install benchmark report for selector if configured.
+if (SC.BENCHMARK_SELECTOR) {
+  ['$$S','$$C','$$T','$S','$C','$T'].each(function(mname) {
+    SC.Benchmark.install(SC._PathModule,mname) ;
+  })  ;
+  SC.Benchmark.install(window,'$$$') ;
+}
+
+// longer form aliases of the functions.
+Object.extend(SC._PathModule, {
+  $$class: SC._PathModule.$$C,
+  $$tag: SC._PathModule.$$T,
+  $$sel: SC._PathModule.$$S,
+  $$prop: SC._PathModule.$$P,
+  
+  $class: SC._PathModule.$C,
+  $tag: SC._PathModule.$T,
+  $sel: SC._PathModule.$S,
+  $prop: SC._PathModule.$P
+}) ;
+
+// longer form aliases of the functions.
+Object.extend(SC.PathModule, {
+  $$class: SC.PathModule.$$C,
+  $$tag: SC.PathModule.$$T,
+  $$sel: SC.PathModule.$$S,
+  $$prop: SC.PathModule.$$P,
+  
+  $class: SC.PathModule.$C,
+  $tag: SC.PathModule.$T,
+  $sel: SC.PathModule.$S,
+  $prop: SC.PathModule.$P
+}) ;
+
+// Add _PathModule to the appropriate elements.  Add to Element.Methods which
+// will cause it to be copied onto elements automatically in IE when you 
+// call IE.
+Object.extend(Element.Methods,SC._PathModule) ;
+Object.extend(Element,SC._PathModule) ;
+
+// applies to Element.
+if (typeof HTMLElement != 'undefined') {
+  Object.extend(HTMLElement.prototype,SC.PathModule) ;
+}
+
+// applies to document
+Object.extend(document,SC.PathModule) ;
+document.rootElement = document ;
+
+// applies to window.
+Object.extend(Object.extend(window,SC.PathModule), {
+  $$func: function(func, levels, max, nest) {
+    return document.$$func(func,levels,max,nest) ;
+  }
+});
+
+// applies to arrays. Note the override of $$func to act on the group.
+Object.extend(Object.extend(Array.prototype,SC.PathModule), {
+  $$func: function(func, levels, max, nest) {
+    var ret = [] ;
+    for(var loc=0;loc<this.length;loc++) {
+      ret = ret.concat(this[loc].$$func(func,levels,max,nest)) ;
+    }
+    return ret ;
+  }
+}) ;