sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

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

@@ -0,0 +1,154 @@
+// ==========================================================================
+// 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 = {
+  
+  /** 
+    Call this method whenever your source content changes to ensure the 
+    selection always remains up-to-date and valid.
+  */
+  updateSelectionAfterContentChange: function() {
+    var objects = SC.makeArray(this.get('arrangedObjects')) ;
+    var currentSelection = SC.makeArray(this.get('selection')) ;
+    var sel = [] ;
+    
+    // the new selection is the current selection that exists in 
+    // arrangedObjects or an empty selection if selection is not allowed.
+    var max = currentSelection.get('length') ;
+    if (this.get('allowsSelection')) {
+      for(var idx=0;idx<max;idx++) {
+        var obj = currentSelection.objectAt(idx) ;
+        if (objects.indexOf(obj) >= 0) sel.push(obj) ;
+      }
+    }
+    
+    // if the new selection is a multiple selection, get the first object
+    var selectionLength = sel.get('length') ;
+    if ((selectionLength > 1) && !this.get('allowsMultipleSelection')) {
+      sel = [sel.objectAt(0)] ;
+    }
+    
+    // if the selection is empty, select the first item.
+    if ((selectionLength == 0) && !this.get('allowsEmptySelection')) {
+      if (objects.get('length') > 0) sel = [objects.objectAt(0)] ;
+    }
+    
+    // update the selection.
+    this.set('selection', sel) ;
+  },
+  
+  /**
+    @property
+    @type SC.Array
+    
+    Returns the set of content objects the selection should be a part of.
+    Selections in general may contain objects outside of this content, but
+    this set will be used when enforcing items such as no empty selection.
+    
+    The default version of this property returns the receiver.
+  */
+  arrangedObjects: function() { return this; }.property(),
+  
+  /**
+    @property
+    @type SC.Set
+    
+    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) {
+      // are we even allowing selection at all? If not, return early...
+      if (!this.get('allowsSelection')) return this._selection ;
+      
+      value = SC.makeArray(value) ; // always force to an array
+      
+      // ok, new decide if the *type* of seleciton is allowed...
+      switch (value.get('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
+          if (!this.get('allowsEmptySelection')) {
+            var objects = this.get('arrangedObjects') ;
+            if (objects.get('length') > 0) value = [objects.objectAt(0)];
+          }
+          this._selection = value ;
+          break;
+        case 1:
+          this._selection = value;
+          break;
+        default:
+          // fall through for >= 2, only allow if configured for multi-select
+          this._selection = this.get('allowsMultipleSelection') ?
+            value :
+            this._selection ;
+          break;
+      }
+    }
+    else return this._selection ;
+  }.property(),
+  
+  /**
+    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,
+  
+  /**
+    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')
+  
+};

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

@@ -0,0 +1,101 @@
+// ==========================================================================
+// 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.  
+  
+  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.
+  
+  @since SproutCore 1.0
+*/
+SC.StaticLayout = {
+
+  /**
+    Walk like a duck
+  */
+  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.
+  */
+  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,237 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+// 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.  */
+  w: function() { return this.split(' '); }
+    
+} ;
+
+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
+

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

