sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

data/frameworks/sproutcore/frameworks/foundation/mixins/selection_support.js

@@ -0,0 +1,232 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+/**
+  @namespace
+  
+  Implements common selection management properties for controllers.
+  
+  Selection can be managed by any controller in your applications.  This
+  mixin provides some common management features you might want such as
+  disabling selection, or restricting empty or multiple selections.
+  
+  To use this mixin, simply add it to any controller you want to manage 
+  selection and call updateSelectionAfterContentChange()
+  whenever your source content changes.  You can also override the properties
+  defined below to configure how the selection management will treat your 
+  content.
+  
+  This mixin assumes the arrangedObjects property will return an SC.Array of 
+  content you want the selection to reflect.
+  
+  Add this mixin to any controller you want to manage selection.  It is 
+  already applied to the CollectionController and ArrayController.
+  
+  @author Charles Jolley
+  @author Erich Ocean
+  @version 1.0
+  @since 0.9
+*/
+SC.SelectionSupport = {
+  
+  // ..........................................................
+  // PROPERTIES
+  // 
+  
+  hasSelectionSupport: YES,
+  
+  /**
+    If YES, selection is allowed. Default is YES.
+    
+    @type Boolean
+  */
+  allowsSelection: YES,
+  
+  /**
+    If YES, multiple selection is allowed. Default is YES.
+    
+    @type Boolean
+  */
+  allowsMultipleSelection: YES,
+  
+  /**
+    If YES, allow empty selection Default is YES.
+    
+    @type Boolean
+  */
+  allowsEmptySelection: YES,
+  
+  /**
+    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.
+    
+    @property
+    @type SC.SelectionSet
+  */
+  selection: function(key, value) {
+    var content, empty;
+    
+    if (value !== undefined) {
+      
+      // are we even allowing selection at all?  Also, must be enumerable
+      if (this.get('allowsSelection') && value && value.isEnumerable) {
+        
+        // ok, new decide if the *type* of selection is allowed...
+        switch (value.get('length')) {
+          
+          // check to see if we're attempting to set an empty array
+          // if that's not allowed, set to the first available item in 
+          // arrangedObjects
+          case 0:
+            empty   = this.get('allowsEmptySelection');
+            content = this.get('arrangedObjects');
+            if (empty && content && content.get('length')>0) {
+                value = SC.SelectionSet.create().add(content, 0).freeze();
+            } else value = null ;
+            break;
+            
+          // single items are always allows
+          case 1:
+            break;
+
+          // fall through for >= 2, only allow if configured for multi-select
+          default:
+            if (!this.get('allowsMultipleSelection')) value = null;
+            break;
+        }
+      } else value = null;
+      
+      // always make selection into something then save
+      if (!value) value = SC.SelectionSet.EMPTY;
+      this._scsel_selection = value;
+      
+    // read only mode
+    } else return this._scsel_selection ;
+    
+  }.property('arrangedObjects', 'allowsEmptySelection', 
+      'allowsMultipleSelection', 'allowsSelection').cacheable(),
+  
+  /**
+    YES if the receiver currently has a non-zero selection.
+    
+    @property Boolean
+  */
+  hasSelection: function() {
+    var sel = this.get('selection') ;
+    return !!sel && (sel.get('length') > 0) ;
+  }.property('selection').cacheable(),
+  
+  // ..........................................................
+  // METHODS
+  // 
+
+  /**
+    Selects the passed objects in your content.  If you set "extend" to YES,
+    then this will attempt to extend your selection as well.
+  
+    @param {SC.Enumerable} objects objects to select
+    @param {Boolean} extend optionally set to YES to extend selection
+    @returns {Object} receiver
+  */
+  selectObjects: function(objects, extend) {
+
+    // handle passing an empty array
+    if (!objects || objects.get('length')===0) {
+      if (!extend) this.set('selection', SC.SelectionSet.EMPTY);
+      return this;
+    }
+    
+    var sel = this.get('selection');
+    if (extend && sel) sel = sel.copy();
+    else sel = SC.SelectionSet.create();
+    
+    sel.addObjects(objects).freeze();
+    this.set('selection', sel);
+    return this ;
+  },
+  
+  /**
+    Selects a single passed object in your content.  If you set "extend" to 
+    YES then this will attempt to extend your selection as well.
+    
+    @param {Object} object object to select
+    @param {Boolean} extend optionally set to YES to extend selection
+    @returns {Object} receiver
+  */
+  selectObject: function(object, extend) {
+    if (object === null) {
+      if (!extend) this.set('selection', null);
+      return this ;
+      
+    } else return this.selectObjects([object], extend);
+  },    
+
+  /**
+    Deselects the passed objects in your content.
+    
+    @param {SC.Enumerable} objects objects to select
+    @returns {Object} receiver
+  */
+  deselectObjects: function(objects) {
+
+    if (!objects || objects.get('length')===0) return this; // nothing to do
+    
+    var sel = this.get('selection');
+    if (!sel || sel.get('length')===0) return this; // nothing to do
+
+    // find index for each and remove it
+    sel = sel.copy().removeObjects(objects).freeze();
+    this.set('selection', sel.freeze());
+    return this ;
+  },
+  
+  /**
+    Deselects the passed object in your content.
+    
+    @param {SC.Object} object single object to select
+    @returns {Object} receiver
+  */
+  deselectObject: function(object) {
+    if (!object) return this; // nothing to do
+    else return this.deselectObjects([object]);
+  },
+  
+  /** 
+    Call this method whenever your source content changes to ensure the 
+    selection always remains up-to-date and valid.
+  */
+  updateSelectionAfterContentChange: function() {
+    
+    var content = this.get('arrangedObjects'),
+        sel     = this.get('selection'),
+        indexes, len, max, ret;
+
+    if (!sel) sel = SC.SelectionSet.EMPTY;
+    
+    // if selection is not allowed, just force to be empty.
+    if (!this.get('allowsSelection') && sel.get('length')>0) {
+      ret = SC.SelectionSet.EMPTY;
+      
+      
+    // selection is allowed, make sure it is valid
+    } else {
+      
+      // remove from the sel any items selected beyond the length of the new
+      // arrangedObjects
+      indexes = content ? sel.indexSetForSource(content) : null;
+      len     = content ? content.get('length') : 0;
+      max     = indexes ? indexes.get('max') : 0;
+      if (max > len) ret = sel.copy().constrain(content).freeze();
+      
+    }
+  
+    if (ret) this.set('selection', ret);
+    return this ;
+  }
+    
+};

