sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

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

@@ -0,0 +1,171 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+
+/**
+  Used for contentIndexDisclosureState().  Indicates open branch node.
+*/
+SC.BRANCH_OPEN = 0x0011;
+
+/**
+  Used for contentIndexDisclosureState().  Indicates closed branch node.
+*/
+SC.BRANCH_CLOSED = 0x0012;
+
+/**
+  Used for contentIndexDisclosureState().  Indicates leaf node.
+*/
+SC.LEAF_NODE = 0x0020;
+
+/**
+  @namespace
+
+  This mixin provides standard methods used by a CollectionView to provide
+  additional meta-data about content in a collection view such as selection
+  or enabled state.
+  
+  You can apply this mixin to a class that you set as a delegate or to the
+  object you set as content.  SC.ArrayControllers automatically implement
+  this mixin.
+  
+  @since SproutCore 1.0
+*/
+SC.CollectionContent = {
+
+  /**
+    Used to detect the mixin by SC.CollectionView
+  */
+  isCollectionContent: YES,
+  
+  /**
+    Return YES if the content index should be selected.  Default behavior 
+    looks at the selection property on the view.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
+  */
+  contentIndexIsSelected: function(view, content, idx) {
+    var sel = view.get('selection');
+    return sel ? sel.contains(content, idx) : NO ;
+  },
+  
+  /**
+    Returns YES if the content index should be enabled.  Default looks at the
+    isEnabled state of the collection view.
+    looks at the selection property on the view.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
+  */
+  contentIndexIsEnabled: function(view, content, idx) {
+    return view.get('isEnabled');
+  },
+  
+  // ..........................................................
+  // GROUPING
+  // 
+  
+  /**
+    Optionally return an index set containing the indexes that may be group
+    views.  For each group view, the delegate will actually be asked to 
+    confirm the view is a group using the contentIndexIsGroup() method.
+    
+    If grouping is not enabled, return null.
+    
+    @param {SC.CollectionView} view the calling view
+    @param {SC.Array} content the content object
+    @return {SC.IndexSet} 
+  */
+  contentGroupIndexes: function(view, content) {
+    return null;
+  },
+  
+  /**
+    Returns YES if the item at the specified content index should be rendered
+    using the groupExampleView instead of the regular exampleView.  Note that
+    a group view is different from a branch/leaf view.  Group views often 
+    appear with different layout and a different look and feel.
+
+    Default always returns NO.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
+  */
+  contentIndexIsGroup: function(view, content, idx) {
+    return NO ;
+  },
+  
+  // ..........................................................
+  // OUTLINE VIEWS
+  // 
+  
+  /**
+    Returns the outline level for the item at the specified index.  Can be 
+    used to display hierarchical lists.
+    
+    Default always returns -1 (no outline).
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
+  */
+  contentIndexOutlineLevel: function(view, content, idx) {
+    return -1;
+  },
+  
+  /**
+    Returns a constant indicating the disclosure state of the item.  Must be
+    one of SC.BRANCH_OPEN, SC.BRANCH_CLOSED, SC.LEAF_NODE.  If you return one
+    of the BRANCH options then the item may be rendered with a disclosure 
+    triangle open or closed.  If you return SC.LEAF_NODe then the item will 
+    be rendered as a leaf node.  
+
+    Default returns SC.LEAF_NODE.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
+  */
+  contentIndexDisclosureState: function(view, content, idx) {
+    return SC.LEAF_NODE;    
+  },
+  
+  /**
+    Called to expand a content index item if it is currently in a closed 
+    disclosure state.  The default implementation does nothing.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {void}
+  */
+  contentIndexExpand: function(view, content, idx) {
+    console.log('contentIndexExpand(%@, %@, %@)'.fmt(view,content,idx));
+  },
+  
+  /**
+    Called to collapse a content index item if it is currently in an open 
+    disclosure state.  The default implementation does nothing.  
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.Array} content the content object
+    @param {Number} idx the content index
+    @returns {void}
+  */
+  contentIndexCollapse: function(view, content, idx) {
+    console.log('contentIndexCollapse(%@, %@, %@)'.fmt(view,content,idx));
+  }
+    
+};

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

