sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

data/frameworks/sproutcore/frameworks/desktop/views/web.js

@@ -0,0 +1,86 @@
+// ==========================================================================
+// 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
+
+  Used to display an iframe. The source, (specified by the value property) of 
+  the iFrame should be from the same domain. (i.e. the src / value should be 
+  from the same domain) if you want to access the contents of the iframe.
+
+  @extends SC.View, SC.Control
+  @since SproutCore 1.0
+*/
+SC.WebView = SC.View.extend(SC.Control, {
+
+  classNames: 'sc-web-view',
+  displayProperties: ['value', 'shouldAutoResize'],
+
+  /**
+  The content of the iframe can be bigger than the size specifed when creating
+  the view. If you want the view to be auto-resized to the dimensions of the 
+  iframe, then set the value of this property to YES.
+  The web view can be auto resized only if the contents are from the same
+  domain as the parent domain.
+  @property{Boolean}
+  */
+  shouldAutoResize: NO,
+
+  render: function(context, firstTime) {
+    var src = this.get('value');
+    if (firstTime) {
+      context.push('<iframe src="' + src + 
+      '" style="position: absolute; width: 100%; height: 100%; border: 0px; margin: 0px; padding: 0p;"></iframe>');
+    } else {
+      var iframe = this.$('iframe');
+      // clear out the previous src, to force a reload
+      iframe.attr('src', 'javascript:;');
+      iframe.attr('src', src);
+    }
+  },
+
+  /**
+  Called when the layer gets created. 
+  */
+  didCreateLayer: function() {
+    var f = this.$('iframe');
+    // Attach an onload event to the iframe.
+    SC.Event.add(f, 'load', this, this.iframeDidLoad);
+  },
+
+
+  /** 
+  Called when iframe onload event is fired.
+  1. Resizes the view to fit the contents of the iframe using the 
+  scroll width and scroll height of the contents of the iframe
+  
+  The iframe contents can be accessed only when the src is from the same
+  domain as the parent document
+  @returns {void}
+  */
+  iframeDidLoad: function() {
+    //fit the iframe to size of the contents.
+    if (this.get('shouldAutoResize') === YES){
+      var contentWindow;
+      var iframeElt = this.$('iframe')[0];
+      if(iframeElt && iframeElt.contentWindow){
+        contentWindow = iframeElt.contentWindow;
+        if(contentWindow && contentWindow.document && contentWindow.document.documentElement){
+          var docElement = contentWindow.document.documentElement;
+          // setting the width before the height gives more accurate results.. 
+          // atleast for the test iframe content i'm using.
+          //TODO: try out document flows other than top to bottom.
+          if (!SC.browser.isIE){
+            this.$().width(docElement.scrollWidth);
+            this.$().height(docElement.scrollHeight);          
+          } else {
+            this.$().width(docElement.scrollWidth + 12);
+            this.$().height(docElement.scrollHeight + 5);          
+          }
+        }
+      }
+    }
+  }
+});

data/frameworks/sproutcore/frameworks/foundation/TESTING

@@ -0,0 +1,46 @@
+SproutCore Unit Testing
+
+ABOUT UNIT TESTS
+
+Unit tests are divided into two types of tests: API unit tests and integration 
+tests. API unit tests test each public method and property to ensure that the method behaves correctly according to its documentation.  Integration tests 
+spot check the way various API methods are used together to ensure they 
+function correctly in usage scenarios.
+
+Most unit tests found in the SproutCore framework are API unit tests.  
+Typically the testing directory for a framework will contain a folder 
+structure matching the framework source.  Within those folders will be one 
+folder per source class file.  Within that folder will be one test file per
+method (or groups of methods of the methods are very closely related).
+
+Integration tests, on the other hand, are all kept in the tests/integration
+folder.  Each file is named for the general type of integration scenarios 
+tested, but the structure and naming of this directory is less rigid.
+
+WHERE TO ADD NEW UNIT TESTS
+
+If you find a bug and reduce the problem down to a particular API method that
+is not responding in the way you might expect, then the best place to add a 
+test for this is in the API unit tests.  This will effectively make your unit
+test part of the API "specification" that must be satisified for all future
+releases.
+
+Often times, however, you will find bugs that are not due to a particular 
+method behaving badly but is due to a problem that occurs when you use a 
+series of API methods together in a certain way.  For these kinds of tests
+you should add a test to the integration directory.  If one of the existing
+files makes sense for your scenario, add it there.  Otherwise, create a new
+test file and add it there.
+
+HOW TO WRITE API UNIT TESTS VS INTEGRATION
+
+The purpose of an API unit test is to excercise individual methods in the API
+in isolation of the rest of the API.  You should swap out methods, mock objects, or make any other temporary modifications to the framework needed to
+make the method run as isolated as possible from other methods.
+
+Integration tests, on the other hand, are about testing API usage in place.
+Avoid mocking parts of the framework unless necessary.  Try to run the 
+framework code in its natural state to ensure the full stack is excercised 
+just as it would be in production code.
+
+