data/frameworks/sproutcore/frameworks/foundation/mixins/static_layout.js

@@ -0,0 +1,132 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+/**
+  @namespace 
+
+  Normally, SproutCore views use absolute positioning to display themselves
+  on the screen.  While this is both the fastest and most efficient way to 
+  display content in the web browser, sometimes your user interface might need
+  to take advantage of the more advanced "flow" layout offered by the browser
+  when you use static and relative positioning.
+  
+  This mixin can be added to a view class to enable the use of any kind of 
+  static and relative browser positionining.  In exchange for using static
+  layout, you will lose a few features that are normally available on a view
+  class such as the 'frame' and 'clippingFrame' properties as well as 
+  notifications when your view or parentView are resized.
+  
+  Normally, if you are allowing the browser to manage the size and positioning
+  of your view, these feature will not be useful to your code anyway.
+  
+  h2. Using StaticLayout
+  
+  To enable static layout on your view, just include this mixin on the view.
+  SproutCore's builtin views that are capable of being used in static 
+  layouts already incorporate this mixin.  Then set the "useStaticLayout" 
+  property on your view class to YES.
+  
+  You can then use CSS or the render() method on your view to setup the 
+  positioning on your view using any browser layout mechanism you want.
+  
+  h2. Example
+  
+  {{{
+    
+    // JavaScript
+    
+    MyApp.CommentView = SC.View.extend(SC.StaticLayout, {
+    
+      classNames: ['comment-view'],
+      
+      useStaticLayout: YES,
+
+      ...
+    });
+    
+    // CSS
+    
+    .comment-view {
+      display: block;
+      position: relative;
+    }
+    
+  }}}
+  
+  @since SproutCore 1.0
+*/
+SC.StaticLayout = {
+
+  /**
+    Walk like a duck.  Used to determine that this mixin has been applied.  
+    Note that a view that hasStaticLayout still may not actually use static
+    layout unless useStaticLayout is also set to YES.
+    
+    @type {Boolean}
+  */
+  hasStaticLayout: YES,
+  
+  /**
+    Activates use of brower's static layout.  You can apply this mixin and
+    still use absolute positioning.  To activate static positioning, set this
+    property to YES.
+
+    @type {Boolean}
+  */
+  useStaticLayout: NO,
+  
+  /** @private - add sc-static-layout class if needed. */
+  renderMixin: function(context, firstTime) {
+    context.setClass('sc-static-layout', this.get('useStaticLayout'));
+  },
+  
+  /**
+    Not available on views with static layout.  Calling this method will raise 
+    an exception.
+  */
+  convertFrameToView: null,
+
+  /**
+    Not available on views with static layout.  Calling this method will raise 
+    an exception.
+  */
+  convertFrameFromView: null,
+  
+  /**
+    Frame is not available on views with static layout.  This property will
+    always return null.
+  */
+  frame: null,
+  
+
+  /**
+    clippingFrame is not available on views with static layout.  This 
+    property will always return null.
+  */
+  clippingFrame: null,
+  
+  /**
+    This method is not supported on static layout views.
+  */
+  parentViewDidResize: null,
+  
+  /**
+    This method is not supported on static layout views.
+  */
+  beginLiveResize: null,
+
+  /**
+    This method is not supported on static layout views.
+  */
+  endLiveResize: null,
+
+  /**
+    This method is not supported on static layout views.
+  */
+  viewDidResize: null
+  
+};

