sproutcore 0.9.0

data/frameworks/sproutcore/foundation/observable.js

@@ -0,0 +1,451 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+/**
+  @namespace Implements Key-Value Observing
+
+  Key-Value Observing is one of the fundamental ways that models, controllers
+  and views communicate with each other in a SproutCore application.  Any 
+  object that has this module applied to it can be used in KVO-operations.
+  
+  This module is applied automatically to all objects that inherit from
+  SC.Object, which includes most objects bundled with the SproutCore 
+  framework.  You will not generally apply this module to classes yourself,
+  but you will use the features provided by this module frequently, so it is
+  important to understand how to use it.
+  
+  h2. About Key Value Observing
+
+  Key-Value-Observing (KVO) simply allows one object to observe changes to a 
+  property on another object.  This can replace much of the "glue code" that
+  you often have to write to make parts of your application work together.
+  
+  Using KVO is easy.  All you have to do is use the KVO methods to get and set
+  properties.  Instead of writing:
+  
+  {{{
+    var aName = contact.firstName ;
+    contact.firstName = 'Charles' ;
+  }}}
+  
+  you use:
+
+  {{{
+    var aName = contact.get('firstName') ;
+    contact.set('firstName', 'Charles') ;
+  }}}
+  
+  get() and set() work just like the normal "dot operators" provided by 
+  JavaScript but they provide you with much more power, including not only
+  observing but computed properties as well.
+  
+  INCOMPLETE
+
+*/
+SC.Observable = {
+
+  /**  
+    Manually add a new binding to an object.  This is the same as doing
+    the more familiar propertyBinding: 'property.path' approach.
+  */
+  bind: function(toKey, fromPropertyPath) {
+    
+    var r = SC.idt.active ;
+    
+    var binding ;
+    var props = { to: [this, toKey] } ;
+
+    // for strings try to do default relay
+    var pathType = $type(fromPropertyPath) ;
+    if (pathType == T_STRING || pathType == T_ARRAY) {
+      binding = this[toKey + 'BindingDefault'] || SC.Binding.From;
+      binding = binding(fromPropertyPath) ;
+    } else binding = fromPropertyPath ;
+
+    // check the 'from' value of the relay. if it starts w/
+    // '.' || '*' then convert to a local tuple.
+    var relayFrom = binding.prototype.from ;
+    if ($type(relayFrom) == T_STRING) switch(relayFrom.slice(0,1)) {
+      case '*':
+      case '.':
+        relayFrom = [this,relayFrom.slice(1,relayFrom.length)];
+    }        
+
+    if(r) bt = new Date().getTime();
+
+    binding = binding.create(props, { from: relayFrom }) ;
+    this.bindings.push(binding) ;
+
+    if (r) SC.idt.b1_t += (new Date().getTime()) - bt ;
+    
+    return binding ;
+  },
+  
+  /**  
+    didChangeFor makes it easy for you to verify that you haven't seen any
+    changed values.  You need to use this if your method observes multiple
+    properties.  To use this, call it like this:
+  
+    if (this.didChangeFor('render','height','width')) {
+       // DO SOMETHING HERE IF CHANGED.
+    }
+  */  
+  didChangeFor: function(context) {    
+    var keys = $A(arguments) ;
+    context = keys.shift() ;
+    
+    var ret = false ;
+    if (!this._didChangeCache) this._didChangeCache = {} ;
+    if (!this._didChangeRevisionCache) this._didChangeRevisionCache = {};
+    
+    var seen = this._didChangeCache[context] || {} ;
+    var seenRevisions = this._didChangeRevisionCache[context] || {} ;
+    var loc = keys.length ;
+    var rev = this._kvo().revision ;
+    
+    while(--loc >= 0) {
+      var key = keys[loc] ;
+      if (seenRevisions[key] != rev) {
+        var val = this.get(key) ;
+        if (seen[key] !== val) ret = true ;
+        seen[key] = val ;
+      }
+      seenRevisions[key] = rev ;
+    }
+    
+    this._didChangeCache[context] = seen ;
+    this._didChangeRevisionCache[context] = seenRevisions ;
+    return ret ;
+  },
+
+  // ..........................................
+  // PROPERTIES
+  // 
+  // Use these methods to get/set properties.  This will handle observing
+  // notifications as well as allowing you to define functions that can be 
+  // used as properties.
+
+  /**  
+    Use this to get a property value instead of obj.key.
+  */
+  get: function(key) {
+    var ret = this[key] ;
+    if (ret === undefined) {
+      return this.unknownProperty(key) ;
+    } else if (ret && (ret instanceof Function) && ret.isProperty) {
+      return ret.call(this,key) ;
+    } else return ret ;
+  },
+
+  /**  
+    use this to set a property value instead of obj.key = value.
+  */
+  set: function(key, value) {
+    var func = this[key] ;
+    var ret = value ;
+
+    this.propertyWillChange(key) ;
+
+    // set the value.
+    if (func && (func instanceof Function) && (func.isProperty)) {
+      ret = func.call(this,key,value) ;
+    } else if (func === undefined) {
+      ret = this.unknownProperty(key,value) ;
+    } else ret = this[key] = value ;
+
+    // post out notifications.
+    this.propertyDidChange(key, ret) ;
+    return ret ;
+  },  
+
+  /**  
+    use this to automatically navigate a property path.
+  */
+  getPath: function(path) {
+    var tuple = SC.Object.tupleForPropertyPath(path, this) ;
+    if (tuple[0] == null) return null ;
+    return tuple[0].get(tuple[1]) ;
+  },
+  
+  setPath: function(path, value) {
+    var tuple = SC.Object.tupleForPropertyPath(path, this) ;
+    if (tuple[0] == null) return null ;
+    return tuple[0].set(tuple[1], value) ;
+  },
+  
+  /**  
+    Increments the value of a property.
+  */
+  incrementProperty: function(key) { 
+    return this.set(key,(this.get(key) || 0)+1); 
+  },
+
+  /**  
+    decrements a property
+  */
+  decrementProperty: function(key) {
+    return this.set(key,(this.get(key) || 0) - 1 ) ;
+  },
+
+  /**  
+    inverts a property.  Property should be a bool.
+  */
+  toggleProperty: function(key,value,alt) { 
+    if (value === undefined) value = true ;
+    if (alt == undefined) alt = false ;
+    value = (this.get(key) == value) ? alt : value ;
+    this.set(key,value);
+  },
+
+  /**  
+  This is a generic property handler.  If you define it, it will be called
+  when the named property is not yet set in the object.  The default does
+  nothing.
+  */
+  unknownProperty: function(key,value) {
+    if (!(value === undefined)) { this[key] = value; }
+    return value ;
+  },
+
+  /**  
+    Override to receive generic observation notices.
+  */
+  propertyObserver: function(observer,target,key,value) {},
+
+  /**  
+    You can wrap property changes with these methods to cause notifications
+    to be delivered only after groups are closed.
+  */
+  beginPropertyChanges: function() {
+    this._kvo().changes++ ;
+  },
+
+  endPropertyChanges: function() {
+    var kvo = this._kvo() ;  kvo.changes--;
+    if (kvo.changes <= 0) this._notifyPropertyObservers() ;
+  },
+
+  /**  
+    If you are not going to use get/set, you can notify observers this way.
+  */
+  propertyWillChange: function(key) {
+    this._kvo().changes++ ;
+  },
+
+  propertyDidChange: function(key,value) {
+    this._kvo().changed[key] = value ;
+    var kvo = this._kvo() ;  kvo.changes--; kvo.revision++ ;
+    if (kvo.changes <= 0) this._notifyPropertyObservers() ;
+  },
+
+  /**  
+    This may be a simpler way to notify of changes if you are making a major
+    update or don't know exactly which properties have changed.  This ignores
+    property gorups.
+  */
+  allPropertiesDidChange: function() {
+    this._notifyPropertyObservers(true) ;
+  },
+
+  /**  
+    Add an observer
+  */
+  addObserver: function(key,func) {
+    var kvo = this._kvo() ;
+
+    // if the key contains a '.', then create a chained observer.
+    key = key.toString() ;
+    var parts = key.split('.') ;
+    if (parts.length > 1) {
+      var co = SC._ChainObserver.createChain(this,parts,func) ;
+      co.masterFunc = func ;
+      var chainObservers = kvo.chainObservers[key] || [] ;
+      chainObservers.push(co) ;
+      kvo.chainObservers[key] = chainObservers ;
+
+    // otherwise, bind as a normal property
+    } else {      
+      var observers = kvo.observers[key] = (kvo.observers[key] || []) ;
+      var found = false; var loc = observers.length;
+      while(!found && --loc >= 0) found = (observers[loc] == func) ;
+      if (!found) observers.push(func) ;
+    }
+
+  },
+
+  addProbe: function(key) { this.addObserver(key,logChange); },
+  removeProbe: function(key) { this.removeObserver(key,logChange); },
+
+  /**  
+    This method will listen for the observed value to change one time and 
+    then will remove itself.  You can also set an optional timeout that
+    will cause the function to be triggered (and the observer removed) after
+    a set amount of time even if the value never changes.  The function
+    can expect an extra parameter, 'didTimeout', set to true.
+  
+    The returned value is the function actually set as the observer. You
+    can manually remove this observer by calling the cancel() method on it.
+  */
+  observeOnce: function(key, func, timeout) {
+    var timeoutObject = null ;
+    var target = this ;
+    var handler = function(theTarget,theKey,theValue,didTimeout) {
+      func(theTarget,theKey,theValue,didTimeout) ;
+      target.removeObserver(key,handler) ;
+      if (timeoutObject) { clearTimeout(timeoutObject); }
+    } ;
+
+    target.addObserver(key,handler) ;
+    if (timeout) timeoutObject = setTimeout(function() {
+      handler(target,key,target.get(key),true) ;
+    }, timeout) ;
+
+    handler.cancel = function() { target.removeObserver(key,handler); } ;
+    return handler ;
+  },
+
+  removeObserver: function(key,func) {
+    var kvo = this._kvo() ;
+
+    // if the key contains a '.', this is a chained observer.
+    key = key.toString() ;
+    var parts = key.split('.') ;
+    if (parts.length > 1) {
+      var chainObservers = kvo.chainObserver[key] || [] ;
+      var newObservers = [] ;
+      chainObservers.each(function(co) {
+        if (co.masterFunc != func) newObservers.push(co) ;
+      }) ;
+      kvo.chainObservers[key] = newObservers ;
+
+    // otherwise, just like a normal observer.
+    } else {
+      var observers = kvo.observers[key] || [] ;
+      observers = observers.without(func) ;
+      kvo.observers[key] = observers ;
+    }
+  },
+
+  /**
+    Use this to indicate that one key changes if other keys it depends on 
+    change.
+  */  
+  registerDependentKey: function(key) {
+    var keys = $A(arguments) ;
+    var dependent = keys.shift() ;
+    var kvo = this._kvo() ;
+    for(var loc=0;loc<keys.length;loc++) {
+    	var key = keys[loc];
+    	if (key instanceof Array) {
+    		key.push(dependent) ;
+    		this.registerDependentKey.apply(this,key) ;
+    	} else {
+				var dependents = kvo.dependents[key] || [] ;
+				dependents.push(dependent) ;
+				kvo.dependents[key] = dependents ;
+    	}
+    }
+  },
+
+  // INTERNAL PROPERTY SUPPORT
+
+  // returns the kvo object.
+  _kvo: function() {
+    if (!this._kvod) this._kvod = { 
+      changes: 0, changed: {}, observers: {}, dependents: {},
+      chainObservers: {}, revision: 0
+    } ;
+    return this._kvod ;
+  },
+
+  propertyRevision: 1,
+  
+  // this is invoked when the properties changed.
+  _notifyPropertyObservers: function(allObservers) {
+    // locals
+    var key ; var observers ; var keys = [] ;
+    var loc; var oloc ; var value ;
+    var kvo = this._kvo() ;
+
+    SC.Observers.flush() ; // hookup as many observers as possible.
+
+    // increment revision
+    this.propertyRevision++;
+    
+    // find the keys to notify on.
+    var keySource = (allObservers) ? kvo.observers : kvo.changed ;
+    var allKeys = {} ;
+    
+    // This private function is used to recursively discover all 
+    // dependent keys.
+    var _addDependentKeys = function(key) {
+      if (allKeys[key] !== undefined) return ;
+      allKeys[key] = key ;
+
+      if (allObservers) return ;
+      var dependents = kvo.dependents[key] ;
+      if (dependents && dependents.length > 0) {
+        var loc = dependents.length ;
+        while(--loc >= 0) {
+          var depKey = dependents[loc] ;
+          _addDependentKeys(depKey) ;
+        }
+      }
+    } ;
+
+    // loop throught keys to notify.  find all dependent keys as well.
+    // note that this loops recursively.
+    for(key in keySource) { 
+      if (!keySource.hasOwnProperty(key)) continue ;
+      _addDependentKeys(key) ;
+    }
+
+    // Convert the found keys into an array
+    for(key in allKeys) {
+      if (!allKeys.hasOwnProperty(key)) continue ;
+      keys.push(key) ;
+    }
+    var starObservers = kvo.observers['*'] ;
+
+    // clear out changed to avoid recursion.
+    var changed = kvo.changed ; kvo.changed = {} ;
+
+    // notify all observers.
+    var target = this ; 
+    loc = keys.length ;
+    
+    var notifiedKeys = {} ; // avoid duplicates.
+    while(--loc >= 0) {
+      key = keys[loc] ; observers = kvo.observers[key] ;
+      if (!notifiedKeys[key]) {
+        notifiedKeys[key] = key ;
+        value = (allObservers || (!changed[key])) ? this.get(key) : changed[key];
+
+        if (starObservers) {
+          observers = (observers) ? observers.concat(starObservers) : starObservers ;  
+        }
+
+        if (observers) {
+          oloc = observers.length ;
+          var args = [target, key, value, this.propertyRevision] ;
+          while(--oloc >= 0) {
+            var observer = observers[oloc] ;
+            SC.NotificationQueue.add(null, observer, args) ;
+          } // while(oloc)
+        } // if (observers) 
+
+        // notify self.
+        if (this.propertyObserver != SC.Object.prototype.propertyObserver) {
+          SC.NotificationQueue.add(this, this.propertyObserver,
+            [null, target, key, value, this.propertyRevision]) ;
+        }
+      }
+
+    } // while(--loc)
+
+    SC.NotificationQueue.flush() ; 
+  }
+    
+} ;