@@ -0,0 +1,88 @@
+// ==========================================================================
+// 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
+
+  The SC.ContentDisplay mixin makes it easy to automatically update your view
+  display whenever relevant properties on a content object change.  To use
+  this mixin, include it in your view and then add the names of the 
+  properties on the content object you want to trigger a displayDidChange() 
+  method on your view. Your updateDisplay() method will then be called at the 
+  end of the run loop.
+  
+  h2. Example
+  
+  {{{
+    MyApp.MyViewClass = SC.View.extend(SC.ContentDisplay, { 
+      contentDisplayProperties: 'title isEnabled hasChildren'.w(),
+      ...
+    });
+  }}}
+  
+*/
+SC.ContentDisplay = {
+  
+  /** @private */
+  concatenatedProperties: 'contentDisplayProperties',
+
+  /** @private */
+  displayProperties: ['content'],
+  
+  /** 
+    Add an array with the names of any property on the content object that
+    should trigger an update of the display for your view.  Changes to the
+    content object will only invoke your display method once per runloop.
+  */
+  contentDisplayProperties: [],
+  
+  /** @private */
+  _display_contentDidChange: function(target, key, value) {
+    // handle changes to the content...
+    if ((value = this.get('content')) != this._display_content) {
+
+      // get the handler method
+      var f = this._display_contentPropertyDidChange ;
+      
+      // stop listening to old content.
+      var content = this._display_content;
+      if (content) {
+        if (SC.isArray(content)) {
+          content.invoke('removeObserver', '*', this, f) ;
+        } else if (content.removeObserver) {
+          content.removeObserver('*', this, f) ;
+        }
+      }
+      
+      // start listening for changes on the new content object.
+      content = this._display_content = value ; 
+      if (content) {
+        if (SC.isArray(content)) {
+          content.invoke('addObserver', '*', this, f) ;
+        } else if (content.addObserver) {
+          content.addObserver('*', this, f) ;
+        }
+      }
+
+      // notify everyone that everything is different now.
+      this.allPropertiesDidChange() ;
+      this.endPropertyChanges() ;
+    }
+  }.observes('content'),
+  
+  /** @private Invoked when properties on the content object change. */
+  _display_contentPropertyDidChange: function(target, key, value, propertyRevision) {
+    if (key === '*') {
+      this.displayDidChange() ;
+    } else {
+      // only update if a displayProperty actually changed...s
+      var ary = this.get('contentDisplayProperties') ;
+      if (ary && ary.indexOf(key)>=0) this.displayDidChange();
+    }
+  }
+  
+} ;

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