data/frameworks/sproutcore/frameworks/foundation/mixins/string.js

@@ -0,0 +1,251 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+sc_require('system/locale');
+
+// These are basic enhancements to the string class used throughout 
+// SproutCore.
+SC.STRING_TITLEIZE_REGEXP = (/([\s|\-|\_|\n])([^\s|\-|\_|\n]?)/g);
+
+/**
+  @namespace
+  
+  SproutCore implements a variety of enhancements to the built-in String 
+  object that make it easy to perform common substitutions and conversions.
+  
+  Most of the utility methods defined here mirror those found in Prototype
+  1.6.
+  
+  @since SproutCore 1.0
+*/
+SC.String = {
+
+  /**
+    Localizes the string.  This will look up the reciever string as a key 
+    in the current Strings hash.  If the key matches, the loc'd value will be
+    used.  The resulting string will also be passed through fmt() to insert
+    any variables.
+    
+    @param args {Object...} optional arguments to interpolate also
+    @returns {String} the localized and formatted string.
+  */
+  loc: function() {
+    // NB: This could be implemented as a wrapper to locWithDefault() but
+    // it would add some overhead to deal with the arguments and adds stack
+    // frames, so we are keeping the implementation separate.
+    if(!SC.Locale.currentLocale) SC.Locale.createCurrentLocale();
+    var str = SC.Locale.currentLocale.locWithDefault(this) || this;
+    return str.fmt.apply(str,arguments) ;
+  },
+
+  /**
+    Works just like loc() except that it will return the passed default 
+    string if a matching key is not found.
+    
+    @param {String} def the default to return
+    @param {Object...} args optional formatting arguments
+    @returns {String} localized and formatted string
+  */
+  locWithDefault: function(def) {
+    if(!SC.Locale.currentLocale) SC.Locale.createCurrentLocale();
+    var str = SC.Locale.currentLocale.locWithDefault(def) || this;
+    var args = SC.$A(arguments); args.shift(); // remove def param
+    return str.fmt.apply(str,args) ;
+  },
+  
+  /** 
+    Capitalizes a string.
+
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | My favorite items |
+    | css-class-name | Css-class-name |
+    | action_name | Action_name |
+    | innerHTML | InnerHTML |
+
+    @return {String} capitalized string
+  */
+  capitalize: function() {
+    return this.charAt(0).toUpperCase() + this.slice(1) ;
+  },
+  
+  /**
+    Capitalizes every word in a string.  Unlike titleize, spaces or dashes 
+    will remain in-tact.
+    
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | My Favorite Items |
+    | css-class-name | Css-Class-Name |
+    | action_name | Action_Name |
+    | innerHTML | InnerHTML |
+
+    @returns {String} capitalized string
+  */
+  capitalizeEach: function() {
+    return this.replace(SC.STRING_TITLEIZE_REGEXP, 
+      function(str,sep,character) { 
+        return (character) ? (sep + character.toUpperCase()) : sep;
+      }).capitalize() ;
+  },
+
+  /**
+    Converts a string to a title.  This will decamelize the string, convert
+    separators to spaces and capitalize every word.
+
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | My Favorite Items |
+    | css-class-name | Css Class Name |
+    | action_name | Action Name |
+    | innerHTML | Inner HTML |
+
+    @return {String} titleized string.
+  */
+  titleize: function() {
+    var ret = this.replace(/([a-z])([A-Z])/g,'$1_$2'); // decamelize
+    return ret.replace(SC.STRING_TITLEIZE_REGEXP, 
+      function(str,separater,character) { 
+        return (character) ? (' ' + character.toUpperCase()) : ' ';
+      }).capitalize() ;
+  },
+  
+  /**
+    Camelizes a string.  This will take any words separated by spaces, dashes
+    or underscores and convert them into camelCase.
+    
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | myFavoriteItems |
+    | css-class-name | cssClassName |
+    | action_name | actionName |
+    | innerHTML | innerHTML |
+
+    @returns {String} camelized string
+  */
+  camelize: function() {
+    var ret = this.replace(SC.STRING_TITLEIZE_REGEXP, 
+      function(str,separater,character) { 
+        return (character) ? character.toUpperCase() : '' ;
+      }) ;
+    var first = ret.charAt(0), lower = first.toLowerCase() ;
+    return (first !== lower) ? (lower + ret.slice(1)) : ret ;
+  },
+  
+  /**
+    Converts the string into a class name.  This method will camelize your 
+    string and then capitalize the first letter.
+    
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | MyFavoriteItems |
+    | css-class-name | CssClassName |
+    | action_name | ActionName |
+    | innerHTML | InnerHtml |
+
+    @returns {String}
+  */
+  classify: function() {
+    var ret = this.replace(SC.STRING_TITLEIZE_REGEXP, 
+      function(str,separater,character) { 
+        return (character) ? character.toUpperCase() : '' ;
+      }) ;
+    var first = ret.charAt(0), upper = first.toUpperCase() ;
+    return (first !== upper) ? (upper + ret.slice(1)) : ret ;
+  },
+  
+  /**
+    Converts a camelized string into all lower case separated by underscores.
+    
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | my favorite items |
+    | css-class-name | css-class-name |
+    | action_name | action_name |
+    | innerHTML | inner_html |
+
+    @returns {String} the decamelized string.
+  */
+  decamelize: function() { 
+    return this.replace(/([a-z])([A-Z])/g,'$1_$2').toLowerCase();
+  },
+
+  /**
+    Converts a camelized string or a string with spaces or underscores into
+    a string with components separated by dashes.
+    
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | my-favorite-items |
+    | css-class-name | css-class-name |
+    | action_name | action-name |
+    | innerHTML | inner-html |
+
+    @returns {String} the dasherized string.
+  */
+  dasherize: function() {
+    return this.decamelize().replace(/[ _]/g,'-') ;  
+  },
+  
+  /**
+    Converts a camelized string or a string with dashes or underscores into
+    a string with components separated by spaces.
+    
+    h2. Examples
+    
+    | *Input String* | *Output String* |
+    | my favorite items | my favorite items |
+    | css-class-name | css class name |
+    | action_name | action name |
+    | innerHTML | inner html |
+
+    @returns {String} the humanized string.
+  */
+  humanize: function() {
+    return this.decamelize().replace(/[\-_]/g,' ') ;
+  },
+  
+  /**
+    Removes any extra whitespace from the edges of the strings. This method is 
+    also aliased as strip().
+    
+    @returns {String} the trimmed string
+  */
+  trim: function () {
+    return this.replace(/^\s+|\s+$/g,"");
+  },
+  
+  /**
+    Splits the string into words, separated by spaces. Empty strings are
+    removed from the results.
+    
+    @returns {Array} an array of non-empty strings
+  */
+  w: function() { 
+    var ary = [], ary2 = this.split(' '), len = ary2.length ;
+    for (var idx=0; idx<len; ++idx) {
+      var str = ary2[idx] ;
+      if (str.length !== 0) ary.push(str) ; // skip empty strings
+    }
+    return ary ;
+  }
+  
+};
+
+SC.String.strip = SC.String.trim; // convenience alias.
+
+// Apply SC.String mixin to built-in String object
+SC.mixin(String.prototype, SC.String) ;
+SC.String.fmt = String.prototype.fmt; // copy from runtime
+