sproutcore 0.9.0

data/frameworks/sproutcore/controllers/collection.js

@@ -0,0 +1,305 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('controllers/object') ;
+
+/** @class
+
+  A CollectionController works just like an ObjectController except that
+  it includes support for a few extra items including the arrangedObjects
+  property (which may have a filter applied), and a selection.
+
+  This expects the content object to be a Collection object.
+
+  @extends SC.ObjectController
+*/
+SC.CollectionController = SC.ObjectController.extend(
+  /** @scope SC.CollectionController.prototype */
+  {
+
+  // ...................................
+  // PROPERTIES
+  //
+
+  /**
+    This is the current set of objects for the UI.
+    
+    @type Array
+  */
+  arrangedObjects: [],
+  
+  /**  
+    @property {Array} selection 
+    This is the current selection.  You can make this selection and another
+    controller's selection work in concert by binding them together. You
+    generally have a master selection that relays changes TO all the others.
+  */
+  selection: function(key,value)
+  {
+    if (value !== undefined)
+    {
+      // selection must be an array... force if needed....
+      value = (value) ? ((value instanceof Array) ? value : [value]) : [];
+      
+      var allowsSelection         = this.get('allowsSelection');
+      var allowsEmptySelection    = this.get('allowsEmptySelection');
+      var allowsMultipleSelection = this.get('allowsMultipleSelection');
+      
+      // are we even allowing selection at all?
+      // if not, then bail out.
+      if ( !allowsSelection ) return this._selection;
+      
+      // ok, new decide if the *type* of seleciton is allowed...
+      switch ( value.length )
+      {
+        case 0:
+          // check to see if we're attemting to set an empty array
+          // if that's not allowed, set to the first available item in arrangedObjects
+          this._selection = allowsEmptySelection ? value : (this.get('arrangedObjects') || []).first();
+          break;
+        case 1:
+          // check to see id we've just taken focus away from a new record
+          // if so, queue up the callback to be triggered...
+          if ( this._editingNewRecord && (this._editingNewRecord != value[0]) )
+          {
+            setTimeout(this._newRecordDidLoseFocus.bind(this,this._editingNewRecord),1);
+            this._editingNewRecord = null;
+          }
+          this._selection = value;
+          break;
+        default:
+          // fall through for >= 2 items...
+          // only allow if configured for multi-select
+          this._selection = allowsMultipleSelection ? value : this._selection;
+          break;
+      }
+      
+      if ( this._selection && (this._selection.length > 1) )
+      {
+        var collection = this.get('content');
+        var order = collection ? collection.get('orderBy') : null;
+        if ( !order ) order = ['guid'];
+        this._selection = this._selection.sort(function(a,b) { return a.compareTo(b,order); });
+      }
+    }
+    
+    return this._selection;
+  }.property(),
+  
+  /**
+    If true, selection is allowed.
+
+    @type bool
+  */
+  allowsSelection: true,
+  
+  /**
+    If true, multiple selection is allowed.
+  
+    @type bool
+  */
+  allowsMultipleSelection: true,
+  
+  /**
+    If true, allow empty selection
+  
+    @type bool
+  */
+  allowsEmptySelection: true,
+  
+  /**
+    If true, new, add, remove will work.
+  
+    @type bool
+  */
+  canEditCollection: false,
+
+  /**
+    Set to the total number of items to show on a single page.  If set to
+    zero, then no pagination will be performed.
+  
+    @type number
+  */
+  pageSize: 0,
+  
+  /**
+    [RO] read only property with the current total number of pages.
+  */
+  pageCount: function() {
+    var pageSize = this.get('pageSize') ;
+    if (pageSize <= 0) return 1 ;
+    
+    var content = this.get('content') ;
+    var count = (content && content.get) ? content.get('count') : 0 ;
+    if (count === null) count = 0 ;
+    return Math.ceil(count / pageSize) ;
+  }.property(),
+  
+  /**
+    Set to the current page.  This will change the offset and limit shown in
+    the collection.  If you try to set the page to a number greater than the
+    maximum, then it will be set to the last page.
+  */
+  currentPage: function(key, value) {
+    if (value !== undefined) {
+      // constrain pages.
+      if (this._currentPage != value) {
+        var pc = Math.max(this.get('pageCount')-1,0);
+        if (value > pc) value = pc ;
+        if (value < 0) value = 0 ;
+        this._currentPage = value ;
+      }
+    }
+    return this._currentPage || 0 ;  
+  }.property(),
+  
+  // ...................................
+  // METHODS
+  //
+
+  // adds a new object to the current collection, if allowed, and sets it
+  // as the current selection.
+  newObject: function(settings) {
+    var content = this.get('content') ;
+    if (!content || !this.get('canEditCollection')) return ; // only if allowed 
+    try {
+      if (content.newRecord) { 
+        var rec = content.newRecord(settings) ;
+        var controller = this ;
+        setTimeout(function() {
+          controller.set('selection',(rec) ? [rec] : []) ;
+          controller._editingNewRecord = rec ;
+        },1) ;
+        return rec;
+      }
+    }   
+    catch (e) {
+      // DO SOMETHING
+    }
+  },
+
+  addObjects: function(objects) {
+    var content = this.get('content') ;
+    if (!content || !this.get('canEditCollection')) return ; // only if allowed 
+    try {
+      objects = $A(arguments).flatten() ;
+      if (content.addRecords) { 
+        content.addRecords(objects) ;
+        this.set('selection',(objects) ? objects : []) ;
+      }
+    }   
+    catch (e) {
+      // DO SOMETHING
+    }
+  },
+  
+  addSelection: function() { 
+    return this.addObjects(this.get('selection'));
+  },
+  
+  // adds a new object to the current collection, if allowed, and sets it
+  // as the current selection.
+  removeObjects: function(objects) {
+    var content = this.get('content') ;
+    if (!content || !this.get('canEditCollection')) return ; // only if allowed 
+    try {
+      objects = $A(arguments).flatten() ;
+      if (content.removeRecords) { 
+        var rec = content.removeRecords(objects) ;
+        var sel = (this.get('selection') || []).without(objects) ;
+        this.set('selection',(sel) ? sel : []) ;
+      }
+    }   
+    catch (e) {
+      // DO SOMETHING
+    }
+  },
+
+  removeSelection: function() {
+    return this.removeObjects(this.get('selection')) ;
+  },
+
+  // this method is called if a new object was created through the controller
+  // and then the selection was changed from the new record without the 
+  // record being saved first.  By default, this will remove the object, but
+  // you could override it to just do a commit.
+  newObjectDidLoseFocus: function(rec) { rec.destroy() ; },
+  
+  // ...................................
+  // PRIVATE
+  //
+  
+  _newRecordDidLoseFocus: function(rec) {
+    if (rec.get('newRecord')) this.newObjectDidLoseFocus(rec) ;
+  },
+  
+  // Update the current page.
+  _pageObserver: function() {
+    // get content -- nothing to do if no content.
+    var content = this.get('content') ; 
+    if (content instanceof Array) content = content[0] ;
+    if (!content) return ; 
+    
+    var curOffset = content.get('offset') || 0 ;
+    var curLimit = content.get('limit') || 0 ;
+    var count = content.get('count') || 0 ;
+
+    // calculate the offset and limit.
+    var currentPage = this.get('currentPage') ;
+    var pageSize = this.get('pageSize') ;
+    var newOffset, newLimit ;
+    if (pageSize == 0) {
+      newOffset = 0; newLimit = 0 ;
+    } else {
+      newOffset = currentPage * pageSize ;
+      newLimit = pageSize ;      
+    }
+    
+    // set new page info.
+    if ((newOffset != curOffset) || (newLimit != curLimit)) {
+      content.beginPropertyChanges() ;
+      content.set('offset',newOffset) ;
+      content.set('limit',newLimit) ;
+      content.endPropertyChanges() ;
+    }    
+  }.observes('currentPage','pageCount','pageSize'),
+  
+  // invoked whenever the list changes.  Updated the arrangedObjects and
+  // potentially the selection.
+  _recordsObserver: function(target,key,value) {
+    var old = this.get('arrangedObjects') ;
+    value = Array.asArray(target.get(key)) ;
+    
+    this.set('arrangedObjects',value.slice()) ;
+    // update selection.
+    var objects = this.get('arrangedObjects') || [] ;
+    if (!(objects instanceof Array)) objects = [objects] ;
+    
+    var currentSelection = this.get('selection') || [] ;
+    var sel = [] ;
+
+    // the new selection is the current selection that exists in 
+    // arrangedObjects.
+    currentSelection.each(function(obj) {
+      if (objects.include(obj)) sel.push(obj) ;
+    }) ;
+    
+    // make new selection match current selection settings.
+    if (!this.allowsSelection) {
+      sel = [] ;
+    }
+    
+    if ((sel.length>1) && !this.allowsMultipleSelection) {
+      sel = [sel[0]] ;
+    }
+    
+    if ((sel.length == 0) && !this.allowsEmptySelection) {
+      if (objects.length > 0) sel = [objects[0]] ;
+    }
+    
+    this.set('selection',sel) ;
+  }.observes('records') 
+  
+}) ;