@@ -0,0 +1,352 @@
+// ==========================================================================
+// 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('mixins/string');
+
+/** Indicates a value has a mixed state of both on and off. */
+SC.MIXED_STATE = '__MIXED__' ;
+
+/** Option for HUGE control size. */
+SC.HUGE_CONTROL_SIZE = 'sc-huge-size' ;
+
+/** Option for large control size. */
+SC.LARGE_CONTROL_SIZE = 'sc-large-size' ;
+
+/** Option for standard control size. */
+SC.REGULAR_CONTROL_SIZE = 'sc-regular-size' ;
+
+/** Option for small control size. */
+SC.SMALL_CONTROL_SIZE = 'sc-small-size' ;
+
+/** Option for tiny control size */
+SC.TINY_CONTROL_SIZE = 'sc-tiny-size' ;
+
+/**
+  @namespace
+  
+  A Control is a view that also implements some basic state functionality.
+  Apply this mixin to any view that you want to have standard control
+  functionality including showing a selected state, enabled state, focus
+  state, etc.
+  
+  h2. About Values and Content
+  
+  Controls typically are used to represent a single value, such as a number,
+  boolean or string.  The value a control is managing is typically stored in
+  a "value" property.  You will typically use the value property when working
+  with controls such as buttons and text fields in a form.
+  
+  An alternative way of working with a control is to use it to manage some
+  specific aspect of a content object.  For example, you might use a label
+  view control to display the "name" property of a Contact record.  This 
+  approach is often necessary when using the control as part of a collection
+  view.
+  
+  You can use the content-approach to work with a control by setting the 
+  "content" and "contentValueKey" properties of the control.  The 
+  "content" property is the content object you want to manage, while the 
+  "contentValueKey" is the name of the property on the content object 
+  you want the control to display.
+  
+  The default implementation of the Control mixin will essentially map the
+  contentValueKey of a content object to the value property of the 
+  control.  Thus if you are writing a custom control yourself, you can simply
+  work with the value property and the content object support will come for
+  free.  Just write an observer for the value property and update your 
+  view accordingly.
+  
+  If you are working with a control that needs to display multiple aspects
+  of a single content object (for example showing an icon and label), then
+  you can override the contentValueDidChange() method instead of observing
+  the value property.  This method will be called anytime _any_ property 
+  on the content object changes.  You should use this method to check the
+  properties you care about on the content object and update your view if 
+  anything you care about has changed.
+  
+  h2. Delegate Support
+  
+  Controls can optionally get the contentDisplayProperty from a 
+  displayDelegate, if it is set.  The displayDelegate is often used to 
+  delegate common display-related configurations such as which content value
+  to show.  Anytime your control is shown as part of a collection view, the
+  collection view will be automatically set as its displayDelegate.
+  
+  @since SproutCore 1.0
+*/
+SC.Control = {
+  
+  initMixin: function() {
+    this._control_contentDidChange() ; // setup content observing if needed.
+  },
+  
+  /** 
+    The selected state of this control.  Possible options are YES, NO or 
+    SC.MIXED_STATE.
+    
+    @type Boolean or SC.MIXED_STATE
+  */
+  isSelected: NO,
+  
+  /** @private */
+  isSelectedBindingDefault: SC.Binding.oneWay().bool(),
+  
+  /**
+    Set to YES when the item is currently active.  Usually this means the 
+    mouse is current pressed and hovering over the control, however the 
+    specific implementation my vary depending on the control.
+    
+    Changing this property value by default will cause the Control mixin to
+    add/remove an 'active' class name to the root element.
+    
+    @type Boolean
+  */
+  isActive: NO,
+  
+  /** @private */
+  isActiveBindingDefault: SC.Binding.oneWay().bool(),
+  
+  /**
+    The value represented by this control.
+    
+    Most controls represent a value of some type, such as a number, string
+    or image URL.  This property should hold that value.  It is bindable
+    and observable.  Changing this value will immediately change the
+    appearance of the control.  Likewise, editing the control 
+    will immediately change this value.
+    
+    If instead of setting a single value on a control, you would like to 
+    set a content object and have the control display a single property
+    of that control, then you should use the content property instead.
+  */
+  value: null,
+  
+  /**
+    The content object represented by this control.
+    
+    Often you need to use a control to display some single aspect of an 
+    object, especially if you are using the control as an item view in a
+    collection view.
+    
+    In those cases, you can set the content and contentValueKey for the
+    control.  This will cause the control to observe the content object for
+    changes to the value property and then set the value of that property 
+    on the "value" property of this object.
+    
+    Note that unless you are using this control as part of a form or 
+    collection view, then it would be better to instead bind the value of
+    the control directly to a controller property.
+    
+    @type SC.Object
+  */
+  content: null,
+  
+  /**
+    The property on the content object that would want to represent the 
+    value of this control.  This property should only be set before the
+    content object is first set.  If you have a displayDelegate, then
+    you can also use the contentValueKey of the displayDelegate.
+    
+    @type String
+  */
+  contentValueKey: null,
+  
+  /**
+    Invoked whenever any property on the content object changes.  
+    
+    The default implementation will update the value property of the view
+    if the contentValueKey property has changed.  You can override this
+    method to implement whatever additional changes you would like.
+    
+    The key will typically contain the name of the property that changed or 
+    '*' if the content object itself has changed.  You should generally do
+    a total reset of '*' is changed.
+    
+    @param {Object} target the content object
+    @param {String} key the property that changes
+    @test in content
+  */
+  contentPropertyDidChange: function(target, key) {
+    return this.updatePropertyFromContent('value', key, 'contentValueKey');
+  },
+  
+  /**
+    Helper method you can use from your own implementation of 
+    contentPropertyDidChange().  This method will look up the content key to
+    extract a property and then update the property if needed.  If you do
+    not pass the content key or the content object, they will be computed 
+    for you.  It is more efficient, however, for you to compute these values
+    yourself if you expect this method to be called frequently.
+    
+    @param {String} prop local property to update
+    @param {String} key the contentproperty that changed
+    @param {String} contentKey the local property that contains the key
+    @param {Object} content
+    @returns {SC.Control} receiver
+  */
+  updatePropertyFromContent: function(prop, key, contentKey, content) {
+    var all = key === '*';
+    if (contentKey === undefined) {
+      contentKey = "content%@Key".fmt(prop.capitalize());
+    }
+    if (content === undefined) content = this.get('content');
+    
+    // get actual content key
+    contentKey = this[contentKey] ?
+      this.get(contentKey) :
+      this.getDelegateProperty(contentKey, this.displayDelegate) ;
+    
+    if (contentKey && (all || key === contentKey)) {
+      var v = (content) ?
+        (content.get ? content.get(contentKey) : content[contentKey]) :
+        null ;
+      this.set(prop, v) ;
+    }
+    return this ;
+  },
+  
+  /**
+    Relays changes to the value back to the content object if you are using
+    a content object.
+    
+    This observer is triggered whenever the value changes.  It will only do
+    something if it finds you are using the content property and
+    contentValueKey and the new value does not match the old value of the
+    content object.  
+    
+    If you are using contentValueKey in some other way than typically
+    implemented by this mixin, then you may want to override this method as
+    well.
+  */
+  updateContentWithValueObserver: function() {
+    var key = this.contentValueKey ?
+      this.get('contentValueKey') :
+      this.getDelegateProperty('contentValueKey', this.displayDelegate) ;
+    
+    var content = this.get('content') ;
+    if (!key || !content) return ; // do nothing if disabled
+    
+    // get value -- set on content if changed
+    var value = this.get('value');
+    if (typeof content.setIfChanged === SC.T_FUNCTION) {
+      content.setIfChanged(key, value);
+    } else {
+      // avoid re-writing inherited props
+      if (content[key] !== value) content[key] = value ;
+    }
+  }.observes('value'),
+  
+  /**
+    The name of the property this control should display if it is part of an
+    SC.FormView.
+    
+    If you add a control as part of an SC.FormView, then the form view will 
+    automatically bind the value to the property key you name here on the 
+    content object.
+    
+    @type String
+  */
+  fieldKey: null,
+  
+  /**
+    The human readable label you want shown for errors.  May be a loc string.
+    
+    If your field fails validation, then this is the name that will be shown
+    in the error explanation.  If you do not set this property, then the 
+    fieldKey or the class name will be used to generate a human readable name.
+    
+    @type String
+  */
+  fieldLabel: null,
+  
+  /**
+    The human readable label for this control for use in error strings.  This
+    property is computed dynamically using the following rules:
+    
+    # If the fieldLabel is defined, that property is localized and returned.
+    # Otherwise, if the keyField is defined, try to localize using the string 
+    # "ErrorLabel.{fieldKeyName}".  If a localized name cannot be found, use a
+    # humanized form of the fieldKey.
+    # Try to localize using the string "ErrorLabel.{ClassName}"
+    # Return a humanized form of the class name.
+    
+    @type String
+  */
+  errorLabel: function() {
+    var ret, fk, def ;
+    if (ret = this.get('fieldLabel')) return ret ;
+    
+    // if field label is not provided, compute something...
+    fk = this.get('fieldKey') || this.constructor.toString() ;
+    def = (fk || '').humanize().capitalize() ;
+    return "ErrorLabel.%@".fmt(fk)
+      .locWithDefault("FieldKey.%@".fmt(fk).locWithDefault(def)) ;
+      
+  }.property('fieldLabel','fieldKey').cacheable(),
+
+  /**
+    The control size.  This will set a CSS style on the element that can be 
+    used by the current theme to vary the appearance of the control.
+  */
+  controlSize: SC.REGULAR_CONTROL_SIZE,
+  
+  displayProperties: 'isEnabled isSelected isActive controlSize'.w(),
+  
+  /** @private */
+  _CONTROL_TMP_CLASSNAMES: {},
+  
+  /**
+    Invoke this method in your updateDisplay() method to update any basic 
+    control CSS classes.
+  */
+  renderMixin: function(context, firstTime) {
+    var sel = this.get('isSelected'), disabled = !this.get('isEnabled');
+    
+    // update the CSS classes for the control.  note we reuse the same hash
+    // to avoid consuming more memory
+    var names = this._CONTROL_TMP_CLASSNAMES ; // temporary object
+    names.mixed = sel === SC.MIXED_STATE;
+    names.sel = sel && (sel !== SC.MIXED_STATE) ;
+    names.active = this.get('isActive') ;
+    context.setClass(names).addClass(this.get('controlSize'));
+    
+    // if the control implements the $input() helper, then fixup the input
+    // tags
+    if (!firstTime && this.$input) {
+      this.$input().attr('disabled', disabled);
+    }
+  },
+  
+  /** @private
+    This should be null so that if content is also null, the
+    _contentDidChange won't do anything on init.
+  */
+  _control_content: null,
+  
+  /** @private
+    Observes when a content object has changed and handles notifying 
+    changes to the value of the content object.
+  */
+  _control_contentDidChange: function() {
+    var content = this.get('content') ;
+    if (this._control_content === content) return; // nothing changed
+    
+    var f = this.contentPropertyDidChange ;
+    
+    // remove an observer from the old content if necessary
+    var old = this._control_content ;
+    if (old && old.removeObserver) old.removeObserver('*', this, f) ;
+    
+    // add observer to new content if necessary.
+    this._control_content = content ;
+    if (content && content.addObserver) content.addObserver('*', this, f) ;
+    
+    // notify that value did change.
+    this.contentPropertyDidChange(content, '*') ;
+    
+  }.observes('content')
+  
+};