sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/views/list_item.js

@@ -0,0 +1,225 @@
+// ==========================================================================
+// SC.ListItemView
+// ==========================================================================
+
+require('Core') ;
+require('views/view') ;
+require('mixins/control');
+
+SC.LIST_ITEM_ACTION_CANCEL = 'sc-list-item-cancel-action';
+SC.LIST_ITEM_ACTION_REFRESH = 'sc-list-item-cancel-refresh';
+SC.LIST_ITEM_ACTION_EJECT = 'sc-list-item-cancel-eject';
+
+/** @class
+
+  Displays a list item with a label, optional icon, count, and right icon.
+
+  @extends SC.View
+  @extends SC.Control
+  @author    AuthorName  
+  @version 0.1
+*/
+SC.ListItemView = SC.View.extend(SC.Control,
+/** @scope SC.ListItemView.prototype */ {
+  
+  /** A ListItemView has an img tag, label, count, optional right button, and
+    an optional right arrow.  These items are made visible/hidden based on a
+    variety of CSS classes.
+  */
+  emptyElement: '<div class="sc-list-item-view sc-collection-item"></div>',
+  
+  /**
+    The content object the list item will display.
+  */
+  content: null,
+  
+  /**
+    (displayDelegate) True if you want the item view to display an icon.
+    
+    If false, the icon on the list item view will be hidden.  Otherwise,
+    space will be left for the icon next to the list item view.
+  */
+  hasContentIcon: NO,
+  
+  /**
+    (displayDelegate) True if you want space to be allocated for a branch 
+    arrow.
+    
+    If false, the space for the branch arrow will be collapsed.
+  */
+  hasContentBranch: NO,
+  
+  /**
+    (displayDelegate) Property key to use for the icon url
+
+    This property will be checked on the content object to determine the 
+    icon to display.  It must return either a URL or a CSS class name.
+  */
+  contentIconKey: null,
+  
+  /**
+    (displayDelegate) The name of the property used for label itself
+    
+    If null, then the content object itself will be used..
+  */
+  contentValueKey: null,
+  
+  /**
+    (displayDelegate) The name of the property used to find the count of 
+    unread items. 
+    
+    The count will only be visible if this property is not null and the 
+    returned value is not 0.
+  */
+  contentUnreadCountKey: null,
+  
+  /**
+    (displayDelegate) The name of the property used to determine if the item
+    is a branch or leaf (i.e. if the branch icon should be displayed to the
+    right edge.)
+    
+    If this is null, then the branch view will be completely hidden.
+    Otherwise space will be allocated for it.
+  */
+  contentIsBranchKey: null,
+  
+  
+  contentPropertyDidChange: function() {
+    this.render() ;  
+  },
+  
+  
+  /**
+    Regenerates the innerHTML for this view and updates it if necessary.
+  */
+  render: function() {
+    var html = [] ;
+    var content = this.get('content') ;
+    var del = this.displayDelegate ;
+    
+    // handle icon
+    if (this.getDelegateProperty(del, 'hasContentIcon')) {
+       var iconKey = this.getDelegateProperty(del,'contentIconKey') ;
+       var icon = (iconKey && content && content.get) ? content.get(iconKey) : null ;
+       html.push(this.renderIconHTML(icon));
+    }
+    
+    // handle label
+    var labelKey = this.getDelegateProperty(del, 'contentValueKey') ;
+    var label = (labelKey && content && content.get) ? content.get(labelKey) : null ;
+    html.push(this.renderLabelHTML(label));
+    
+    // handle unread count
+    var countKey = this.getDelegateProperty(del, 'contentUnreadCountKey') ;
+    var count = (countKey && content && content.get) ? content.get(countKey) : null ;
+    if ((count != null) && (count != 0)) {
+      html.push(this.renderCountHTML(count));
+    }
+    
+    // handle action 
+    var actionKey = this.getDelegateProperty(del, 'listItemActionProperty') ;
+    var actionClassName = (actionKey && content && content.get) ? content.get(actionKey) : null ;
+    if (actionClassName) {
+       html.push(this.renderActionHTML(actionClassName));
+    }
+    this.setClassName('sc-has-action', actionClassName) ;
+    
+    // handle branch
+    if (this.getDelegateProperty(del, 'hasContentBranch')) {
+      var branchKey = this.getDelegateProperty(del, 'contentIsBranchKey');
+      var hasBranch = (branchKey && content && content.get) ? content.get(branchKey) : false ;
+      html.push(this.renderBranchHTML(hasBranch));
+      this.setClassName('sc-has-branch', true) ;
+    } else this.setClassName('sc-has-branch', false) ;
+    
+    html = html.join('') ;
+    if (html != this._lastRenderedHtml) {
+      this._lastRenderedHtml = html ;
+      this.set('innerHTML', html) ;
+    }
+  },
+  
+  /** 
+     renderIconHTML generates the html string used to represent the icon for your 
+     list item.  override this to return your own custom HTML
+     @returns {String}
+     @arguments {String} the icon property based on your view's contentIconKey
+   */
+   renderIconHTML: function(icon){
+     var html = [];
+     // get a class name and url to include if relevant
+     var url = null, className = null ;
+     if (icon && SC.ImageView.valueIsUrl(icon)) {
+       url = icon; className = '' ;
+     } else {
+       className = icon; url = static_url('blank.gif') ;
+     }
+     html.push('<img class="sc-icon ');
+     html.push(className || '');
+     html.push('" src="');
+     html.push(url || static_url('blank.gif')) ;
+     html.push('" />') ;
+     html=html.join('');
+     return html;
+   },
+   
+   /** 
+       renderLabelHTML generates the html string used to represent the label for your 
+       list item.  override this to return your own custom HTML
+       @returns {String}
+       @arguments {String} the label property based on your view's contentValueKey
+     */
+   renderLabelHTML: function(label){
+     var html = [];
+     html.push('<span class="sc-label">') ;
+     html.push(label || '') ;
+     html.push('</span>') ;
+     return html.join('');    
+   },
+   
+   /** 
+        renderCountHTML generates the html string used to represent the count (like unread count)
+        for your list item.  override this to return your own custom HTML
+        @returns {String}
+        @arguments {Integer} the label property based on your view's contentValueKey
+    */
+   renderCountHTML: function(count) {
+     var html= [];
+      html.push('<span class="sc-count"><span class="inner">') ;
+       html.push(count.toString()) ;
+       html.push('</span></span>') ;
+       return html.join('');
+   },
+   
+   /** 
+        renderActiontHTML generates the html string used to represent the action item
+        for your list item.  override this to return your own custom HTML
+        @returns {String}
+        @arguments {String} the name of the action item.
+    */
+   renderActionHTML: function(actionClassName){
+     var html = [];
+     html.push('<img src="') ;
+     html.push(static_url('blank.gif')) ;
+     html.push('" class="sc-action" />') ;
+     return html.join('');
+   },
+   
+   /** 
+         renderBranchHTML generates the html string used to represent the branch arrow.
+         override this to return your own custom HTML
+         @returns {String}
+         @arguments {Boolean} whehter the branch is 
+   */
+   
+   renderBranchHTML: function(hasBranch) {
+     var html = [];
+     html.push('<span class="sc-branch ');
+     html.push(hasBranch ? 'sc-branch-visible' : 'sc-branch-hidden') ;
+     html.push('">&nbsp;</span>');
+     return html.join('');
+   }
+  
+  
+  
+}) ;

