sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/views/{text_field.js → field/text_field.js}

@@ -1,21 +1,34 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('views/field') ;
+require('views/field/field') ;
 
-// A text field is an input element with type "text".  This view adds support
-// for hinted values, etc.
-SC.TextFieldView = SC.FieldView.extend({
+/**
+  @class
+  
+  A text field is an input element with type "text".  This view adds support
+  for hinted values, etc.
+  
+  @extends SC.FieldView
+  @author Charles Jolley
+*/
+SC.TextFieldView = SC.FieldView.extend(
+/** @scope SC.TextFieldView.prototype */ {
   
   emptyElement: '<input type="text" value="" />',
 
   // PROPERTIES
-  // set this property to the hinted value.
+
+  /**
+    The hint to display while the field is not active.  Can be a loc key.
+  */  
   hint: null,
   
-  // automatically set by text field if the hint is current showing.
+  /**
+    automatically set to YES if the hint is currently showing.
+  */
   isHintShowing: false,
 
 
@@ -59,7 +72,10 @@ SC.TextFieldView = SC.FieldView.extend({
       this.resignFirstResponder() ;
     }
   },
-  
+
+  /**
+    tied to the isEnabled state
+  */
   acceptsFirstResponder: function() {
     return this.get('isEnabled');
   }.property('isEnabled'),
@@ -70,6 +86,7 @@ SC.TextFieldView = SC.FieldView.extend({
 
   // when we become first responder, focus the text field if needed and
   // hide the hint text.
+  /** @private */
   didBecomeFirstResponder: function() {
 
     // focus the text field.
@@ -87,6 +104,7 @@ SC.TextFieldView = SC.FieldView.extend({
 
   // when we lose first responder, blur the text field if needed and show
   // the hint text if needed.
+  /** @private */
   willLoseFirstResponder: function() {
     
     if (this._isFocused) {
@@ -116,16 +134,19 @@ SC.TextFieldView = SC.FieldView.extend({
   },
   
   // field value updates...
+  /** @private */
   getFieldValue: function() {
     return this._value ;
   },
   
+  /** @private */
   setFieldValue: function(value) {
     if (this._value == value) return ;
     this._value = value ;
     this._updateFieldHint() ;
   },
   
+  /** @private */
   mouseDown: function(e)
   {
     e._stopWhenHandled = false;
@@ -133,6 +154,7 @@ SC.TextFieldView = SC.FieldView.extend({
   },
   
   // trap key-press events and notify as needed.
+  /** @private */
   keyDown: function(evt) {
     if (this._value != this.rootElement.value) {
       this._value = this.rootElement.value ;
@@ -143,6 +165,7 @@ SC.TextFieldView = SC.FieldView.extend({
     //return false;
   },
   
+  /** @private */
   keyUp: function() {
     if (this._value != this.rootElement.value) {
       this._value = this.rootElement.value ;
@@ -162,18 +185,44 @@ SC.TextFieldView = SC.FieldView.extend({
   // THESE ARE DUMMY IMPLEMENTATIONS OF THE REPONDER METHODS FOR KEYBOARD
   // ACTIONS HANDLED BY THE BROWSER.  This avoids having the responder 
   // bubble up these items.
+
+  /** @private */
   deleteBackward: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   deleteForward: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveLeft: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveRight: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveUp: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveDown: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveLeftAndModifySelection: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveRightAndModifySelection: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveUpAndModifySelection: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveDownAndModifySelection: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveToBeginningOfDocument: function(evt) { evt._stopWhenHandled = false; return true; },
+
+  /** @private */
   moveToEndOfDocument: function(evt) { evt._stopWhenHandled = false; return true; },
+  
+  /** @private */
   selectAll: function(evt) { evt._stopWhenHandled = false; return true; }
   
 }) ;

data/frameworks/sproutcore/views/{textarea_field.js → field/textarea_field.js}

@@ -1,11 +1,21 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('views/text_field') ;
+require('views/field/text_field') ;
 
-SC.TextareaFieldView = SC.TextFieldView.extend({
+/**
+  @class
+  
+  Manages a text area field.
+  
+  @extends SC.TextFieldView
+  @author Skip Baney
+  @version 1.0
+*/
+SC.TextareaFieldView = SC.TextFieldView.extend(
+/** @scope SC.TextareaFieldView.prototype */ {
   
   emptyElement: '<textarea></textarea>',
 

data/frameworks/sproutcore/views/filter_button.js

@@ -1,9 +1,9 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('views/button') ;
+require('views/button/button') ;
 
 // A filter button sets a filter property to whatever you specifiy.  It 
 // also binds to the same property and updates its isSelected state based

data/frameworks/sproutcore/views/form.js

@@ -1,11 +1,11 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
-require('views/button') ;
-require('views/text_field') ;
+require('views/button/button') ;
+require('views/field/text_field') ;
 
 // FormView provides a simple way for you to "stage" input by capturing
 // data from your views into the form before it is set on your actual

data/frameworks/sproutcore/views/image.js

@@ -1,38 +1,134 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
+require('mixins/control') ;
 
 lc_cnt = 0 ;
 
-SC.ImageView = SC.View.extend({
-  emptyElement: '<img src="%@" />'.fmt(static_url('blank')),
+SC.IMAGE_STATE_NONE = 'none';
+SC.IMAGE_STATE_LOADING = 'loading';
+SC.IMAGE_STATE_LOADED = 'loaded';
+SC.IMAGE_STATE_FAILED = 'failed';
+
+/**
+  URL to a transparent GIF.  Used for spriting.
+*/
+SC.BLANK_IMAGE_URL = static_url('blank.gif');
+
+/**
+  @class
+
+  Displays an image in the browser.  
+  
+  The ImageView can be used to efficiently display images in the browser.
+  It includes a built in support for a number of features that can improve
+  your page load time if you use a lot of images including a image loading
+  queue and automatic support for CSS spriting.
+
+  @extends SC.View
+  @extends SC.Control
+  @author Charles Jolley
+*/
+SC.ImageView = SC.View.extend(SC.Control, 
+/** @scope SC.ImageView.prototype */ {
   
-  status: 'unknown',
+  /** Image views contain an img tag. */
+  emptyElement: '<img src="%@" class="sc-image-view" />'.fmt(SC.BLANK_IMAGE_URL),
   
-  content: null, // becomes the url.
-  contentBindingDefault: SC.Binding.Single,
+  /**
+    Current load status of the image.
+    
+    This status changes as an image is loaded from the server.  If spriting
+    is used, this will always be loaded.  Must be one of the following
+    constants: SC.IMAGE_STATE_NONE, SC.IMAGE_STATE_LOADING, 
+    SC.IMAGE_STATE_LOADED, SC.IMAGE_STATE_FAILED
+  */
+  status: SC.IMAGE_STATE_NONE,
   
-  // override with your own function to transform content into a URL.
+  /**
+    A url or CSS class name.
+    
+    This is the image you want the view to display.  It should be either a
+    url or css class name.  You can also set the content and 
+    contentValueKey properties to have this value extracted 
+    automatically.
+    
+    If you want to use CSS spriting, set this value to a CSS class name.  If
+    you need to use multiple class names to set your icon, separate them by
+    spaces.
+  */
+  value: null,
+  _value: null,
+
+  /**
+    Invoked whenever the content or value changes. (To be removed in 
+    SproutCore 1.0)
+    
+    This method is no longer necessary since we have the standard SC.Control
+    behavior.
+    
+    @deprecated
+    @param {Object} content The content object.
+    @returns {String} the URL or CSS class name
+  */
   transform: function(content) { return content; },
   
-  contentObserver: function() {
-    var prop = this.get('content') || '' ;
-    var url = this.transform(prop) ;
+  valueObserver: function() {
+    
+    // get the new URL.
+    var value = this.get('value') ;
+    
+    // invoke the old transform method if it is defined
+    if (this.transform !== SC.ImageView.prototype.transform) {
+      var content = this.get('content') || '' ;
+      value = this.transform(content) ;
+    }
+    
+    // if the value has not changed, do nothing.
+    if (value == this._value) return ;
     
-    if (url && url.length > 0) {
+    // if the old value was a class name, then we need to remove it.
+    if (this._value && this._value.length>0 && !SC.ImageView.valueIsUrl(this._value)) {
+      var classNames = this._value.split(' ') ;
+      var idx = classNames.length ;
+      while(--idx >= 0) { 
+        this.removeClassName(classNames[idx]); 
+      }
+      this.removeClassName('sc-sprite') ;
+    }
+    this._value = value ;
+    
+    // if the new value is empty, just clear the img.
+    if (!value || value.length == 0) {
+      this.rootElement.src = SC.BLANK_IMAGE_URL;
+      this.set('status', SC.IMAGE_STATE_NONE) ;
+      
+    // if a new value was set that is a URL, load the image URL.
+    } else if (SC.ImageView.valueIsUrl(value)) {
       this.beginPropertyChanges() ;
-      this.set('status','loading') ;
-      SC.imageCache.loadImage(url, this, this._onLoadComplete) ;
+      this.set('status', SC.IMAGE_STATE_LOADING) ;
+      SC.imageCache.loadImage(value, this, this._onLoadComplete) ;
       this.endPropertyChanges() ;
+      
+    // if the new is a CSS class name, set an empty image and add class name 
     } else {
-      this.rootElement.src = '' ;
-      this.set('status','unknown') ;
+      var classNames = value.split(' ');
+      var idx = classNames.length ;
+      while(--idx >= 0) this.addClassName(classNames[idx]) ;
+      this.addClassName('sc-sprite') ;
+      this.rootElement.src = SC.BLANK_IMAGE_URL ;
+      this.set('status', SC.IMAGE_STATE_LOADED) ;
     }
-  }.observes('content') ,
+  }.observes('value'),
   
+
+  /** 
+    Invoked once an image loads.  If an image has already been loaded,
+    this method will be invoked immediately.
+  */
   _onLoadComplete: function(url, status, img) {  
     this.beginPropertyChanges() ;
     this.set('imageWidth', parseInt(img.width,0)) ;
@@ -40,7 +136,7 @@ SC.ImageView = SC.View.extend({
     this.set('status',status) ;
     this.endPropertyChanges() ;
     
-    if (status == 'loaded') {
+    if (status == SC.IMAGE_STATE_LOADED) {
       if (this.imageDidLoad) this.imageDidLoad(url) ;
       this.rootElement.src =  url ;
     } else {
@@ -50,6 +146,7 @@ SC.ImageView = SC.View.extend({
   
   init: function() {
     arguments.callee.base.apply(this,arguments) ;
+    this.valueObserver() ;
     if (this.rootElement.src) {
       this.set('imageWidth',parseInt(this.rootElement.width,0)) ;
       this.set('imageHeight',parseInt(this.rootElement.height,0)) ;
@@ -58,9 +155,19 @@ SC.ImageView = SC.View.extend({
   
 }) ;
 
-// The image cache will create Image objects to preload a set of 
-// images.  This will control the number of images being loaded to maximize
-// browser throughput.
+/**
+  Returns YES if the passed value looks like an URL and not a CSS class
+  name.
+*/
+SC.ImageView.valueIsUrl = function(value) {
+  return (value.indexOf('/') >= 0) || (value.indexOf('.') >= 0) ;
+} ;
+
+/**
+  The image cache will create Image objects to preload a set of 
+  images.  This will control the number of images being loaded to maximize
+  browser throughput.
+*/
 SC.imageCache = SC.Object.create({  
   
   // this restricts the maximum number of images that can load in.
@@ -83,7 +190,7 @@ SC.imageCache = SC.Object.create({
     if (dta.img == null) {
       this._queue.push(dta) ;
       if (!this._imgTimeout) {
-        this._imgTimeout = setTimeout(this.loadNextImage.bind(this),100) ;
+        this._imgTimeout = this.invokeLater(this.loadNextImage, 100) ;
       }
     }
 

data/frameworks/sproutcore/views/inline_text_editor.js

@@ -1,6 +1,6 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 SC.inlineTextEditor = SC.View.extend({

data/frameworks/sproutcore/views/label.js

@@ -1,22 +1,113 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
+require('mixins/control') ;
+require('mixins/delegate_support');
 
-SC.LabelView = SC.View.extend({
+/**
+  @class
+  
+  Displays a static string of text.
+  
+  You use a label view anytime you need to display a static string of text 
+  or to display text that may need to be edited using only an inline control.
+  
+  @extends SC.View
+  @extends SC.Control
+  @extends SC.DelegateSupport
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.LabelView = SC.View.extend(SC.DelegateSupport, SC.Control,
+/** @scope SC.LabelView.prototype */ {
+
+  emptyElement: '<span class="sc-label-view"></span>',
 
   /**
-  * Can the label be edited using the inline editor?
-  * @type Boolean
-  **/
-  isEditable: false,
+    If true, value will be escaped to avoid scripting attacks.
+    
+    This is a default value that can be overridden by the
+    settings on the owner view.
+  */
+  escapeHtml: true,
+
+  /**
+    If true, then the value will be localized.
+    
+    This is a default default that can be overidden by the
+    settings in the owner view.
+  */
+  localize: false,
+  
   /**
-  * Is the editor open?
-  * @type Boolean
-  **/
-  isEditing: false,
+    Set this to a validator or to a function and the value
+    will be passed through it before being set.
+    
+    This is a default default that can be overidden by the
+    settings in the owner view.
+  */
+  formatter: null,
+
+  /** 
+    The value of the label.
+    
+    You may also set the value using a content object and a contentValueKey.
+    
+    @field {String}
+  */
+  value: '',
+  
+  /**
+    [RO] The value that will actually be displayed.
+    
+    This property is dynamically computed by applying localization, 
+    string conversion and other normalization utilities.
+    
+    @field
+  */
+  displayValue: function() {
+    var value = this.get('value') ;
+    
+    // 1. apply the formatter
+    var formatter = this.getDelegateProperty(this.displayDelegate, 'formatter') ;
+    if (formatter) {
+      var formattedValue = ($type(formatter) == T_FUNCTION) ? formatter(value, this) : formatter.fieldValueForObject(value, this) ;
+      if (formattedValue != null) value = formattedValue ;
+    }
+    
+    // 2. If the returned value is an array, convert items to strings and 
+    // join with commas.
+    if ($type(value) == T_ARRAY) {
+      var ary = [];
+      for(var idx=0;idx<value.get('length');idx++) {
+        var x = value.objectAt(idx) ;
+        if (x != null && x.toString) x = x.toString() ;
+        ary.push(x) ;
+      }
+      value = ary.join(',') ;
+    }
+    
+    // 3. If value is not a string, convert to string. (handles 0)
+    if (value != null && value.toString) value = value.toString() ;
+    
+    // 4. Localize
+    if (value && this.getDelegateProperty(this.displayDelegate, 'localize')) value = value.loc() ;
+    
+    return value ;
+  }.property('value'),
+  
+  /**
+    enables editing using the inline editor
+  */
+  isEditable: NO,
+
+  /**
+    YES if currently editing label view.
+  */
+  isEditing: NO,
 
 
   /**
@@ -29,24 +120,13 @@ SC.LabelView = SC.View.extend({
   */
   localize: false,
   
-  
-  /**
-  * @constructor
-  */
-  init: function()
-  {
-    arguments.callee.base.call(this) ;
-    if (this.get("localize"))
-    {
-      var inner = this.get("asHTML");
-      if (inner !== "") this.set("content", inner);
-    }
-  },
 
   /**
-  * Event dispatcher callback.
-  * If isEditable is set to true, opens the inline text editor view.
-  * @param {DOMMouseEvent} evt DOM event
+    Event dispatcher callback.
+    If isEditable is set to true, opens the inline text editor view.
+
+    @param {DOMMouseEvent} evt DOM event
+    
   */
   doubleClick: function( evt )
   {
@@ -55,30 +135,32 @@ SC.LabelView = SC.View.extend({
   
   
   /**
-  * Opens the inline text editor (closing it if it was already open for another view).
-  * @return void
-  **/
+    Opens the inline text editor (closing it if it was already open for another view).
+    
+    @return void
+  */
   beginInlineEdit: function()
   {
     if ( !this.get('isEditable') ) return;
     if ( this.get('isEditing') ) return;
     
     this.set('isEditing', true);
-    this.set("asHTML", ''); // blank out the label contents
+    this.set("innerHTML", ''); // blank out the label contents
     this.appendChild( SC.inlineTextEditor );
-    SC.inlineTextEditor.field.set('value', this.get('content'));
+    SC.inlineTextEditor.field.set('value', this.get('value'));
     SC.inlineTextEditor.field.becomeFirstResponder();
   },
   /**
-  * Closes the inline text editor.
-  * @return void
-  **/
+    Closes the inline text editor.
+    
+    @return void
+  */
   endInlineEdit: function()
   {
     if ( !this.get('isEditing') ) return;
 
     // if there were changes, then commit them... 
-    if ( SC.inlineTextEditor.field.get('value') != this.get('content') )
+    if ( SC.inlineTextEditor.field.get('value') != this.get('value') )
     {
       this._inlineEditValue = SC.inlineTextEditor.field.get('value') ;
       this._closeInlineEditor(false) ;
@@ -103,78 +185,53 @@ SC.LabelView = SC.View.extend({
     this.removeChild( SC.inlineTextEditor );
     if(!canceled)
     {
-      this.set('content',this._inlineEditValue) ;
+      this.set('value',this._inlineEditValue) ;
       this.commitInlineEdit();
     }  
     else
     {
-      this._updateValue() ; // restore value.
+      this._valueDidChange() ; // restore value.
     }  
   },
   
   // abstract method... implement to persist changes made in the editor.
   commitInlineEdit: function() {},
-
-
-  // setting this to a non-null value will cause the label to get the
-  // property value and use that for display.
-  property: function(key, value) {
-    if ((value !== undefined) && (value != this._property)) {
-      if (this._content) {
-        var func = this._boundObserver() ;
-        if (this._property && this._content && this._content.removeObserver) this._content.removeObserver(this._property,func);
-        this._property = value ;
-        if (this._property && this._content && this._content.addObserver) this._content.addObserver(this._property,func) ;
-      } else this._property = value ;
-    }
-    return this._property ;
-  }.property(),
   
-  // set to a validator object to have your content converted using the
-  // validator.  The formatter will be applied before localization.
-  formatter: null,
-  
-  // change this property value to update the content.
-  content: function(key,value) {
-    if ((value !== undefined) && (this._content != value)) {
-      var prop = this.get('property') ;
-      var func = this._boundObserver() ;
-      if (prop && this._content && this._content.removeObserver) this._content.removeObserver(prop, func) ;
-      this._content = value ;
-      if (prop && this._content && this._content.addObserver) this._content.addObserver(prop, func) ;
-      this._updateValue() ;      
-    } 
-    return this._content ;
-  }.property(),
-
-  contentBindingDefault: SC.Binding.Single,
-
-  _updateValue: function() {
-    var value = this._content ;
-    var prop = this.get('property') ;
-    if (prop && value && value.get) value = value.get(prop) ;
-
-    // apply formatter
-    var formatter = this.get('formatter') ;
-    if (formatter) {
-      var formattedValue = (SC.typeOf(formatter) == "function") ? formatter(value,this) : formatter.fieldValueForObject(value) ;
-      if (formattedValue) value = formattedValue ;
+  /** @private */
+  init: function()
+  {
+    arguments.callee.base.call(this) ;
+    
+    // if we are supposed to localize, get the content value
+    if (this.get("localize")) {
+      this.value = this._value = this.get('innerHTML').loc() ;
+      if (this.value != '') this.set('innerHTML', this.value) ;
     }
+  },
 
-    if ($type(value) == 'number') value = value.toString() ; // handle 0
+  /** 
+    @private
+    
+    Invoked whenever the monitored value on the content object 
+    changes.
     
-    // localize
-    if (value && this.get('localize')) value = value.loc() ;
-    if (value && this.get('escapeHTML') && value.escapeHTML) value = value.escapeHTML() ;
+    The value processed is either the contentValueKey, if set, or 
+    it is the content object itself.
+  */
+  _valueDidChange: function() {
+
+    var value = this.get('value') ;
+    if (value == this._value) return; // nothing to do
+
+    // get display value
+    var value = this.get('displayValue') ;
     
-    // set
-    this.set('asHTML',value || '') ;
+    // Escape HTML
+    if (this.getDelegateProperty(this.displayDelegate, 'escapeHtml')) {
+      this.set('innerText', value || '') ;
+    } else this.set('innerHTML', value || '') ;
 
-  },
+  }.observes('value')
   
-  _boundObserver: function() {
-    if (!this._observer) this._observer = this._updateValue.bind(this) ;
-    return this._observer ;
-  }
 
 });