sproutit-sproutcore 1.0.203 → 1.0.20090721145236

data/frameworks/sproutcore/frameworks/foundation/system/routes.js

@@ -1,487 +0,0 @@
-// ==========================================================================
-// Project:   SproutCore - JavaScript Application Framework
-// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
-//            Portions ©2008-2009 Apple, Inc. All rights reserved.
-// License:   Licened under MIT license (see license.js)
-// ==========================================================================
-
-/**
-  @class
-  
-  Routes makes it possible to load a location in the browser.
-  
-  This is useful when application need to change state depending upon the URL 
-  change. Applications can support deep-linking using routes, which means user 
-  can type specific URL to see certain state of the app e.g.
-  http://localhost:4020/routes_demo#Documents/Photographs
-  
-  To use Routes, first add routes by using SC.route.add(route, target, 
-  method).
-  
-  - *route* - Route is the part of the URL that come after hash (#).
-  - *target* - Object whose route handler needs to be invoked.
-  - *method* - Method that is the route handler.
-  
-  This registers the route to the routes system. When application's URL 
-  matches a registered route, system triggers the route handler. Route handler 
-  should contain the app logic to bring the app to the required state.
-  
-  Second thing to do with routes is to set location. Whenever you want to 
-  register any URL location in browser history you can use 
-  SC.routes.set('location', 'some_path'); 
-  
-  This will register the URL to browser history and also change the URL of the 
-  application. Ideally when you set the location you would like route handler 
-  to get invoked. You should have a route registered to match this pattern of 
-  the location.
-  
-  h2. Example
-  
-  {{{
-    SC.routes.add(':', RoutesDemo, 'routeHandler');
-  }}}
-  
-  This route would match any URL change. Whatever comes after # would get 
-  passed as parameter. RouteDemo is the object that contains method 
-  'routeHandler'.
-  
-  {{{
-    SC.routes.set('location', 'Documents/Photographs');
-  }}}
-  
-  Doing this changes the location to #Documents/Photographs. Part after #, 
-  Documents/Photographs in this case, gets passed as parameter to route 
-  handler.
-  
-  @extends SC.Object
-  @since SproutCore 1.0
-*/
-SC.routes = SC.Object.create(
-/** @scope SC.routes.prototype */ {
-  
-  // set this property to your current app lication
-  location: function(key,value) {
-    if (value !== undefined) {
-      if (value === null) value = '' ;
-      
-      // convert an object hash to a string, if it was passed.
-      if (typeof(value) == "object") {
-        
-        // get the original route and any params
-        var parts = value.route ? value.route.split('&') : [''] ;
-        var route = parts.shift() ;
-        var params = {} ;
-        parts.forEach(function(p) {
-          var bits = p.split('=') ;
-          params[bits[0]] = bits[1] ;
-        }) ;
-        
-        // overlay any params passed in the object.
-        for(key in value) {
-          if (!value.hasOwnProperty(key)) continue ;
-          if (key != 'route') {
-            params[key] = encodeURIComponent(''+value[key]) ;
-          }
-        }
-        
-        // now build params.
-        parts = [route] ;
-        for(key in params) {
-          if (!params.hasOwnProperty(key)) continue ;
-          parts.push([key,params[key]].join('=')) ;          
-        }
-        
-        // and combine.
-        value = parts.join('&') ;
-      }
-      
-      if (this._location != value) {
-        this._location = value ;
-        this._setWindowLocation(value) ;
-        //this.gotoRoute(value) ;
-      }
-    }
-    return this._location ;
-  }.property(),
-  
-  /**
-    Ensures we are at the current route location.
-  */
-  ping: function() { 
-    if (!this._didSetupHistory) {
-      this._didSetupHistory = true ;
-      this._setupHistory() ;
-    }
-    this._checkWindowLocation(); 
-  },
-  
-  /**
-    Register a route here.  Routes have the following format:
-    
-    static/route/path -- matches this path only.
-    static/route/:path -- matches any static/route, :path passed as param.
-    static/ *route -- matches any static, route gets rest of URL.
-    
-    parameters can also be passed using &.
-    static/route&param1=value&param2=value2
-    
-    @param {string} route
-    @param {Object} target
-    @param {Function or String} method or method name on target
-    @returns {SC.routes} receiver
-  */
-  add: function(route, target, method) {
-    // normalize the target/method
-    if (method===undefined && SC.typeOf(target) === SC.T_FUNCTION) {
-      method = target; target = null ;
-    } else if (SC.typeOf(method) === SC.T_STRING) {
-      method = target[method] ;
-    }
-    
-    var parts = route.split('/') ;
-    if (!this._routes) this._routes = SC.routes._Route.create() ;
-    this._routes.addRoute(parts, target, method) ;
-    return this;
-  },
-  
-  /**
-    Eval routes.
-    
-    @param {String} route
-  */
-  gotoRoute: function(route) {
-    var params = {},
-        parts, routeHandler, target, method ;
-    
-    // save this route for window location sensing
-    this._lastRoute = route ;
-    
-    // step 1: split out parameters
-    parts = route.split('&') ;
-    if (parts && parts.length > 0) {
-      route = parts.shift() ;
-      parts.forEach(function(part) {
-        var param = part.split('=') ;
-        if (param && param.length > 1) params[param[0]] = decodeURIComponent(param[1]) ;
-      }) ;
-    } else route = '' ;
-    
-    // step 2: split our route parts
-    parts = route.split('/') ;
-    
-    // step 3: evaluate route.
-    if (!this._routes) this._routes = SC.routes._Route.create() ;
-    
-    routeHandler = this._routes.functionForRoute(parts,params) ;
-    
-    if (routeHandler) {
-      target = routeHandler._target;
-      method = routeHandler._method;
-      method.call(target, params);
-    }
-      //else console.log('could not find route for: "'+route+'"') ;
-  },
-  
-  /** @private */
-  init: function() {
-    arguments.callee.base.call(this) ;
-    if (SC.browser.isSafari && !(SC.browser.safari >= 3)) {
-      SC.mixin(this,this.browserFuncs.safari) ;  
-    } else if (SC.browser.isIE) {
-      SC.mixin(this,this.browserFuncs.ie) ;  
-    }
-    this._didSetupHistory = false ;
-  },
-  
-  // use this method instead of invokeLater() to check windowLocation since
-  // we don't want to trigger runLoops.
-  invokeCheckWindowLocation: function(after) {
-    var f = this.__checkWindowLocation, that = this;
-    if (!f) {
-      f = this.__checkWindowLocation = function() {
-        that._checkWindowLocation();
-      };
-    }
-    setTimeout(f, after);
-  },
-  
-  /** @private
-    _checkWindowLocation and _setWindowLocation are implemented separately for
-    each browser.  Below are the implementations, which get copied during init.
-  */
-  browserFuncs: {
-    
-    // for Safari2 and earlier.
-    safari: {
-      
-      _setupHistory: function() {
-        // get initial cloc.
-        var cloc = location.hash ;
-        cloc = (cloc && cloc.length > 0) ? cloc.slice(1,cloc.length) : '' ;
-        this._cloc = cloc ;
-        
-        // create back stack.
-        this._backStack = [] ;
-        this._backStack.length = history.length ;
-        this._backStack.push(cloc) ;
-        
-        // create forward stack.
-        this._forwardStack = [] ;
-        
-        this.invokeCheckWindowLocation(1000) ;
-      },
-      
-      _checkWindowLocation: function() { 
-        // The way we know the user has moved forward or back in the history 
-        // is when the length of the history array no longer matched our own 
-        // copy of the history. However, when we first change locations, it 
-        // takes a little while for Safari to catch up.  So what we do instead 
-        // is first check to see if Safari's length has changed from its last 
-        // known length and only then check for a delta.
-        var historyDidChange = (history.length - this._lastLength) !== 0;
-        var delta = (historyDidChange) ? (history.length - this._backStack.length) : 0 ;
-        this._lastLength = history.length ;
-        
-        if (historyDidChange) console.log('historyDidChange') ;
-        
-        // if the history length has changed, then we need to move forward or 
-        // back in the history.
-        if (delta) {
-          if (delta < 0) { // back button has been pushed
-            
-            // shift out the current loc.
-            this._forwardStack.push(this._cloc) ; 
-            
-            // shift out other items.
-            for(var i=0; i < Math.abs(delta+1);i++) {
-              this._forwardStack.push(this._backStack.pop()) ;
-            }
-            
-            // set new cloc.
-            this._cloc = this._backStack.pop() ;
-            
-            
-          } else { // forward button has been pushed
-            
-            // shift out the current loc.
-            this._backStack.push(this._cloc) ;
-            
-            for(i=0; i < (delta-1); i++) {
-              this._backStack.push(this._forwardStack.pop()) ;
-            }
-            
-            this._cloc = this._forwardStack.pop() ;
-          }
-          
-        // if the history has changed but the delta hasn't, then that means
-        // a new location was set via _setWindowLocation().  Normally we would
-        // call gotoRoute in that method, but doing so will crash Safari.
-        // Instead, we wait until Safari registers the change and then do the
-        // route change.
-        } else if (historyDidChange && this._locationDidChange) {
-          this.gotoRoute(this._cloc) ;
-          this._locationDidChange = false ;
-        }
-        
-        var cloc = this._cloc ;
-        var loc = this.get('location') ;
-        if (cloc != loc) {
-          this.set('location',(cloc) ? cloc : '') ;
-          this.gotoRoute(cloc) ;
-        }
-        
-        this.invokeCheckWindowLocation(50) ;
-      },
-      
-      _setWindowLocation: function(loc) {
-        var cloc = this._cloc ;
-        if (cloc != loc) {
-          this._backStack.push(this._cloc) ;
-          this._forwardStack.length = 0 ;
-          this._cloc = loc ;          
-          location.hash = (loc && loc.length > 0) ? loc : '' ;
-          this._locationDidChange = true ;
-        }
-      }
-      
-    },
-    
-    // for IE.
-    ie: {
-      _setupHistory: function() {
-        this.invokeCheckWindowLocation(1000) ;
-      },
-      
-      _checkWindowLocation: function() {
-        var loc = this.get('location') ;
-        var cloc = location.hash ;
-        cloc = (cloc && cloc.length > 0) ? cloc.slice(1,cloc.length) : '' ;
-        if (cloc != loc) this.set('location',(cloc) ? cloc : '') ;
-        this.invokeCheckWindowLocation(100) ;
-      },
-      
-      _setWindowLocation: function(loc) {
-        //console.log('_setWindowLocation('+loc+')') ;
-        var cloc = location.hash ;
-        cloc = (cloc && cloc.length > 0) ? cloc.slice(1,cloc.length) : '' ;
-        if (cloc != loc) {
-          location.hash = (loc && loc.length > 0) ? loc : '#' ;
-        }
-        this.gotoRoute(loc) ;
-      }
-    }
-  },
-  
-  /** @private */
-  _setupHistory: function() {
-    var that = this ;
-    this.invokeCheckWindowLocation(1000) ;
-  },
-  
-  /** @private */
-  _checkWindowLocation: function() {
-    var loc = this.get('location') ;
-    var cloc = location.hash ;
-    cloc = (cloc && cloc.length > 0) ? cloc.slice(1,cloc.length) : '' ;
-    if (cloc != loc) {
-      SC.RunLoop.begin();
-      this.set('location',(cloc) ? cloc : '') ;
-      SC.RunLoop.end();
-    }
-    
-    this.invokeCheckWindowLocation(150) ;
-  },
-  
-  /** @private */
-  _setWindowLocation: function(loc) {
-    //console.log('_setWindowLocation('+loc+')') ;
-    var cloc = location.hash ;
-    cloc = (cloc && cloc.length > 0) ? cloc.slice(1,cloc.length) : '' ;
-    if (cloc != loc) {
-      location.hash = (loc && loc.length > 0) ? loc : '#' ;
-    }
-    this.gotoRoute(loc) ;
-  },
-  
-  /** @private */
-  _routes: null,
-  
-  /** @private This object handles a single route level. */
-  _Route: SC.Object.extend({
-    
-    // route handler class.
-    _target: null,
-    
-    // route handler
-    _method: null,
-    
-    // staticly named routes.
-    _static: null,
-    
-    // dynamically named routes.
-    _dynamic: null,
-    
-    // set the wildcard route name here.
-    _wildcard: null,
-    
-    addRoute: function(parts, target, method) {
-      
-      if (!parts || parts.length === 0) {
-        this._target = target;
-        this._method = method;
-        
-      // add to route table.
-      } else {
-        var part = parts.shift() ; // get next route.
-        var nextRoute = null ;
-        switch(part.slice(0,1)) {
-          
-          // add a dynamic route
-          case ':':
-            part = part.slice(1,part.length) ;
-            var routes = this._dynamic[part] || [] ;
-            nextRoute = SC.routes._Route.create() ;
-            routes.push(nextRoute) ;
-            this._dynamic[part] = routes ;
-            break ;
-            
-          // setup wildcard route
-          case '*':
-            part = part.slice(1,part.length) ;
-            this._wildcard = part ;
-            this._target = target;        
-            this._method = method;
-            break ;
-            
-          // setup a normal static route.
-          default:
-            routes = this._static[part] || [] ;
-            nextRoute = SC.routes._Route.create() ;
-            routes.push(nextRoute) ;
-            this._static[part] = routes ;
-        }
-        
-        // if we need to go another level deeper, call nextRoute
-        if (nextRoute) nextRoute.addRoute(parts, target, method) ;
-      }
-    },
-    
-    // process the next level of the route and pass on.
-    functionForRoute: function(parts, params) {
-      
-      // if parts it empty, then we are here, so return func
-      if (!parts || parts.length === 0) {
-        return this ;        
-        
-      // process the next part
-      } else {
-        var part = parts.shift(),
-            ret  = null,
-           routes, nextRoute, loc ;
-        
-        // try to match to static
-        routes = this._static[part] ;
-        if (routes) {
-          for(loc=0;(loc < routes.length) && (ret===null);loc++) {
-            var clone = parts.slice() ;
-            ret = routes[loc].functionForRoute(clone, params) ;
-          }
-        }
-        
-        // try to match dynamic if no static match was found.
-        if (ret === null) {
-          for(var key in this._dynamic) {
-            routes = this._dynamic[key] ;
-            if (routes) {
-              for(loc=0;(loc<routes.length) && (ret === null);loc++) {
-                clone = parts.slice() ;
-                ret = routes[loc].functionForRoute(clone,params) ;
-            
-                // if a route was found, save the current part in params.
-                if (ret && params) params[key] = part ;
-              }
-            }
-
-            if (ret) break ; 
-          }
-        }
-        
-        
-        // if nothing still found, and there is a wildcard, match that.
-        if ((ret === null) && this._wildcard) {
-          parts.unshift(part) ;
-          if (params) params[this._wildcard] = parts.join('/') ;
-          ret = this;
-        }
-        
-        return ret ;
-      }
-    },
-    
-    init: function() {
-      arguments.callee.base.call(this) ;
-      this._static = {} ; this._dynamic = {} ;
-    }
-  })
-  
-});