data/frameworks/sproutcore/frameworks/foundation/controllers/array.js

@@ -0,0 +1,509 @@
+// ========================================================================
+// SproutCore -- JavaScript Application Framework
+// Copyright ©2006-2008, Sprout Systems, Inc. and contributors.
+// Portions copyright ©2008 Apple, Inc.  All rights reserved.
+// ========================================================================
+
+require('controllers/controller');
+require('mixins/selection_support');
+
+/**
+  @class
+
+  An ArrayController provides a way for you to publish an array of objects
+  for CollectionView or other controllers to work with.  To work with an 
+  ArrayController, set the content property to the array you want the 
+  controller to manage.  Then work directly with the controller object as if
+  it were the array itself.
+  
+  When you want to display an array of objects in a CollectionView, bind the
+  "arrangedObjects" of the array controller to the CollectionView's "content"
+  property.  This will automatically display the array in the collection view.
+
+  @extends SC.Controller
+  @extends SC.Array
+  @extends SC.SelectionSupport
+  @author Charles Jolley
+  @since SproutCore 1.0
+*/
+SC.ArrayController = SC.Controller.extend(SC.Array, SC.SelectionSupport,
+/** @scope SC.ArrayController.prototype */ {
+
+  // ..........................................................
+  // PROPERTIES
+  // 
+  
+  /**
+    The content array managed by this controller.  
+    
+    You can set the content of the ArrayController to any object that 
+    implements SC.Array or SC.Enumerable.  If you set the content to an object
+    that implements SC.Enumerable only, you must also set the orderBy property
+    so that the ArrayController can order the enumerable for you.
+    
+    If you set the content to a non-enumerable and non-array object, then the
+    ArrayController will wrap the item in an array in an attempt to normalize
+    the result.
+    
+    @type SC.Array
+  */
+  content: null,
+
+  /**
+    Makes the array editable or not.  If this is set to NO, then any attempts
+    at changing the array content itself will throw an exception.
+    
+    @property
+    @type Boolean
+  */
+  isEditable: YES,
+  
+  /**
+    Used to sort the array.
+    
+    If you set this property to a key name, array of key names, or a function,
+    then then ArrayController will automatically reorder your content array
+    to match the sort order.  (If you set a function, the function will be
+    used to sort).
+
+    Normally, you should only use this property if you set the content of the
+    controller to an unordered enumerable such as SC.Set or SC.SelectionSet.
+    In this case the orderBy property is required in order for the controller
+    to property order the content for display.
+    
+    If you set the content to an array, it is usually best to maintain the 
+    array in the proper order that you want to display things rather than 
+    using this method to order the array since it requires an extra processing
+    step.  You can use this orderBy property, however, for displaying smaller 
+    arrays of content.
+    
+    Note that you can only to use addObject() to insert new objects into an
+    array that is ordered.  You cannot manually reorder or insert new objects
+    into specific locations because the order is managed by this property 
+    instead.
+    
+    If you pass a function, it should be suitable for use in compare().
+    
+    @property
+    @type String|Array|Function
+  */
+  orderBy: null,
+    
+  /**
+    Set to YES if you want the controller to wrap non-enumerable content    
+    in an array and publish it.  Otherwise, it will treat single content like 
+    null content.
+    
+    @property
+    @type Boolean
+  */
+  allowsSingleContent: YES,
+  
+  /**
+    Set to YES if you want objects removed from the array to also be
+    deleted.  This is a convenient way to manage lists of items owned
+    by a parent record object.
+    
+    Note that even if this is set to NO, calling destroyObject() instead of
+    removeObject() will still destroy the object in question as well as 
+    removing it from the parent array.
+    
+    @type {Boolean}
+  */
+  destroyOnRemoval: NO,
+
+  /**
+    Returns an SC.Array object suitable for use in a CollectionView.  
+    Depending on how you have your ArrayController configured, this property
+    may be one of several different values.  
+    
+    @property
+    @type SC.Array
+  */
+  arrangedObjects: function() {
+    return this;
+  }.property().cacheable(),
+  
+  /**
+    Computed property indicates whether or not the array controller can 
+    remove content.  You can delete content only if the content is not single
+    content and isEditable is YES.
+    
+    @property
+    @type Boolean
+  */
+  canRemoveContent: function() {
+    var content = this.get('content'), ret;
+    ret = !!content && this.get('isEditable') && this.get('hasContent');
+    if (ret) {
+      return !content.isEnumerable || 
+             (SC.typeOf(content.removeObject) === SC.T_FUNCTION);
+    } else return NO ;
+  }.property('content', 'isEditable', 'hasContent'),
+  
+  /**
+    Computed property indicates whether you can reorder content.  You can
+    reorder content as long a the controller isEditable and the content is a
+    real SC.Array-like object.  You cannot reorder content when orderBy is
+    non-null.
+    
+    @property
+    @type Boolean
+  */
+  canReorderContent: function() {
+    var content = this.get('content'), ret;
+    ret = !!content && this.get('isEditable') && !this.get('orderBy');
+    return ret && !!content.isSCArray;
+  }.property('content', 'isEditable', 'orderBy'),
+  
+  /**
+    Computed property insides whether you can add content.  You can add 
+    content as long as the controller isEditable and the content is not a 
+    single object.
+    
+    Note that the only way to simply add object to an ArrayController is to
+    use the addObject() or pushObject() methods.  All other methods imply 
+    reordering and will fail.
+    
+    @property
+    @type Boolean
+  */
+  canAddContent: function() {
+    var content = this.get('content'), ret ;
+    ret = content && this.get('isEditable') && content.isEnumerable;
+    if (ret) {
+      return (SC.typeOf(content.addObject) === SC.T_FUNCTION) || 
+             (SC.typeOf(content.pushObject) === SC.T_FUNCTION); 
+    } else return NO ;
+  }.property('content', 'isEditable'),
+  
+  /**
+    Set to YES if the controller has valid content that can be displayed,
+    even an empty array.  Returns NO if the content is null or not enumerable
+    and allowsSingleContent is NO.
+    
+    @property
+    @type Boolean
+  */
+  hasContent: function() {
+    var content = this.get('content');
+    return !!content && 
+           (!!content.isEnumerable || !!this.get('allowsSingleContent'));
+  }.property('content', 'allowSingleContent'),
+
+  /**
+    The current load state of the RecordArray.  If the storeKeys has a state
+    property, then this property will return that value.  Otherwise it returns
+    SC.Record.READY.
+  */
+  state: function() {
+    var content = this.get('content'),
+        ret = content ? content.get('state') : null;
+    return ret ? ret : SC.Record.READY;
+  }.property().cacheable(),
+  
+  // ..........................................................
+  // METHODS
+  // 
+  
+  /**
+    Adds an object to the array.  If the content is ordered, this will add the 
+    object to the end of the content array.  The content is not ordered, the
+    location depends on the implementation of the content.
+    
+    If the source content does not support adding an object, then this method 
+    will throw an exception.
+    
+    @param {Object} object the object to add
+    @returns {SC.ArrayController} receiver
+  */
+  addObject: function(object) {
+    if (!this.get('canAddContent')) throw "%@ cannot add content".fmt(this);
+    
+    var content = this.get('content');
+    if (content.isSCArray) content.pushObject(object);
+    else if (content.addObject) content.addObject(object);
+    else throw "%@.content does not support addObject".fmt(this);
+    
+    return this;
+  },
+  
+  /**
+    Removes the passed object from the array.  If the underyling content 
+    is a single object, then this simply sets the content to null.  Otherwise
+    it will call removeObject() on the content.
+    
+    Also, if destroyOnRemoval is YES, this will actually destroy the object.
+    
+    @param {Object} object the object to remove
+    @returns {SC.ArrayController} receiver
+  */
+  removeObject: function(object) {
+    if (!this.get('canRemoveContent')) {
+      throw "%@ cannot remove content".fmt(this);
+    }
+    
+    var content = this.get('content');
+    if (content.isEnumerable) content.removeObject(object);
+    else {
+      this.set('content', null);
+      this.enumerableContentDidChange();
+    }
+    
+    if (this.get('destroyOnRemoval') && object.destroy) object.destroy();
+    return this; 
+  },
+  
+  // ..........................................................
+  // SC.ARRAY SUPPORT
+  // 
+
+  /**
+    Compute the length of the array based on the observable content
+  */
+  length: function() {
+    var content = this._scac_observableContent();
+    return content ? content.get('length') : 0;
+  }.property().cacheable(),
+
+  /**
+    Returns the object at the specified index based on the observable content
+  */
+  objectAt: function(idx) {
+    var content = this._scac_observableContent();
+    return content ? content.objectAt(idx) : undefined ;    
+  },
+  
+  /**
+    Forwards a replace on to the content, but only if reordering is allowed.
+  */
+  replace: function(start, amt, objects) {
+    // check for various conditions before a replace is allowed
+    if (!objects || objects.get('length')===0) {
+      if (!this.get('canRemoveContent')) {
+        throw "%@ cannot remove objects from the current content".fmt(this);
+      }
+    } else if (!this.get('canReorderContent')) {
+      throw "%@ cannot add or reorder the current content".fmt(this);
+    }    
+    
+    // if we can do this, then just forward the change.  This should fire
+    // updates back up the stack, updating rangeObservers, etc.
+    var content = this.get('content'); // note: use content, not observable
+    var objsToDestroy = [], i;
+    if (this.get('destroyOnRemoval')){
+      for(i=0; i<amt; i++){
+        objsToDestroy.push(content.objectAt(i+start));
+      }
+    }
+    
+    if (content) content.replace(start, amt, objects);
+    for(i=0; i<objsToDestroy.length; i++){
+      
+      objsToDestroy[i].destroy();
+    }
+    objsToDestroy = null;
+    
+    return this; 
+  },
+  
+  // ..........................................................
+  // INTERNAL SUPPORT
+  // 
+  
+  init: function() {
+    sc_super();
+    this._scac_contentDidChange();
+  },
+  
+  /** @private
+    Cached observable content property.  Set to NO to indicate cache is 
+    invalid.
+  */
+  _scac_cached: NO,
+  
+  /**
+    @private
+    
+    Returns the current array this controller is actually managing.  Usually
+    this should be the same as the content property, but sometimes we need to
+    generate something different because the content is not a regular array.
+    
+    Passing YES to the force parameter will force this value to be recomputed.
+  
+    @returns {SC.Array} observable or null
+  */
+  _scac_observableContent: function() {
+    var ret = this._scac_cached;
+    if (ret !== NO) return ret;
+    
+    var content = this.get('content'),
+        orderBy, func, t, len;
+    
+    // empty content
+    if (SC.none(content)) return this._scac_cached = [];
+
+    // wrap non-enumerables
+    if (!content.isEnumerable) {
+      ret = this.get('allowsSingleContent') ? [content] : [];
+      return (this._scac_cached = ret);
+    } 
+    
+    // no-wrap
+    orderBy = this.get('orderBy');
+    if (!orderBy) {
+      if (content.isSCArray) return (this._scac_cached = content) ;
+      else throw "%@.orderBy is required for unordered content".fmt(this);     
+    }
+    
+    // all remaining enumerables must be sorted.
+    
+    // build array - then sort it
+    switch(SC.typeOf(orderBy)) {
+    case SC.T_STRING:
+      orderBy = [orderBy];
+      break;
+    case SC.T_FUNCTION:
+      func = orderBy ;
+      break;
+    case SC.T_ARRAY:
+      break;
+    default:
+      throw "%@.orderBy must be Array, String, or Function".fmt(this);
+    }
+    
+    len = orderBy.get('length');
+    
+    // generate comparison function if needed - use orderBy
+    if (!func) {
+      func = function(a,b) {
+        var idx=0, status=0, key, aValue, bValue;
+        for(idx=0;(idx<len)&&(status===0);idx++) {
+          key = orderBy.objectAt(idx);
+        
+          if (!a) aValue = a ;
+          else if (a.isObservable) aValue = a.get(key);
+          else aValue = a[key];
+
+          if (!b) bValue = b ;
+          else if (b.isObservable) bValue = b.get(key);
+          else bValue = b[key];
+        
+          status = SC.compare(aValue, bValue);
+        }
+        return status ; 
+      };
+    }
+
+    ret = [];
+    content.forEach(function(o) { ret.push(o); });
+    ret.sort(func);
+    
+    func = null ; // avoid memory leaks
+    return (this._scac_cached = ret) ;
+  },
+  
+  /**
+    Whenever content changes, setup and teardown observers on the content
+    as needed.
+  */
+  _scac_contentDidChange: function() {
+
+    this._scac_cached = NO; // invalidate observable content
+    
+    var cur    = this.get('content'),
+        orders = !!this.get('orderBy'),
+        last   = this._scac_content,
+        oldlen = this._scac_length || 0,
+        ro     = this._scac_rangeObserver,
+        func   = this._scac_rangeDidChange,
+        efunc  = this._scac_enumerableDidChange,
+        sfunc  = this._scac_contentStateDidChange,
+        newlen;
+        
+    if (last === cur) return this; // nothing to do
+
+    // teardown old observer
+    if (last) {
+      if (ro && last.isSCArray) last.removeRangeObserver(ro);
+      else if (last.isEnumerable) last.removeObserver('[]', this, efunc);
+      last.removeObserver('state', this, sfunc);
+    }
+    
+    ro = null;
+    
+    // save new cached values 
+    this._scac_cached = NO;
+    this._scac_content = cur ;
+    
+    // setup new observers
+    // also, calculate new length.  do it manually instead of using 
+    // get(length) because we want to avoid computed an ordered array.
+    if (cur) {
+      if (!orders && cur.isSCArray) ro = cur.addRangeObserver(null,this,func);
+      else if (cur.isEnumerable) cur.addObserver('[]', this, efunc);
+      newlen = cur.isEnumerable ? cur.get('length') : 1; 
+      cur.addObserver('state', this, sfunc);
+      
+    } else newlen = SC.none(cur) ? 0 : 1;
+
+    this._scac_rangeObserver = ro;
+    
+
+    // finally, notify enumerable content has changed.
+    this._scac_length = newlen;
+    this._scac_contentStateDidChange();
+    this.enumerableContentDidChange(0, newlen, newlen - oldlen);
+    this.updateSelectionAfterContentChange();
+  }.observes('content'),
+  
+  /**
+    Whenever enumerable content changes, need to regenerate the 
+    observableContent and notify that the range has changed.  
+    
+    IMPORTANT: Assumes content is not null and is enumerable
+  */
+  _scac_enumerableDidChange: function() {
+    var content = this.get('content'), // use content directly
+        newlen  = content.get('length'),
+        oldlen  = this._scac_length;
+        
+    this._scac_length = newlen;
+    this.beginPropertyChanges();
+    this._scac_cached = NO; // invalidate
+    this.enumerableContentDidChange(0, newlen, newlen-oldlen);
+    this.endPropertyChanges();
+    this.updateSelectionAfterContentChange();
+  },
+  
+  /**
+    Whenever array content changes, need to simply forward notification.
+    
+    Assumes that content is not null and is SC.Array.
+  */
+  _scac_rangeDidChange: function(array, objects, key, indexes) {
+    if (key !== '[]') return ; // nothing to do
+    
+    var content = this.get('content');
+    this._scac_length = content.get('length');
+    this._scac_cached = NO; // invalidate
+    
+    // if array length has changed, just notify every index from min up
+    if (indexes) {
+      this.beginPropertyChanges();
+      indexes.forEachRange(function(start, length) {
+        this.enumerableContentDidChange(start, length, 0);
+      }, this);
+      this.endPropertyChanges();
+      this.updateSelectionAfterContentChange();
+    }
+  },
+  
+  /**
+    Whenver the content "state" property changes, relay out.
+  */
+  _scac_contentStateDidChange: function() {
+    this.notifyPropertyChange('state');
+  }
+  
+});