@@ -0,0 +1,176 @@
+// ==========================================================================
+// 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
+
+  Views that include the Validatable mixin can be used with validators to 
+  ensure their values are valid.  
+  
+*/
+SC.Validatable = {
+  
+  initMixin: function() {
+    this._validatable_validatorDidChange() ;
+  },
+  
+  /**
+    The validator for this field.  
+  
+    Set to a validator class or instance.  If this points to a class, it will 
+    be instantiated when the validator is first used.
+  */
+  validator: null,
+
+  /**
+    This property must return the human readable name you want used when 
+    describing an error condition.  For example, if set this property to
+    "Your Email", then the returned error string might be something like
+    "Your Email is not valid".
+    
+    You can return a loc string here if you like.  It will be localized when
+    it is placed into the error string.
+  */
+  errorLabel: null,
+
+  /**
+    YES if the receiver is currently valid.
+    
+    This property watches the value property by default.  You can override
+    this property if you want to use some other method to calculate the
+    current valid state.
+    
+    @field
+  */
+  isValid: function() { 
+    return SC.typeOf(this.get('value')) !== SC.T_ERROR; 
+  }.property('value'),
+  
+  /**
+    The form that the view belongs to.  May be null if the view does not 
+    belong to a form.  This property is usually set automatically by an 
+    owner form view.
+  */
+  ownerForm: null,
+  
+  /**
+    Attempts to validate the receiver. 
+    
+    Runs the validator and returns SC.VALIDATE_OK, SC.VALIDATE_NO_CHANGE,
+    or an error object.  If no validator is installed, this method will
+    always return SC.VALIDATE_OK.
+
+    @param {Boolean} partialChange YES if this is a partial edit.
+    @returns SC.VALIDATE_OK, error, or SC.VALIDATE_NO_CHANGE
+  */
+  performValidate: function(partialChange) {
+    var ret = SC.VALIDATE_OK ;
+
+    if (this._validator) {
+      var form = this.get('ownerForm') ;
+      if (partialChange) {
+        ret = this._validator.validatePartial(form,this) ;
+
+        // if the partial returned NO_CHANGE, then check to see if the 
+        // field is valid anyway.  If it is not valid, then don't update the
+        // value.  This way the user can have partially constructed values 
+        // without the validator trying to convert it to an object.
+        if ((ret == SC.VALIDATE_NO_CHANGE) && (this._validator.validateChange(form, this) == SC.VALIDATE_OK)) {
+          ret = SC.VALIDATE_OK; 
+        }
+      } else ret = this._validator.validateChange(form, this) ;
+    }
+    return ret ;
+  },
+
+  /**
+    Runs validateSubmit.  You should use this in your implementation of 
+    validateSubmit.  If no validator is installed, this always returns
+    SC.VALIDATE_OK
+  */
+  performValidateSubmit: function() {
+    return this._validator ? this._validator.validateSubmit(this.get('ownerForm'), this) : SC.VALIDATE_OK;
+  },
+  
+  /**
+    Runs a keypress validation.  Returns YES if the keypress should be 
+    allowed, NO otherwise.  If no validator is defined, always returns YES.
+    
+    @param {String} charStr the key string
+    @returns {Boolean}
+  */
+  performValidateKeyDown: function(evt) {
+    // ignore anything with ctrl or meta key press
+    var charStr = evt.getCharString();
+    if (!charStr) return YES ;
+    return this._validator ? this._validator.validateKeyDown(this.get('ownerForm'), this, charStr) : YES;
+  },
+  
+  /**
+    Returns the validator object, if one has been created.
+    
+    @property {SC.Validator} the object
+  */
+  validatorObject: function() {
+    return this._validator;
+  }.property(),
+  
+  /**
+    Invoked by the owner form just before submission.  Override with your 
+    own method to commit any final changes after you perform validation. 
+    
+    The default implementation simply calls performValidateSubmit() and 
+    returns that value.
+  */
+  validateSubmit: function() { return this.performValidateSubmit(); },
+  
+  /**
+    Convert the field value string into an object.
+    
+    This method will call the validators objectForFieldValue if it exists.
+    
+    @param fieldValue the raw value from the field.
+    @returns converted object
+  */
+  objectForFieldValue: function(fieldValue, partialChange) {
+    return this._validator ? this._validator.objectForFieldValue(fieldValue, this.get('ownerForm'), this) : fieldValue ;
+  },
+  
+  /**
+    Convert the object into a field value.
+    
+    This method will call the validator's fieldValueForObject if it exists.
+    
+    @param object the objec to convert
+    @returns converted field value
+  */
+  fieldValueForObject: function(object) {
+    return this._validator ? this._validator.fieldValueForObject(object, this.get('ownerForm'), this) : object ;
+  },
+  
+  _validatable_displayObserver: function() {
+    this.displayDidChange();
+  }.observes('isValid'),
+  
+  updateLayerMixin: function(context) {
+    context.setClass('invalid', !this.get('isValid'));
+  },
+  
+  // invoked whenever the attached validator changes.
+  _validatable_validatorDidChange: function() {
+    var form = this.get('ownerForm') ;
+    var val = SC.Validator.findFor(form, this, this.get('validator')) ;
+    if (val != this._validator) {
+      this.propertyWillChange('validatorObject');
+      if (this._validator) this._validator.detachFrom(form, this) ;
+      this._validator = val;
+      if (this._validator) this._validator.attachTo(form, this) ;
+      this.propertyDidChange('validatorObject');
+    }  
+  }.observes('validator', 'ownerForm')
+      
+};