data/frameworks/sproutcore/views/menu_item.js

@@ -1,13 +1,19 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
 
-// This is a basic menu item for inclusion in a popup menu.  This is a type
-// of button that will automatically close the popup menu when it is
-// pressed.
+/** @class
+
+  This is a basic menu item for inclusion in a popup menu.  This is a type
+  of button that will automatically close the popup menu when it is
+  pressed.
+  
+  @extends SC.ButtonView
+  
+*/
 SC.MenuItemView = SC.ButtonView.extend({
 
   emptyElement: [

data/frameworks/sproutcore/views/pagination.js

@@ -1,14 +1,21 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
 require('controllers/collection') ;
 
-// A pagination view renders a widget for showing the total number of pages and
-// for switching between them.  It includes a forward arrow, back arrow, and
-// a popup.
+/**
+
+  @class
+
+  A pagination view renders a widget for showing the total number of pages and
+  for switching between them.  It includes a forward arrow, back arrow, and
+  a popup.
+  
+  @extends SC.View
+*/
 SC.PaginationView = SC.View.extend({
 
   // ......................................

data/frameworks/sproutcore/views/popup_button.js

@@ -1,19 +1,22 @@
-require('views/button') ;
+require('views/button/button') ;
 
 /**
-* @class
-* @constructor
-* @extends SC.ButtonView
-* @author Skip Baney
-* @copyright 2006-2007, Sprout Systems, Inc. and contributors.
-* @version 0.1
+  @class
+
+  @extends SC.ButtonView
+  @author Skip Baney
+  @copyright 2006-2008, Sprout Systems, Inc. and contributors.
+  @version 1.0
 */
 SC.PopupButtonView = SC.ButtonView.extend({
 
   /**
-  * Overriding the default SC.ButtonView#performKeyEquivalent method to pass it onto the menu
-  * @param {string} keystring method name corresponding to the keys pressed (i.e alt_shift_z)
-  * @param {DOMMouseEvent} evt mousedown event
+    Overriding the default SC.ButtonView#performKeyEquivalent method to pass 
+    it onto the menu
+
+    @param {string} keystring method name corresponding to the keys pressed 
+    (i.e alt_shift_z)
+    @param {DOMMouseEvent} evt mousedown event
   */
   performKeyEquivalent: function( keystring, evt )
   {
@@ -28,14 +31,14 @@ SC.PopupButtonView = SC.ButtonView.extend({
   },
   
   /**
-  * Name of the menu view to use.
-  * @type {string}
+    Name of the menu view to use.
+    @type {string}
   */
   menuName: null,
 
   /**
-  * PopupMenu reference. Will be lazy-loaded from the 'menuName' string.
-  * @type {SC.PopupMenu}
+    PopupMenu reference. Will be lazy-loaded from the 'menuName' string.
+    @type {SC.PopupMenu}
   */
   menu: function( key, value )
   {
@@ -53,15 +56,16 @@ SC.PopupButtonView = SC.ButtonView.extend({
     }
     return this._menu;
   }.property(),
+  
   /**
-  * Binds the button's selection state to the menu's visibility.
-  * @private
+    Binds the button's selection state to the menu's visibility.
+    @private
   */
   isSelectedBinding: '*_menu.isVisible',
   
   /**
-  * Button action handler
-  * @param {DOMMouseEvent} evt mouseup event that triggered the action
+    Button action handler
+    @param {DOMMouseEvent} evt mouseup event that triggered the action
   */
   action: function( evt )
   {
@@ -70,9 +74,9 @@ SC.PopupButtonView = SC.ButtonView.extend({
     if (!menu) return false;
     
     if (!this._didFirstRun) {
-      // for some reason the menu#isVisible is true the first time we get it...
-      // and since this#isSelected is bound to it... we get an incorrect conditional check.
-      // hacking it here to keep moving.
+      // for some reason the menu#isVisible is true the first time we get 
+      // it... and since this#isSelected is bound to it... we get an incorrect 
+      // conditional check. hacking it here to keep moving.
       menu.popup(this, evt);
       this._didFirstRun = true;
     } else {

data/frameworks/sproutcore/views/popup_menu.js

@@ -1,13 +1,19 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
 
-// This is a basic popup menu. You can show the popup menu by calling the 
-// view's popup() method.  Pass in the root element and event so that is can
-// be positioned.
+/**
+  @class
+  
+  This is a basic popup menu. You can show the popup menu by calling the 
+  view's popup() method.  Pass in the root element and event so that is can
+  be positioned.
+  
+  @extends SC.View
+*/
 SC.PopupMenuView = SC.View.extend({
   emptyElement: "<ul></ul>",
   

data/frameworks/sproutcore/views/progress.js

@@ -1,32 +1,45 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
 
-// ProgressView displays a progress bar.  It does this mostly through CSS classes
-// so that you can style them however you want.  A progress bar must have the
-// following structure:
-//
-// <div class="outer progress"><div class="inner"></div></div>
-//
-// The outer can form the boundary of the bar while the inner will be adjusted 
-// to fit the percentage of the progress.
-//
-// Style the progress bar with the following CSS classes:
-//
-// .progress.indeterminate = to show an indeterminate progress. inner will hide.
-// .progress.disabled = show as disabled.
+/**
+  @class
 
+  ProgressView displays a progress bar.  It does this mostly through CSS 
+  classes so that you can style them however you want.  A progress bar must 
+  have the following structure:
+
+  <div class="outer progress"><div class="inner"></div></div>
+
+  The outer can form the boundary of the bar while the inner will be adjusted 
+  to fit the percentage of the progress.
+
+  Style the progress bar with the following CSS classes:
+
+  .progress.indeterminate = to show an indeterminate progress. inner will 
+      hide.
+  .progress.disabled = show as disabled.
+
+  @extends SC.View
+*/
 SC.ProgressView = SC.View.extend({
   
   // ........................................
   // PROPERTIES
   //
   
-  minimum: 0, // the minimum value of the progress 
-  maximum: 1.0, // the maximum value of the progress bar.
+  /**
+    The minimum value of the progress.
+  */ 
+  minimum: 0,
+
+  /**
+    The maximum value of the progress bar.
+  */
+  maximum: 1.0,
 
   // Bind this to the current value of the progress bar.  Note that by default an
   // empty value will disable the progress bar and a multiple value too make it