data/frameworks/sproutcore/controllers/controller.js

@@ -0,0 +1,323 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('foundation/object') ;
+
+/** 
+  @class   SC.Controller
+
+  The controller base class provides some common functions you will need
+  for controllers in your applications, especially related to maintaining
+  an editing context.
+
+  In general you will not use this class, but you can use a subclass such
+  as ObjectController, CollectionController, or ArrayController.
+
+  h2. EDITING CONTEXTS
+  
+  One major function of a controller is to mediate between changes in the
+  UI and changes in the model.  In particular, you usually do not want 
+  changes you make in the UI to be applied to a model object directly.  
+  Instead, you often will want to collect changes to an object and then
+  apply them only when the user is ready to commit their changes.
+
+  The editing contact support in the controller class will help you
+  provide this capability.
+  
+  @extends SC.Object
+*/
+SC.Controller = SC.Object.extend(
+  /** @scope SC.Controller.prototype  */
+  {  
+  
+  /**
+    The controller will set this property to true whenever there are 
+    changes that need to be committed.  This property is true whenever
+    the controller itself has uncommitted changes or when any dependent
+    editors have uncommitted changes.  In your own subclass, call 
+    this.objectDidChange(this) to register changes.
+
+    @type Boolean
+  */
+  hasChanges: false,
+  
+  /**
+    This is the controller's parent controller usually.  The controller will
+    notify this controller when its changes are committed or discarded.
+
+    @type SC.Controller
+  */
+  context: null,
+  
+  /**
+    If this is false, then the controller will only commit changes when you
+    explicitly call commitChanges.  Otherwise it will commit them
+    immediately.  You usually want this set to false.  It is initially set to
+    true for compatibility.
+
+    @type Boolean
+  */
+  commitChangesImmediately: true,
+  
+  /**
+  * Sets the commitChangesImmediately to the parent context's value if a context was passed.
+  * The Controller also observes changes to the context property and adjusts the commitChangesImmediately prop
+  */
+  init: function()
+  {
+    arguments.callee.base.apply(this,arguments);
+    this._contextObserver();
+  },
+  
+  /**
+  * @private
+  */
+  _contextObserver: function()
+  {
+    if ( this.context )
+    {
+      // inherit the parent contexts inherit property
+      this.commitChangesImmediately = this.context.commitChangesImmediately;
+    }
+  }.observes('context'),
+  
+  /**
+    If the controller has uncommitted changes, call this method to 
+    commit them.  This method will commit the changes for any dependent
+    editors as well.  This will return true if the commit completed and 
+    false or an error object if it failed.
+  */
+  commitChanges: function() {
+    this._commitTimeout = null ; // clear timeout 
+    var ret = this._canCommitChanges() ;
+    if (!$ok(ret)) return ret ;
+    return this._performCommitChanges() ;
+  },
+  
+  /**
+    If this controller has uncommitted changes that you do not want to keep,
+    call this method to discard them.  This method will also discard 
+    changes for any dependent editors as well.
+  */
+  discardChanges: function() {
+    var ret = this._canDiscardChanges() ;
+    if (!$ok(ret)) return ret ;
+    return this._performDiscardChanges() ;
+  },
+  
+  /**
+    This method will return an appropriate controller object for the 
+    value of the property you name.  This will return one of:
+  
+    <table>
+    <tr> <th>Value Type</th>        <th>Returns</th> </tr>
+    <tr> <td>Array-compatible</td>  <td>SC.ArrayController</td></tr>
+    <tr> <td>SC.Collection</td>     <td>SC.CollectionController</td></tr>
+    <tr> <td>Kind of SC.Object</td> <td>SC.ObjectController</td></tr>
+    <tr> <td>other</td>             <td>value</td></tr>
+    </table>
+  
+    This is a helper method used by subclasses to create the appropriate 
+    type of controller.
+  
+  */
+  controllerForValue: function(value) {
+    var ret = null ;
+    switch($type(value)) {
+      case T_OBJECT:
+        if (value.kindOf(SC.Collection)) {
+          ret = SC.CollectionController ;          
+        } else ret = SC.ObjectController ;
+        break ;
+      case T_ARRAY:
+        ret = SC.ArrayController ;
+        break ;
+      default:
+        ret = null ;
+    }
+    
+    return (ret) ? ret.create({ content: value, context: this }) : value;
+  },
+  
+  /**
+    Call this method whenever you have uncommitted changes.  This will
+    handle notifying your parent context as well.
+  
+    @param {SC.Controller} editor 
+      This is the object that has uncommitted changes.  Normally you should 
+      not pass a value.  If you do pass an object, then that object will  
+      become a dependent editor of the receiver.
+  */
+  editorDidChange: function(editor) {
+    if (!editor) editor = this ; // set default value
+    
+    // if this is another editor, add it to the list of editors that need
+    // to be notified of a change.
+    if (editor != this) {
+      if (!this._dirtyEditors) this._dirtyEditors = SC.Set.create();
+      this._dirtyEditors.add(editor) ;
+    } else {
+      this._hasLocalChanges = true ;
+    }
+    if (!this.get('hasChanges')) {
+      this.set('hasChanges', true) ;
+      
+      // if we have a parent context notify them
+      if (this.context) {
+        this.context.editorDidChange(this) ; 
+        
+      // otherwise, if commit changes immediately is true, schedule commit.
+      // commit is only done once per cycle so that at least all the
+      // changes you might make at one time will be batched.
+      } else if (this.get('commitChangesImmediately')) {
+        if (!this._commitTimeout) {
+          this._commitTimeout = this.commitChanges.bind(this).defer();
+        }
+      }
+    }
+  },
+  
+  /**
+    Call this method when your object no longer has uncommitted changes.
+    This will clear your hasChanges property and notify your parent context.
+    This is called automatically whenever changes are committed or discarded
+    on your controller.
+  */  
+  editorDidClearChanges: function(editor) {
+    if (!editor) editor = this ; // set default value
+    
+    if (editor != this) {
+      // if we are currently clearing changes, then we will clean up the
+      // hasChanges state and dirtyeditors in bulk when this is all done.
+      // so do nothing.
+      if (this._clearingChanges) return ;
+      if (this._dirtyEditors) this._dirtyEditors.remove(editor) ;
+    } else {
+      this._hasLocalChanges = false ;
+    }
+    
+    // _dirtyEditors may be undefined so use !! to force this to a bool value.
+    var hasChanges = !!(this._hasLocalChanges || (this._dirtyEditors && this._dirtyEditors.length > 0)) ;
+    
+    if (this.get('hasChanges') != hasChanges) {
+      this.set('hasChanges', hasChanges) ;
+      if (this.context) this.context.editorDidClearChanges(editor) ;
+    }
+  },
+  
+  /**
+    Override this method to determine if your controller can commit the
+    changes.  This should validate your changes.  Return false or an error
+    object if you cannot commit the change.  This method will not be called
+    unless hasChanges is true and all your dependent editors are return
+    true as well.
+  */  
+  canCommitChanges: function() {
+    return true ;
+  },
+  
+  /**
+    Override this method to actually commit the changes for your controller.
+    This will only be called if all controllers indicate that they can
+    commit.  Return true if you succeeded or false or an error if you failed.
+  */
+  performCommitChanges: function() {
+    return $error('performCommitChanges is not implemented') ;
+  },
+  
+  /**
+    Override this method to determine if your controller can discard the 
+    changes it has built up.  This method will not be called unless you
+    have set hasChanges to true.  Return false or an error object if you
+    cannot discard the change.
+  */
+  canDiscardChanges: function() {
+    return true ;
+  },
+  
+  /**
+    Override this method to actually discard the changes for your controller.
+    This will only be called if all controllers indicate that they can discard
+    their changes.  Return true if you succeed or false or an error if you 
+    failed.
+  */
+  performDiscardChanges: function() {
+    return $error('performDiscardChanges is not implemented');
+  },
+  
+  // ....................................
+  // PRIVATE
+  
+  _canCommitChanges: function() {
+    if (!this.get('hasChanges')) return false ;
+    
+    // validate editors.
+    var ret = true ;
+    if (this._dirtyEditors) {
+      ret = this._dirtyEditors.invokeWhile(true, '_canCommitChanges') ;
+      if (!$ok(ret)) return ret ;
+    }
+    
+    // then validate receiver
+    return this.canCommitChanges() ;
+  },
+  
+  _performCommitChanges: function() {
+    if (!this.get('hasChanges')) return true ;
+    
+    // first commit any editors.  If not successful, return. otherwise,
+    // clear editors.
+    var ret = true ;
+    if (this._dirtyEditors) {
+      this._clearingChanges = true ;
+      ret = this._dirtyEditors.invokeWhile(true, '_performCommitChanges') ;
+      this._clearingChanges = false ;
+      
+      if ($ok(ret)) {
+        this._dirtyEditors = null ;
+      } else return ret ;
+    }
+
+    // now commit changes for the receiver.
+    ret = this.performCommitChanges() ;
+    if ($ok(ret)) this.editorDidClearChanges() ;
+    return ret ;
+  },
+
+  _canDiscardChanges: function() {
+    if (!this.get('hasChanges')) return false ;
+    // validate editors.
+    var ret = true ;
+    if (this._dirtyEditors) {
+      ret = this._dirtyEditors.invokeWhile(true, '_canDiscardChanges') ;
+      if (!$ok(ret)) return ret ;
+    }
+    
+    // then validate receiver
+    return this.canDiscardChanges() ;
+  },
+  
+  _performDiscardChanges: function() {
+    if (!this.get('hasChanges')) return true ;
+    
+    // first discard changes for any editors.  If not successful, return. 
+    // otherwise, clear editors.
+    var ret = true ;
+    if (this._dirtyEditors) {
+      this._clearingChanges = true ;
+      ret = this._dirtyEditors.invokeWhile(true, '_performDiscardChanges') ;
+      this._clearingChanges = false ;
+      if ($ok(ret)) {
+        this._dirtyEditors = null ;
+      } else return ret ;
+    }
+    
+    // now discard changes for the receiver.
+    ret = this.performDiscardChanges() ;
+    if ($ok(ret)) this.editorDidClearChanges() ;
+    return ret ;
+  }
+  
+}) ;