data/frameworks/sproutcore/foundation/page.js

@@ -0,0 +1,63 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('foundation/path_module') ;
+
+/**
+  @class SC.Page
+  
+  The Page object is used to store a set of views that can be lazily 
+  configured on page load.  Page assumes that all of its properties are
+  basically outlets and will try to configure them as such.
+
+  @extends SC.Object
+*/
+SC.Page = SC.Object.extend(
+  /** @scope SC.Page.prototype */
+  {
+  
+  get: function(key) {
+    var value = this[key] ;
+    if (value && (value instanceof Function) && (value.isOutlet)) {
+      var ret = this.outlet(key) ;
+      if (SC.window && !ret.parentNode) {
+        SC.window._insertBefore(ret, null, false) ;
+        SC.window._rebuildChildNodes();
+      }
+      ret.awake() ;
+      return ret ;
+    } else return arguments.callee.base.apply(this,arguments) ;
+  },
+  
+  // in addition to activating bindings, calling awake on the page object
+  // will cause any outlet properties to be loaded.
+  awake: function() {
+    arguments.callee.base.call(this) ;
+    for(var key in this) {
+      if (this.hasOwnProperty(key) && this[key] && this[key].isOutlet) {
+        this.get(key) ; // convert to outlet.
+      } 
+    }
+  },
+  
+  init: function() {
+    arguments.callee.base.apply(this,arguments) ;
+    var el = this.rootElement = $('resources') ;
+    SC.callOnLoad(function() {
+      if (el && el.parentNode) el.parentNode.removeChild(el) ;
+    }) ;
+  },
+  
+  // returns the property, but only if it is already configured.
+  getIfConfigured: function(key) {
+    var value = this[key] ;
+    if (value && (value instanceof Function) && (value.isOutlet)) {
+      return null ;
+    } else return value ;
+  }
+  
+}) ;
+
+Object.extend(SC.Page.prototype, SC.PathModule) ;