sproutcore 0.9.10 → 0.9.11

data/frameworks/sproutcore/foundation/application.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core');
+require('core');
 require('foundation/responder');
 
 /** 

data/frameworks/sproutcore/foundation/benchmark.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/date');
 require('foundation/string') ;
 
@@ -205,7 +205,7 @@ SC.Benchmark = {
     return ret ;
   },
   
-  reset: function() { this.stats = {} ;  debugger;},
+  reset: function() { this.stats = {} ;  /*debugger;*/},
   
   // This is private, but it is used in some places, so we are keeping this for
   // compatibility.

data/frameworks/sproutcore/foundation/error.js

@@ -5,15 +5,54 @@
 
 require('foundation/object');
 
-// Error is used to communicate errors throughout the app.
-SC.Error = SC.Object.extend({
-  code: -1, // error code. Used to designate type.
-  description: '', // human readable dscriptions.
-  label: null // optionally set to human readable the name of the item with the error.
+/**
+  @class
+  
+  An error, used to represent an error state.
+  
+  Many API's within SproutCore will return an instance of this object whenever
+  they have an error occur.  An error includes an error code, description,
+  and optional human readable label that indicates the item that failed. 
+  
+  Depending on the error, other properties may also be added to the object
+  to help you recover from the failure.
+  
+  You can pass error objects to various UI elements to display the error in
+  the interface. You can easily determine if the value returned by some API is 
+  an error or not using the helper SC.$ok(value).
+  
+  @extends SC.Object
+  @since SproutCore 1.0
+*/
+SC.Error = SC.Object.extend(
+/** @scope SC.Error.prototype */ {
+  
+  /**
+    error code.  Used to designate the error type.
+  */
+  code: -1,
+  
+  /**
+    Human readable description of the error.  This can also be a non-localized
+    key.
+  */
+  description: '',
+  
+  /**
+    Human readable name of the item with the error.
+  */
+  label: null
 }) ;
 
-// this will create a new instance of the receiver with the passed 
-// description, etc.
+/**
+  Creates a new SC.Error instance with the passed description, label, and
+  code.  All parameters are optional.
+  
+  @param description {String} human readable description of the error
+  @param label {String} human readable name of the item with the error
+  @param code {Number} an error code to use for testing.
+  @returns {SC.Error} new error instance.
+*/
 SC.Error.desc = function(description, label, code) {
   var opts = { description: description } ;
   if (label !== undefined) opts.label = label ;
@@ -21,19 +60,25 @@ SC.Error.desc = function(description, label, code) {
   return this.create(opts) ;
 } ;
 
-// returns an error object.
-function $error(description, label, c) { 
+/**
+  Shorthand form of the SC.Error.desc method.
+*/
+SC.$error = function(description, label, c) { 
   return SC.Error.desc(description,label, c); 
 } ;
+var $error = SC.$error ; // export globally
 
-
-// returns true if the return value is not false or an error.
-function $ok(ret) {
+/**
+  Returns YES if the passed value is an error object, otherwise NO.
+*/
+SC.$ok = function(ret) {
   return (ret !== false) && ($type(ret) != T_ERROR) ;
-}
-
+};
+var $ok = SC.$ok ; // export globally.
 
 // STANDARD ERROR OBJECTS
 
-// Used by objects that do not support multiple values.
-SC.Error.HAS_MULTIPLE_VALUES = -100 ;
+/**
+  Standard error code for errors that do not support multiple values.
+*/
+SC.Error.HAS_MULTIPLE_VALUES = -100 ;

data/frameworks/sproutcore/foundation/input_manager.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/object') ;
 
 /** @class

data/frameworks/sproutcore/foundation/mock.js

@@ -1,4 +1,4 @@
-require('Core');
+require('core');
 require('foundation/object');
 
 /**

data/frameworks/sproutcore/foundation/node_descriptor.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 
 /**
   This object can generate HTML DOM elements from a hash-based description of 
@@ -55,5 +55,5 @@ SC.NodeDescriptor = {
   },
   
   ignoredProperties: ['tag','cssClass','id','style','childNodes','innerHTML']
-}
+};
 

data/frameworks/sproutcore/foundation/object.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/benchmark') ;
 require('mixins/observable') ;
 require('mixins/array') ;

data/frameworks/sproutcore/foundation/path_module.js

@@ -12,7 +12,7 @@
 //
 // ==========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/benchmark') ;
 
 // Constants

data/frameworks/sproutcore/foundation/responder.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/object') ;
 require('foundation/input_manager');
 

data/frameworks/sproutcore/foundation/run_loop.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 
 /**
   @class

data/frameworks/sproutcore/foundation/server.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 
 // The Server object knows how to send requests to the server and how to
 // get things back from the server.  It automatically handles situations

data/frameworks/sproutcore/foundation/string.js

@@ -154,8 +154,15 @@ Object.extend(String,
     var ret = (this.useAutodetectedLanguage) ? (this.browserLanguage || this.preferredLanguage || 'en') : (this.preferredLanguage || this.browserLanguage || 'en') ;
 
     // then try a couple of normalized forms...
-    if (!this[ret]) switch(ret)
-    {
+    if (!this[ret]) ret = this.normalizedLanguage(ret);
+    return ret ;
+  },
+  
+  /**
+    Returns a normalized language string for the two letter country code.
+  */
+  normalizedLanguage: function(ret) {
+    switch(ret) {
       case 'fr':
         ret = 'French'; 
         break ;
@@ -170,11 +177,33 @@ Object.extend(String,
         ret = 'English' ;
         break ;
       
+      case 'es':
+        ret = 'Spanish' ;
+        break;
+        
       default:
         break ;
     }
+    return ret;
+  },
+  
+  /**
+    Adds loc strings for the named language.  This method takes care of 
+    creating the localized string hash if it does not already exist.
+    The language can be one of the following or any two-letter country code.
     
-    return ret ;
+    English, French, German, Japanese, Spanish
+    
+    @param language {String} the language code
+    @param strings {Hash} hash of loc strings.
+    @returns {this}
+  */
+  addStringsFor: function(language, strings) {    
+    // convert language to a normalized name...
+    language = String.normalizedLanguage(language) ;
+    if (!String[language]) String[language] = {} ;
+    Object.extend(String[language], strings || {}); 
+    return this;
   }
 
 });

data/frameworks/sproutcore/foundation/timer.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/object');
 
 /**

data/frameworks/sproutcore/foundation/undo_manager.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008, Sprout Systems, Inc. and contributors.
 // ==========================================================================
 
-require('Core');
+require('core');
 
 /**
   @class

data/frameworks/sproutcore/globals/window.js

@@ -3,7 +3,7 @@
 // copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('Core') ;
+require('core') ;
 require('foundation/responder');
 require('panes/pane');
 

data/frameworks/sproutcore/lib/core_views.rb

@@ -195,7 +195,7 @@ view_helper :image_view do
   property :value
   
   attribute :src, static_url('blank')
-  
+  attribute :alt, ''
   var :tag, 'img'
   css_class_names << 'sc-image-view'
 end

data/frameworks/sproutcore/lib/index.rhtml

@@ -21,10 +21,16 @@
 	 # stylesheets, you don't need to change it here.  Instead, use the
 	 # :requires option in routes.rb. 
 -%>
+    <script src="<%= static_url('detect-browser') %>" type="text/javascript"></script>
+    
     <%= stylesheets_for_client %>
 <%= @content_for_page_styles %>
   </head>
-  <body class="<%= @theme || 'sc-theme' %> focus">    
+  <body class="<%= @theme || 'sc-theme' %> focus">  
+    <script>
+    if (SC.setupBodyClassNames) SC.setupBodyClassNames() ;
+    </script>
+      
 <% #
    # This is where you root body element will appear.  To cause your 
    # content to appear here, just declare content_for('body') in one of

data/frameworks/sproutcore/mixins/observable.js

@@ -518,7 +518,6 @@ SC.Observable = {
     Adds an observer on a property.
     
     This is the core method used to register an observer for a property.
-    The observer can be either a simple function or an object and a method.
     
     Once you call this method, anytime the key's value is set, your observer
     will be notified.  Note that the observers are triggered anytime the
@@ -526,9 +525,8 @@ SC.Observable = {
     observer should be prepared to handle that.
     
     @param key {String} the key to observer
-    @param target {Object} the object holding the action to call.  May benull.
-    @param action {String,Function} the action to call.
-    @returns {void}
+    @param func {String} the function to call when the key changes.
+    @returns {SC.Object}
   */
   addObserver: function(key,func) {
     var kvo = this._kvo() ;
@@ -550,6 +548,8 @@ SC.Observable = {
       while(!found && --loc >= 0) found = (observers[loc] == func) ;
       if (!found) observers.push(func) ;
     }
+    
+    return this;
 
   },
 
@@ -573,6 +573,8 @@ SC.Observable = {
       observers = observers.without(func) ;
       kvo.observers[key] = observers ;
     }
+    
+    return this;
   },
 
   addProbe: function(key) { this.addObserver(key,logChange); },
@@ -745,10 +747,116 @@ SC.Observable = {
 // FUNCTION ENHANCEMENTS
 //
 // Enhance function.
-Object.extend(Function.prototype,{
+Object.extend(Function.prototype,
+/** @scope Function.prototype */ {
   
-  // Declare a function as a property.  This makes it something that can be
-  // accessed via get/set.
+  /**
+    Indicates that the function should be treated as a computed property.
+    
+    Computed properties are methods that you want to treat as if they were
+    static properties.  When you use get() or set() on a computed property,
+    the object will call the property method and return its value instead of 
+    returning the method itself.  This makes it easy to create "virtual 
+    properties" that are computed dynamically from other properties.
+    
+    Consider the following example:
+    
+    {{{
+      contact = SC.Object.create({
+
+        firstName: "Charles",
+        lastName: "Jolley",
+        
+        // This is a computed property!
+        fullName: function() {
+          return this.getEach('firstName','lastName').compact().join(' ') ;
+        }.property('firstName', 'lastName'),
+        
+        // this is not
+        getFullName: function() {
+          return this.getEach('firstName','lastName').compact().join(' ') ;
+        }
+      });
+
+      contact.get('firstName') ;
+      --> "Charles"
+      
+      contact.get('fullName') ;
+      --> "Charles Jolley"
+      
+      contact.get('getFullName') ;
+      --> function()
+    }}}
+    
+    Note that when you get the fullName property, SproutCore will call the
+    fullName() function and return its value whereas when you get() a property
+    that contains a regular method (such as getFullName above), then the 
+    function itself will be returned instead.
+    
+    h2. Using Dependent Keys
+
+    Computed properties are often computed dynamically from other member 
+    properties.  Whenever those properties change, you need to notify any
+    object that is observing the computed property that the computed property
+    has changed also.  We call these properties the computed property is based
+    upon "dependent keys".
+    
+    For example, in the contact object above, the fullName property depends on
+    the firstName and lastName property.  If either property value changes,
+    any observer watching the fullName property will need to be notified as 
+    well.
+    
+    You inform SproutCore of these dependent keys by passing the key names
+    as parameters to the property() function.  Whenever the value of any key
+    you name here changes, the computed property will be marked as changed
+    also.
+    
+    You should always register dependent keys for computed properties to 
+    ensure they update.
+    
+    h2. Using Computed Properties as Setters
+    
+    Computed properties can be used to modify the state of an object as well
+    as to return a value.  Unlike many other key-value system, you use the 
+    same method to both get and set values on a computed property.  To 
+    write a setter, simply declare two extra parameters: key and value.
+    
+    Whenever your property function is called as a setter, the value 
+    parameter will be set.  Whenever your property is called as a getter the
+    value parameter will be undefined.
+    
+    For example, the following object will split any full name that you set
+    into a first name and last name components and save them.
+    
+    {{{
+      contact = SC.Object.create({
+        
+        fullName: function(key, value) {
+          if (value !== undefined) {
+            var parts = value.split(' ') ;
+            this.beginPropertyChanges()
+              .set('firstName', parts[0])
+              .set('lastName', parts[1])
+            .endPropertyChanges() ;
+          }
+          return this.getEach('firstName', 'lastName').compact().join(' ');
+        }.property('firstName','lastName')
+        
+      }) ;
+      
+    }}}
+    
+    bq. *Why Use The Same Method for Getters and Setters?*  Most property-
+    based frameworks expect you to write two methods for each property but
+    SproutCore only uses one.  We do this because most of the time when
+    you write a setter is is basically a getter plus some extra work.  There 
+    is little added benefit in writing both methods when you can conditionally
+    exclude part of it.  This helps to keep your code more compact and easier
+    to maintain.
+    
+    @param dependentKeys {String...} optional set of dependent keys
+    @returns {Function} the declared function instance
+  */
   property: function() {
     this.dependentKeys = $A(arguments) ; 
     this.isProperty = true; return this;