From 6207eecbcf567e0f745955ee2554b752f08c0862 Mon Sep 17 00:00:00 2001 From: Piotr Sarnacki Date: Wed, 26 Sep 2012 15:06:34 +0200 Subject: [PATCH 01/13] Add foreman and rerun to Gemfile --- Gemfile | 5 +++++ Gemfile.lock | 6 ++++++ 2 files changed, 11 insertions(+) diff --git a/Gemfile b/Gemfile index f2716cfb..f4014fb7 100644 --- a/Gemfile +++ b/Gemfile @@ -24,3 +24,8 @@ group :assets do gem 'tilt' gem 'guard' end + +group :development do + gem 'foreman' + gem 'rerun' +end diff --git a/Gemfile.lock b/Gemfile.lock index 128f6eb6..43f06f14 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -140,6 +140,8 @@ GEM multi_json (~> 1.0) faraday (0.8.4) multipart-post (~> 1.1) + foreman (0.59.0) + thor (>= 0.13.6) fssm (0.2.9) guard (1.3.3) listen (>= 0.4.2) @@ -202,6 +204,8 @@ GEM json (~> 1.4) redcarpet (2.1.1) redis (3.0.1) + rerun (0.7.1) + listen rollout (1.1.0) sass (3.2.1) signature (0.1.4) @@ -246,6 +250,7 @@ DEPENDENCIES bunny coffee-script compass + foreman gh! guard hubble! @@ -253,6 +258,7 @@ DEPENDENCIES pg (~> 0.13.2) rake-pipeline! rake-pipeline-web-filters! + rerun sinatra sinatra-contrib tilt From b31515fa579b10ad2e5c275468201ea55630577a Mon Sep 17 00:00:00 2001 From: Piotr Sarnacki Date: Wed, 26 Sep 2012 15:07:52 +0200 Subject: [PATCH 02/13] Update ember and ember-data --- assets/javascripts/vendor/ember-data.js | 23 +- assets/javascripts/vendor/ember.js | 7919 +++++++++++++--------- public/javascripts/vendor.js | 8008 ++++++++++++++--------- 3 files changed, 9533 insertions(+), 6417 deletions(-) diff --git a/assets/javascripts/vendor/ember-data.js b/assets/javascripts/vendor/ember-data.js index 823d77df..1252eb43 100644 --- a/assets/javascripts/vendor/ember-data.js +++ b/assets/javascripts/vendor/ember-data.js @@ -1748,6 +1748,7 @@ DS.Store = Ember.Object.extend({ loadMany: function(type, ids, hashes) { var clientIds = Ember.A([]); + if (hashes === undefined) { hashes = ids; ids = []; @@ -3131,8 +3132,8 @@ DS.Model = Ember.Object.extend(Ember.Evented, { if (cachedValue) { var key = association.options.key || get(this, 'namingConvention').keyToJSONKey(name), ids = data.get(key) || []; - - var clientIds; + + var clientIds; if(association.options.embedded) { clientIds = store.loadMany(association.type, ids).clientIds; } else { @@ -3140,7 +3141,7 @@ DS.Model = Ember.Object.extend(Ember.Evented, { return store.clientIdForId(association.type, id); }); } - + set(cachedValue, 'content', Ember.A(clientIds)); cachedValue.fetch(); } @@ -3155,7 +3156,7 @@ DS.Model = Ember.Object.extend(Ember.Evented, { also call methods with the given name. */ trigger: function(name) { - this[name].apply(this, [].slice.call(arguments, 1)); + Ember.tryInvoke(this, name, [].slice.call(arguments, 1)); this._super.apply(this, arguments); } }); @@ -3671,8 +3672,8 @@ DS.Adapter = Ember.Object.extend({ (function() { var set = Ember.set; -Ember.onLoad('application', function(app) { - app.registerInjection({ +Ember.onLoad('Ember.Application', function(Application) { + Application.registerInjection({ name: "store", before: "controllers", @@ -3683,11 +3684,11 @@ Ember.onLoad('application', function(app) { } }); - app.registerInjection({ + Application.registerInjection({ name: "giveStoreToControllers", injection: function(app, stateManager, property) { - if (property.match(/Controller$/)) { + if (/^[A-Z].*Controller$/.test(property)) { var controllerName = property.charAt(0).toLowerCase() + property.substr(1); var store = stateManager.get('store'); var controller = stateManager.get(controllerName); @@ -3765,7 +3766,7 @@ DS.FixtureAdapter = DS.Adapter.extend({ return ids.indexOf(item.id) !== -1; }); } - + if (fixtures) { this.simulateRemoteCall(function() { store.loadMany(type, fixtures); @@ -3785,7 +3786,7 @@ DS.FixtureAdapter = DS.Adapter.extend({ findQuery: function(store, type, query, array) { var fixtures = this.fixturesForType(type); - + Ember.assert("Unable to find fixtures for model type "+type.toString(), !!fixtures); fixtures = this.queryFixtures(fixtures, query); @@ -3846,7 +3847,7 @@ var get = Ember.get, set = Ember.set; DS.RESTAdapter = DS.Adapter.extend({ bulkCommit: false, - + createRecord: function(store, type, record) { var root = this.rootForType(type); diff --git a/assets/javascripts/vendor/ember.js b/assets/javascripts/vendor/ember.js index d34c1bb4..84635130 100644 --- a/assets/javascripts/vendor/ember.js +++ b/assets/javascripts/vendor/ember.js @@ -1,10 +1,21 @@ -// Version: v1.0.pre -// Last commit: 7955b85 (2012-08-03 14:50:17 -0700) +// Version: v1.0.pre-137-gaffa940 +// Last commit: affa940 (2012-09-15 21:25:55 +0200) (function() { /*global __fail__*/ +/** +Ember Debug + +@module ember +@submodule ember-debug +*/ + +/** +@class Ember +*/ + if ('undefined' === typeof Ember) { Ember = {}; @@ -29,15 +40,12 @@ if (!('MANDATORY_SETTER' in Ember.ENV)) { // Fail unconditionally Ember.assert('This code path should never be run') - @static - @function - @param {String} desc - A description of the assertion. This will become the text of the Error - thrown if the assertion fails. + @method assert + @param {String} desc A description of the assertion. This will become + the text of the Error thrown if the assertion fails. - @param {Boolean} test - Must be truthy for the assertion to pass. If falsy, an exception will be - thrown. + @param {Boolean} test Must be truthy for the assertion to pass. If + falsy, an exception will be thrown. */ Ember.assert = function(desc, test) { if (!test) throw new Error("assertion failed: "+desc); @@ -48,13 +56,10 @@ Ember.assert = function(desc, test) { Display a warning with the provided message. Ember build tools will remove any calls to Ember.warn() when doing a production build. - @static - @function - @param {String} message - A warning to display. - - @param {Boolean} test - An optional boolean. If falsy, the warning will be displayed. + @method warn + @param {String} message A warning to display. + @param {Boolean} test An optional boolean. If falsy, the warning + will be displayed. */ Ember.warn = function(message, test) { if (!test) { @@ -68,13 +73,10 @@ Ember.warn = function(message, test) { (Chrome and Firefox only). Ember build tools will remove any calls to Ember.deprecate() when doing a production build. - @static - @function - @param {String} message - A description of the deprecation. - - @param {Boolean} test - An optional boolean. If falsy, the deprecation will be displayed. + @method deprecate + @param {String} message A description of the deprecation. + @param {Boolean} test An optional boolean. If falsy, the deprecation + will be displayed. */ Ember.deprecate = function(message, test) { if (Ember && Ember.TESTING_DEPRECATION) { return; } @@ -119,13 +121,9 @@ Ember.deprecate = function(message, test) { Ember build tools will not remove calls to Ember.deprecateFunc(), though no warnings will be shown in production. - @static - @function - @param {String} message - A description of the deprecation. - - @param {Function} func - The function to be deprecated. + @method deprecateFunc + @param {String} message A description of the deprecation. + @param {Function} func The function to be deprecated. */ Ember.deprecateFunc = function(message, func) { return function() { @@ -142,29 +140,19 @@ window.ember_deprecateFunc = Ember.deprecateFunc("ember_deprecateFunc is deprec })(); -// Version: v1.0.pre-5-gf1ec52a -// Last commit: f1ec52a (2012-08-06 17:23:55 -0700) +// Version: v1.0.pre-137-gaffa940 +// Last commit: affa940 (2012-09-15 21:25:55 +0200) (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Em:true ENV */ -if ('undefined' === typeof Ember) { - // Create core object. Make it act like an instance of Ember.Namespace so that - // objects assigned to it are given a sane string representation. - Ember = {}; -} +/** +@module ember +@submodule ember-metal +*/ /** - @namespace - @name Ember - @version 1.0.pre - All Ember methods and functions are defined inside of this namespace. You generally should not add new properties to this namespace as it may be overwritten by future versions of Ember. @@ -179,8 +167,18 @@ if ('undefined' === typeof Ember) { The core Runtime framework is based on the jQuery API with a number of performance optimizations. + + @class Ember + @static + @version 1.0.pre */ +if ('undefined' === typeof Ember) { + // Create core object. Make it act like an instance of Ember.Namespace so that + // objects assigned to it are given a sane string representation. + Ember = {}; +} + // aliases needed to keep minifiers from removing the global context if ('undefined' !== typeof window) { window.Em = window.Ember = Em = Ember; @@ -194,21 +192,20 @@ Ember.toString = function() { return "Ember"; }; /** - @static + @property VERSION @type String @default '1.0.pre' - @constant + @final */ Ember.VERSION = '1.0.pre'; /** - @static - @type Hash - @constant - Standard environmental variables. You can define these in a global `ENV` variable before loading Ember to control various configuration settings. + + @property ENV + @type Hash */ Ember.ENV = Ember.ENV || ('undefined' === typeof ENV ? {} : ENV); @@ -219,11 +216,6 @@ Ember.config = Ember.config || {}; // /** - @static - @type Boolean - @default true - @constant - Determines whether Ember should enhances some built-in object prototypes to provide a more friendly API. If enabled, a few methods will be added to Function, String, and Array. Object.prototype will not be @@ -232,50 +224,46 @@ Ember.config = Ember.config || {}; In general we recommend leaving this option set to true since it rarely conflicts with other code. If you need to turn it off however, you can define an ENV.EXTEND_PROTOTYPES config to disable it. + + @property EXTEND_PROTOTYPES + @type Boolean + @default true */ Ember.EXTEND_PROTOTYPES = (Ember.ENV.EXTEND_PROTOTYPES !== false); /** - @static + Determines whether Ember logs a full stack trace during deprecation warnings + + @property LOG_STACKTRACE_ON_DEPRECATION @type Boolean @default true - @constant - - Determines whether Ember logs a full stack trace during deprecation warnings */ Ember.LOG_STACKTRACE_ON_DEPRECATION = (Ember.ENV.LOG_STACKTRACE_ON_DEPRECATION !== false); /** - @static + Determines whether Ember should add ECMAScript 5 shims to older browsers. + + @property SHIM_ES5 @type Boolean @default Ember.EXTEND_PROTOTYPES - @constant - - Determines whether Ember should add ECMAScript 5 shims to older browsers. */ Ember.SHIM_ES5 = (Ember.ENV.SHIM_ES5 === false) ? false : Ember.EXTEND_PROTOTYPES; /** - @static - @type Boolean - @default true - @constant - Determines whether computed properties are cacheable by default. This option will be removed for the 1.1 release. When caching is enabled by default, you can use `volatile()` to disable caching on individual computed properties. + + @property CP_DEFAULT_CACHEABLE + @type Boolean + @default true */ Ember.CP_DEFAULT_CACHEABLE = (Ember.ENV.CP_DEFAULT_CACHEABLE !== false); /** - @static - @type Boolean - @default true - @constant - Determines whether views render their templates using themselves as the context, or whether it is inherited from the parent. This option will be removed in the 1.1 release. @@ -283,42 +271,47 @@ Ember.CP_DEFAULT_CACHEABLE = (Ember.ENV.CP_DEFAULT_CACHEABLE !== false); If you need to update your application to use the new context rules, simply prefix property access with `view.`: - // Before: - {{#each App.photosController}} - Photo Title: {{title}} - {{#view App.InfoView contentBinding="this"}} - {{content.date}} - {{content.cameraType}} - {{otherViewProperty}} - {{/view}} - {{/each}} + Before: - // After: - {{#each App.photosController}} - Photo Title: {{title}} - {{#view App.InfoView}} - {{date}} - {{cameraType}} - {{view.otherViewProperty}} - {{/view}} - {{/each}} + ``` handlebars + {{#each App.photosController}} + Photo Title: {{title}} + {{#view App.InfoView contentBinding="this"}} + {{content.date}} + {{content.cameraType}} + {{otherViewProperty}} + {{/view}} + {{/each}} + ``` + + After: + + ``` handlebars + {{#each App.photosController}} + Photo Title: {{title}} + {{#view App.InfoView}} + {{date}} + {{cameraType}} + {{view.otherViewProperty}} + {{/view}} + {{/each}} + ``` + + @property VIEW_PRESERVES_CONTEXT + @type Boolean + @default true */ Ember.VIEW_PRESERVES_CONTEXT = (Ember.ENV.VIEW_PRESERVES_CONTEXT !== false); /** Empty function. Useful for some operations. - @returns {Object} + @method K @private + @return {Object} */ Ember.K = function() { return this; }; -/** - @namespace - @name window - @description The global window object -*/ - // Stub out the methods defined by the ember-debug package in case it's not loaded @@ -335,7 +328,6 @@ if ('undefined' === typeof ember_assert) { window.ember_assert = Ember.K; } if ('undefined' === typeof ember_warn) { window.ember_warn = Ember.K; } if ('undefined' === typeof ember_deprecate) { window.ember_deprecate = Ember.K; } if ('undefined' === typeof ember_deprecateFunc) { - /** @private */ window.ember_deprecateFunc = function(_, func) { return func; }; } @@ -345,13 +337,53 @@ if ('undefined' === typeof ember_deprecateFunc) { // /** - @class - Inside Ember-Metal, simply uses the window.console object. Override this to provide more robust logging functionality. + + @class Logger + @namespace Ember */ Ember.Logger = window.console || { log: Ember.K, warn: Ember.K, error: Ember.K, info: Ember.K, debug: Ember.K }; + +// .......................................................... +// ERROR HANDLING +// + +/** + A function may be assigned to `Ember.onerror` to be called when Ember internals encounter an error. + This is useful for specialized error handling and reporting code. + + @event onerror + @for Ember + @param {Exception} error the error object +*/ +Ember.onerror = null; + +/** + @private + + Wrap code block in a try/catch if {{#crossLink "Ember/onerror"}}{{/crossLink}} is set. + + @method handleErrors + @for Ember + @param {Function} func + @param [context] +*/ +Ember.handleErrors = function(func, context) { + // Unfortunately in some browsers we lose the backtrace if we rethrow the existing error, + // so in the event that we don't have an `onerror` handler we don't wrap in a try/catch + if ('function' === typeof Ember.onerror) { + try { + return func.apply(context || this); + } catch (error) { + Ember.onerror(error); + } + } else { + return func.apply(context || this); + } +}; + })(); @@ -359,20 +391,22 @@ Ember.Logger = window.console || { log: Ember.K, warn: Ember.K, error: Ember.K, (function() { /*jshint newcap:false*/ +/** +@module ember-metal +*/ + // NOTE: There is a bug in jshint that doesn't recognize `Object()` without `new` // as being ok unless both `newcap:false` and not `use strict`. // https://github.com/jshint/jshint/issues/392 // Testing this is not ideal, but we want to use native functions // if available, but not to use versions created by libraries like Prototype -/** @private */ var isNativeFunc = function(func) { // This should probably work in all browsers likely to have ES5 array methods return func && Function.prototype.toString.call(func).indexOf('[native code]') > -1; }; // From: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/array/map -/** @private */ var arrayMap = isNativeFunc(Array.prototype.map) ? Array.prototype.map : function(fun /*, thisp */) { //"use strict"; @@ -398,7 +432,6 @@ var arrayMap = isNativeFunc(Array.prototype.map) ? Array.prototype.map : functio }; // From: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/array/foreach -/** @private */ var arrayForEach = isNativeFunc(Array.prototype.forEach) ? Array.prototype.forEach : function(fun /*, thisp */) { //"use strict"; @@ -420,7 +453,6 @@ var arrayForEach = isNativeFunc(Array.prototype.forEach) ? Array.prototype.forEa } }; -/** @private */ var arrayIndexOf = isNativeFunc(Array.prototype.indexOf) ? Array.prototype.indexOf : function (obj, fromIndex) { if (fromIndex === null || fromIndex === undefined) { fromIndex = 0; } else if (fromIndex < 0) { fromIndex = Math.max(0, this.length + fromIndex); } @@ -464,17 +496,14 @@ var utils = Ember.EnumerableUtils = { if (Ember.SHIM_ES5) { if (!Array.prototype.map) { - /** @private */ Array.prototype.map = arrayMap; } if (!Array.prototype.forEach) { - /** @private */ Array.prototype.forEach = arrayForEach; } if (!Array.prototype.indexOf) { - /** @private */ Array.prototype.indexOf = arrayIndexOf; } } @@ -484,30 +513,29 @@ if (Ember.SHIM_ES5) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Node */ /** - @class +@module ember-metal +*/ +/** Platform specific methods and feature detectors needed by the framework. - @name Ember.platform + @class platform + @namespace Ember + @static */ var platform = Ember.platform = {}; + /** Identical to Object.create(). Implements if not available natively. - @memberOf Ember.platform - @name create + @method create + @for Ember */ Ember.create = Object.create; if (!Ember.create) { - /** @private */ var K = function() {}; Ember.create = function(obj, props) { @@ -528,7 +556,6 @@ if (!Ember.create) { Ember.create.isSimulated = true; } -/** @private */ var defineProperty = Object.defineProperty; var canRedefineProperties, canDefinePropertyOnDOM; @@ -537,7 +564,6 @@ if (defineProperty) { try { defineProperty({}, 'a',{get:function(){}}); } catch (e) { - /** @private */ defineProperty = null; } } @@ -545,7 +571,6 @@ if (defineProperty) { if (defineProperty) { // Detects a bug in Android <3.2 where you cannot redefine a property using // Object.defineProperty once accessors have already been set. - /** @private */ canRedefineProperties = (function() { var obj = {}; @@ -568,7 +593,6 @@ if (defineProperty) { // This is for Safari 5.0, which supports Object.defineProperty, but not // on DOM nodes. - /** @private */ canDefinePropertyOnDOM = (function(){ try { defineProperty(document.createElement('div'), 'definePropertyOnDOM', {}); @@ -579,10 +603,8 @@ if (defineProperty) { })(); if (!canRedefineProperties) { - /** @private */ defineProperty = null; } else if (!canDefinePropertyOnDOM) { - /** @private */ defineProperty = function(obj, keyName, desc){ var isNode; @@ -602,24 +624,28 @@ if (defineProperty) { } } +/** +@class platform +@namespace Ember +*/ + /** Identical to Object.defineProperty(). Implements as much functionality as possible if not available natively. - @memberOf Ember.platform - @name defineProperty + @method defineProperty @param {Object} obj The object to modify @param {String} keyName property name to modify @param {Object} desc descriptor hash - @returns {void} + @return {void} */ platform.defineProperty = defineProperty; /** Set to true if the platform supports native getters and setters. - @memberOf Ember.platform - @name hasPropertyAccessors + @property hasPropertyAccessors + @final */ platform.hasPropertyAccessors = true; @@ -642,11 +668,10 @@ if (Ember.ENV.MANDATORY_SETTER && !platform.hasPropertyAccessors) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var o_defineProperty = Ember.platform.defineProperty, o_create = Ember.create, // Used for guid generation... @@ -659,9 +684,6 @@ var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER; /** @private - @static - @type String - @constant A unique key used to assign guids and other private metadata to objects. If you inspect an object in your browser debugger you will often see these. @@ -669,6 +691,11 @@ var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER; On browsers that support it, these properties are added with enumeration disabled so they won't show up when you iterate over your properties. + + @property GUID_KEY + @for Ember + @type String + @final */ Ember.GUID_KEY = GUID_KEY; @@ -686,18 +713,18 @@ var GUID_DESC = { pass in. You will rarely need to use this method. Instead you should call Ember.guidFor(obj), which return an existing guid if available. - @param {Object} obj - Optional object the guid will be used for. If passed in, the guid will + @method generateGuid + @for Ember + @param {Object} [obj] Object the guid will be used for. If passed in, the guid will be saved on the object and reused whenever you pass the same object again. If no object is passed, just generate a new guid. - @param {String} prefix - Optional prefix to place in front of the guid. Useful when you want to + @param {String} [prefix] Prefix to place in front of the guid. Useful when you want to separate the guid into separate namespaces. - @returns {String} the guid + @return {String} the guid */ Ember.generateGuid = function generateGuid(obj, prefix) { if (!prefix) prefix = 'ember'; @@ -718,9 +745,10 @@ Ember.generateGuid = function generateGuid(obj, prefix) { You can also use this method on DOM Element objects. - @method + @method guidFor + @for Ember @param obj {Object} any object, string, number, Element, or primitive - @returns {String} the unique guid for this instance. + @return {String} the unique guid for this instance. */ Ember.guidFor = function guidFor(obj) { @@ -773,7 +801,10 @@ var META_KEY = Ember.GUID_KEY+'_meta'; /** The key used to store meta information on object for property observing. - @static + @property META_KEY + @for Ember + @private + @final @type String */ Ember.META_KEY = META_KEY; @@ -808,9 +839,6 @@ if (isDefinePropertySimulated) { } /** - @private - @function - Retrieves the meta hash for an object. If 'writable' is true ensures the hash is writable for this object as well. @@ -819,14 +847,16 @@ if (isDefinePropertySimulated) { not access this information directly but instead work with higher level methods that manipulate this hash indirectly. - @param {Object} obj - The object to retrieve meta for + @method meta + @for Ember + @private - @param {Boolean} writable - Pass false if you do not intend to modify the meta hash, allowing the - method to avoid making an unnecessary copy. + @param {Object} obj The object to retrieve meta for - @returns {Hash} + @param {Boolean} [writable=true] Pass false if you do not intend to modify + the meta hash, allowing the method to avoid making an unnecessary copy. + + @return {Hash} */ Ember.meta = function meta(obj, writable) { @@ -896,6 +926,8 @@ Ember.setMeta = function setMeta(obj, property, value) { undefined if `prepareMetaPath` discovers any part of the path that shared or undefined. + @method metaPath + @for Ember @param {Object} obj The object whose meta we are examining @param {Array} path An array of keys to walk down @param {Boolean} writable whether or not to create a new meta @@ -931,13 +963,11 @@ Ember.metaPath = function metaPath(obj, path, writable) { when the function is invoked. This is the primitive we use to implement calls to super. - @param {Function} func - The function to call - - @param {Function} superFunc - The super function. - - @returns {Function} wrapped function. + @method wrap + @for Ember + @param {Function} func The function to call + @param {Function} superFunc The super function. + @return {Function} wrapped function. */ Ember.wrap = function(func, superFunc) { @@ -971,8 +1001,10 @@ Ember.wrap = function(func, superFunc) { Ember.isArray([]); // true Ember.isArray( Ember.ArrayProxy.create({ content: [] }) ); // true + @method isArray + @for Ember @param {Object} obj The object to test - @returns {Boolean} + @return {Boolean} */ Ember.isArray = function(obj) { if (!obj || obj.setInterval) { return false; } @@ -996,8 +1028,10 @@ Ember.isArray = function(obj) { var controller = Ember.ArrayProxy.create({ content: [] }); Ember.makeArray(controller) === controller; => true + @method makeArray + @for Ember @param {Object} obj the object - @returns {Array} + @return {Array} */ Ember.makeArray = function(obj) { if (obj === null || obj === undefined) { return []; } @@ -1011,8 +1045,8 @@ function canInvoke(obj, methodName) { /** Checks to see if the `methodName` exists on the `obj`. - @function - + @method canInvoke + @for Ember @param {Object} obj The object to check for the method @param {String} methodName The method name to check for */ @@ -1022,18 +1056,16 @@ Ember.canInvoke = canInvoke; Checks to see if the `methodName` exists on the `obj`, and if it does, invokes it with the arguments passed. - @function - + @method tryInvoke + @for Ember @param {Object} obj The object to check for the method @param {String} methodName The method name to check for - @param {Array} args The arguments to pass to the method - - @returns {Boolean} true if the method does not return false - @returns {Boolean} false otherwise + @param {Array} [args] The arguments to pass to the method + @return {anything} the return value of the invoked method or undefined if it cannot be invoked */ Ember.tryInvoke = function(obj, methodName, args) { if (canInvoke(obj, methodName)) { - return obj[methodName].apply(obj, args); + return obj[methodName].apply(obj, args || []); } }; @@ -1043,6 +1075,10 @@ Ember.tryInvoke = function(obj, methodName, args) { (function() { /** +@module ember-metal +*/ + +/* JavaScript (before ES6) does not have a Map implementation. Objects, which are often used as dictionaries, may only have Strings as keys. @@ -1061,7 +1097,6 @@ Ember.tryInvoke = function(obj, methodName, args) { Map is mocked out to look like an Ember object, so you can do `Ember.Map.create()` for symmetry with other Ember classes. */ -/** @private */ var guidFor = Ember.guidFor, indexOf = Ember.ArrayPolyfills.indexOf; @@ -1085,23 +1120,43 @@ var copyMap = function(original, newObject) { return newObject; }; -// This class is used internally by Ember.js and Ember Data. -// Please do not use it at this time. We plan to clean it up -// and add many tests soon. +/** + This class is used internally by Ember.js and Ember Data. + Please do not use it at this time. We plan to clean it up + and add many tests soon. + + @class OrderedSet + @namespace Ember + @constructor + @private +*/ var OrderedSet = Ember.OrderedSet = function() { this.clear(); }; +/** + @method create + @static + @return {Ember.OrderedSet} +*/ OrderedSet.create = function() { return new OrderedSet(); }; + OrderedSet.prototype = { + /** + @method clear + */ clear: function() { this.presenceSet = {}; this.list = []; }, + /** + @method add + @param obj + */ add: function(obj) { var guid = guidFor(obj), presenceSet = this.presenceSet, @@ -1113,6 +1168,10 @@ OrderedSet.prototype = { list.push(obj); }, + /** + @method remove + @param obj + */ remove: function(obj) { var guid = guidFor(obj), presenceSet = this.presenceSet, @@ -1126,10 +1185,31 @@ OrderedSet.prototype = { } }, + /** + @method isEmpty + @return {Boolean} + */ isEmpty: function() { return this.list.length === 0; }, + /** + @method has + @param obj + @return {Boolean} + */ + has: function(obj) { + var guid = guidFor(obj), + presenceSet = this.presenceSet; + + return guid in presenceSet; + }, + + /** + @method forEach + @param {Function} function + @param target + */ forEach: function(fn, self) { // allow mutation during iteration var list = this.list.slice(); @@ -1139,10 +1219,18 @@ OrderedSet.prototype = { } }, + /** + @method toArray + @return {Array} + */ toArray: function() { return this.list.slice(); }, + /** + @method copy + @return {Ember.OrderedSet} + */ copy: function() { var set = new OrderedSet(); @@ -1168,14 +1256,21 @@ OrderedSet.prototype = { add the key to the `keys` OrderedSet, and create or replace an entry in `values`. When an entry is deleted, we delete its entry in `keys` and `values`. -*/ -/** @private */ + @class Map + @namespace Ember + @private + @constructor +*/ var Map = Ember.Map = function() { this.keys = Ember.OrderedSet.create(); this.values = {}; }; +/** + @method create + @static +*/ Map.create = function() { return new Map(); }; @@ -1184,6 +1279,7 @@ Map.prototype = { /** Retrieve the value associated with a given key. + @method get @param {anything} key @return {anything} the value associated with the key, or undefined */ @@ -1198,6 +1294,7 @@ Map.prototype = { Adds a value to the map. If a value for the given key has already been provided, the new value will replace the old value. + @method set @param {anything} key @param {anything} value */ @@ -1213,8 +1310,9 @@ Map.prototype = { /** Removes a value from the map for an associated key. + @method remove @param {anything} key - @returns {Boolean} true if an item was removed, false otherwise + @return {Boolean} true if an item was removed, false otherwise */ remove: function(key) { // don't use ES6 "delete" because it will be annoying @@ -1237,8 +1335,9 @@ Map.prototype = { /** Check whether a key is present. + @method has @param {anything} key - @returns {Boolean} true if the item was present, false otherwise + @return {Boolean} true if the item was present, false otherwise */ has: function(key) { var values = this.values, @@ -1253,6 +1352,7 @@ Map.prototype = { The keys are guaranteed to be iterated over in insertion order. + @method forEach @param {Function} callback @param {anything} self if passed, the `this` value inside the callback. By default, `this` is the map. @@ -1267,16 +1367,36 @@ Map.prototype = { }); }, + /** + @method copy + @return {Ember.Map} + */ copy: function() { return copyMap(this, new Map()); } }; +/** + @class MapWithDefault + @namespace Ember + @extends Ember.Map + @private + @constructor + @param [options] + @param {anything} [options.defaultValue] +*/ var MapWithDefault = Ember.MapWithDefault = function(options) { Map.call(this); this.defaultValue = options.defaultValue; }; +/** + @method create + @static + @param [options] + @param {anything} [options.defaultValue] + @return {Ember.MapWithDefault|Ember.Map} If options are passed, returns Ember.MapWithDefault otherwise returns Ember.Map +*/ MapWithDefault.create = function(options) { if (options) { return new MapWithDefault(options); @@ -1287,6 +1407,13 @@ MapWithDefault.create = function(options) { MapWithDefault.prototype = Ember.create(Map.prototype); +/** + Retrieve the value associated with a given key. + + @method get + @param {anything} key + @return {anything} the value associated with the key, or the default value +*/ MapWithDefault.prototype.get = function(key) { var hasValue = this.has(key); @@ -1299,6 +1426,10 @@ MapWithDefault.prototype.get = function(key) { } }; +/** + @method copy + @return {Ember.MapWithDefault} +*/ MapWithDefault.prototype.copy = function() { return copyMap(this, new MapWithDefault({ defaultValue: this.defaultValue @@ -1310,16 +1441,14 @@ MapWithDefault.prototype.copy = function() { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var META_KEY = Ember.META_KEY, get, set; var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER; -/** @private */ var IS_GLOBAL = /^([A-Z$]|([0-9][A-Z$]))/; var IS_GLOBAL_PATH = /^([A-Z$]|([0-9][A-Z$])).*[\.\*]/; var HAS_THIS = /^this[\.\*]/; @@ -1332,7 +1461,30 @@ var FIRST_KEY = /^([^\.\*]+)/; // Otherwise simulate accessors by looking up the property directly on the // object. -/** @private */ +/** + Gets the value of a property on an object. If the property is computed, + the function will be invoked. If the property is not defined but the + object implements the unknownProperty() method then that will be invoked. + + If you plan to run on IE8 and older browsers then you should use this + method anytime you want to retrieve a property on an object that you don't + know for sure is private. (My convention only properties beginning with + an underscore '_' are considered private.) + + On all newer browsers, you only need to use this method to retrieve + properties if the property might not be defined on the object and you want + to respect the unknownProperty() handler. Otherwise you can ignore this + method. + + Note that if the obj itself is null, this method will simply return + undefined. + + @method get + @for Ember + @param {Object} obj The object to retrieve from. + @param {String} keyName The property key to retrieve + @return {Object} the property value or null. +*/ get = function get(obj, keyName) { // Helpers that operate with 'this' within an #each if (keyName === '') { @@ -1369,7 +1521,29 @@ get = function get(obj, keyName) { } }; -/** @private */ +/** + Sets the value of a property on an object, respecting computed properties + and notifying observers and other listeners of the change. If the + property is not defined but the object implements the unknownProperty() + method then that will be invoked as well. + + If you plan to run on IE8 and older browsers then you should use this + method anytime you want to set a property on an object that you don't + know for sure is private. (My convention only properties beginning with + an underscore '_' are considered private.) + + On all newer browsers, you only need to use this method to set + properties if the property might not be defined on the object and you want + to respect the unknownProperty() handler. Otherwise you can ignore this + method. + + @method set + @for Ember + @param {Object} obj The object to modify. + @param {String} keyName The property key to set + @param {Object} value The value to set + @return {Object} the passed value. +*/ set = function set(obj, keyName, value, tolerant) { if (typeof obj === 'string') { Ember.assert("Path '" + obj + "' must be global if no obj is given.", IS_GLOBAL.test(obj)); @@ -1425,13 +1599,11 @@ set = function set(obj, keyName, value, tolerant) { return value; }; -/** @private */ function firstKey(path) { return path.match(FIRST_KEY)[0]; } // assumes path is already normalized -/** @private */ function normalizeTuple(target, path) { var hasThis = HAS_THIS.test(path), isGlobal = !hasThis && IS_GLOBAL_PATH.test(path), @@ -1452,7 +1624,6 @@ function normalizeTuple(target, path) { return [ target, path ]; } -/** @private */ function getPath(root, path) { var hasThis, parts, tuple, idx, len; @@ -1480,7 +1651,6 @@ function getPath(root, path) { return root; } -/** @private */ function setPath(root, path, value, tolerant) { var keyName; @@ -1516,13 +1686,11 @@ function setPath(root, path, value, tolerant) { paths (i.e. a path beginning with a captial letter not defined on the target) and * separators. - @param {Object} target - The current target. May be null. - - @param {String} path - A path on the target or a global property path. - - @returns {Array} a temporary array with the normalized target/path pair. + @method normalizeTuple + @for Ember + @param {Object} target The current target. May be null. + @param {String} path A path on the target or a global property path. + @return {Array} a temporary array with the normalized target/path pair. */ Ember.normalizeTuple = function(target, path) { return normalizeTuple(target, path); @@ -1536,66 +1704,9 @@ Ember.getWithDefault = function(root, key, defaultValue) { }; -/** - @function - - Gets the value of a property on an object. If the property is computed, - the function will be invoked. If the property is not defined but the - object implements the unknownProperty() method then that will be invoked. - - If you plan to run on IE8 and older browsers then you should use this - method anytime you want to retrieve a property on an object that you don't - know for sure is private. (My convention only properties beginning with - an underscore '_' are considered private.) - - On all newer browsers, you only need to use this method to retrieve - properties if the property might not be defined on the object and you want - to respect the unknownProperty() handler. Otherwise you can ignore this - method. - - Note that if the obj itself is null, this method will simply return - undefined. - - @param {Object} obj - The object to retrieve from. - - @param {String} keyName - The property key to retrieve - - @returns {Object} the property value or null. -*/ Ember.get = get; Ember.getPath = Ember.deprecateFunc('getPath is deprecated since get now supports paths', Ember.get); -/** - @function - - Sets the value of a property on an object, respecting computed properties - and notifying observers and other listeners of the change. If the - property is not defined but the object implements the unknownProperty() - method then that will be invoked as well. - - If you plan to run on IE8 and older browsers then you should use this - method anytime you want to set a property on an object that you don't - know for sure is private. (My convention only properties beginning with - an underscore '_' are considered private.) - - On all newer browsers, you only need to use this method to set - properties if the property might not be defined on the object and you want - to respect the unknownProperty() handler. Otherwise you can ignore this - method. - - @param {Object} obj - The object to modify. - - @param {String} keyName - The property key to set - - @param {Object} value - The value to set - - @returns {Object} the passed value. -*/ Ember.set = set; Ember.setPath = Ember.deprecateFunc('setPath is deprecated since set now supports paths', Ember.set); @@ -1605,6 +1716,12 @@ Ember.setPath = Ember.deprecateFunc('setPath is deprecated since set now support This is primarily used when syncing bindings, which may try to update after an object has been destroyed. + + @method trySet + @for Ember + @param {Object} obj The object to modify. + @param {String} keyName The property key to set + @param {Object} value The value to set */ Ember.trySet = function(root, path, value) { return set(root, path, value, true); @@ -1615,8 +1732,11 @@ Ember.trySetPath = Ember.deprecateFunc('trySetPath has been renamed to trySet', Returns true if the provided path is global (e.g., "MyApp.fooController.bar") instead of local ("foo.bar.baz"). + @method isGlobalPath + @for Ember + @private @param {String} path - @returns Boolean + @return Boolean */ Ember.isGlobalPath = function(path) { return IS_GLOBAL.test(path); @@ -1635,11 +1755,10 @@ if (Ember.config.overrideAccessors) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var GUID_KEY = Ember.GUID_KEY, META_KEY = Ember.META_KEY, EMPTY_META = Ember.EMPTY_META, @@ -1654,13 +1773,15 @@ var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER; // /** - @private - @constructor - Objects of this type can implement an interface to responds requests to get and set. The default implementation handles simple properties. You generally won't need to create or subclass this directly. + + @class Descriptor + @namespace Ember + @private + @constructor */ var Descriptor = Ember.Descriptor = function() {}; @@ -1701,22 +1822,18 @@ var Descriptor = Ember.Descriptor = function() {}; Ember.defineProperty(contact, 'fullName', Ember.computed(function() { return this.firstName+' '+this.lastName; }).property('firstName', 'lastName').cacheable()); + + @method defineProperty + @for Ember + @param {Object} obj the object to define this property on. This may be a prototype. + @param {String} keyName the name of the property + @param {Ember.Descriptor} [desc] an instance of Ember.Descriptor (typically a + computed property) or an ES5 descriptor. + You must provide this or `data` but not both. + @param {anything} [data] something other than a descriptor, that will + become the explicit value of this property. */ Ember.defineProperty = function(obj, keyName, desc, data, meta) { - // The first two parameters to defineProperty are mandatory: - // - // * obj: the object to define this property on. This may be - // a prototype. - // * keyName: the name of the property - // - // One and only one of the following two parameters must be - // provided: - // - // * desc: an instance of Ember.Descriptor (typically a - // computed property) or an ES5 descriptor. - // * data: something other than a descriptor, that will - // become the explicit value of this property. - var descs, existingDesc, watching, value; if (!meta) meta = metaFor(obj); @@ -1789,11 +1906,10 @@ Ember.defineProperty = function(obj, keyName, desc, data, meta) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var AFTER_OBSERVERS = ':change'; var BEFORE_OBSERVERS = ':before'; var guidFor = Ember.guidFor; @@ -1801,7 +1917,6 @@ var guidFor = Ember.guidFor; var deferred = 0; var array_Slice = [].slice; -/** @private */ var ObserverSet = function () { this.targetSet = {}; }; @@ -1822,7 +1937,6 @@ ObserverSet.prototype.clear = function () { this.targetSet = {}; }; -/** @private */ var DeferredEventQueue = function() { this.targetSet = {}; this.queue = []; @@ -1857,7 +1971,6 @@ DeferredEventQueue.prototype.flush = function() { var queue = new DeferredEventQueue(), beforeObserverSet = new ObserverSet(); -/** @private */ function notifyObservers(obj, eventName, keyName, forceNotification) { if (deferred && !forceNotification) { queue.push(obj, eventName, keyName); @@ -1866,18 +1979,24 @@ function notifyObservers(obj, eventName, keyName, forceNotification) { } } -/** @private */ function flushObserverQueue() { beforeObserverSet.clear(); queue.flush(); } +/** + @method beginPropertyChanges + @chainable +*/ Ember.beginPropertyChanges = function() { deferred++; return this; }; +/** + @method endPropertyChanges +*/ Ember.endPropertyChanges = function() { deferred--; if (deferred<=0) flushObserverQueue(); @@ -1891,6 +2010,10 @@ Ember.endPropertyChanges = function() { obj1.set('foo', mayBlowUpWhenSet); obj2.set('bar', baz); }); + + @method changeProperties + @param {Function} callback + @param [binding] */ Ember.changeProperties = function(cb, binding){ Ember.beginPropertyChanges(); @@ -1905,6 +2028,11 @@ Ember.changeProperties = function(cb, binding){ Set a list of properties on an object. These properties are set inside a single `beginPropertyChanges` and `endPropertyChanges` batch, so observers will be buffered. + + @method setProperties + @param target + @param {Hash} properties + @return target */ Ember.setProperties = function(self, hash) { Ember.changeProperties(function(){ @@ -1916,33 +2044,51 @@ Ember.setProperties = function(self, hash) { }; -/** @private */ function changeEvent(keyName) { return keyName+AFTER_OBSERVERS; } -/** @private */ function beforeEvent(keyName) { return keyName+BEFORE_OBSERVERS; } +/** + @method addObserver + @param obj + @param {String} path + @param {Object|Function} targetOrMethod + @param {Function|String} [method] +*/ Ember.addObserver = function(obj, path, target, method) { Ember.addListener(obj, changeEvent(path), target, method); Ember.watch(obj, path); return this; }; -/** @private */ Ember.observersFor = function(obj, path) { return Ember.listenersFor(obj, changeEvent(path)); }; +/** + @method removeObserver + @param obj + @param {String} path + @param {Object|Function} targetOrMethod + @param {Function|String} [method] +*/ Ember.removeObserver = function(obj, path, target, method) { Ember.unwatch(obj, path); Ember.removeListener(obj, changeEvent(path), target, method); return this; }; +/** + @method addBeforeObserver + @param obj + @param {String} path + @param {Object|Function} targetOrMethod + @param {Function|String} [method] +*/ Ember.addBeforeObserver = function(obj, path, target, method) { Ember.addListener(obj, beforeEvent(path), target, method); Ember.watch(obj, path); @@ -1953,7 +2099,6 @@ Ember.addBeforeObserver = function(obj, path, target, method) { // // This should only be used by the target of the observer // while it is setting the observed path. -/** @private */ Ember._suspendBeforeObserver = function(obj, path, target, method, callback) { return Ember._suspendListener(obj, beforeEvent(path), target, method, callback); }; @@ -1962,25 +2107,41 @@ Ember._suspendObserver = function(obj, path, target, method, callback) { return Ember._suspendListener(obj, changeEvent(path), target, method, callback); }; -/** @private */ +var map = Ember.ArrayPolyfills.map; + +Ember._suspendBeforeObservers = function(obj, paths, target, method, callback) { + var events = map.call(paths, beforeEvent); + return Ember._suspendListeners(obj, events, target, method, callback); +}; + +Ember._suspendObservers = function(obj, paths, target, method, callback) { + var events = map.call(paths, changeEvent); + return Ember._suspendListeners(obj, events, target, method, callback); +}; + Ember.beforeObserversFor = function(obj, path) { return Ember.listenersFor(obj, beforeEvent(path)); }; +/** + @method removeBeforeObserver + @param obj + @param {String} path + @param {Object|Function} targetOrMethod + @param {Function|String} [method] +*/ Ember.removeBeforeObserver = function(obj, path, target, method) { Ember.unwatch(obj, path); Ember.removeListener(obj, beforeEvent(path), target, method); return this; }; -/** @private */ Ember.notifyObservers = function(obj, keyName) { if (obj.isDestroying) { return; } notifyObservers(obj, changeEvent(keyName), keyName); }; -/** @private */ Ember.notifyBeforeObservers = function(obj, keyName) { if (obj.isDestroying) { return; } @@ -2003,11 +2164,10 @@ Ember.notifyBeforeObservers = function(obj, keyName) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var guidFor = Ember.guidFor, // utils.js metaFor = Ember.meta, // utils.js get = Ember.get, // accessors.js @@ -2025,13 +2185,11 @@ var guidFor = Ember.guidFor, // utils.js var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER, o_defineProperty = Ember.platform.defineProperty; -/** @private */ function firstKey(path) { return path.match(FIRST_KEY)[0]; } // returns true if the passed path is just a keyName -/** @private */ function isKeyName(path) { return path==='*' || !IS_PATH.test(path); } @@ -2042,7 +2200,6 @@ function isKeyName(path) { var DEP_SKIP = { __emberproto__: true }; // skip some keys and toString -/** @private */ function iterDeps(method, obj, depKey, seen, meta) { var guid = guidFor(obj); @@ -2055,6 +2212,8 @@ function iterDeps(method, obj, depKey, seen, meta) { if (deps) { for(var key in deps) { if (DEP_SKIP[key]) continue; + var desc = meta.descs[key]; + if (desc && desc._suspended === obj) continue; method(obj, key); } } @@ -2064,7 +2223,6 @@ function iterDeps(method, obj, depKey, seen, meta) { var WILL_SEEN, DID_SEEN; // called whenever a property is about to change to clear the cache of any dependent keys (and notify those properties of changes, etc...) -/** @private */ function dependentKeysWillChange(obj, depKey, meta) { if (obj.isDestroying) { return; } @@ -2075,7 +2233,6 @@ function dependentKeysWillChange(obj, depKey, meta) { } // called whenever a property has just changed to update dependent keys -/** @private */ function dependentKeysDidChange(obj, depKey, meta) { if (obj.isDestroying) { return; } @@ -2089,7 +2246,6 @@ function dependentKeysDidChange(obj, depKey, meta) { // CHAIN // -/** @private */ function addChainWatcher(obj, keyName, node) { if (!obj || ('object' !== typeof obj)) return; // nothing to do var m = metaFor(obj); @@ -2103,7 +2259,6 @@ function addChainWatcher(obj, keyName, node) { Ember.watch(obj, keyName); } -/** @private */ function removeChainWatcher(obj, keyName, node) { if (!obj || 'object' !== typeof obj) { return; } // nothing to do var m = metaFor(obj, false), @@ -2118,7 +2273,6 @@ var pendingQueue = []; // attempts to add the pendingQueue chains again. If some of them end up // back in the queue and reschedule is true, schedules a timeout to try // again. -/** @private */ function flushPendingChains() { if (pendingQueue.length === 0) { return; } // nothing to do @@ -2127,14 +2281,9 @@ function flushPendingChains() { forEach.call(queue, function(q) { q[0].add(q[1]); }); - // Ember.warn('Watching an undefined global, Ember expects watched globals to be setup by the time the run loop is flushed, check for typos', pendingQueue.length === 0); - - // if(pendingQueue.length > 0) { - // console.log(pendingQueue) - // } + Ember.warn('Watching an undefined global, Ember expects watched globals to be setup by the time the run loop is flushed, check for typos', pendingQueue.length === 0); } -/** @private */ function isProto(pvalue) { return metaFor(pvalue, false).proto === pvalue; } @@ -2142,7 +2291,6 @@ function isProto(pvalue) { // A ChainNode watches a single key on an object. If you provide a starting // value for the key then the node won't actually watch it. For a root node // pass null for parent and key and object for value. -/** @private */ var ChainNode = function(parent, key, value, separator) { var obj; this._parent = parent; @@ -2370,7 +2518,6 @@ ChainNodePrototype.didChange = function(suppressEvent) { // get the chains for the current object. If the current object has // chains inherited from the proto they will be cloned and reconfigured for // the current object. -/** @private */ function chainsFor(obj) { var m = metaFor(obj), ret = m.chains; if (!ret) { @@ -2381,7 +2528,6 @@ function chainsFor(obj) { return ret; } -/** @private */ function notifyChains(obj, m, keyName, methodName, arg) { var nodes = m.chainWatchers; @@ -2400,12 +2546,10 @@ Ember.overrideChains = function(obj, keyName, m) { notifyChains(obj, m, keyName, 'didChange', true); }; -/** @private */ function chainsWillChange(obj, keyName, m) { notifyChains(obj, m, keyName, 'willChange'); } -/** @private */ function chainsDidChange(obj, keyName, m) { notifyChains(obj, m, keyName, 'didChange'); } @@ -2422,6 +2566,11 @@ function chainsDidChange(obj, keyName, m) { primitive used by observers and dependent keys; usually you will never call this method directly but instead use higher level methods like Ember.addObserver(). + + @method watch + @for Ember + @param obj + @param {String} keyName */ Ember.watch = function(obj, keyName) { // can't watch length on Array - it is special... @@ -2471,7 +2620,6 @@ Ember.isWatching = function isWatching(obj, key) { Ember.watch.flushPending = flushPendingChains; -/** @private */ Ember.unwatch = function(obj, keyName) { // can't watch length on Array - it is special... if (keyName === 'length' && Ember.typeOf(obj) === 'array') { return this; } @@ -2515,6 +2663,10 @@ Ember.unwatch = function(obj, keyName) { Call on an object when you first beget it from another object. This will setup any chained watchers on the object instance as needed. This method is safe to call multiple times. + + @method rewatch + @for Ember + @param obj */ Ember.rewatch = function(obj) { var m = metaFor(obj, false), chains = m.chains; @@ -2555,15 +2707,11 @@ Ember.finishChains = function(obj) { manually along with `Ember.propertyDidChange()` which you should call just after the property value changes. - @memberOf Ember - - @param {Object} obj - The object with the property that will change - - @param {String} keyName - The property key (or path) that will change. - - @returns {void} + @method propertyWillChange + @for Ember + @param {Object} obj The object with the property that will change + @param {String} keyName The property key (or path) that will change. + @return {void} */ function propertyWillChange(obj, keyName, value) { var m = metaFor(obj, false), @@ -2590,15 +2738,11 @@ Ember.propertyWillChange = propertyWillChange; manually along with `Ember.propertyWilLChange()` which you should call just before the property value changes. - @memberOf Ember - - @param {Object} obj - The object with the property that will change - - @param {String} keyName - The property key (or path) that will change. - - @returns {void} + @method propertyDidChange + @for Ember + @param {Object} obj The object with the property that will change + @param {String} keyName The property key (or path) that will change. + @return {void} */ function propertyDidChange(obj, keyName) { var m = metaFor(obj, false), @@ -2625,8 +2769,10 @@ var NODE_STACK = []; Tears down the meta on an object so that it can be garbage collected. Multiple calls will have no effect. + @method destroy + @for Ember @param {Object} obj the object to destroy - @returns {void} + @return {void} */ Ember.destroy = function (obj) { var meta = obj[META_KEY], node, nodes, key, nodeObject; @@ -2665,11 +2811,10 @@ Ember.destroy = function (obj) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + Ember.warn("Computed properties will soon be cacheable by default. To enable this in your app, set `ENV.CP_DEFAULT_CACHEABLE = true`.", Ember.CP_DEFAULT_CACHEABLE); @@ -2695,9 +2840,7 @@ var get = Ember.get, // __emberproto__: SRC_OBJ // } -/** - @private - +/* This function returns a map of unique dependencies for a given object and key. */ @@ -2716,11 +2859,7 @@ function keysForDep(obj, depsMeta, depKey) { return keys; } -/** - @private - - return obj[META_KEY].deps - */ +/* return obj[META_KEY].deps */ function metaForDeps(obj, meta) { var deps = meta.deps; // If the current object has no dependencies... @@ -2737,7 +2876,6 @@ function metaForDeps(obj, meta) { return deps; } -/** @private */ function addDependentKeys(desc, obj, keyName, meta) { // the descriptor has a list of dependent keys, so // add all of its dependent keys. @@ -2757,7 +2895,6 @@ function addDependentKeys(desc, obj, keyName, meta) { } } -/** @private */ function removeDependentKeys(desc, obj, keyName, meta) { // the descriptor has a list of dependent keys, so // add all of its dependent keys. @@ -2781,23 +2918,21 @@ function removeDependentKeys(desc, obj, keyName, meta) { // COMPUTED PROPERTY // -/** @private */ +/** + @class ComputedProperty + @namespace Ember + @extends Ember.Descriptor + @constructor +*/ function ComputedProperty(func, opts) { this.func = func; this._cacheable = (opts && opts.cacheable !== undefined) ? opts.cacheable : Ember.CP_DEFAULT_CACHEABLE; this._dependentKeys = opts && opts.dependentKeys; } -/** - @constructor -*/ Ember.ComputedProperty = ComputedProperty; ComputedProperty.prototype = new Ember.Descriptor(); -/** - @extends Ember.ComputedProperty - @private -*/ var ComputedPropertyPrototype = ComputedProperty.prototype; /** @@ -2817,11 +2952,9 @@ var ComputedPropertyPrototype = ComputedProperty.prototype; Properties are cacheable by default. - @memberOf Ember.ComputedProperty.prototype - @name cacheable - @function + @method cacheable @param {Boolean} aFlag optional set to false to disable caching - @returns {Ember.ComputedProperty} receiver + @chainable */ ComputedPropertyPrototype.cacheable = function(aFlag) { this._cacheable = aFlag !== false; @@ -2838,10 +2971,8 @@ ComputedPropertyPrototype.cacheable = function(aFlag) { }.property().volatile() }); - @memberOf Ember.ComputedProperty.prototype - @name volatile - @function - @returns {Ember.ComputedProperty} receiver + @method volatile + @chainable */ ComputedPropertyPrototype.volatile = function() { return this.cacheable(false); @@ -2860,11 +2991,9 @@ ComputedPropertyPrototype.volatile = function() { }).property('firstName', 'lastName') }); - @memberOf Ember.ComputedProperty.prototype - @name property - @function - @param {String} path... zero or more property paths - @returns {Ember.ComputedProperty} receiver + @method property + @param {String} path* zero or more property paths + @chainable */ ComputedPropertyPrototype.property = function() { var args = []; @@ -2893,11 +3022,9 @@ ComputedPropertyPrototype.property = function() { exposes a public API for retrieving these values from classes, via the `metaForProperty()` function. - @memberOf Ember.ComputedProperty.prototype - @name meta - @function + @method meta @param {Hash} meta - @returns {Ember.ComputedProperty} property descriptor instance + @chainable */ ComputedPropertyPrototype.meta = function(meta) { @@ -2909,7 +3036,7 @@ ComputedPropertyPrototype.meta = function(meta) { } }; -/** @private - impl descriptor API */ +/* impl descriptor API */ ComputedPropertyPrototype.willWatch = function(obj, keyName) { // watch already creates meta for this instance var meta = obj[META_KEY]; @@ -2928,7 +3055,7 @@ ComputedPropertyPrototype.didUnwatch = function(obj, keyName) { } }; -/** @private - impl descriptor API */ +/* impl descriptor API */ ComputedPropertyPrototype.didChange = function(obj, keyName) { // _suspended is set via a CP.set to ensure we don't clear // the cached value set by the setter @@ -2943,7 +3070,7 @@ ComputedPropertyPrototype.didChange = function(obj, keyName) { } }; -/** @private - impl descriptor API */ +/* impl descriptor API */ ComputedPropertyPrototype.get = function(obj, keyName) { var ret, cache, meta; if (this._cacheable) { @@ -2960,37 +3087,45 @@ ComputedPropertyPrototype.get = function(obj, keyName) { return ret; }; -/** @private - impl descriptor API */ +/* impl descriptor API */ ComputedPropertyPrototype.set = function(obj, keyName, value) { var cacheable = this._cacheable, meta = metaFor(obj, cacheable), watched = meta.watching[keyName], oldSuspended = this._suspended, - hadCachedValue, + hadCachedValue = false, ret; - this._suspended = obj; - if (watched) { Ember.propertyWillChange(obj, keyName); } - if (cacheable) { - if (keyName in meta.cache) { - delete meta.cache[keyName]; - hadCachedValue = true; + if (cacheable && keyName in meta.cache) { + if (meta.cache[keyName] === value) { + return; } + hadCachedValue = true; } + + if (watched) { Ember.propertyWillChange(obj, keyName); } + + if (cacheable && hadCachedValue) { + delete meta.cache[keyName]; + } + ret = this.func.call(obj, keyName, value); + if (cacheable) { if (!watched && !hadCachedValue) { addDependentKeys(this, obj, keyName, meta); } meta.cache[keyName] = ret; } + if (watched) { Ember.propertyDidChange(obj, keyName); } + this._suspended = oldSuspended; return ret; }; -/** @private - called when property is defined */ +/* called when property is defined */ ComputedPropertyPrototype.setup = function(obj, keyName) { var meta = obj[META_KEY]; if (meta && meta.watching[keyName]) { @@ -2998,7 +3133,7 @@ ComputedPropertyPrototype.setup = function(obj, keyName) { } }; -/** @private - called before property is overridden */ +/* called before property is overridden */ ComputedPropertyPrototype.teardown = function(obj, keyName) { var meta = metaFor(obj); @@ -3011,6 +3146,7 @@ ComputedPropertyPrototype.teardown = function(obj, keyName) { return null; // no value to restore }; + /** This helper returns a new property descriptor that wraps the passed computed property function. You can use this helper to define properties @@ -3021,10 +3157,10 @@ ComputedPropertyPrototype.teardown = function(obj, keyName) { undefined you should set the value first. In either case return the current value of the property. - @param {Function} func - The computed property function. - - @returns {Ember.ComputedProperty} property descriptor instance + @method computed + @for Ember + @param {Function} func The computed property function. + @return {Ember.ComputedProperty} property descriptor instance */ Ember.computed = function(func) { var args; @@ -3049,10 +3185,11 @@ Ember.computed = function(func) { property that is generated lazily, without accidentally causing it to be created. + @method cacheFor + @for Ember @param {Object} obj the object whose property you want to check @param {String} key the name of the property whose cached value you want to return - */ Ember.cacheFor = function cacheFor(obj, key) { var cache = metaFor(obj, false).cache; @@ -3062,12 +3199,22 @@ Ember.cacheFor = function cacheFor(obj, key) { } }; +/** + @method computed.not + @for Ember + @param {String} dependentKey +*/ Ember.computed.not = function(dependentKey) { return Ember.computed(dependentKey, function(key) { return !get(this, dependentKey); }).cacheable(); }; +/** + @method computed.empty + @for Ember + @param {String} dependentKey +*/ Ember.computed.empty = function(dependentKey) { return Ember.computed(dependentKey, function(key) { var val = get(this, dependentKey); @@ -3075,6 +3222,11 @@ Ember.computed.empty = function(dependentKey) { }).cacheable(); }; +/** + @method computed.bool + @for Ember + @param {String} dependentKey +*/ Ember.computed.bool = function(dependentKey) { return Ember.computed(dependentKey, function(key) { return !!get(this, dependentKey); @@ -3086,18 +3238,17 @@ Ember.computed.bool = function(dependentKey) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var o_create = Ember.create, meta = Ember.meta, metaPath = Ember.metaPath, guidFor = Ember.guidFor, a_slice = [].slice; -/** +/* The event system uses a series of nested hashes to store listeners on an object. When a listener is registered, or when an event arrives, these hashes are consulted to determine which target and action pair to invoke. @@ -3122,14 +3273,12 @@ var o_create = Ember.create, // Gets the set of all actions, keyed on the guid of each action's // method property. -/** @private */ function actionSetFor(obj, eventName, target, writable) { return metaPath(obj, ['listeners', eventName, guidFor(target)], writable); } // Gets the set of all targets, keyed on the guid of each action's // target property. -/** @private */ function targetSetFor(obj, eventName) { var listenerSet = meta(obj, false).listeners; if (!listenerSet) { return false; } @@ -3141,7 +3290,6 @@ function targetSetFor(obj, eventName) { // meta system. var SKIP_PROPERTIES = { __ember_source__: true }; -/** @private */ function iterateSet(obj, eventName, callback, params) { var targetSet = targetSetFor(obj, eventName); if (!targetSet) { return false; } @@ -3167,7 +3315,6 @@ function iterateSet(obj, eventName, callback, params) { return false; } -/** @private */ function invokeAction(action, params, sender) { var method = action.method, target = action.target; // If there is no target, the target is the object @@ -3182,9 +3329,14 @@ function invokeAction(action, params, sender) { } /** - The sendEvent arguments > 2 are passed to an event listener. + Add an event listener - @memberOf Ember + @method addListener + @for Ember + @param obj + @param {String} eventName + @param {Object|Function} targetOrMethod A target object or a function + @param {Function|String} method A function or the name of a function to be called on `target` */ function addListener(obj, eventName, target, method) { Ember.assert("You must pass at least an object and event name to Ember.addListener", !!obj && !!eventName); @@ -3206,7 +3358,18 @@ function addListener(obj, eventName, target, method) { } } -/** @memberOf Ember */ +/** + Remove an event listener + + Arguments should match those passed to {{#crossLink "Ember/addListener"}}{{/crossLink}} + + @method removeListener + @for Ember + @param obj + @param {String} eventName + @param {Object|Function} targetOrMethod A target object or a function + @param {Function|String} method A function or the name of a function to be called on `target` +*/ function removeListener(obj, eventName, target, method) { Ember.assert("You must pass at least an object and event name to Ember.removeListener", !!obj && !!eventName); @@ -3227,13 +3390,24 @@ function removeListener(obj, eventName, target, method) { } } -// Suspend listener during callback. -// -// This should only be used by the target of the event listener -// when it is taking an action that would cause the event, e.g. -// an object might suspend its property change listener while it is -// setting that property. -/** @private */ +/** + @private + + Suspend listener during callback. + + This should only be used by the target of the event listener + when it is taking an action that would cause the event, e.g. + an object might suspend its property change listener while it is + setting that property. + + @method suspendListener + @for Ember + @param obj + @param {String} eventName + @param {Object|Function} targetOrMethod A target object or a function + @param {Function|String} method A function or the name of a function to be called on `target` + @param {Function} callback +*/ function suspendListener(obj, eventName, target, method, callback) { if (!method && 'function' === typeof target) { method = target; @@ -3252,8 +3426,64 @@ function suspendListener(obj, eventName, target, method, callback) { } } -// returns a list of currently watched events -/** @memberOf Ember */ +/** + @private + + Suspend listener during callback. + + This should only be used by the target of the event listener + when it is taking an action that would cause the event, e.g. + an object might suspend its property change listener while it is + setting that property. + + @method suspendListener + @for Ember + @param obj + @param {Array} eventName Array of event names + @param {Object|Function} targetOrMethod A target object or a function + @param {Function|String} method A function or the name of a function to be called on `target` + @param {Function} callback +*/ +function suspendListeners(obj, eventNames, target, method, callback) { + if (!method && 'function' === typeof target) { + method = target; + target = null; + } + + var oldActions = [], + actionSets = [], + eventName, actionSet, methodGuid, action, i, l; + + for (i=0, l=eventNames.length; i ignore ? slice.call(args, ignore) : null; } - // Unfortunately in some browsers we lose the backtrace if we rethrow the existing error, - // so in the event that we don't have an `onerror` handler we don't wrap in a try/catch - if ('function' === typeof Ember.onerror) { - try { - // IE8's Function.prototype.apply doesn't accept undefined/null arguments. - return method.apply(target || this, args || []); - } catch (error) { - Ember.onerror(error); - } - } else { + return Ember.handleErrors(function() { // IE8's Function.prototype.apply doesn't accept undefined/null arguments. return method.apply(target || this, args || []); - } + }, this); } @@ -3389,17 +3634,30 @@ function invoke(target, method, args, ignore) { var timerMark; // used by timers... -/** @private */ +/** +Ember RunLoop (Private) + +@class RunLoop +@namespace Ember +@private +@constructor +*/ var RunLoop = function(prev) { this._prev = prev || null; this.onceTimers = {}; }; RunLoop.prototype = { + /** + @method end + */ end: function() { this.flush(); }, + /** + @method prev + */ prev: function() { return this._prev; }, @@ -3408,6 +3666,12 @@ RunLoop.prototype = { // Delayed Actions // + /** + @method schedule + @param {String} queueName + @param target + @param method + */ schedule: function(queueName, target, method) { var queues = this._queues, queue; if (!queues) { queues = this._queues = {}; } @@ -3419,6 +3683,10 @@ RunLoop.prototype = { return this; }, + /** + @method flush + @param {String} queueName + */ flush: function(queueName) { var queueNames, idx, len, queue, log; @@ -3510,11 +3778,6 @@ Ember.RunLoop = RunLoop; // .......................................................... // Ember.run - this is ideally the only public API the dev sees // -/** -* @namespace Ember.run is both a function and a namespace for -* RunLoop-related functions. -* @name Ember.run -*/ /** Runs the passed target and method inside of a RunLoop, ensuring any @@ -3527,22 +3790,19 @@ Ember.RunLoop = RunLoop; call. Ember.run(function(){ - // code to be execute within a RunLoop + // code to be execute within a RunLoop }); - @name run - @methodOf Ember.run - @param {Object} target - (Optional) target of method to call - - @param {Function|String} method - Method to invoke. May be a function or a string. If you pass a string + @class run + @namespace Ember + @static + @constructor + @param {Object} [target] target of method to call + @param {Function|String} method Method to invoke. + May be a function or a string. If you pass a string then it will be looked up on the passed target. - - @param {Object...} args - Any additional arguments you wish to pass to the method. - - @returns {Object} return value from invoking the passed function. + @param {Object} [args*] Any additional arguments you wish to pass to the method. + @return {Object} return value from invoking the passed function. */ Ember.run = function(target, method) { var ret, loop; @@ -3555,7 +3815,6 @@ Ember.run = function(target, method) { return ret; }; -/** @private */ var run = Ember.run; @@ -3565,11 +3824,11 @@ var run = Ember.run; an lower-level way to use a RunLoop instead of using Ember.run(). Ember.run.begin(); - // code to be execute within a RunLoop + // code to be execute within a RunLoop Ember.run.end(); - - @returns {void} + @method begin + @return {void} */ Ember.run.begin = function() { run.currentRunLoop = new RunLoop(run.currentRunLoop); @@ -3581,10 +3840,11 @@ Ember.run.begin = function() { instead of using Ember.run(). Ember.run.begin(); - // code to be execute within a RunLoop + // code to be execute within a RunLoop Ember.run.end(); - @returns {void} + @method end + @return {void} */ Ember.run.end = function() { Ember.assert('must have a current run loop', run.currentRunLoop); @@ -3602,6 +3862,7 @@ Ember.run.end = function() { simply adding the queue name to this array. Normally you should not need to inspect or modify this property. + @property queues @type Array @default ['sync', 'actions', 'destroy', 'timers'] */ @@ -3629,22 +3890,19 @@ Ember.run.queues = ['sync', 'actions', 'destroy', 'timers']; // scheduled on sync queue // scheduled on timers queue - @param {String} queue - The name of the queue to schedule against. Default queues are 'sync' and - 'actions' + @method schedule + @param {String} queue The name of the queue to schedule against. + Default queues are 'sync' and 'actions' - @param {Object} target - (Optional) target object to use as the context when invoking a method. + @param {Object} [target] target object to use as the context when invoking a method. - @param {String|Function} method - The method to invoke. If you pass a string it will be resolved on the - target object at the time the scheduled item is invoked allowing you to - change the target function. + @param {String|Function} method The method to invoke. If you pass a string it + will be resolved on the target object at the time the scheduled item is + invoked allowing you to change the target function. - @param {Object} arguments... - Optional arguments to be passed to the queued method. + @param {Object} [arguments*] Optional arguments to be passed to the queued method. - @returns {void} + @return {void} */ Ember.run.schedule = function(queue, target, method) { var loop = run.autorun(); @@ -3652,20 +3910,17 @@ Ember.run.schedule = function(queue, target, method) { }; var scheduledAutorun; -/** @private */ function autorun() { scheduledAutorun = null; if (run.currentRunLoop) { run.end(); } } // Used by global test teardown -/** @private */ Ember.run.hasScheduledTimers = function() { return !!(scheduledAutorun || scheduledLater || scheduledNext); }; // Used by global test teardown -/** @private */ Ember.run.cancelTimers = function () { if (scheduledAutorun) { clearTimeout(scheduledAutorun); @@ -3688,9 +3943,11 @@ Ember.run.cancelTimers = function () { ensure the RunLoop always finishes. You normally do not need to call this method directly. Instead use Ember.run(). - Ember.run.autorun(); - @returns {Ember.RunLoop} the new current RunLoop + @method autorun + @example + Ember.run.autorun(); + @return {Ember.RunLoop} the new current RunLoop */ Ember.run.autorun = function() { if (!run.currentRunLoop) { @@ -3716,7 +3973,8 @@ Ember.run.autorun = function() { Ember.run.sync(); - @returns {void} + @method sync + @return {void} */ Ember.run.sync = function() { run.autorun(); @@ -3730,7 +3988,6 @@ Ember.run.sync = function() { var timers = {}; // active timers... var scheduledLater; -/** @private */ function invokeLaterTimers() { scheduledLater = null; var now = (+ new Date()), earliest = -1; @@ -3765,20 +4022,20 @@ function invokeLaterTimers() { // code here will execute within a RunLoop in about 500ms with this == myContext }, 500); - @param {Object} target - (optional) target of method to invoke + @method later + @param {Object} [target] target of method to invoke - @param {Function|String} method - The method to invoke. If you pass a string it will be resolved on the + @param {Function|String} method The method to invoke. + If you pass a string it will be resolved on the target at the time the method is invoked. - @param {Object...} args - Optional arguments to pass to the timeout. + @param {Object} [args*] Optional arguments to pass to the timeout. @param {Number} wait Number of milliseconds to wait. - @returns {String} a string you can use to cancel the timer in Ember.run.cancel() later. + @return {String} a string you can use to cancel the timer in + {{#crossLink "Ember/run.cancel"}}{{/crossLink}} later. */ Ember.run.later = function(target, method) { var args, expires, timer, guid, wait; @@ -3802,13 +4059,41 @@ Ember.run.later = function(target, method) { return guid; }; -/** @private */ function invokeOnceTimer(guid, onceTimers) { if (onceTimers[this.tguid]) { delete onceTimers[this.tguid][this.mguid]; } - if (timers[guid]) { invoke(this.target, this.method, this.args, 2); } + if (timers[guid]) { invoke(this.target, this.method, this.args); } delete timers[guid]; } +function scheduleOnce(queue, target, method, args) { + var tguid = Ember.guidFor(target), + mguid = Ember.guidFor(method), + onceTimers = run.autorun().onceTimers, + guid = onceTimers[tguid] && onceTimers[tguid][mguid], + timer; + + if (guid && timers[guid]) { + timers[guid].args = args; // replace args + } else { + timer = { + target: target, + method: method, + args: args, + tguid: tguid, + mguid: mguid + }; + + guid = Ember.guidFor(timer); + timers[guid] = timer; + if (!onceTimers[tguid]) { onceTimers[tguid] = {}; } + onceTimers[tguid][mguid] = guid; // so it isn't scheduled more than once + + run.schedule(queue, timer, invokeOnceTimer, guid, onceTimers); + } + + return guid; +} + /** Schedules an item to run one time during the current RunLoop. Calling this method with the same target/method combination will have no effect. @@ -3824,50 +4109,27 @@ function invokeOnceTimer(guid, onceTimers) { // doFoo will only be executed once at the end of the RunLoop }); - @param {Object} target - (optional) target of method to invoke + @method once + @param {Object} [target] target of method to invoke - @param {Function|String} method - The method to invoke. If you pass a string it will be resolved on the + @param {Function|String} method The method to invoke. + If you pass a string it will be resolved on the target at the time the method is invoked. - @param {Object...} args - Optional arguments to pass to the timeout. + @param {Object} [args*] Optional arguments to pass to the timeout. - @returns {Object} timer + @return {Object} timer */ Ember.run.once = function(target, method) { - var tguid = Ember.guidFor(target), - mguid = Ember.guidFor(method), - onceTimers = run.autorun().onceTimers, - guid = onceTimers[tguid] && onceTimers[tguid][mguid], - timer; + return scheduleOnce('actions', target, method, slice.call(arguments, 2)); +}; - if (guid && timers[guid]) { - timers[guid].args = slice.call(arguments); // replace args - } else { - timer = { - target: target, - method: method, - args: slice.call(arguments), - tguid: tguid, - mguid: mguid - }; - - guid = Ember.guidFor(timer); - timers[guid] = timer; - if (!onceTimers[tguid]) { onceTimers[tguid] = {}; } - onceTimers[tguid][mguid] = guid; // so it isn't scheduled more than once - - run.schedule('actions', timer, invokeOnceTimer, guid, onceTimers); - } - - return guid; +Ember.run.scheduleOnce = function(queue, target, method, args) { + return scheduleOnce(queue, target, method, slice.call(arguments, 3)); }; var scheduledNext; -/** @private */ function invokeNextTimers() { scheduledNext = null; for(var key in timers) { @@ -3888,17 +4150,16 @@ function invokeNextTimers() { // code to be executed in the next RunLoop, which will be scheduled after the current one }); - @param {Object} target - (optional) target of method to invoke + @method next + @param {Object} [target] target of method to invoke - @param {Function|String} method - The method to invoke. If you pass a string it will be resolved on the + @param {Function|String} method The method to invoke. + If you pass a string it will be resolved on the target at the time the method is invoked. - @param {Object...} args - Optional arguments to pass to the timeout. + @param {Object} [args*] Optional arguments to pass to the timeout. - @returns {Object} timer + @return {Object} timer */ Ember.run.next = function(target, method) { var guid, @@ -3935,10 +4196,9 @@ Ember.run.next = function(target, method) { }); Ember.run.cancel(runOnce); - @param {Object} timer - Timer object to cancel - - @returns {void} + @method cancel + @param {Object} timer Timer object to cancel + @return {void} */ Ember.run.cancel = function(timer) { delete timers[timer]; @@ -3949,27 +4209,26 @@ Ember.run.cancel = function(timer) { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== // Ember.Logger // get, set, trySet // guidFor, isArray, meta // addObserver, removeObserver // Ember.run.schedule +/** +@module ember-metal +*/ + // .......................................................... // CONSTANTS // /** - @static - Debug parameter you can turn on. This will log all bindings that fire to the console. This should be disabled in production code. Note that you can also enable this from the console or temporarily. + @property LOG_BINDINGS + @for Ember @type Boolean @default false */ @@ -3981,7 +4240,6 @@ var get = Ember.get, isGlobalPath = Ember.isGlobalPath; -/** @private */ function getWithGlobals(obj, path) { return get(isGlobalPath(path) ? window : obj, path); } @@ -3990,7 +4248,6 @@ function getWithGlobals(obj, path) { // BINDING // -/** @private */ var Binding = function(toPath, fromPath) { this._direction = 'fwd'; this._from = fromPath; @@ -3998,10 +4255,17 @@ var Binding = function(toPath, fromPath) { this._directionMap = Ember.Map.create(); }; -Binding.prototype = /** @scope Ember.Binding.prototype */ { +/** +@class Binding +@namespace Ember +*/ + +Binding.prototype = { /** This copies the Binding so it can be connected to another object. - @returns {Ember.Binding} + + @method copy + @return {Ember.Binding} */ copy: function () { var copy = new Binding(this._to, this._from); @@ -4022,8 +4286,9 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { you pass when you connect() the binding. It follows the same rules as `get()` - see that method for more information. + @method from @param {String} propertyPath the property path to connect to - @returns {Ember.Binding} receiver + @return {Ember.Binding} receiver */ from: function(path) { this._from = path; @@ -4039,8 +4304,9 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { you pass when you connect() the binding. It follows the same rules as `get()` - see that method for more information. + @method to @param {String|Tuple} propertyPath A property path or tuple - @returns {Ember.Binding} this + @return {Ember.Binding} this */ to: function(path) { this._to = path; @@ -4053,14 +4319,14 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { means that if you change the "to" side directly, the "from" side may have a different value. - @returns {Ember.Binding} receiver + @method oneWay + @return {Ember.Binding} receiver */ oneWay: function() { this._oneWay = true; return this; }, - /** @private */ toString: function() { var oneWay = this._oneWay ? '[oneWay]' : ''; return "Ember.Binding<" + guidFor(this) + ">(" + this._from + " -> " + this._to + ")" + oneWay; @@ -4075,8 +4341,9 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { changes. This method will raise an exception if you have not set the from/to properties yet. + @method connect @param {Object} obj The root object for this binding. - @returns {Ember.Binding} this + @return {Ember.Binding} this */ connect: function(obj) { Ember.assert('Must pass a valid object to Ember.Binding.connect()', !!obj); @@ -4099,10 +4366,9 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { Disconnects the binding instance. Changes will no longer be relayed. You will not usually need to call this method. - @param {Object} obj - The root object you passed when connecting the binding. - - @returns {Ember.Binding} this + @method disconnect + @param {Object} obj The root object you passed when connecting the binding. + @return {Ember.Binding} this */ disconnect: function(obj) { Ember.assert('Must pass a valid object to Ember.Binding.disconnect()', !!obj); @@ -4124,17 +4390,16 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { // PRIVATE // - /** @private - called when the from side changes */ + /* called when the from side changes */ fromDidChange: function(target) { this._scheduleSync(target, 'fwd'); }, - /** @private - called when the to side changes */ + /* called when the to side changes */ toDidChange: function(target) { this._scheduleSync(target, 'back'); }, - /** @private */ _scheduleSync: function(obj, dir) { var directionMap = this._directionMap; var existingDir = directionMap.get(obj); @@ -4152,7 +4417,6 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { } }, - /** @private */ _sync: function(obj) { var log = Ember.LOG_BINDINGS; @@ -4195,7 +4459,6 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { }; -/** @private */ function mixinProperties(to, from) { for (var key in from) { if (from.hasOwnProperty(key)) { @@ -4204,11 +4467,13 @@ function mixinProperties(to, from) { } } -mixinProperties(Binding, -/** @scope Ember.Binding */ { +mixinProperties(Binding, { /** - @see Ember.Binding.prototype.from + See {{#crossLink "Ember.Binding/from"}}{{/crossLink}} + + @method from + @static */ from: function() { var C = this, binding = new C(); @@ -4216,7 +4481,10 @@ mixinProperties(Binding, }, /** - @see Ember.Binding.prototype.to + See {{#crossLink "Ember.Binding/to"}}{{/crossLink}} + + @method to + @static */ to: function() { var C = this, binding = new C(); @@ -4225,16 +4493,17 @@ mixinProperties(Binding, /** Creates a new Binding instance and makes it apply in a single direction. - A one-way binding will relay changes on the "from" side object (supplies + A one-way binding will relay changes on the "from" side object (supplied as the `from` argument) the "to" side, but not the other way around. This means that if you change the "to" side directly, the "from" side may have a different value. + See {{#crossLink "Binding/oneWay"}}{{/crossLink}} + + @method oneWay @param {String} from from path. @param {Boolean} [flag] (Optional) passing nothing here will make the binding oneWay. You can - instead pass false to disable oneWay, making the binding two way again. - - @see Ember.Binding.prototype.oneWay + instead pass false to disable oneWay, making the binding two way again. */ oneWay: function(from, flag) { var C = this, binding = new C(null, from); @@ -4244,8 +4513,6 @@ mixinProperties(Binding, }); /** - @class - An Ember.Binding connects the properties of two objects so that whenever the value of one property changes, the other property will be changed also. @@ -4343,30 +4610,46 @@ mixinProperties(Binding, create bindings for you. You should always use the highest-level APIs available, even if you understand how it works underneath. + @class Binding + @namespace Ember @since Ember 0.9 */ Ember.Binding = Binding; + /** Global helper method to create a new binding. Just pass the root object along with a to and from path to create and connect the binding. - @param {Object} obj - The root object of the transform. + @method bind + @for Ember + @param {Object} obj The root object of the transform. - @param {String} to - The path to the 'to' side of the binding. Must be relative to obj. + @param {String} to The path to the 'to' side of the binding. + Must be relative to obj. - @param {String} from - The path to the 'from' side of the binding. Must be relative to obj or - a global path. + @param {String} from The path to the 'from' side of the binding. + Must be relative to obj or a global path. - @returns {Ember.Binding} binding instance + @return {Ember.Binding} binding instance */ Ember.bind = function(obj, to, from) { return new Ember.Binding(to, from).connect(obj); }; +/** + @method oneWay + @for Ember + @param {Object} obj The root object of the transform. + + @param {String} to The path to the 'to' side of the binding. + Must be relative to obj. + + @param {String} from The path to the 'from' side of the binding. + Must be relative to obj or a global path. + + @return {Ember.Binding} binding instance +*/ Ember.oneWay = function(obj, to, from) { return new Ember.Binding(to, from).oneWay().connect(obj); }; @@ -4376,11 +4659,10 @@ Ember.oneWay = function(obj, to, from) { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember-metal +*/ + var Mixin, REQUIRED, Alias, classToString, superClassString, a_map = Ember.ArrayPolyfills.map, @@ -4393,7 +4675,6 @@ var Mixin, REQUIRED, Alias, defineProperty = Ember.defineProperty, guidFor = Ember.guidFor; -/** @private */ function mixinsMeta(obj) { var m = Ember.meta(obj, true), ret = m.mixins; if (!ret) { @@ -4405,7 +4686,6 @@ function mixinsMeta(obj) { return ret; } -/** @private */ function initMixin(mixin, args) { if (args && args.length > 0) { mixin.mixins = a_map.call(args, function(x) { @@ -4422,18 +4702,15 @@ function initMixin(mixin, args) { return mixin; } -/** @private */ function isMethod(obj) { return 'function' === typeof obj && obj.isMethod !== false && obj !== Boolean && obj !== Object && obj !== Number && obj !== Array && obj !== Date && obj !== String; } -/** @private */ function mergeMixins(mixins, m, descs, values, base) { var len = mixins.length, idx, mixin, guid, props, value, key, ovalue, concats; - /** @private */ function removeKeys(keyName) { delete descs[keyName]; delete values[keyName]; @@ -4501,7 +4778,6 @@ function mergeMixins(mixins, m, descs, values, base) { } } -/** @private */ function writableReq(obj) { var m = Ember.meta(obj), req = m.required; if (!req || req.__emberproto__ !== obj) { @@ -4513,7 +4789,6 @@ function writableReq(obj) { var IS_BINDING = Ember.IS_BINDING = /^.+Binding$/; -/** @private */ function detectBinding(obj, key, value, m) { if (IS_BINDING.test(key)) { var bindings = m.bindings; @@ -4527,7 +4802,6 @@ function detectBinding(obj, key, value, m) { } } -/** @private */ function connectBindings(obj, m) { // TODO Mixin.apply(instance) should disconnect binding if exists var bindings = m.bindings, key, binding, to; @@ -4556,7 +4830,6 @@ function finishPartial(obj, m) { return obj; } -/** @private */ function applyMixin(obj, mixins, partial) { var descs = {}, values = {}, m = Ember.meta(obj), req = m.required, key, value, desc, prevValue, paths, len, idx; @@ -4661,6 +4934,13 @@ function applyMixin(obj, mixins, partial) { return obj; } +/** + @method mixin + @for Ember + @param obj + @param mixins* + @return obj +*/ Ember.mixin = function(obj) { var args = a_slice.call(arguments, 1); applyMixin(obj, args, false); @@ -4668,8 +4948,6 @@ Ember.mixin = function(obj) { }; /** - @class - The `Ember.Mixin` class allows you to create mixins, whose properties can be added to other classes. For instance, @@ -4692,13 +4970,14 @@ Ember.mixin = function(obj) { Note that Mixins are created with `Ember.Mixin.create`, not `Ember.Mixin.extend`. + + @class Mixin + @namespace Ember */ Ember.Mixin = function() { return initMixin(this, arguments); }; -/** @private */ Mixin = Ember.Mixin; -/** @private */ Mixin._apply = applyMixin; Mixin.applyPartial = function(obj) { @@ -4708,6 +4987,11 @@ Mixin.applyPartial = function(obj) { Mixin.finishPartial = finishPartial; +/** + @method create + @static + @param arguments* +*/ Mixin.create = function() { classToString.processed = false; var M = this; @@ -4716,6 +5000,10 @@ Mixin.create = function() { var MixinPrototype = Mixin.prototype; +/** + @method reopen + @param arguments* +*/ MixinPrototype.reopen = function() { var mixin, tmp; @@ -4746,6 +5034,11 @@ MixinPrototype.reopen = function() { return this; }; +/** + @method apply + @param obj + @return applied object +*/ MixinPrototype.apply = function(obj) { return applyMixin(obj, [this], false); }; @@ -4754,7 +5047,6 @@ MixinPrototype.applyPartial = function(obj) { return applyMixin(obj, [this], true); }; -/** @private */ function _detect(curMixin, targetMixin, seen) { var guid = guidFor(curMixin); @@ -4769,6 +5061,11 @@ function _detect(curMixin, targetMixin, seen) { return false; } +/** + @method detect + @param obj + @return {Boolean} +*/ MixinPrototype.detect = function(obj) { if (!obj) { return false; } if (obj instanceof Mixin) { return _detect(obj, this, {}); } @@ -4785,7 +5082,6 @@ MixinPrototype.without = function() { return ret; }; -/** @private */ function _keys(ret, mixin, seen) { if (seen[guidFor(mixin)]) { return; } seen[guidFor(mixin)] = true; @@ -4809,12 +5105,11 @@ MixinPrototype.keys = function() { return ret; }; -/** @private - make Mixin's have nice displayNames */ +/* make Mixins have nice displayNames */ var NAME_KEY = Ember.GUID_KEY+'_name'; var get = Ember.get; -/** @private */ function processNames(paths, root, seen) { var idx = paths.length; for(var key in root) { @@ -4833,7 +5128,6 @@ function processNames(paths, root, seen) { paths.length = idx; // cut out last item } -/** @private */ function findNamespaces() { var Namespace = Ember.Namespace, obj, isNamespace; @@ -4862,9 +5156,13 @@ function findNamespaces() { } } +/** + @private + @method identifyNamespaces + @for Ember +*/ Ember.identifyNamespaces = findNamespaces; -/** @private */ superClassString = function(mixin) { var superclass = mixin.superclass; if (superclass) { @@ -4875,7 +5173,6 @@ superClassString = function(mixin) { } }; -/** @private */ classToString = function() { var Namespace = Ember.Namespace, namespace; @@ -4930,16 +5227,41 @@ Mixin.mixins = function(obj) { REQUIRED = new Ember.Descriptor(); REQUIRED.toString = function() { return '(Required Property)'; }; +/** + Denotes a required property for a mixin + + @method required + @for Ember +*/ Ember.required = function() { return REQUIRED; }; -/** @private */ Alias = function(methodName) { this.methodName = methodName; }; Alias.prototype = new Ember.Descriptor(); +/** + Makes a property or method available via an additional name. + + App.PaintSample = Ember.Object.extend({ + color: 'red', + colour: Ember.alias('color'), + name: function(){ + return "Zed"; + }, + moniker: Ember.alias("name") + }); + var paintSample = App.PaintSample.create() + paintSample.get('colour'); //=> 'red' + paintSample.moniker(); //=> 'Zed' + + @method alias + @for Ember + @param {String} methodName name of the method or property to alias + @return {Ember.Descriptor} +*/ Ember.alias = function(methodName) { return new Alias(methodName); }; @@ -4948,6 +5270,13 @@ Ember.alias = function(methodName) { // OBSERVER HELPER // +/** + @method observer + @for Ember + @param {Function} func + @param {String} propertyNames* + @return func +*/ Ember.observer = function(func) { var paths = a_slice.call(arguments, 1); func.__ember_observes__ = paths; @@ -4956,6 +5285,13 @@ Ember.observer = function(func) { // If observers ever become asynchronous, Ember.immediateObserver // must remain synchronous. +/** + @method immediateObserver + @for Ember + @param {Function} func + @param {String} propertyNames* + @return func +*/ Ember.immediateObserver = function() { for (var i=0, l=arguments.length; i 'object' + @method typeOf + @for Ember @param item {Object} the item to check - @returns {String} the type + @return {String} the type */ Ember.typeOf = function(item) { var ret; @@ -5109,8 +5420,10 @@ Ember.typeOf = function(item) { Ember.none([]); => false Ember.none(function(){}); => false + @method none + @for Ember @param {Object} obj Value to test - @returns {Boolean} + @return {Boolean} */ Ember.none = function(obj) { return obj === null || obj === undefined; @@ -5130,11 +5443,13 @@ Ember.none = function(obj) { Ember.empty('tobias fünke'); => false Ember.empty([0,1,2]); => false + @method empty + @for Ember @param {Object} obj Value to test - @returns {Boolean} + @return {Boolean} */ Ember.empty = function(obj) { - return obj === null || obj === undefined || (obj.length === 0 && typeof obj !== 'function'); + return obj === null || obj === undefined || (obj.length === 0 && typeof obj !== 'function') || (typeof obj === 'object' && Ember.get(obj, 'length') === 0); }; /** @@ -5152,9 +5467,11 @@ Ember.empty = function(obj) { Ember.compare('abc', 'dfg'); => -1 Ember.compare(2, 1); => 1 + @method compare + @for Ember @param {Object} v First value to compare @param {Object} w Second value to compare - @returns {Number} -1 if v < w, 0 if v = w and 1 if v > w. + @return {Number} -1 if v < w, 0 if v = w and 1 if v > w. */ Ember.compare = function compare(v, w) { if (v === w) { return 0; } @@ -5245,7 +5562,6 @@ Ember.compare = function compare(v, w) { } }; -/** @private */ function _copy(obj, deep, seen, copies) { var ret, loc, key; @@ -5291,9 +5607,11 @@ function _copy(obj, deep, seen, copies) { If the passed object implements the clone() method, then this function will simply call that method and return the result. + @method copy + @for Ember @param {Object} object The object to clone @param {Boolean} deep If true, a deep copy of the object is made - @returns {Object} The cloned object + @return {Object} The cloned object */ Ember.copy = function(obj, deep) { // fast paths @@ -5306,8 +5624,10 @@ Ember.copy = function(obj, deep) { Convenience method to inspect an object. This method will attempt to convert the object into a useful string description. + @method inspect + @for Ember @param {Object} obj The object you want to inspect. - @returns {String} A description of the object + @return {String} A description of the object */ Ember.inspect = function(obj) { var v, ret = []; @@ -5325,26 +5645,25 @@ Ember.inspect = function(obj) { /** Compares two objects, returning true if they are logically equal. This is a deeper comparison than a simple triple equal. For sets it will compare the - internal objects. For any other object that implements `isEqual()` it will + internal objects. For any other object that implements `isEqual()` it will respect that method. Ember.isEqual('hello', 'hello'); => true Ember.isEqual(1, 2); => false Ember.isEqual([4,2], [4,2]); => false + @method isEqual + @for Ember @param {Object} a first object to compare @param {Object} b second object to compare - @returns {Boolean} + @return {Boolean} */ Ember.isEqual = function(a, b) { if (a && 'function'===typeof a.isEqual) return a.isEqual(b); return a === b; }; -/** - @private - Used by Ember.compare -*/ +// Used by Ember.compare Ember.ORDER_DEFINITION = Ember.ENV.ORDER_DEFINITION || [ 'undefined', 'null', @@ -5364,9 +5683,10 @@ Ember.ORDER_DEFINITION = Ember.ENV.ORDER_DEFINITION || [ when inspecting objects for debugging. On browsers that support it, this uses the native Object.keys implementation. - @function + @method keys + @for Ember @param {Object} obj - @returns {Array} Array containing keys of obj + @return {Array} Array containing keys of obj */ Ember.keys = Object.keys; @@ -5384,18 +5704,23 @@ if (!Ember.keys) { // ERROR // -/** - @class +var errorProps = ['description', 'fileName', 'lineNumber', 'message', 'name', 'number', 'stack']; +/** A subclass of the JavaScript Error object for use in Ember. + + @class Error + @namespace Ember + @extends Error + @constructor */ Ember.Error = function() { var tmp = Error.prototype.constructor.apply(this, arguments); - for (var p in tmp) { - if (tmp.hasOwnProperty(p)) { this[p] = tmp[p]; } + // Unfortunately errors are not enumerable in Chrome (at least), so `for prop in tmp` doesn't work. + for (var idx = 0; idx < errorProps.length; idx++) { + this[errorProps[idx]] = tmp[errorProps[idx]]; } - this.message = tmp.message; }; Ember.Error.prototype = Ember.create(Error.prototype); @@ -5405,13 +5730,11 @@ Ember.Error.prototype = Ember.create(Error.prototype); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ -/** @private **/ var STRING_DASHERIZE_REGEXP = (/[ _]/g); var STRING_DASHERIZE_CACHE = {}; var STRING_DECAMELIZE_REGEXP = (/([a-z])([A-Z])/g); @@ -5424,6 +5747,8 @@ var STRING_UNDERSCORE_REGEXP_2 = (/\-|\s+/g); the `Ember.String.loc()` helper. To localize, add string values to this hash. + @property STRINGS + @for Ember @type Hash */ Ember.STRINGS = {}; @@ -5433,7 +5758,9 @@ Ember.STRINGS = {}; Unless Ember.EXTEND_PROTOTYPES = false these methods will also be added to the String.prototype as well. - @namespace + @class String + @namespace Ember + @static */ Ember.String = { @@ -5450,8 +5777,9 @@ Ember.String = { "Hello %@ %@".fmt('John', 'Doe') => "Hello John Doe" "Hello %@2, %@1".fmt('John', 'Doe') => "Hello Doe, John" + @method fmt @param {Object...} [args] - @returns {String} formatted string + @return {String} formatted string */ fmt: function(str, formats) { // first, replace any ORDERED replacements. @@ -5483,13 +5811,10 @@ Ember.String = { Ember.String.loc("_Hello %@ %@", ["John", "Smith"]); => "Bonjour John Smith"; - @param {String} str - The string to format - - @param {Array} formats - Optional array of parameters to interpolate into string. - - @returns {String} formatted string + @method loc + @param {String} str The string to format + @param {Array} formats Optional array of parameters to interpolate into string. + @return {String} formatted string */ loc: function(str, formats) { str = Ember.STRINGS[str] || str; @@ -5508,25 +5833,23 @@ Ember.String = { > beta > gamma - @param {String} str - The string to split - - @returns {String} split string + @method w + @param {String} str The string to split + @return {String} split string */ w: function(str) { return str.split(/\s+/); }, /** Converts a camelized string into all lower case separated by underscores. - + 'innerHTML'.decamelize() => 'inner_html' 'action_name'.decamelize() => 'action_name' 'css-class-name'.decamelize() => 'css-class-name' 'my favorite items'.decamelize() => 'my favorite items' - @param {String} str - The string to decamelize. - - @returns {String} the decamelized string. + @method decamelize + @param {String} str The string to decamelize. + @return {String} the decamelized string. */ decamelize: function(str) { return str.replace(STRING_DECAMELIZE_REGEXP, '$1_$2').toLowerCase(); @@ -5534,16 +5857,15 @@ Ember.String = { /** Replaces underscores or spaces with dashes. - + 'innerHTML'.dasherize() => 'inner-html' 'action_name'.dasherize() => 'action-name' 'css-class-name'.dasherize() => 'css-class-name' 'my favorite items'.dasherize() => 'my-favorite-items' - @param {String} str - The string to dasherize. - - @returns {String} the dasherized string. + @method dasherize + @param {String} str The string to dasherize. + @return {String} the dasherized string. */ dasherize: function(str) { var cache = STRING_DASHERIZE_CACHE, @@ -5567,10 +5889,9 @@ Ember.String = { 'css-class-name'.camelize() => 'cssClassName' 'my favorite items'.camelize() => 'myFavoriteItems' - @param {String} str - The string to camelize. - - @returns {String} the camelized string. + @method camelize + @param {String} str The string to camelize. + @return {String} the camelized string. */ camelize: function(str) { return str.replace(STRING_CAMELIZE_REGEXP, function(match, separator, chr) { @@ -5584,7 +5905,11 @@ Ember.String = { 'innerHTML'.classify() => 'InnerHTML' 'action_name'.classify() => 'ActionName' 'css-class-name'.classify() => 'CssClassName' - 'my favorite items'.classift() => 'MyFavoriteItems' + 'my favorite items'.classify() => 'MyFavoriteItems' + + @method classify + @param {String} str the string to classify + @return {String} the classified string */ classify: function(str) { var camelized = Ember.String.camelize(str); @@ -5600,10 +5925,9 @@ Ember.String = { 'css-class-name'.underscore() => 'css_class_name' 'my favorite items'.underscore() => 'my_favorite_items' - @param {String} str - The string to underscore. - - @returns {String} the underscored string. + @property underscore + @param {String} str The string to underscore. + @return {String} the underscored string. */ underscore: function(str) { return str.replace(STRING_UNDERSCORE_REGEXP_1, '$1_$2'). @@ -5616,12 +5940,13 @@ Ember.String = { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + + + var fmt = Ember.String.fmt, w = Ember.String.w, loc = Ember.String.loc, @@ -5633,49 +5958,70 @@ var fmt = Ember.String.fmt, if (Ember.EXTEND_PROTOTYPES) { /** - @see Ember.String.fmt + See {{#crossLink "Ember.String/fmt"}}{{/crossLink}} + + @method fmt + @for String */ String.prototype.fmt = function() { return fmt(this, arguments); }; /** - @see Ember.String.w + See {{#crossLink "Ember.String/w"}}{{/crossLink}} + + @method w + @for String */ String.prototype.w = function() { return w(this); }; /** - @see Ember.String.loc + See {{#crossLink "Ember.String/loc"}}{{/crossLink}} + + @method loc + @for String */ String.prototype.loc = function() { return loc(this, arguments); }; /** - @see Ember.String.camelize + See {{#crossLink "Ember.String/camelize"}}{{/crossLink}} + + @method camelize + @for String */ String.prototype.camelize = function() { return camelize(this); }; /** - @see Ember.String.decamelize + See {{#crossLink "Ember.String/decamelize"}}{{/crossLink}} + + @method decamelize + @for String */ String.prototype.decamelize = function() { return decamelize(this); }; /** - @see Ember.String.dasherize + See {{#crossLink "Ember.String/dasherize"}}{{/crossLink}} + + @method dasherize + @for String */ String.prototype.dasherize = function() { return dasherize(this); }; /** - @see Ember.String.underscore + See {{#crossLink "Ember.String/underscore"}}{{/crossLink}} + + @method underscore + @for String */ String.prototype.underscore = function() { return underscore(this); @@ -5689,12 +6035,11 @@ if (Ember.EXTEND_PROTOTYPES) { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + var a_slice = Array.prototype.slice; if (Ember.EXTEND_PROTOTYPES) { @@ -5744,10 +6089,11 @@ if (Ember.EXTEND_PROTOTYPES) { will instead clear the cache so that it is updated when the next `get` is called on the property. - Note: you will usually want to use `property(...)` with `cacheable()`. + See {{#crossLink "Ember.ComputedProperty"}}{{/crossLink}}, + {{#crossLink "Ember/computed"}}{{/crossLink}} - @see Ember.ComputedProperty - @see Ember.computed + @method property + @for Function */ Function.prototype.property = function() { var ret = Ember.computed(this); @@ -5768,7 +6114,10 @@ if (Ember.EXTEND_PROTOTYPES) { }.observes('value') }); - @see Ember.Observable + See {{#crossLink "Ember.Observable/observes"}}{{/crossLink}} + + @method observes + @for Function */ Function.prototype.observes = function() { this.__ember_observes__ = a_slice.call(arguments); @@ -5789,7 +6138,10 @@ if (Ember.EXTEND_PROTOTYPES) { }.observesBefore('value') }); - @see Ember.Observable + See {{#crossLink "Ember.Observable/observesBefore"}}{{/crossLink}} + + @method observesBefore + @for Function */ Function.prototype.observesBefore = function() { this.__ember_observesBefore__ = a_slice.call(arguments); @@ -5804,26 +6156,16 @@ if (Ember.EXTEND_PROTOTYPES) { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - - - - +/** +@module ember +@submodule ember-runtime +*/ // .......................................................... // HELPERS @@ -5834,18 +6176,16 @@ var a_slice = Array.prototype.slice; var a_indexOf = Ember.EnumerableUtils.indexOf; var contexts = []; -/** @private */ + function popCtx() { return contexts.length===0 ? {} : contexts.pop(); } -/** @private */ function pushCtx(ctx) { contexts.push(ctx); return null; } -/** @private */ function iter(key, value) { var valueProvided = arguments.length === 2; @@ -5857,8 +6197,6 @@ function iter(key, value) { } /** - @class - This mixin defines the common interface implemented by enumerable objects in Ember. Most of these methods follow the standard Array iteration API defined up to JavaScript 1.8 (excluding language-specific features that @@ -5891,13 +6229,15 @@ function iter(key, value) { libraries by implementing only methods that mostly correspond to the JavaScript 1.8 API. + @class Enumerable + @namespace Ember @extends Ember.Mixin @since Ember 0.9 */ Ember.Enumerable = Ember.Mixin.create( /** @scope Ember.Enumerable.prototype */ { - /** @private - compatibility */ + // compatibility isEnumerable: true, /** @@ -5926,10 +6266,11 @@ Ember.Enumerable = Ember.Mixin.create( The default implementation of this method simply looks up the index. This works great on any Array-like objects. + @method nextObject @param {Number} index the current index of the iteration @param {Object} previousObject the value returned by the last call to nextObject. @param {Object} context a context object you can use to maintain state. - @returns {Object} the next object in the iteration or undefined + @return {Object} the next object in the iteration or undefined */ nextObject: Ember.required(Function), @@ -5949,7 +6290,8 @@ Ember.Enumerable = Ember.Mixin.create( var arr = []; arr.firstObject(); => undefined - @returns {Object} the object or undefined + @property firstObject + @return {Object} the object or undefined */ firstObject: Ember.computed(function() { if (get(this, 'length')===0) return undefined ; @@ -5972,7 +6314,8 @@ Ember.Enumerable = Ember.Mixin.create( var arr = []; arr.lastObject(); => undefined - @returns {Object} the last object or undefined + @property lastObject + @return {Object} the last object or undefined */ lastObject: Ember.computed(function() { var len = get(this, 'length'); @@ -5995,10 +6338,9 @@ Ember.Enumerable = Ember.Mixin.create( arr.contains("a"); => true arr.contains("z"); => false - @param {Object} obj - The object to search for. - - @returns {Boolean} true if object is found in enumerable. + @method contains + @param {Object} obj The object to search for. + @return {Boolean} true if object is found in enumerable. */ contains: function(obj) { return this.find(function(item) { return item===obj; }) !== undefined; @@ -6022,9 +6364,10 @@ Ember.Enumerable = Ember.Mixin.create( object that will be set as "this" on the context. This is a good way to give your iterator function access to the current object. + @method forEach @param {Function} callback The callback to execute @param {Object} [target] The target object to use - @returns {Object} receiver + @return {Object} receiver */ forEach: function(callback, target) { if (typeof callback !== "function") throw new TypeError() ; @@ -6045,8 +6388,9 @@ Ember.Enumerable = Ember.Mixin.create( /** Alias for mapProperty + @method getEach @param {String} key name of the property - @returns {Array} The mapped array. + @return {Array} The mapped array. */ getEach: function(key) { return this.mapProperty(key); @@ -6058,9 +6402,10 @@ Ember.Enumerable = Ember.Mixin.create( implements Ember.Observable, the value will be changed to set(), otherwise it will be set directly. null objects are skipped. + @method setEach @param {String} key The key to set @param {Object} value The object to set - @returns {Object} receiver + @return {Object} receiver */ setEach: function(key, value) { return this.forEach(function(item) { @@ -6087,9 +6432,10 @@ Ember.Enumerable = Ember.Mixin.create( object that will be set as "this" on the context. This is a good way to give your iterator function access to the current object. + @method map @param {Function} callback The callback to execute @param {Object} [target] The target object to use - @returns {Array} The mapped array. + @return {Array} The mapped array. */ map: function(callback, target) { var ret = []; @@ -6103,8 +6449,9 @@ Ember.Enumerable = Ember.Mixin.create( Similar to map, this specialized function returns the value of the named property on all items in the enumeration. + @method mapProperty @param {String} key name of the property - @returns {Array} The mapped array. + @return {Array} The mapped array. */ mapProperty: function(key) { return this.map(function(next) { @@ -6132,9 +6479,10 @@ Ember.Enumerable = Ember.Mixin.create( object that will be set as "this" on the context. This is a good way to give your iterator function access to the current object. + @method filter @param {Function} callback The callback to execute @param {Object} [target] The target object to use - @returns {Array} A filtered array. + @return {Array} A filtered array. */ filter: function(callback, target) { var ret = []; @@ -6149,9 +6497,10 @@ Ember.Enumerable = Ember.Mixin.create( can pass an optional second argument with the target value. Otherwise this will match any property that evaluates to true. + @method filterProperty @param {String} key the property to test @param {String} [value] optional value to test against. - @returns {Array} filtered array + @return {Array} filtered array */ filterProperty: function(key, value) { return this.filter(iter.apply(this, arguments)); @@ -6177,9 +6526,10 @@ Ember.Enumerable = Ember.Mixin.create( object that will be set as "this" on the context. This is a good way to give your iterator function access to the current object. + @method find @param {Function} callback The callback to execute @param {Object} [target] The target object to use - @returns {Object} Found item or null. + @return {Object} Found item or null. */ find: function(callback, target) { var len = get(this, 'length') ; @@ -6204,9 +6554,10 @@ Ember.Enumerable = Ember.Mixin.create( This method works much like the more generic find() method. + @method findProperty @param {String} key the property to test @param {String} [value] optional value to test against. - @returns {Object} found item or null + @return {Object} found item or null */ findProperty: function(key, value) { return this.find(iter.apply(this, arguments)); @@ -6235,9 +6586,10 @@ Ember.Enumerable = Ember.Mixin.create( if (people.every(isEngineer)) { Paychecks.addBigBonus(); } + @method every @param {Function} callback The callback to execute @param {Object} [target] The target object to use - @returns {Boolean} + @return {Boolean} */ every: function(callback, target) { return !this.find(function(x, idx, i) { @@ -6249,9 +6601,10 @@ Ember.Enumerable = Ember.Mixin.create( Returns true if the passed property resolves to true for all items in the enumerable. This method is often simpler/faster than using a callback. + @method everyProperty @param {String} key the property to test @param {String} [value] optional value to test against. - @returns {Array} filtered array + @return {Array} filtered array */ everyProperty: function(key, value) { return this.every(iter.apply(this, arguments)); @@ -6281,9 +6634,10 @@ Ember.Enumerable = Ember.Mixin.create( if (people.some(isManager)) { Paychecks.addBiggerBonus(); } + @method some @param {Function} callback The callback to execute @param {Object} [target] The target object to use - @returns {Array} A filtered array. + @return {Array} A filtered array. */ some: function(callback, target) { return !!this.find(function(x, idx, i) { @@ -6295,9 +6649,10 @@ Ember.Enumerable = Ember.Mixin.create( Returns true if the passed property resolves to true for any item in the enumerable. This method is often simpler/faster than using a callback. + @method someProperty @param {String} key the property to test @param {String} [value] optional value to test against. - @returns {Boolean} true + @return {Boolean} true */ someProperty: function(key, value) { return this.some(iter.apply(this, arguments)); @@ -6328,10 +6683,11 @@ Ember.Enumerable = Ember.Mixin.create( pass a target object to set as this for the callback. It's part of the spec. Sorry. + @method reduce @param {Function} callback The callback to execute @param {Object} initialValue Initial value for the reduce @param {String} reducerProperty internal use only. - @returns {Object} The reduced value. + @return {Object} The reduced value. */ reduce: function(callback, initialValue, reducerProperty) { if (typeof callback !== "function") { throw new TypeError(); } @@ -6350,9 +6706,10 @@ Ember.Enumerable = Ember.Mixin.create( implements it. This method corresponds to the implementation in Prototype 1.6. + @method invoke @param {String} methodName the name of the method @param {Object...} args optional arguments to pass as well. - @returns {Array} return values from calling invoke. + @return {Array} return values from calling invoke. */ invoke: function(methodName) { var args, ret = []; @@ -6372,7 +6729,8 @@ Ember.Enumerable = Ember.Mixin.create( Simply converts the enumerable into a genuine array. The order is not guaranteed. Corresponds to the method implemented by Prototype. - @returns {Array} the enumerable as an array. + @method toArray + @return {Array} the enumerable as an array. */ toArray: function() { var ret = []; @@ -6386,7 +6744,8 @@ Ember.Enumerable = Ember.Mixin.create( var arr = ["a", null, "c", null]; arr.compact(); => ["a", "c"] - @returns {Array} the array without null elements. + @method compact + @return {Array} the array without null elements. */ compact: function() { return this.without(null); }, @@ -6398,8 +6757,9 @@ Ember.Enumerable = Ember.Mixin.create( var arr = ["a", "b", "a", "c"]; arr.without("a"); => ["b", "c"] + @method without @param {Object} value - @returns {Ember.Enumerable} + @return {Ember.Enumerable} */ without: function(value) { if (!this.contains(value)) return this; // nothing to do @@ -6417,7 +6777,8 @@ Ember.Enumerable = Ember.Mixin.create( var arr = ["a", "a", "b", "b"]; arr.uniq(); => ["a", "b"] - @returns {Ember.Enumerable} + @method uniq + @return {Ember.Enumerable} */ uniq: function() { var ret = []; @@ -6435,6 +6796,7 @@ Ember.Enumerable = Ember.Mixin.create( For plain enumerables, this property is read only. Ember.Array overrides this method. + @property [] @type Ember.Array */ '[]': Ember.computed(function(key, value) { @@ -6448,6 +6810,10 @@ Ember.Enumerable = Ember.Mixin.create( /** Registers an enumerable observer. Must implement Ember.EnumerableObserver mixin. + + @method addEnumerableObserver + @param target {Object} + @param opts {Hash} */ addEnumerableObserver: function(target, opts) { var willChange = (opts && opts.willChange) || 'enumerableWillChange', @@ -6463,6 +6829,10 @@ Ember.Enumerable = Ember.Mixin.create( /** Removes a registered enumerable observer. + + @method removeEnumerableObserver + @param target {Object} + @param [opts] {Hash} */ removeEnumerableObserver: function(target, opts) { var willChange = (opts && opts.willChange) || 'enumerableWillChange', @@ -6480,6 +6850,7 @@ Ember.Enumerable = Ember.Mixin.create( Becomes true whenever the array currently has observers watching changes on the array. + @property hasEnumerableObservers @type Boolean */ hasEnumerableObservers: Ember.computed(function() { @@ -6492,15 +6863,12 @@ Ember.Enumerable = Ember.Mixin.create( change. You can either omit the parameters completely or pass the objects to be removed or added if available or just a count. - @param {Ember.Enumerable|Number} removing - An enumerable of the objects to be removed or the number of items to - be removed. - - @param {Ember.Enumerable|Number} adding - An enumerable of the objects to be added or the number of items to be - added. - - @returns {Ember.Enumerable} receiver + @method enumerableContentWillChange + @param {Ember.Enumerable|Number} removing An enumerable of the objects to + be removed or the number of items to be removed. + @param {Ember.Enumerable|Number} adding An enumerable of the objects to be + added or the number of items to be added. + @chainable */ enumerableContentWillChange: function(removing, adding) { @@ -6533,19 +6901,14 @@ Ember.Enumerable = Ember.Mixin.create( start and end values where the content changed so that it can be used to notify range observers. - @param {Number} start - optional start offset for the content change. For unordered - enumerables, you should always pass -1. - - @param {Ember.Enumerable|Number} removing - An enumerable of the objects to be removed or the number of items to - be removed. - - @param {Ember.Enumerable|Number} adding - An enumerable of the objects to be added or the number of items to be - added. - - @returns {Object} receiver + @method enumerableContentDidChange + @param {Number} [start] optional start offset for the content change. + For unordered enumerables, you should always pass -1. + @param {Ember.Enumerable|Number} removing An enumerable of the objects to + be removed or the number of items to be removed. + @param {Ember.Enumerable|Number} adding An enumerable of the objects to + be added or the number of items to be added. + @chainable */ enumerableContentDidChange: function(removing, adding) { var notify = this.propertyDidChange, removeCnt, addCnt, hasDelta; @@ -6580,26 +6943,23 @@ Ember.Enumerable = Ember.Mixin.create( (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + // .......................................................... // HELPERS // var get = Ember.get, set = Ember.set, meta = Ember.meta, map = Ember.EnumerableUtils.map, cacheFor = Ember.cacheFor; -/** @private */ function none(obj) { return obj===null || obj===undefined; } // .......................................................... // ARRAY // /** - @namespace - This module implements Observer-friendly Array-like behavior. This mixin is picked up by the Array class as well as other controllers, etc. that want to appear to be arrays. @@ -6626,19 +6986,22 @@ function none(obj) { return obj===null || obj===undefined; } Note that the Ember.Array mixin also incorporates the Ember.Enumerable mixin. All Ember.Array-like objects are also enumerable. - @extends Ember.Enumerable + @class Array + @namespace Ember + @extends Ember.Mixin + @uses Ember.Enumerable @since Ember 0.9.0 */ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.prototype */ { - /** @private - compatibility */ + // compatibility isSCArray: true, /** - @field {Number} length - Your array must support the length property. Your replace methods should set this property whenever it changes. + + @property {Number} length */ length: Ember.required(), @@ -6658,6 +7021,7 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot arr.objectAt(4); => undefined arr.objectAt(5); => undefined + @method objectAt @param {Number} idx The index of the item to return. */ @@ -6673,6 +7037,7 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot arr.objectsAt([0, 1, 2]) => ["a", "b", "c"] arr.objectsAt([2, 3, 4]) => ["c", "d", undefined] + @method objectsAt @param {Array} indexes An array of indexes of items to return. */ @@ -6681,19 +7046,19 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot return map(indexes, function(idx){ return self.objectAt(idx); }); }, - /** @private (nodoc) - overrides Ember.Enumerable version */ + // overrides Ember.Enumerable version nextObject: function(idx) { return this.objectAt(idx); }, /** - @field [] - This is the handler for the special array content property. If you get this property, it will return this. If you set this property it a new array, it will replace the current content. This property overrides the default property defined in Ember.Enumerable. + + @property [] */ '[]': Ember.computed(function(key, value) { if (value !== undefined) this.replace(0, get(this, 'length'), value) ; @@ -6708,7 +7073,7 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot return this.objectAt(get(this, 'length')-1); }).property().cacheable(), - /** @private (nodoc) - optimized version from Enumerable */ + // optimized version from Enumerable contains: function(obj){ return this.indexOf(obj) >= 0; }, @@ -6724,9 +7089,10 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot arr.slice(0, 2); => ['red', 'green'] arr.slice(1, 100); => ['green', 'blue'] + @method slice @param beginIndex {Integer} (Optional) index to begin slicing from. @param endIndex {Integer} (Optional) index to end the slice at. - @returns {Array} New array with specified slice + @return {Array} New array with specified slice */ slice: function(beginIndex, endIndex) { var ret = []; @@ -6753,9 +7119,10 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot arr.indexOf("b", 3); => -1 arr.indexOf("a", 100); => -1 + @method indexOf @param {Object} object the item to search for @param {Number} startAt optional starting location to search, default 0 - @returns {Number} index or -1 if not found + @return {Number} index or -1 if not found */ indexOf: function(object, startAt) { var idx, len = get(this, 'length'); @@ -6783,9 +7150,10 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot arr.lastIndexOf("b", 3); => 1 arr.lastIndexOf("a", 100); => 4 + @method lastIndexOf @param {Object} object the item to search for @param {Number} startAt optional starting location to search, default 0 - @returns {Number} index or -1 if not found + @return {Number} index or -1 if not found */ lastIndexOf: function(object, startAt) { var idx, len = get(this, 'length'); @@ -6821,14 +7189,11 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot which you can use to override the method names that will be invoked on the target. - @param {Object} target - The observer object. - - @param {Hash} opts - Optional hash of configuration options including willChange, didChange, - and a context option. - - @returns {Ember.Array} receiver + @method addArrayObserver + @param {Object} target The observer object. + @param {Hash} opts Optional hash of configuration options including + willChange, didChange, and a context option. + @return {Ember.Array} receiver */ addArrayObserver: function(target, opts) { var willChange = (opts && opts.willChange) || 'arrayWillChange', @@ -6847,10 +7212,9 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot registered. Calling this method multiple times with the same object will have no effect. - @param {Object} target - The object observing the array. - - @returns {Ember.Array} receiver + @method removeArrayObserver + @param {Object} target The object observing the array. + @return {Ember.Array} receiver */ removeArrayObserver: function(target, opts) { var willChange = (opts && opts.willChange) || 'arrayWillChange', @@ -6868,7 +7232,7 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot Becomes true whenever the array currently has observers watching changes on the array. - @type Boolean + @property Boolean */ hasArrayObservers: Ember.computed(function() { return Ember.hasListeners(this, '@array:change') || Ember.hasListeners(this, '@array:before'); @@ -6880,16 +7244,11 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot invalidate any related properties. Pass the starting index of the change as well as a delta of the amounts to change. - @param {Number} startIdx - The starting index in the array that will change. - - @param {Number} removeAmt - The number of items that will be removed. If you pass null assumes 0 - - @param {Number} addAmt - The number of items that will be added. If you pass null assumes 0. - - @returns {Ember.Array} receiver + @method arrayContentWillChange + @param {Number} startIdx The starting index in the array that will change. + @param {Number} removeAmt The number of items that will be removed. If you pass null assumes 0 + @param {Number} addAmt The number of items that will be added. If you pass null assumes 0. + @return {Ember.Array} receiver */ arrayContentWillChange: function(startIdx, removeAmt, addAmt) { @@ -6968,6 +7327,8 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot on the array. Just get an equivalent property on this object and it will return an enumerable that maps automatically to the named key on the member objects. + + @property @each */ '@each': Ember.computed(function() { if (!this.__each) this.__each = new Ember.EachProxy(this); @@ -6981,20 +7342,20 @@ Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.protot (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /** - @namespace +@module ember +@submodule ember-runtime +*/ + +/** Implements some standard methods for comparing objects. Add this mixin to any class you create that can compare its instances. You should implement the compare() method. + @class Comparable + @namespace Ember @extends Ember.Mixin @since Ember 0.9 */ @@ -7003,9 +7364,9 @@ Ember.Comparable = Ember.Mixin.create( /** @scope Ember.Comparable.prototype */{ /** walk like a duck. Indicates that the object can be compared. + @property isComparable @type Boolean @default true - @constant */ isComparable: true, @@ -7019,9 +7380,10 @@ Ember.Comparable = Ember.Mixin.create( /** @scope Ember.Comparable.prototype */{ Default implementation raises an exception. + @method compare @param a {Object} the first object to compare @param b {Object} the second object to compare - @returns {Integer} the result of the comparison + @return {Integer} the result of the comparison */ compare: Ember.required(Function) @@ -7033,17 +7395,16 @@ Ember.Comparable = Ember.Mixin.create( /** @scope Ember.Comparable.prototype */{ (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2010 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + + + var get = Ember.get, set = Ember.set; /** - @namespace - Implements some standard methods for copying an object. Add this mixin to any object you create that can create a copy of itself. This mixin is added automatically to the built-in array. @@ -7053,6 +7414,8 @@ var get = Ember.get, set = Ember.set; Note that frozenCopy() will only work if you also implement Ember.Freezable. + @class Copyable + @namespace Ember @extends Ember.Mixin @since Ember 0.9 */ @@ -7063,9 +7426,9 @@ Ember.Copyable = Ember.Mixin.create( Override to return a copy of the receiver. Default implementation raises an exception. - @function + @method copy @param deep {Boolean} if true, a deep copy of the object should be made - @returns {Object} copy of receiver + @return {Object} copy of receiver */ copy: Ember.required(Function), @@ -7080,7 +7443,8 @@ Ember.Copyable = Ember.Mixin.create( since a freezable object can simply return itself without actually consuming more memory. - @returns {Object} copy of receiver or receiver + @method frozenCopy + @return {Object} copy of receiver or receiver */ frozenCopy: function() { if (Ember.Freezable && Ember.Freezable.detect(this)) { @@ -7099,22 +7463,15 @@ Ember.Copyable = Ember.Mixin.create( (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2010 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - - - +/** +@module ember +@submodule ember-runtime +*/ var get = Ember.get, set = Ember.set; /** - @namespace - The Ember.Freezable mixin implements some basic methods for marking an object as frozen. Once an object is frozen it should be read only. No changes may be made the internal state of the object. @@ -7166,6 +7523,8 @@ var get = Ember.get, set = Ember.set; Ember.Copyable protocol, which defines a frozenCopy() method that will return a frozen object, if the object implements this method as well. + @class Freezable + @namespace Ember @extends Ember.Mixin @since Ember 0.9 */ @@ -7176,6 +7535,7 @@ Ember.Freezable = Ember.Mixin.create( Set to true when the object is frozen. Use this property to detect whether your object is frozen or not. + @property isFrozen @type Boolean */ isFrozen: false, @@ -7184,7 +7544,8 @@ Ember.Freezable = Ember.Mixin.create( Freezes the object. Once this method has been called the object should no longer allow any properties to be edited. - @returns {Object} receiver + @method freeze + @return {Object} receiver */ freeze: function() { if (get(this, 'isFrozen')) return this; @@ -7196,24 +7557,19 @@ Ember.Freezable = Ember.Mixin.create( Ember.FROZEN_ERROR = "Frozen object cannot be modified."; - - - })(); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + var forEach = Ember.EnumerableUtils.forEach; /** - @class - This mixin defines the API for modifying generic enumerables. These methods can be applied to an object regardless of whether it is ordered or unordered. @@ -7244,8 +7600,10 @@ var forEach = Ember.EnumerableUtils.forEach; this mixin in your class and implement the required methods. In your unit tests, be sure to apply the Ember.MutableEnumerableTests to your object. + @class MutableEnumerable + @namespace Ember @extends Ember.Mixin - @extends Ember.Enumerable + @uses Ember.Enumerable */ Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.MutableEnumerable.prototype */ { @@ -7260,20 +7618,18 @@ Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable, If the passed object is of a type not supported by the receiver then this method should raise an exception. - @function - - @param {Object} object - The object to add to the enumerable. - - @returns {Object} the passed object + @method addObject + @param {Object} object The object to add to the enumerable. + @return {Object} the passed object */ addObject: Ember.required(Function), /** Adds each object in the passed enumerable to the receiver. + @method addObjects @param {Ember.Enumerable} objects the objects to add. - @returns {Object} receiver + @return {Object} receiver */ addObjects: function(objects) { Ember.beginPropertyChanges(this); @@ -7292,12 +7648,9 @@ Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable, If the passed object is of a type not supported by the receiver then this method should raise an exception. - @function - - @param {Object} object - The object to remove from the enumerable. - - @returns {Object} the passed object + @method removeObject + @param {Object} object The object to remove from the enumerable. + @return {Object} the passed object */ removeObject: Ember.required(Function), @@ -7305,8 +7658,9 @@ Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable, /** Removes each objects in the passed enumerable from the receiver. + @method removeObjects @param {Ember.Enumerable} objects the objects to remove - @returns {Object} receiver + @return {Object} receiver */ removeObjects: function(objects) { Ember.beginPropertyChanges(this); @@ -7322,11 +7676,10 @@ Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable, (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ // .......................................................... // CONSTANTS // @@ -7341,8 +7694,6 @@ var EMPTY = []; var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach; /** - @class - This mixin defines the API for modifying array-like objects. These methods can be applied only to a collection that keeps its items in an ordered set. @@ -7350,9 +7701,11 @@ var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach; For example, one might implement a SparseArray that cannot be directly modified, but if its underlying enumerable changes, it will change also. + @class MutableArray + @namespace Ember @extends Ember.Mixin - @extends Ember.Array - @extends Ember.MutableEnumerable + @uses Ember.Array + @uses Ember.MutableEnumerable */ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, /** @scope Ember.MutableArray.prototype */ { @@ -7364,19 +7717,13 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, should replace amt objects started at idx with the objects in the passed array. You should also call this.enumerableContentDidChange() ; - @function - - @param {Number} idx - Starting index in the array to replace. If idx >= length, then append - to the end of the array. - - @param {Number} amt - Number of elements that should be removed from the array, starting at - *idx*. - - @param {Array} objects - An array of zero or more objects that should be inserted into the array - at *idx* + @method replace + @param {Number} idx Starting index in the array to replace. If idx >= length, + then append to the end of the array. + @param {Number} amt Number of elements that should be removed from the array, + starting at *idx*. + @param {Array} objects An array of zero or more objects that should be inserted + into the array at *idx* */ replace: Ember.required(), @@ -7389,7 +7736,8 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.clear(); => [] colors.length(); => 0 - @returns {Ember.Array} An empty Array. + @method clear + @return {Ember.Array} An empty Array. */ clear: function () { var len = get(this, 'length'); @@ -7406,6 +7754,7 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.insertAt(2, "yellow"); => ["red", "green", "yellow", "blue"] colors.insertAt(5, "orange"); => Error: Index out of range + @method insertAt @param {Number} idx index of insert the object at. @param {Object} object object to insert */ @@ -7427,14 +7776,12 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.removeAt(2, 2); => ["green", "blue"] colors.removeAt(4, 2); => Error: Index out of range + @method removeAt @param {Number} start index, start of range @param {Number} len length of passing range - @returns {Object} receiver + @return {Object} receiver */ removeAt: function(start, len) { - - var delta = 0; - if ('number' === typeof start) { if ((start < 0) || (start >= get(this, 'length'))) { @@ -7457,6 +7804,8 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.pushObject("black"); => ["red", "green", "blue", "black"] colors.pushObject(["yellow", "orange"]); => ["red", "green", "blue", "black", ["yellow", "orange"]] + @method pushObject + @param {anything} obj object to push */ pushObject: function(obj) { this.insertAt(get(this, 'length'), obj) ; @@ -7471,8 +7820,9 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.pushObjects("black"); => ["red", "green", "blue", "black"] colors.pushObjects(["yellow", "orange"]); => ["red", "green", "blue", "black", "yellow", "orange"] + @method pushObjects @param {Ember.Enumerable} objects the objects to add - @returns {Ember.Array} receiver + @return {Ember.Array} receiver */ pushObjects: function(objects) { this.replace(get(this, 'length'), 0, objects); @@ -7487,6 +7837,8 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.popObject(); => "blue" console.log(colors); => ["red", "green"] + @method popObject + @return object */ popObject: function() { var len = get(this, 'length') ; @@ -7505,6 +7857,8 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.shiftObject(); => "red" console.log(colors); => ["green", "blue"] + @method shiftObject + @return object */ shiftObject: function() { if (get(this, 'length') === 0) return null ; @@ -7521,6 +7875,8 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.unshiftObject("yellow"); => ["yellow", "red", "green", "blue"] colors.unshiftObject(["black", "white"]); => [["black", "white"], "yellow", "red", "green", "blue"] + @method unshiftObject + @param {anything} obj object to unshift */ unshiftObject: function(obj) { this.insertAt(0, obj) ; @@ -7535,8 +7891,9 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, colors.unshiftObjects(["black", "white"]); => ["black", "white", "red", "green", "blue"] colors.unshiftObjects("yellow"); => Type Error: 'undefined' is not a function + @method unshiftObjects @param {Ember.Enumerable} objects the objects to add - @returns {Ember.Array} receiver + @return {Ember.Array} receiver */ unshiftObjects: function(objects) { this.replace(0, 0, objects); @@ -7547,6 +7904,7 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, Reverse objects in the array. Works just like reverse() but it is KVO-compliant. + @method reverseObjects @return {Ember.Array} receiver */ reverseObjects: function() { @@ -7557,11 +7915,31 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, return this; }, + /** + Replace all the the receiver's content with content of the argument. + If argument is an empty array receiver will be cleared. + + var colors = ["red", "green", "blue"]; + colors.setObjects(["black", "white"]); => ["black", "white"] + colors.setObjects([]); => [] + + @method setObjects + @param {Ember.Array} objects array whose content will be used for replacing + the content of the receiver + @return {Ember.Array} receiver with the new content + */ + setObjects: function(objects) { + if (objects.length === 0) return this.clear(); + + var len = get(this, 'length'); + this.replace(0, len, objects); + return this; + }, + // .......................................................... // IMPLEMENT Ember.MutableEnumerable // - /** @private (nodoc) */ removeObject: function(obj) { var loc = get(this, 'length') || 0; while(--loc >= 0) { @@ -7571,7 +7949,6 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, return this ; }, - /** @private (nodoc) */ addObject: function(obj) { if (!this.contains(obj)) this.pushObject(obj); return this ; @@ -7585,17 +7962,14 @@ Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable, (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty; /** - @class - ## Overview This mixin provides properties and property observing functionality, core @@ -7653,11 +8027,13 @@ var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty; resulting value of the computed property is unchanged. This is necessary because computed properties are not computed until `get` is called. + @class Observable + @namespace Ember @extends Ember.Mixin */ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { - /** @private - compatibility */ + // compatibility isObserverable: true, /** @@ -7692,8 +8068,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { instead. This allows you to implement "virtual" properties that are not defined upfront. + @method get @param {String} key The property to retrieve - @returns {Object} The property value or undefined. + @return {Object} The property value or undefined. */ get: function(keyName) { return get(this, keyName); @@ -7709,8 +8086,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { record.getProperties(['firstName', 'lastName', 'zipCode']); // => { firstName: 'John', lastName: 'Doe', zipCode: '10011' } + @method getProperties @param {String...|Array} list of keys to get - @returns {Hash} + @return {Hash} */ getProperties: function() { var ret = {}; @@ -7765,9 +8143,10 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { record.set('firstName', 'Charles').set('lastName', 'Jolley'); + @method set @param {String} key The property to set @param {Object} value The value to set or null. - @returns {Ember.Observable} + @return {Ember.Observable} */ set: function(keyName, value) { set(this, keyName, value); @@ -7780,8 +8159,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { record.setProperties({ firstName: 'Charles', lastName: 'Jolley' }); + @method setProperties @param {Hash} hash the hash of keys and values to set - @returns {Ember.Observable} + @return {Ember.Observable} */ setProperties: function(hash) { return Ember.setProperties(this, hash); @@ -7797,7 +8177,8 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { notifications. When you are done making changes, call endPropertyChanges() to deliver the deferred change notifications and end deferring. - @returns {Ember.Observable} + @method beginPropertyChanges + @return {Ember.Observable} */ beginPropertyChanges: function() { Ember.beginPropertyChanges(); @@ -7814,7 +8195,8 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { notifications. When you are done making changes, call this method to deliver the deferred change notifications and end deferring. - @returns {Ember.Observable} + @method endPropertyChanges + @return {Ember.Observable} */ endPropertyChanges: function() { Ember.endPropertyChanges(); @@ -7834,8 +8216,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { a pair. If you do not, it may get the property change groups out of order and cause notifications to be delivered more often than you would like. + @method propertyWillChange @param {String} key The property key that is about to change. - @returns {Ember.Observable} + @return {Ember.Observable} */ propertyWillChange: function(keyName){ Ember.propertyWillChange(this, keyName); @@ -7855,8 +8238,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { a pair. If you do not, it may get the property change groups out of order and cause notifications to be delivered more often than you would like. + @method propertyDidChange @param {String} keyName The property key that has just changed. - @returns {Ember.Observable} + @return {Ember.Observable} */ propertyDidChange: function(keyName) { Ember.propertyDidChange(this, keyName); @@ -7867,8 +8251,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { Convenience method to call `propertyWillChange` and `propertyDidChange` in succession. + @method notifyPropertyChange @param {String} keyName The property key to be notified about. - @returns {Ember.Observable} + @return {Ember.Observable} */ notifyPropertyChange: function(keyName) { this.propertyWillChange(keyName); @@ -7918,10 +8303,11 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { only a sender and key value as parameters or, if you aren't interested in any of these values, to write an observer that has no parameters at all. + @method addObserver @param {String} key The key to observer @param {Object} target The target object to invoke @param {String|Function} method The method to invoke. - @returns {Ember.Object} self + @return {Ember.Object} self */ addObserver: function(key, target, method) { Ember.addObserver(this, key, target, method); @@ -7932,10 +8318,11 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { the same key, target, and method you passed to addObserver() and your target will no longer receive notifications. + @method removeObserver @param {String} key The key to observer @param {Object} target The target object to invoke @param {String|Function} method The method to invoke. - @returns {Ember.Observable} receiver + @return {Ember.Observable} receiver */ removeObserver: function(key, target, method) { Ember.removeObserver(this, key, target, method); @@ -7947,8 +8334,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { an expensive action until someone begins observing a particular property on the object. + @method hasObserverFor @param {String} key Key to check - @returns {Boolean} + @return {Boolean} */ hasObserverFor: function(key) { return Ember.hasListeners(this, key+':change'); @@ -7959,8 +8347,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { property that has not been defined in one of the typical ways. Override this method to create "virtual" properties. + @method unknownProperty @param {String} key The name of the unknown property that was requested. - @returns {Object} The property value or undefined. Default is undefined. + @return {Object} The property value or undefined. Default is undefined. */ unknownProperty: function(key) { return undefined; @@ -7971,6 +8360,7 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { property that has not been defined in one of the typical ways. Override this method to create "virtual" properties. + @method setUnknownProperty @param {String} key The name of the unknown property to be set. @param {Object} value The value the unknown property is to be set to. */ @@ -7981,8 +8371,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { /** @deprecated + @method getPath @param {String} path The property path to retrieve - @returns {Object} The property value or undefined. + @return {Object} The property value or undefined. */ getPath: function(path) { Ember.deprecate("getPath is deprecated since get now supports paths"); @@ -7991,9 +8382,10 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { /** @deprecated + @method setPath @param {String} path The path to the property that will be set @param {Object} value The value to set or null. - @returns {Ember.Observable} + @return {Ember.Observable} */ setPath: function(path, value) { Ember.deprecate("setPath is deprecated since set now supports paths"); @@ -8006,9 +8398,10 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { person.getWithDefault('lastName', 'Doe'); + @method getWithDefault @param {String} keyName The name of the property to retrieve @param {Object} defaultValue The value to return if the property value is undefined - @returns {Object} The property value or the defaultValue. + @return {Object} The property value or the defaultValue. */ getWithDefault: function(keyName, defaultValue) { return Ember.getWithDefault(this, keyName, defaultValue); @@ -8020,9 +8413,10 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { person.incrementProperty('age'); team.incrementProperty('score', 2); + @method incrementProperty @param {String} keyName The name of the property to increment @param {Object} increment The amount to increment by. Defaults to 1 - @returns {Object} The new property value + @return {Object} The new property value */ incrementProperty: function(keyName, increment) { if (!increment) { increment = 1; } @@ -8036,9 +8430,10 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { player.decrementProperty('lives'); orc.decrementProperty('health', 5); + @method decrementProperty @param {String} keyName The name of the property to decrement @param {Object} increment The amount to decrement by. Defaults to 1 - @returns {Object} The new property value + @return {Object} The new property value */ decrementProperty: function(keyName, increment) { if (!increment) { increment = 1; } @@ -8052,8 +8447,9 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { starship.toggleProperty('warpDriveEnaged'); + @method toggleProperty @param {String} keyName The name of the property to toggle - @returns {Object} The new property value + @return {Object} The new property value */ toggleProperty: function(keyName) { set(this, keyName, !get(this, keyName)); @@ -8066,29 +8462,38 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { without accidentally invoking it if it is intended to be generated lazily. + @method cacheFor @param {String} keyName - @returns {Object} The cached value of the computed property, if any + @return {Object} The cached value of the computed property, if any */ cacheFor: function(keyName) { return Ember.cacheFor(this, keyName); }, - /** @private - intended for debugging purposes */ + // intended for debugging purposes observersForKey: function(keyName) { return Ember.observersFor(this, keyName); } }); - - })(); (function() { +/** +@module ember +@submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set; +/** +@class TargetActionSupport +@namespace Ember +@extends Ember.Mixin +*/ Ember.TargetActionSupport = Ember.Mixin.create({ target: null, action: null, @@ -8135,12 +8540,16 @@ Ember.TargetActionSupport = Ember.Mixin.create({ (function() { /** - @class +@module ember +@submodule ember-runtime +*/ - @extends Ember.Mixin +/** + @class Evented + @namespace Ember + @extends Ember.Mixin */ -Ember.Evented = Ember.Mixin.create( - /** @scope Ember.Evented.prototype */ { +Ember.Evented = Ember.Mixin.create({ on: function(name, target, method) { Ember.addListener(this, name, target, method); }, @@ -8194,40 +8603,39 @@ Ember.Evented = Ember.Mixin.create( (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - +/** +@module ember +@submodule ember-runtime +*/ // NOTE: this object should never be included directly. Instead use Ember. // Ember.Object. We only define this separately so that Ember.Set can depend on it - -var classToString = Ember.Mixin.prototype.toString; -var set = Ember.set, get = Ember.get; -var o_create = Ember.create, +var set = Ember.set, get = Ember.get, + o_create = Ember.create, o_defineProperty = Ember.platform.defineProperty, a_slice = Array.prototype.slice, + GUID_KEY = Ember.GUID_KEY, + guidFor = Ember.guidFor, + generateGuid = Ember.generateGuid, meta = Ember.meta, rewatch = Ember.rewatch, finishChains = Ember.finishChains, - finishPartial = Ember.Mixin.finishPartial, - reopen = Ember.Mixin.prototype.reopen; + destroy = Ember.destroy, + schedule = Ember.run.schedule, + Mixin = Ember.Mixin, + applyMixin = Mixin._apply, + finishPartial = Mixin.finishPartial, + reopen = Mixin.prototype.reopen, + classToString = Mixin.prototype.toString; var undefinedDescriptor = { configurable: true, @@ -8236,7 +8644,6 @@ var undefinedDescriptor = { value: undefined }; -/** @private */ function makeCtor() { // Note: avoid accessing any properties on the object since it makes the @@ -8249,14 +8656,14 @@ function makeCtor() { if (!wasApplied) { Class.proto(); // prepare prototype... } - var m = Ember.meta(this); + o_defineProperty(this, GUID_KEY, undefinedDescriptor); + o_defineProperty(this, '_super', undefinedDescriptor); + var m = meta(this); m.proto = this; if (initMixins) { this.reopen.apply(this, initMixins); initMixins = null; } - o_defineProperty(this, Ember.GUID_KEY, undefinedDescriptor); - o_defineProperty(this, '_super', undefinedDescriptor); finishPartial(this, m); delete m.proto; finishChains(this); @@ -8266,7 +8673,7 @@ function makeCtor() { Class.toString = classToString; Class.willReopen = function() { if (wasApplied) { - Class.PrototypeMixin = Ember.Mixin.create(Class.PrototypeMixin); + Class.PrototypeMixin = Mixin.create(Class.PrototypeMixin); } wasApplied = false; @@ -8292,23 +8699,27 @@ function makeCtor() { var CoreObject = makeCtor(); -CoreObject.PrototypeMixin = Ember.Mixin.create( -/** @scope Ember.CoreObject.prototype */ { +CoreObject.PrototypeMixin = Mixin.create({ reopen: function() { - Ember.Mixin._apply(this, arguments, true); + applyMixin(this, arguments, true); return this; }, isInstance: true, - /** @private */ init: function() {}, - /** @field */ + /** + @property isDestroyed + @default false + */ isDestroyed: false, - /** @field */ + /** + @property isDestroying + @default false + */ isDestroying: false, /** @@ -8321,7 +8732,8 @@ CoreObject.PrototypeMixin = Ember.Mixin.create( Note that destruction is scheduled for the end of the run loop and does not happen immediately. - @returns {Ember.Object} receiver + @method destroy + @return {Ember.Object} receiver */ destroy: function() { if (this.isDestroying) { return; } @@ -8331,18 +8743,20 @@ CoreObject.PrototypeMixin = Ember.Mixin.create( if (this.willDestroy) { this.willDestroy(); } set(this, 'isDestroyed', true); - Ember.run.schedule('destroy', this, this._scheduledDestroy); + schedule('destroy', this, this._scheduledDestroy); return this; }, /** + @private + Invoked by the run loop to actually destroy the object. This is scheduled for execution by the `destroy` method. - @private + @method _scheduledDestroy */ _scheduledDestroy: function() { - Ember.destroy(this); + destroy(this); if (this.didDestroy) { this.didDestroy(); } }, @@ -8353,7 +8767,7 @@ CoreObject.PrototypeMixin = Ember.Mixin.create( }, toString: function() { - return '<'+this.constructor.toString()+':'+Ember.guidFor(this)+'>'; + return '<'+this.constructor.toString()+':'+guidFor(this)+'>'; } }); @@ -8363,8 +8777,7 @@ if (Ember.config.overridePrototypeMixin) { CoreObject.__super__ = null; -var ClassMixin = Ember.Mixin.create( -/** @scope Ember.ClassMixin.prototype */ { +var ClassMixin = Mixin.create({ ClassMixin: Ember.required(), @@ -8376,8 +8789,8 @@ var ClassMixin = Ember.Mixin.create( extend: function() { var Class = makeCtor(), proto; - Class.ClassMixin = Ember.Mixin.create(this.ClassMixin); - Class.PrototypeMixin = Ember.Mixin.create(this.PrototypeMixin); + Class.ClassMixin = Mixin.create(this.ClassMixin); + Class.PrototypeMixin = Mixin.create(this.PrototypeMixin); Class.ClassMixin.ownerConstructor = Class; Class.PrototypeMixin.ownerConstructor = Class; @@ -8389,7 +8802,7 @@ var ClassMixin = Ember.Mixin.create( proto = Class.prototype = o_create(this.prototype); proto.constructor = Class; - Ember.generateGuid(proto, 'ember'); + generateGuid(proto, 'ember'); meta(proto).proto = proto; // this will disable observers on prototype Class.ClassMixin.apply(Class); @@ -8410,7 +8823,7 @@ var ClassMixin = Ember.Mixin.create( reopenClass: function() { reopen.apply(this.ClassMixin, arguments); - Ember.Mixin._apply(this, arguments, false); + applyMixin(this, arguments, false); return this; }, @@ -8446,6 +8859,9 @@ var ClassMixin = Ember.Mixin.create( MyClass.metaForProperty('person'); This will return the original hash that was passed to `meta()`. + + @method metaForProperty + @param key {String} property name */ metaForProperty: function(key) { var desc = meta(this.proto(), false).descs[key]; @@ -8457,6 +8873,10 @@ var ClassMixin = Ember.Mixin.create( /** Iterate over each computed property for the class, passing its name and any associated metadata (see `metaForProperty`) to the callback. + + @method eachComputedProperty + @param {Function} callback + @param {Object} binding */ eachComputedProperty: function(callback, binding) { var proto = this.proto(), @@ -8483,7 +8903,8 @@ CoreObject.ClassMixin = ClassMixin; ClassMixin.apply(CoreObject); /** - @class + @class CoreObject + @namespace Ember */ Ember.CoreObject = CoreObject; @@ -8495,16 +8916,14 @@ Ember.CoreObject = CoreObject; (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set, guidFor = Ember.guidFor, none = Ember.none; /** - @class - An unordered collection of objects. A Set works a bit like an array except that its items are not ordered. @@ -8592,11 +9011,12 @@ var get = Ember.get, set = Ember.set, guidFor = Ember.guidFor, none = Ember.none code that can know with certainty when the underlying set data will or will not be modified. - @extends Ember.Enumerable - @extends Ember.MutableEnumerable - @extends Ember.Copyable - @extends Ember.Freezable - + @class Set + @namespace Ember + @extends Ember.CoreObject + @uses Ember.MutableEnumerable + @uses Ember.Copyable + @uses Ember.Freezable @since Ember 0.9 */ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Ember.Freezable, @@ -8609,6 +9029,7 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb /** This property will change as the number of objects in the set changes. + @property length @type number @default 0 */ @@ -8623,7 +9044,8 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.clear(); colors.length; => 0 - @returns {Ember.Set} An empty Set + @method clear + @return {Ember.Set} An empty Set */ clear: function() { if (this.isFrozen) { throw new Error(Ember.FROZEN_ERROR); } @@ -8661,8 +9083,9 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb same_colors.isEqual(colors); => true same_colors.isEqual(["purple", "brown"]); => false + @method isEqual @param {Ember.Set} obj the other object. - @returns {Boolean} + @return {Boolean} */ isEqual: function(obj) { // fail fast @@ -8692,9 +9115,9 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.add(null); => ["blue", "red"] colors.add(undefined); => ["blue", "red"] - @function + @method add @param {Object} obj The object to add. - @returns {Ember.Set} The set itself. + @return {Ember.Set} The set itself. */ add: Ember.alias('addObject'), @@ -8708,9 +9131,9 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.remove("purple"); => ["blue", "green"] colors.remove(null); => ["blue", "green"] - @function + @method remove @param {Object} obj The object to remove - @returns {Ember.Set} The set itself. + @return {Ember.Set} The set itself. */ remove: Ember.alias('removeObject'), @@ -8722,7 +9145,8 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.pop(); => "green" colors.pop(); => null - @returns {Object} The removed object from the set or null. + @method pop + @return {Object} The removed object from the set or null. */ pop: function() { if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR); @@ -8742,8 +9166,8 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.push("green"); => ["red", "green"] colors.push("blue"); => ["red", "green", "blue"] - @function - @returns {Ember.Set} The set itself. + @method push + @return {Ember.Set} The set itself. */ push: Ember.alias('addObject'), @@ -8757,8 +9181,8 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.shift(); => "green" colors.shift(); => null - @function - @returns {Object} The removed object from the set or null. + @method shift + @return {Object} The removed object from the set or null. */ shift: Ember.alias('pop'), @@ -8773,8 +9197,8 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb colors.unshift("green"); => ["red", "green"] colors.unshift("blue"); => ["red", "green", "blue"] - @function - @returns {Ember.Set} The set itself. + @method unshift + @return {Ember.Set} The set itself. */ unshift: Ember.alias('push'), @@ -8786,9 +9210,9 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb var colors = new Ember.Set(); colors.addEach(["red", "green", "blue"]); => ["red", "green", "blue"] - @function + @method addEach @param {Ember.Enumerable} objects the objects to add. - @returns {Ember.Set} The set itself. + @return {Ember.Set} The set itself. */ addEach: Ember.alias('addObjects'), @@ -8800,9 +9224,9 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb var colors = new Ember.Set(["red", "green", "blue"]); colors.removeEach(["red", "blue"]); => ["green"] - @function + @method removeEach @param {Ember.Enumerable} objects the objects to remove. - @returns {Ember.Set} The set itself. + @return {Ember.Set} The set itself. */ removeEach: Ember.alias('removeObjects'), @@ -8810,28 +9234,27 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb // PRIVATE ENUMERABLE SUPPORT // - /** @private */ init: function(items) { this._super(); if (items) this.addObjects(items); }, - /** @private (nodoc) - implement Ember.Enumerable */ + // implement Ember.Enumerable nextObject: function(idx) { return this[idx]; }, - /** @private - more optimized version */ + // more optimized version firstObject: Ember.computed(function() { return this.length > 0 ? this[0] : undefined; }).property().cacheable(), - /** @private - more optimized version */ + // more optimized version lastObject: Ember.computed(function() { return this.length > 0 ? this[this.length-1] : undefined; }).property().cacheable(), - /** @private (nodoc) - implements Ember.MutableEnumerable */ + // implements Ember.MutableEnumerable addObject: function(obj) { if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR); if (none(obj)) return this; // nothing to do @@ -8859,7 +9282,7 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb return this; }, - /** @private (nodoc) - implements Ember.MutableEnumerable */ + // implements Ember.MutableEnumerable removeObject: function(obj) { if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR); if (none(obj)) return this; // nothing to do @@ -8898,12 +9321,11 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb return this; }, - /** @private (nodoc) - optimized version */ + // optimized version contains: function(obj) { return this[guidFor(obj)]>=0; }, - /** @private (nodoc) */ copy: function() { var C = this.constructor, ret = new C(), loc = get(this, 'length'); set(ret, 'length', loc); @@ -8914,7 +9336,6 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb return ret; }, - /** @private */ toString: function() { var len = this.length, idx, array = []; for(idx = 0; idx < len; idx++) { @@ -8930,20 +9351,20 @@ Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Emb (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /** - @class +@module ember +@submodule ember-runtime +*/ +/** `Ember.Object` is the main base class for all Ember objects. It is a subclass of `Ember.CoreObject` with the `Ember.Observable` mixin applied. For details, see the documentation for each of these. + @class Object + @namespace Ember @extends Ember.CoreObject - @extends Ember.Observable + @uses Ember.Observable */ Ember.Object = Ember.CoreObject.extend(Ember.Observable); @@ -8952,15 +9373,14 @@ Ember.Object = Ember.CoreObject.extend(Ember.Observable); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + var indexOf = Ember.ArrayPolyfills.indexOf; /** - @private A Namespace is an object usually used to contain other objects or methods such as an application or framework. Create a namespace anytime you want to define one of these new containers. @@ -8971,6 +9391,9 @@ var indexOf = Ember.ArrayPolyfills.indexOf; VERSION: '1.0.0' }); + @class Namespace + @namespace Ember + @extends Ember.Object */ Ember.Namespace = Ember.Object.extend({ isNamespace: true, @@ -9001,14 +9424,12 @@ Ember.Namespace.PROCESSED = false; (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /** - @private +@module ember +@submodule ember-runtime +*/ +/** Defines a namespace that will contain an executable application. This is very similar to a normal namespace except that it is expected to include at least a 'ready' function which can be run to initialize the application. @@ -9028,6 +9449,9 @@ Ember.Namespace.PROCESSED = false; //..init code goes here... } + @class Application + @namespace Ember + @extends Ember.Namespace */ Ember.Application = Ember.Namespace.extend(); @@ -9037,16 +9461,15 @@ Ember.Application = Ember.Namespace.extend(); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + + var get = Ember.get, set = Ember.set; /** - @class - An ArrayProxy wraps any other object that implements Ember.Array and/or Ember.MutableArray, forwarding all requests. This makes it very useful for a number of binding use cases or other cases where being able to swap @@ -9074,9 +9497,10 @@ var get = Ember.get, set = Ember.set; ap.get('firstObject'); // => 'DOG' + @class ArrayProxy + @namespace Ember @extends Ember.Object - @extends Ember.Array - @extends Ember.MutableArray + @uses Ember.MutableArray */ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, /** @scope Ember.ArrayProxy.prototype */ { @@ -9085,6 +9509,7 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, The content array. Must be an object that implements Ember.Array and/or Ember.MutableArray. + @property content @type Ember.Array */ content: null, @@ -9093,6 +9518,8 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, The array that the proxy pretends to be. In the default `ArrayProxy` implementation, this and `content` are the same. Subclasses of `ArrayProxy` can override this property to provide things like sorting and filtering. + + @property arrangedContent */ arrangedContent: Ember.computed('content', function() { return get(this, 'content'); @@ -9105,10 +9532,9 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, This method will only be called if content is non-null. - @param {Number} idx - The index to retrieve. - - @returns {Object} the value or undefined if none found + @method objectAtContent + @param {Number} idx The index to retrieve. + @return {Object} the value or undefined if none found */ objectAtContent: function(idx) { return get(this, 'arrangedContent').objectAt(idx); @@ -9121,26 +9547,29 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, This method will only be called if content is non-null. - @param {Number} idx - The starting index - - @param {Number} amt - The number of items to remove from the content. - - @param {Array} objects - Optional array of objects to insert or null if no objects. - - @returns {void} + @method replaceContent + @param {Number} idx The starting index + @param {Number} amt The number of items to remove from the content. + @param {Array} objects Optional array of objects to insert or null if no objects. + @return {void} */ replaceContent: function(idx, amt, objects) { get(this, 'arrangedContent').replace(idx, amt, objects); }, /** + @private + Invoked when the content property is about to change. Notifies observers that the entire array content will change. + + @method _contentWillChange */ _contentWillChange: Ember.beforeObserver(function() { + this._teardownContent(); + }, 'content'), + + _teardownContent: function() { var content = get(this, 'content'); if (content) { @@ -9149,42 +9578,46 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, didChange: 'contentArrayDidChange' }); } - }, 'content'), - + }, contentArrayWillChange: Ember.K, contentArrayDidChange: Ember.K, /** + @private + Invoked when the content property changes. Notifies observers that the entire array content has changed. + + @method _contentDidChange */ _contentDidChange: Ember.observer(function() { - var content = get(this, 'content'), - len = content ? get(content, 'length') : 0; + var content = get(this, 'content'); Ember.assert("Can't set ArrayProxy's content to itself", content !== this); + this._setupContent(); + }, 'content'), + + _setupContent: function() { + var content = get(this, 'content'); + if (content) { content.addArrayObserver(this, { willChange: 'contentArrayWillChange', didChange: 'contentArrayDidChange' }); } - }, 'content'), + }, _arrangedContentWillChange: Ember.beforeObserver(function() { var arrangedContent = get(this, 'arrangedContent'), len = arrangedContent ? get(arrangedContent, 'length') : 0; this.arrangedContentArrayWillChange(this, 0, len, undefined); + this.arrangedContentWillChange(this); - if (arrangedContent) { - arrangedContent.removeArrayObserver(this, { - willChange: 'arrangedContentArrayWillChange', - didChange: 'arrangedContentArrayDidChange' - }); - } + this._teardownArrangedContent(arrangedContent); }, 'arrangedContent'), _arrangedContentDidChange: Ember.observer(function() { @@ -9193,63 +9626,83 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, Ember.assert("Can't set ArrayProxy's content to itself", arrangedContent !== this); + this._setupArrangedContent(); + + this.arrangedContentDidChange(this); + this.arrangedContentArrayDidChange(this, 0, undefined, len); + }, 'arrangedContent'), + + _setupArrangedContent: function() { + var arrangedContent = get(this, 'arrangedContent'); + if (arrangedContent) { arrangedContent.addArrayObserver(this, { willChange: 'arrangedContentArrayWillChange', didChange: 'arrangedContentArrayDidChange' }); } + }, - this.arrangedContentArrayDidChange(this, 0, undefined, len); - }, 'arrangedContent'), + _teardownArrangedContent: function() { + var arrangedContent = get(this, 'arrangedContent'); + + if (arrangedContent) { + arrangedContent.removeArrayObserver(this, { + willChange: 'arrangedContentArrayWillChange', + didChange: 'arrangedContentArrayDidChange' + }); + } + }, + + arrangedContentWillChange: Ember.K, + arrangedContentDidChange: Ember.K, - /** @private (nodoc) */ objectAt: function(idx) { return get(this, 'content') && this.objectAtContent(idx); }, - /** @private (nodoc) */ length: Ember.computed(function() { var arrangedContent = get(this, 'arrangedContent'); return arrangedContent ? get(arrangedContent, 'length') : 0; // No dependencies since Enumerable notifies length of change }).property().cacheable(), - /** @private (nodoc) */ replace: function(idx, amt, objects) { if (get(this, 'content')) this.replaceContent(idx, amt, objects); return this; }, - /** @private (nodoc) */ arrangedContentArrayWillChange: function(item, idx, removedCnt, addedCnt) { this.arrayContentWillChange(idx, removedCnt, addedCnt); }, - /** @private (nodoc) */ arrangedContentArrayDidChange: function(item, idx, removedCnt, addedCnt) { this.arrayContentDidChange(idx, removedCnt, addedCnt); }, - /** @private (nodoc) */ init: function() { this._super(); - this._contentWillChange(); - this._contentDidChange(); - this._arrangedContentWillChange(); - this._arrangedContentDidChange(); + this._setupContent(); + this._setupArrangedContent(); + }, + + willDestroy: function() { + this._teardownArrangedContent(); + this._teardownContent(); } - }); - - })(); (function() { +/** +@module ember +@submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt, @@ -9273,8 +9726,6 @@ function contentPropertyDidChange(content, contentKey) { } /** - @class - `Ember.ObjectProxy` forwards all properties not defined by the proxy itself to a proxied `content` object. @@ -9325,12 +9776,17 @@ function contentPropertyDidChange(content, contentKey) { firstName: 'Tom', lastName: 'Dale' }); // triggers property change for fullName on proxy proxy.get('fullName'); => 'Tom Dale' + + @class ObjectProxy + @namespace Ember + @extends Ember.Object */ Ember.ObjectProxy = Ember.Object.extend( /** @scope Ember.ObjectProxy.prototype */ { /** The object whose properties will be forwarded. + @property content @type Ember.Object @default null */ @@ -9338,26 +9794,26 @@ Ember.ObjectProxy = Ember.Object.extend( _contentDidChange: Ember.observer(function() { Ember.assert("Can't set ObjectProxy's content to itself", this.get('content') !== this); }, 'content'), - /** @private */ + willWatchProperty: function (key) { var contentKey = 'content.' + key; addBeforeObserver(this, contentKey, null, contentPropertyWillChange); addObserver(this, contentKey, null, contentPropertyDidChange); }, - /** @private */ + didUnwatchProperty: function (key) { var contentKey = 'content.' + key; removeBeforeObserver(this, contentKey, null, contentPropertyWillChange); removeObserver(this, contentKey, null, contentPropertyDidChange); }, - /** @private */ + unknownProperty: function (key) { var content = get(this, 'content'); if (content) { return get(content, key); } }, - /** @private */ + setUnknownProperty: function (key, value) { var content = get(this, 'content'); Ember.assert(fmt("Cannot delegate set('%@', %@) to the 'content' property of object proxy %@: its 'content' is undefined.", [key, value, this]), content); @@ -9370,11 +9826,12 @@ Ember.ObjectProxy = Ember.Object.extend( (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + + var set = Ember.set, get = Ember.get, guidFor = Ember.guidFor; var forEach = Ember.EnumerableUtils.forEach; @@ -9401,7 +9858,6 @@ var EachArray = Ember.Object.extend(Ember.Array, { var IS_OBSERVER = /^.+:(before|change)$/; -/** @private */ function addObserverForContentKey(content, keyName, proxy, idx, loc) { var objects = proxy._objects, guid; if (!objects) objects = proxy._objects = {}; @@ -9421,7 +9877,6 @@ function addObserverForContentKey(content, keyName, proxy, idx, loc) { } } -/** @private */ function removeObserverForContentKey(content, keyName, proxy, idx, loc) { var objects = proxy._objects; if (!objects) objects = proxy._objects = {}; @@ -9441,13 +9896,13 @@ function removeObserverForContentKey(content, keyName, proxy, idx, loc) { } /** - @private - @class - This is the object instance returned when you get the @each property on an array. It uses the unknownProperty handler to automatically create EachArray instances for property names. + @private + @class EachProxy + @namespace Ember @extends Ember.Object */ Ember.EachProxy = Ember.Object.extend({ @@ -9467,6 +9922,10 @@ Ember.EachProxy = Ember.Object.extend({ /** You can directly access mapped properties by simply requesting them. The unknownProperty handler will generate an EachArray of each item. + + @method unknownProperty + @param keyName {String} + @param value {anything} */ unknownProperty: function(keyName, value) { var ret; @@ -9575,11 +10034,12 @@ Ember.EachProxy = Ember.Object.extend({ (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + + var get = Ember.get, set = Ember.set; // Add Ember.Array to Array.prototype. Remove methods with native @@ -9681,13 +10141,13 @@ if (ignore.length>0) { Otherwise you can apply the mixin at anytime by calling `Ember.NativeArray.activate`. - @namespace - @extends Ember.MutableArray - @extends Ember.Array - @extends Ember.Enumerable - @extends Ember.MutableEnumerable - @extends Ember.Copyable - @extends Ember.Freezable + @class NativeArray + @namespace Ember + @extends Ember.Mixin + @uses Ember.MutableArray + @uses Ember.MutableEnumerable + @uses Ember.Copyable + @uses Ember.Freezable */ Ember.NativeArray = NativeArray; @@ -9695,7 +10155,9 @@ Ember.NativeArray = NativeArray; Creates an Ember.NativeArray from an Array like object. Does not modify the original object. - @returns {Ember.NativeArray} + @method A + @for Ember + @return {Ember.NativeArray} */ Ember.A = function(arr){ if (arr === undefined) { arr = []; } @@ -9706,7 +10168,10 @@ Ember.A = function(arr){ Activates the mixin on the Array.prototype if not already applied. Calling this method more than once is safe. - @returns {void} + @method activate + @for Ember.NativeArray + @static + @return {void} */ Ember.NativeArray.activate = function() { NativeArray.apply(Array.prototype); @@ -9723,11 +10188,11 @@ if (Ember.EXTEND_PROTOTYPES) Ember.NativeArray.activate(); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set; Ember._PromiseChain = Ember.Object.extend({ @@ -9737,9 +10202,6 @@ Ember._PromiseChain = Ember.Object.extend({ abortCallback: Ember.K, promiseSuccessCallback: Ember.K, - /** - @private - */ runNextPromise: function() { if (get(this, 'isDestroyed')) { return; } @@ -9785,9 +10247,20 @@ Ember._PromiseChain = Ember.Object.extend({ (function() { +/** +@module ember +@submodule ember-runtime +*/ + var loadHooks = {}; var loaded = {}; +/** +@method onLoad +@for Ember +@param name {String} name of hook +@param callback {Function} callback to be called +*/ Ember.onLoad = function(name, callback) { var object; @@ -9799,6 +10272,12 @@ Ember.onLoad = function(name, callback) { } }; +/** +@method runLoadHooks +@for Ember +@param name {String} name of hook +@param object {Object} object to pass to callbacks +*/ Ember.runLoadHooks = function(name, object) { var hooks; @@ -9816,17 +10295,44 @@ Ember.runLoadHooks = function(name, object) { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { +/** +@module ember +@submodule ember-runtime +*/ + +/** + Ember.ControllerMixin provides a standard interface for all classes + that compose Ember's controller layer: Ember.Controller, Ember.ArrayController, + and Ember.ObjectController. + + Within an Ember.Router-managed application single shared instaces of every + Controller object in your application's namespace will be added to the + application's Ember.Router instance. See `Ember.Application#initialize` + for additional information. + + ## Views + By default a controller instance will be the rendering context + for its associated Ember.View. This connection is made during calls to + `Ember.ControllerMixin#connectOutlet`. + + Within the view's template, the Ember.View instance can be accessed + through the controller with `{{view}}`. + + ## Target Forwarding + By default a controller will target your application's Ember.Router instance. + Calls to `{{action}}` within the template of a controller's view are forwarded + to the router. See `Ember.Handlebars.helpers.action` for additional information. + + @class ControllerMixin + @namespace Ember + @extends Ember.Mixin +*/ Ember.ControllerMixin = Ember.Mixin.create({ /** The object to which events from the view should be sent. @@ -9836,11 +10342,21 @@ Ember.ControllerMixin = Ember.Mixin.create({ By default, a controller's `target` is set to the router after it is instantiated by `Ember.Application#initialize`. + + @property target + @default null */ target: null, + store: null }); +/** + @class Controller + @namespace Ember + @extends Ember.Object + @uses Ember.ControllerMixin +*/ Ember.Controller = Ember.Object.extend(Ember.ControllerMixin); })(); @@ -9848,16 +10364,42 @@ Ember.Controller = Ember.Object.extend(Ember.ControllerMixin); (function() { +/** +@module ember +@submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach; /** - @class + Ember.SortableMixin provides a standard interface for array proxies + to specify a sort order and maintain this sorting when objects are added, + removed, or updated without changing the implicit order of their underlying + content array: - @extends Ember.Mixin - @extends Ember.MutableEnumerable + songs = [ + {trackNumber: 4, title: 'Ob-La-Di, Ob-La-Da'}, + {trackNumber: 2, title: 'Back in the U.S.S.R.'}, + {trackNumber: 3, title: 'Glass Onion'}, + ]; + + songsController = Ember.ArrayController.create({ + content: songs, + sortProperties: ['trackNumber'] + }); + + songsController.get('firstObject'); // {trackNumber: 2, title: 'Back in the U.S.S.R.'} + + songsController.addObject({trackNumber: 1, title: 'Dear Prudence'}); + songsController.get('firstObject'); // {trackNumber: 1, title: 'Dear Prudence'} + + + @class SortableMixin + @namespace Ember + @extends Ember.Mixin + @uses Ember.MutableEnumerable */ -Ember.SortableMixin = Ember.Mixin.create(Ember.MutableEnumerable, - /** @scope Ember.Observable.prototype */ { +Ember.SortableMixin = Ember.Mixin.create(Ember.MutableEnumerable, { sortProperties: null, sortAscending: true, @@ -10007,10 +10549,13 @@ Ember.SortableMixin = Ember.Mixin.create(Ember.MutableEnumerable, contentItemSortPropertyDidChange: function(item) { var arrangedContent = get(this, 'arrangedContent'), - index = arrangedContent.indexOf(item); + oldIndex = arrangedContent.indexOf(item), + newIndex = this._binarySearch(item, 0, get(arrangedContent, 'length')); - arrangedContent.removeObject(item); - this.insertItemSorted(item); + if (newIndex !== oldIndex) { + arrangedContent.removeObject(item); + this.insertItemSorted(item); + } }, _binarySearch: function(item, low, high) { @@ -10042,16 +10587,14 @@ Ember.SortableMixin = Ember.Mixin.create(Ember.MutableEnumerable, (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set; /** - @class - Ember.ArrayController provides a way for you to publish a collection of objects so that you can easily bind to the collection from a Handlebars #each helper, an Ember.CollectionView, or other controllers. @@ -10063,17 +10606,21 @@ var get = Ember.get, set = Ember.set; For example, imagine you wanted to display a list of items fetched via an XHR request. Create an Ember.ArrayController and set its `content` property: - MyApp.listController = Ember.ArrayController.create(); + ``` javascript + MyApp.listController = Ember.ArrayController.create(); - $.get('people.json', function(data) { - MyApp.listController.set('content', data); - }); + $.get('people.json', function(data) { + MyApp.listController.set('content', data); + }); + ``` Then, create a view that binds to your new controller: - {{#each MyApp.listController}} - {{firstName}} {{lastName}} - {{/each}} + ``` handlebars + {{#each MyApp.listController}} + {{firstName}} {{lastName}} + {{/each}} + ``` Although you are binding to the controller, the behavior of this controller is to pass through any methods or properties to the underlying array. This @@ -10085,7 +10632,11 @@ var get = Ember.get, set = Ember.set; selection support. If you are creating something that is conceptually a controller, use this class. + @class ArrayController + @namespace Ember @extends Ember.ArrayProxy + @uses Ember.SortableMixin + @uses Ember.ControllerMixin */ Ember.ArrayController = Ember.ArrayProxy.extend(Ember.ControllerMixin, @@ -10096,6 +10647,25 @@ Ember.ArrayController = Ember.ArrayProxy.extend(Ember.ControllerMixin, (function() { +/** +@module ember +@submodule ember-runtime +*/ + +/** + Ember.ObjectController is part of Ember's Controller layer. A single + shared instance of each Ember.ObjectController subclass in your application's + namespace will be created at application initialization and be stored on your + application's Ember.Router instance. + + Ember.ObjectController derives its functionality from its superclass + Ember.ObjectProxy and the Ember.ControllerMixin mixin. + + @class ObjectController + @namespace Ember + @extends Ember.ObjectProxy + @uses Ember.ControllerMixin +**/ Ember.ObjectController = Ember.ObjectProxy.extend(Ember.ControllerMixin); })(); @@ -10109,77 +10679,376 @@ Ember.ObjectController = Ember.ObjectProxy.extend(Ember.ControllerMixin); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +Ember Runtime + +@module ember +@submodule ember-runtime +@requires ember-metal +*/ })(); (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +function visit(vertex, fn, visited, path) { + var name = vertex.name, + vertices = vertex.incoming, + names = vertex.incomingNames, + len = names.length, + i; + if (!visited) { + visited = {}; + } + if (!path) { + path = []; + } + if (visited.hasOwnProperty(name)) { + return; + } + path.push(name); + visited[name] = true; + for (i = 0; i < len; i++) { + visit(vertices[names[i]], fn, visited, path); + } + fn(vertex, path); + path.pop(); +} + +function DAG() { + this.names = []; + this.vertices = {}; +} + +DAG.prototype.add = function(name) { + if (!name) { return; } + if (this.vertices.hasOwnProperty(name)) { + return this.vertices[name]; + } + var vertex = { + name: name, incoming: {}, incomingNames: [], hasOutgoing: false, value: null + }; + this.vertices[name] = vertex; + this.names.push(name); + return vertex; +}; + +DAG.prototype.map = function(name, value) { + this.add(name).value = value; +}; + +DAG.prototype.addEdge = function(fromName, toName) { + if (!fromName || !toName || fromName === toName) { + return; + } + var from = this.add(fromName), to = this.add(toName); + if (to.incoming.hasOwnProperty(fromName)) { + return; + } + function checkCycle(vertex, path) { + if (vertex.name === toName) { + throw new Error("cycle detected: " + toName + " <- " + path.join(" <- ")); + } + } + visit(from, checkCycle); + from.hasOutgoing = true; + to.incoming[fromName] = from; + to.incomingNames.push(fromName); +}; + +DAG.prototype.topsort = function(fn) { + var visited = {}, + vertices = this.vertices, + names = this.names, + len = names.length, + i, vertex; + for (i = 0; i < len; i++) { + vertex = vertices[names[i]]; + if (!vertex.hasOutgoing) { + visit(vertex, fn, visited); + } + } +}; + +DAG.prototype.addEdges = function(name, value, before, after) { + var i; + this.map(name, value); + if (before) { + if (typeof before === 'string') { + this.addEdge(name, before); + } else { + for (i = 0; i < before.length; i++) { + this.addEdge(name, before[i]); + } + } + } + if (after) { + if (typeof after === 'string') { + this.addEdge(after, name); + } else { + for (i = 0; i < after.length; i++) { + this.addEdge(after[i], name); + } + } + } +}; + +Ember.DAG = DAG; + +})(); + + + +(function() { +/** +@module ember +@submodule ember-application +*/ var get = Ember.get, set = Ember.set; /** - @class + An instance of `Ember.Application` is the starting point for every Ember.js + application. It helps to instantiate, initialize and coordinate the many + objects that make up your app. - An Ember.Application instance serves as the namespace in which you define your - application's classes. You can also override the configuration of your + Each Ember.js app has one and only one `Ember.Application` object. In fact, the very + first thing you should do in your application is create the instance: + + ```javascript + window.App = Ember.Application.create(); + ``` + + Typically, the application object is the only global variable. All other + classes in your app should be properties on the `Ember.Application` instance, + which highlights its first role: a global namespace. + + For example, if you define a view class, it might look like this: + + ```javascript + App.MyView = Ember.View.extend(); + ``` + + After all of your classes are defined, call `App.initialize()` to start the application. - By default, Ember.Application will begin listening for events on the document. - If your application is embedded inside a page, instead of controlling the - entire document, you can specify which DOM element to attach to by setting - the `rootElement` property: + Because `Ember.Application` inherits from `Ember.Namespace`, any classes + you create will have useful string representations when calling `toString()`; + see the `Ember.Namespace` documentation for more information. - MyApp = Ember.Application.create({ - rootElement: $('#my-app') - }); + While you can think of your `Ember.Application` as a container that holds the + other classes in your application, there are several other responsibilities + going on under-the-hood that you may want to understand. - The root of an Ember.Application must not be removed during the course of the - page's lifetime. If you have only a single conceptual application for the - entire page, and are not embedding any third-party Ember applications - in your page, use the default document root for your application. + ### Event Delegation - You only need to specify the root if your page contains multiple instances - of Ember.Application. + Ember.js uses a technique called _event delegation_. This allows the framework + to set up a global, shared event listener instead of requiring each view to do + it manually. For example, instead of each view registering its own `mousedown` + listener on its associated element, Ember.js sets up a `mousedown` listener on + the `body`. - @extends Ember.Object + If a `mousedown` event occurs, Ember.js will look at the target of the event and + start walking up the DOM node tree, finding corresponding views and invoking their + `mouseDown` method as it goes. + + `Ember.Application` has a number of default events that it listens for, as well + as a mapping from lowercase events to camel-cased view method names. For + example, the `keypress` event causes the `keyPress` method on the view to be + called, the `dblclick` event causes `doubleClick` to be called, and so on. + + If there is a browser event that Ember.js does not listen for by default, you + can specify custom events and their corresponding view method names by setting + the application's `customEvents` property: + + ```javascript + App = Ember.Application.create({ + customEvents: { + // add support for the loadedmetadata media + // player event + 'loadedmetadata': "loadedMetadata" + } + }); + ``` + + By default, the application sets up these event listeners on the document body. + However, in cases where you are embedding an Ember.js application inside an + existing page, you may want it to set up the listeners on an element inside + the body. + + For example, if only events inside a DOM element with the ID of `ember-app` should + be delegated, set your application's `rootElement` property: + + ```javascript + window.App = Ember.Application.create({ + rootElement: '#ember-app' + }); + ``` + + The `rootElement` can be either a DOM element or a jQuery-compatible selector + string. Note that *views appended to the DOM outside the root element will not + receive events.* If you specify a custom root element, make sure you only append + views inside it! + + To learn more about the advantages of event delegation and the Ember.js view layer, + and a list of the event listeners that are setup by default, visit the + [Ember.js View Layer guide](http://emberjs.com/guides/view_layer#toc_event-delegation). + + ### Dependency Injection + + One thing you may have noticed while using Ember.js is that you define *classes*, not + *instances*. When your application loads, all of the instances are created for you. + Creating these instances is the responsibility of `Ember.Application`. + + When the `Ember.Application` initializes, it will look for an `Ember.Router` class + defined on the applications's `Router` property, like this: + + ```javascript + App.Router = Ember.Router.extend({ + // ... + }); + ``` + + If found, the router is instantiated and saved on the application's `router` + property (note the lowercase 'r'). While you should *not* reference this router + instance directly from your application code, having access to `App.router` + from the console can be useful during debugging. + + After the router is created, the application loops through all of the + registered _injections_ and invokes them once for each property on the + `Ember.Application` object. + + An injection is a function that is responsible for instantiating objects from + classes defined on the application. By default, the only injection registered + instantiates controllers and makes them available on the router. + + For example, if you define a controller class: + + ```javascript + App.MyController = Ember.Controller.extend({ + // ... + }); + ``` + + Your router will receive an instance of `App.MyController` saved on its + `myController` property. + + Libraries on top of Ember.js can register additional injections. For example, + if your application is using Ember Data, it registers an injection that + instantiates `DS.Store`: + + ```javascript + Ember.Application.registerInjection({ + name: 'store', + before: 'controllers', + + injection: function(app, router, property) { + if (property === 'Store') { + set(router, 'store', app[property].create()); + } + } + }); + ``` + + ### Routing + + In addition to creating your application's router, `Ember.Application` is also + responsible for telling the router when to start routing. + + By default, the router will begin trying to translate the current URL into + application state once the browser emits the `DOMContentReady` event. If you + need to defer routing, you can call the application's `deferReadiness()` method. + Once routing can begin, call the `advanceReadiness()` method. + + If there is any setup required before routing begins, you can implement a `ready()` + method on your app that will be invoked immediately before routing begins: + + ```javascript + window.App = Ember.Application.create({ + ready: function() { + this.set('router.enableLogging', true); + } + }); + + To begin routing, you must have at a minimum a top-level controller and view. + You define these as `App.ApplicationController` and `App.ApplicationView`, + respectively. Your application will not work if you do not define these two + mandatory classes. For example: + + ```javascript + App.ApplicationView = Ember.View.extend({ + templateName: 'application' + }); + App.ApplicationController = Ember.Controller.extend(); + ``` + + @class Application + @namespace Ember + @extends Ember.Namespace */ Ember.Application = Ember.Namespace.extend( /** @scope Ember.Application.prototype */{ /** - The root DOM element of the Application. + The root DOM element of the Application. This can be specified as an + element or a + [jQuery-compatible selector string](http://api.jquery.com/category/selectors/). - Can be specified as DOMElement or a selector string. + This is the element that will be passed to the Application's, + `eventDispatcher`, which sets up the listeners for event delegation. Every + view in your application should be a child of the element you specify here. + @property rootElement @type DOMElement @default 'body' */ rootElement: 'body', /** + The `Ember.EventDispatcher` responsible for delegating events to this + application's views. + + The event dispatcher is created by the application at initialization time + and sets up event listeners on the DOM element described by the + application's `rootElement` property. + + See the documentation for `Ember.EventDispatcher` for more information. + + @property eventDispatcher @type Ember.EventDispatcher @default null */ eventDispatcher: null, /** + The DOM events for which the event dispatcher should listen. + + By default, the application's `Ember.EventDispatcher` listens + for a set of standard DOM events, such as `mousedown` and + `keyup`, and delegates them to your application's `Ember.View` + instances. + + If you would like additional events to be delegated to your + views, set your `Ember.Application`'s `customEvents` property + to a hash containing the DOM event name as the key and the + corresponding view method name as the value. For example: + + App = Ember.Application.create({ + customEvents: { + // add support for the loadedmetadata media + // player event + 'loadedmetadata': "loadedMetadata" + } + }); + + @property customEvents @type Object @default null */ customEvents: null, - /** @private */ init: function() { + if (!this.$) { this.$ = Ember.$; } + var eventDispatcher, rootElement = get(this, 'rootElement'); this._super(); @@ -10190,14 +11059,32 @@ Ember.Application = Ember.Namespace.extend( set(this, 'eventDispatcher', eventDispatcher); - // jQuery 1.7 doesn't call the ready callback if already ready - if (Ember.$.isReady) { + // Start off the number of deferrals at 1. This will be + // decremented by the Application's own `initialize` method. + this._readinessDeferrals = 1; + + this.waitForDOMContentLoaded(); + }, + + waitForDOMContentLoaded: function() { + this.deferReadiness(); + + var self = this; + this.$().ready(function() { + self.advanceReadiness(); + }); + }, + + deferReadiness: function() { + Ember.assert("You cannot defer readiness since the `ready()` hook has already been called.", this._readinessDeferrals > 0); + this._readinessDeferrals++; + }, + + advanceReadiness: function() { + this._readinessDeferrals--; + + if (this._readinessDeferrals === 0) { Ember.run.once(this, this.didBecomeReady); - } else { - var self = this; - Ember.$(document).ready(function() { - Ember.run.once(self, self.didBecomeReady); - }); } }, @@ -10220,11 +11107,13 @@ Ember.Application = Ember.Namespace.extend( router.get('commentsController') // router.get('postsController.router') // router + + @method initialize + @param router {Ember.Router} */ initialize: function(router) { - var properties = Ember.A(Ember.keys(this)), - injections = get(this.constructor, 'injections'), - namespace = this, controller, name; + var injections = get(this.constructor, 'injections'), + namespace = this; if (!router && Ember.Router.detect(namespace['Router'])) { router = namespace['Router'].create(); @@ -10243,27 +11132,42 @@ Ember.Application = Ember.Namespace.extend( set(router, 'namespace', this); } - Ember.runLoadHooks('application', this); + var graph = new Ember.DAG(), i, injection; + for (i=0; iMy Blog - {{outlet}} + ``` handlebars +

My Blog

+ {{outlet}} + ``` The view for this outlet is specified by assigning a `view` property to the application's controller. The following code will assign a new `App.PostsView` to that outlet: - applicationController.connectOutlet('posts'); + ``` javascript + applicationController.connectOutlet('posts'); + ``` In general, you will also want to assign a controller to the newly created view. By convention, a controller @@ -11370,27 +12037,37 @@ Ember.ControllerMixin.reopen({ You can supply a `content` for the controller by supplying a final argument after the view class: - applicationController.connectOutlet('posts', App.Post.find()); + ``` javascript + applicationController.connectOutlet('posts', App.Post.find()); + ``` You can specify a particular outlet to use. For example, if your main template looks like: -

My Blog

- {{outlet master}} - {{outlet detail}} + ``` handlebars +

My Blog

+ {{outlet master}} + {{outlet detail}} + ``` You can assign an `App.PostsView` to the master outlet: - applicationController.connectOutlet({ - name: 'posts', - outletName: 'master', - context: App.Post.find() - }); + ``` javascript + applicationController.connectOutlet({ + name: 'posts', + outletName: 'master', + context: App.Post.find() + }); + ``` You can write this as: - applicationController.connectOutlet('master', 'posts', App.Post.find()); + ``` javascript + applicationController.connectOutlet('master', 'posts', App.Post.find()); + ``` + + @method connectOutlet @param {String} outletName a name for the outlet to set @param {String} name a view/controller pair name @param {Object} context a context object to assign to the @@ -11443,7 +12120,7 @@ Ember.ControllerMixin.reopen({ outletName = outletName || 'view'; - Ember.assert("You must supply a name or a view class to connectOutlets, but not both", (!!name && !viewClass && !controller) || (!name && !!viewClass)); + Ember.assert("You must supply a name or a view class to connectOutlet, but not both", (!!name && !viewClass && !controller) || (!name && !!viewClass)); if (name) { var namespace = get(this, 'namespace'), @@ -11457,8 +12134,10 @@ Ember.ControllerMixin.reopen({ Ember.assert("The name you supplied " + name + " did not resolve to a controller " + name + 'Controller', (!!controller && !!context) || !context); } - if (controller && context) { controller.set('content', context); } - view = viewClass.create(); + if (controller && context) { set(controller, 'content', context); } + + view = this.createOutletView(outletName, viewClass); + if (controller) { set(view, 'controller', controller); } set(this, outletName, view); @@ -11474,6 +12153,7 @@ Ember.ControllerMixin.reopen({ overviewController.connectControllers('person', 'post'); + @method connectControllers @param {String...} controllerNames the controllers to make available */ connectControllers: function() { @@ -11485,34 +12165,51 @@ Ember.ControllerMixin.reopen({ controllerName = controllerNames[i] + 'Controller'; set(this, controllerName, get(controllers, controllerName)); } + }, + + /** + `disconnectOutlet` removes previously attached view from given outlet. + + @method disconnectOutlet + @param {String} outletName the outlet name. (optional) + */ + disconnectOutlet: function(outletName) { + outletName = outletName || 'view'; + + set(this, outletName, null); + }, + + /** + `createOutletView` is a hook you may want to override if you need to do + something special with the view created for the outlet. For example + you may want to implement views sharing across outlets. + + @method createOutletView + @param outletName {String} + @param viewClass {Ember.View} + */ + createOutletView: function(outletName, viewClass) { + return viewClass.create(); } }); +})(); + + + +(function() { })(); (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ -})(); - - - -(function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== -var get = Ember.get, set = Ember.set, addObserver = Ember.addObserver; +var get = Ember.get, set = Ember.set, addObserver = Ember.addObserver, removeObserver = Ember.removeObserver; var meta = Ember.meta, fmt = Ember.String.fmt; var a_slice = [].slice; var a_forEach = Ember.EnumerableUtils.forEach; @@ -11537,12 +12234,12 @@ var VIEW_PRESERVES_CONTEXT = Ember.VIEW_PRESERVES_CONTEXT; Ember.warn("The way that the {{view}} helper affects templates is about to change. Previously, templates inside child views would use the new view as the context. Soon, views will preserve their parent context when rendering their template. You can opt-in early to the new behavior by setting `ENV.VIEW_PRESERVES_CONTEXT = true`. For more information, see https://gist.github.com/2494968. You should update your templates as soon as possible; this default will change soon, and the option will be eliminated entirely before the 1.0 release.", VIEW_PRESERVES_CONTEXT); /** - @static - Global hash of shared templates. This will automatically be populated by the build tools so that you can store your Handlebars templates in separate files that get loaded into JavaScript at buildtime. + @property TEMPLATES + @for Ember @type Hash */ Ember.TEMPLATES = {}; @@ -11556,195 +12253,243 @@ var invokeForState = { }; /** - @class - `Ember.View` is the class in Ember responsible for encapsulating templates of HTML content, combining templates with data to render as sections of a page's DOM, and registering and responding to user-initiated events. - + ## HTML Tag The default HTML tag name used for a view's DOM representation is `div`. This can be customized by setting the `tagName` property. The following view class: - ParagraphView = Ember.View.extend({ - tagName: 'em' - }) + ``` javascript + ParagraphView = Ember.View.extend({ + tagName: 'em' + }); + ``` Would result in instances with the following HTML: - + ``` html + + ``` ## HTML `class` Attribute The HTML `class` attribute of a view's tag can be set by providing a `classNames` property that is set to an array of strings: - MyView = Ember.View.extend({ - classNames: ['my-class', 'my-other-class'] - }) + ``` javascript + MyView = Ember.View.extend({ + classNames: ['my-class', 'my-other-class'] + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` `class` attribute values can also be set by providing a `classNameBindings` property - set to an array of properties names for the view. The return value of these properties + set to an array of properties names for the view. The return value of these properties will be added as part of the value for the view's `class` attribute. These properties can be computed properties: - MyView = Ember.View.extend({ - classNameBindings: ['propertyA', 'propertyB'], - propertyA: 'from-a', - propertyB: function(){ - if(someLogic){ return 'from-b'; } - }.property() - }) + ``` javascript + MyView = Ember.View.extend({ + classNameBindings: ['propertyA', 'propertyB'], + propertyA: 'from-a', + propertyB: function(){ + if(someLogic){ return 'from-b'; } + }.property() + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` If the value of a class name binding returns a boolean the property name itself will be used as the class name if the property is true. The class name will not be added if the value is `false` or `undefined`. - MyView = Ember.View.extend({ - classNameBindings: ['hovered'], - hovered: true - }) + ``` javascript + MyView = Ember.View.extend({ + classNameBindings: ['hovered'], + hovered: true + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` - When using boolean class name bindings you can supply a string value other than the + When using boolean class name bindings you can supply a string value other than the property name for use as the `class` HTML attribute by appending the preferred value after a ":" character when defining the binding: - MyView = Ember.View.extend({ - classNameBindings: ['awesome:so-very-cool'], - awesome: true - }) + ``` javascript + MyView = Ember.View.extend({ + classNameBindings: ['awesome:so-very-cool'], + awesome: true + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` Boolean value class name bindings whose property names are in a camelCase-style format will be converted to a dasherized format: - MyView = Ember.View.extend({ - classNameBindings: ['isUrgent'], - isUrgent: true - }) + ``` javascript + MyView = Ember.View.extend({ + classNameBindings: ['isUrgent'], + isUrgent: true + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` Class name bindings can also refer to object values that are found by traversing a path relative to the view itself: - MyView = Ember.View.extend({ - classNameBindings: ['messages.empty'] - messages: Ember.Object.create({ - empty: true - }) - }) + ``` javascript + MyView = Ember.View.extend({ + classNameBindings: ['messages.empty'] + messages: Ember.Object.create({ + empty: true + }) + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` If you want to add a class name for a property which evaluates to true and and a different class name if it evaluates to false, you can pass a binding like this: - // Applies 'enabled' class when isEnabled is true and 'disabled' when isEnabled is false - Ember.View.create({ - classNameBindings: ['isEnabled:enabled:disabled'] - isEnabled: true - }); + ``` + // Applies 'enabled' class when isEnabled is true and 'disabled' when isEnabled is false + Ember.View.create({ + classNameBindings: ['isEnabled:enabled:disabled'] + isEnabled: true + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` When isEnabled is `false`, the resulting HTML reprensentation looks like this: -
+ ``` html +
+ ``` This syntax offers the convenience to add a class if a property is `false`: - // Applies no class when isEnabled is true and class 'disabled' when isEnabled is false - Ember.View.create({ - classNameBindings: ['isEnabled::disabled'] - isEnabled: true - }); + ``` javascript + // Applies no class when isEnabled is true and class 'disabled' when isEnabled is false + Ember.View.create({ + classNameBindings: ['isEnabled::disabled'] + isEnabled: true + }); + ``` Will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` When the `isEnabled` property on the view is set to `false`, it will result in view instances with an HTML representation of: -
+ ``` html +
+ ``` - - Updates to the the value of a class name binding will result in automatic update + Updates to the the value of a class name binding will result in automatic update of the HTML `class` attribute in the view's rendered HTML representation. If the value becomes `false` or `undefined` the class name will be removed. - Both `classNames` and `classNameBindings` are concatenated properties. + Both `classNames` and `classNameBindings` are concatenated properties. See `Ember.Object` documentation for more information about concatenated properties. ## HTML Attributes + The HTML attribute section of a view's tag can be set by providing an `attributeBindings` property set to an array of property names on the view. The return value of these properties will be used as the value of the view's HTML associated attribute: - AnchorView = Ember.View.extend({ - tagName: 'a', - attributeBindings: ['href'], - href: 'http://google.com' - }) + ``` javascript + AnchorView = Ember.View.extend({ + tagName: 'a', + attributeBindings: ['href'], + href: 'http://google.com' + }); + ``` Will result in view instances with an HTML representation of: - + ``` html + + ``` If the return value of an `attributeBindings` monitored property is a boolean the property will follow HTML's pattern of repeating the attribute's name as its value: - MyTextInput = Ember.View.extend({ - tagName: 'input', - attributeBindings: ['disabled'], - disabled: true - }) + ``` javascript + MyTextInput = Ember.View.extend({ + tagName: 'input', + attributeBindings: ['disabled'], + disabled: true + }); + ``` Will result in view instances with an HTML representation of: - + ``` html + + ``` `attributeBindings` can refer to computed properties: - MyTextInput = Ember.View.extend({ - tagName: 'input', - attributeBindings: ['disabled'], - disabled: function(){ - if (someLogic) { - return true; - } else { - return false; - } - }.property() - }) + ``` javascript + MyTextInput = Ember.View.extend({ + tagName: 'input', + attributeBindings: ['disabled'], + disabled: function(){ + if (someLogic) { + return true; + } else { + return false; + } + }.property() + }); + ``` - Updates to the the property of an attribute binding will result in automatic update + Updates to the the property of an attribute binding will result in automatic update of the HTML attribute in the view's rendered HTML representation. `attributeBindings` is a concatenated property. See `Ember.Object` documentation @@ -11756,45 +12501,57 @@ var invokeForState = { a string of HTML that will be inserted within the view's tag. Most typically in Ember this function will be a compiled Ember.Handlebars template. - AView = Ember.View.extend({ - template: Ember.Handlebars.compile('I am the template') - }) + ``` javascript + AView = Ember.View.extend({ + template: Ember.Handlebars.compile('I am the template') + }); + ``` Will result in view instances with an HTML representation of: -
I am the template
+ ``` html +
I am the template
+ ``` The default context of the compiled template will be the view instance itself: - AView = Ember.View.extend({ - template: Ember.Handlebars.compile('Hello {{excitedGreeting}}') - }) + ``` javascript + AView = Ember.View.extend({ + template: Ember.Handlebars.compile('Hello {{excitedGreeting}}') + }); - aView = AView.create({ - content: Ember.Object.create({ - firstName: 'Barry' - }) - excitedGreeting: function(){ - return this.get("content.firstName") + "!!!" - } - }) + aView = AView.create({ + content: Ember.Object.create({ + firstName: 'Barry' + }) + excitedGreeting: function(){ + return this.get("content.firstName") + "!!!" + } + }); + ``` Will result in an HTML representation of: -
Hello Barry!!!
+ ``` html +
Hello Barry!!!
+ ``` Within an Ember application is more common to define a Handlebars templates as part of a page: - + ``` handlebars + + ``` And associate it by name using a view's `templateName` property: - AView = Ember.View.extend({ - templateName: 'some-template' - }) + ``` javascript + AView = Ember.View.extend({ + templateName: 'some-template' + }); + ``` Using a value for `templateName` that does not have a Handlebars template with a matching `data-template-name` attribute will throw an error. @@ -11806,36 +12563,45 @@ var invokeForState = { property set to compiled template function. If a template is not later provided for the view instance the `defaultTemplate` value will be used: - AView = Ember.View.extend({ - defaultTemplate: Ember.Handlebars.compile('I was the default'), - template: null, - templateName: null - }) + ``` javascript + AView = Ember.View.extend({ + defaultTemplate: Ember.Handlebars.compile('I was the default'), + template: null, + templateName: null + }); + ``` Will result in instances with an HTML representation of: -
I was the default
+ ``` html +
I was the default
+ ``` If a `template` or `templateName` is provided it will take precedence over `defaultTemplate`: - AView = Ember.View.extend({ - defaultTemplate: Ember.Handlebars.compile('I was the default') - }) + ``` javascript + AView = Ember.View.extend({ + defaultTemplate: Ember.Handlebars.compile('I was the default') + }); - aView = AView.create({ - template: Ember.Handlebars.compile('I was the template, not default') - }) + aView = AView.create({ + template: Ember.Handlebars.compile('I was the template, not default') + }); + ``` Will result in the following HTML representation when rendered: -
I was the template, not default
+ ``` html +
I was the template, not default
+ ``` ## Layouts + Views can have a secondary template that wraps their main template. Like primary templates, layouts can be any function that accepts an optional context parameter and returns a string of HTML that will be inserted inside view's tag. Views whose HTML element is self closing (e.g. ``) cannot have a layout and this property will be ignored. - + Most typically in Ember a layout will be a compiled Ember.Handlebars template. A view's layout can be set directly with the `layout` property or reference an @@ -11844,105 +12610,121 @@ var invokeForState = { A template used as a layout must contain a single use of the Handlebars `{{yield}}` helper. The HTML contents of a view's rendered `template` will be inserted at this location: - AViewWithLayout = Ember.View.extend({ - layout: Ember.Handlebars.compile("
{{yield}}
") - template: Ember.Handlebars.compile("I got wrapped"), - }) + ``` javascript + AViewWithLayout = Ember.View.extend({ + layout: Ember.Handlebars.compile("
{{yield}}
") + template: Ember.Handlebars.compile("I got wrapped"), + }); + ``` Will result in view instances with an HTML representation of: -
-
- I got wrapped -
-
+ ``` html +
+
+ I got wrapped +
+
+ ``` See `Handlebars.helpers.yield` for more information. ## Responding to Browser Events - Views can respond to user-initiated events in one of three ways: method implementation, + + Views can respond to user-initiated events in one of three ways: method implementation, through an event manager, and through `{{action}}` helper use in their template or layout. ### Method Implementation + Views can respond to user-initiated events by implementing a method that matches the event name. A `jQuery.Event` object will be passed as the argument to this method. - AView = Ember.View.extend({ - click: function(event){ - // will be called when when an instance's - // rendered element is clicked - } - }) + ``` javascript + AView = Ember.View.extend({ + click: function(event){ + // will be called when when an instance's + // rendered element is clicked + } + }); + ``` ### Event Managers + Views can define an object as their `eventManager` property. This object can then implement methods that match the desired event names. Matching events that occur - on the view's rendered HTML or the rendered HTML of any of its DOM descendants - will trigger this method. A `jQuery.Event` object will be passed as the first + on the view's rendered HTML or the rendered HTML of any of its DOM descendants + will trigger this method. A `jQuery.Event` object will be passed as the first argument to the method and an `Ember.View` object as the second. The `Ember.View` will be the view whose rendered HTML was interacted with. This may be the view with the `eventManager` property or one of its descendent views. - AView = Ember.View.extend({ - eventManager: Ember.Object.create({ - doubleClick: function(event, view){ - // will be called when when an instance's - // rendered element or any rendering - // of this views's descendent - // elements is clicked - } - }) - }) + ``` javascript + AView = Ember.View.extend({ + eventManager: Ember.Object.create({ + doubleClick: function(event, view){ + // will be called when when an instance's + // rendered element or any rendering + // of this views's descendent + // elements is clicked + } + }) + }); + ``` An event defined for an event manager takes precedence over events of the same name handled through methods on the view. - - AView = Ember.View.extend({ - mouseEnter: function(event){ - // will never trigger. - }, - eventManager: Ember.Object.create({ - mouseEnter: function(event, view){ - // takes presedence over AView#mouseEnter - } - }) - }) + ``` javascript + AView = Ember.View.extend({ + mouseEnter: function(event){ + // will never trigger. + }, + eventManager: Ember.Object.create({ + mouseEnter: function(event, view){ + // takes presedence over AView#mouseEnter + } + }) + }); + ``` Similarly a view's event manager will take precedence for events of any views rendered as a descendent. A method name that matches an event name will not be called - if the view instance was rendered inside the HTML representation of a view that has + if the view instance was rendered inside the HTML representation of a view that has an `eventManager` property defined that handles events of the name. Events not handled by the event manager will still trigger method calls on the descendent. - OuterView = Ember.View.extend({ - template: Ember.Handlebars.compile("outer {{#view InnerView}}inner{{/view}} outer"), - eventManager: Ember.Object.create({ - mouseEnter: function(event, view){ - // view might be instance of either - // OutsideView or InnerView depending on - // where on the page the user interaction occured - } - }) - }) + ``` javascript + OuterView = Ember.View.extend({ + template: Ember.Handlebars.compile("outer {{#view InnerView}}inner{{/view}} outer"), + eventManager: Ember.Object.create({ + mouseEnter: function(event, view){ + // view might be instance of either + // OutsideView or InnerView depending on + // where on the page the user interaction occured + } + }) + }); - InnerView = Ember.View.extend({ - click: function(event){ - // will be called if rendered inside - // an OuterView because OuterView's - // eventManager doesn't handle click events - }, - mouseEnter: function(event){ - // will never be called if rendered inside - // an OuterView. - } - }) + InnerView = Ember.View.extend({ + click: function(event){ + // will be called if rendered inside + // an OuterView because OuterView's + // eventManager doesn't handle click events + }, + mouseEnter: function(event){ + // will never be called if rendered inside + // an OuterView. + } + }); + ``` ### Handlebars `{{action}}` Helper + See `Handlebars.helpers.action`. ### Event Names + Possible events names for any of the responding approaches described above are: Touch events: 'touchStart', 'touchMove', 'touchEnd', 'touchCancel' @@ -11955,24 +12737,27 @@ var invokeForState = { Form events: 'submit', 'change', 'focusIn', 'focusOut', 'input' HTML5 drag and drop events: 'dragStart', 'drag', 'dragEnter', 'dragLeave', 'drop', 'dragEnd' - + ## Handlebars `{{view}}` Helper + Other `Ember.View` instances can be included as part of a view's template by using the `{{view}}` Handlebars helper. See `Handlebars.helpers.view` for additional information. + @class View + @namespace Ember @extends Ember.Object - @extends Ember.Evented + @uses Ember.Evented */ Ember.View = Ember.Object.extend(Ember.Evented, /** @scope Ember.View.prototype */ { - /** @private */ concatenatedProperties: ['classNames', 'classNameBindings', 'attributeBindings'], /** + @property isView @type Boolean @default true - @constant + @final */ isView: true, @@ -11987,6 +12772,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, `templates` object. By default, this will be a global object shared in `Ember.TEMPLATES`. + @property templateName @type String @default null */ @@ -11999,6 +12785,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, `templates` object. By default, this will be a global object shared in `Ember.TEMPLATES`. + @property layoutName @type String @default null */ @@ -12007,6 +12794,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** The hash in which to look for `templateName`. + @property templates @type Ember.Object @default Ember.TEMPLATES */ @@ -12020,7 +12808,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, In general, you should set the `templateName` property instead of setting the template yourself. - @field + @property template @type Function */ template: Ember.computed(function(key, value) { @@ -12036,6 +12824,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, The controller managing this view. If this property is set, it will be made available for use by the template. + @property controller @type Object */ controller: Ember.computed(function(key, value) { @@ -12060,7 +12849,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, the rendering of the contents of the wrapper to the `template` property on a subclass. - @field + @property layout @type Function */ layout: Ember.computed(function(key, value) { @@ -12094,6 +12883,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, By default, this will be the view itself. + @property context @type Object */ context: Ember.computed(function(key, value) { @@ -12103,7 +12893,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, } else { return get(this, '_context'); } - }).cacheable(), + }).volatile(), /** @private @@ -12121,6 +12911,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, The code in Handlebars that overrides the `_context` property first checks to see whether the view has a specified controller. This is something of a hack and should be revisited. + + @property _context */ _context: Ember.computed(function(key, value) { var parentView, controller, context; @@ -12144,10 +12936,12 @@ Ember.View = Ember.Object.extend(Ember.Evented, }).cacheable(), /** + @private + If a value that affects template rendering changes, the view should be re-rendered to reflect the new value. - @private + @method _displayPropertyDidChange */ _displayPropertyDidChange: Ember.observer(function() { this.rerender(); @@ -12157,6 +12951,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, If the view is currently inserted into the DOM of a parent view, this property will point to the parent of the view. + @property parentView @type Ember.View @default null */ @@ -12181,16 +12976,19 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** If false, the view will appear hidden in DOM. + @property isVisible @type Boolean @default null */ isVisible: true, /** + @private + Array of child views. You should never edit this array directly. Instead, use appendChild and removeFromParent. - @private + @property childViews @type Array @default [] */ @@ -12198,10 +12996,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, _childViews: [], - /** - When it's a virtual view, we need to notify the parent that their - childViews will change. - */ + // When it's a virtual view, we need to notify the parent that their + // childViews will change. _childViewsWillChange: Ember.beforeObserver(function() { if (this.isVirtual) { var parentView = get(this, 'parentView'); @@ -12209,10 +13005,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, } }, 'childViews'), - /** - When it's a virtual view, we need to notify the parent that their - childViews did change. - */ + // When it's a virtual view, we need to notify the parent that their + // childViews did change. _childViewsDidChange: Ember.observer(function() { if (this.isVirtual) { var parentView = get(this, 'parentView'); @@ -12224,8 +13018,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, Return the nearest ancestor that is an instance of the provided class. + @property nearestInstanceOf @param {Class} klass Subclass of Ember.View (or Ember.View itself) - @returns Ember.View + @return Ember.View */ nearestInstanceOf: function(klass) { var view = get(this, 'parentView'); @@ -12239,8 +13034,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Return the nearest ancestor that has a given property. + @property nearestWithProperty @param {String} property A property name - @returns Ember.View + @return Ember.View */ nearestWithProperty: function(property) { var view = get(this, 'parentView'); @@ -12255,8 +13051,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, Return the nearest ancestor whose parent is an instance of `klass`. + @property nearestChildOf @param {Class} klass Subclass of Ember.View (or Ember.View itself) - @returns Ember.View + @return Ember.View */ nearestChildOf: function(klass) { var view = get(this, 'parentView'); @@ -12270,7 +13067,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Return the nearest ancestor that is an Ember.CollectionView - @returns Ember.CollectionView + @property collectionView + @return Ember.CollectionView */ collectionView: Ember.computed(function() { return this.nearestInstanceOf(Ember.CollectionView); @@ -12280,7 +13078,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Return the nearest ancestor that is a direct child of an Ember.CollectionView - @returns Ember.View + @property itemView + @return Ember.View */ itemView: Ember.computed(function() { return this.nearestChildOf(Ember.CollectionView); @@ -12290,7 +13089,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Return the nearest ancestor that has the property `content`. - @returns Ember.View + @property contentView + @return Ember.View */ contentView: Ember.computed(function() { return this.nearestWithProperty('content'); @@ -12301,6 +13101,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, When the parent view changes, recursively invalidate collectionView, itemView, and contentView + + @method _parentViewDidChange */ _parentViewDidChange: Ember.observer(function() { if (this.isDestroying) { return; } @@ -12343,6 +13145,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, property and invoke it with the value of `context`. The value of `context` will be the view's controller unless you override it. + @method render @param {Ember.RenderBuffer} buffer The render buffer */ render: function(buffer) { @@ -12352,7 +13155,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, var template = get(this, 'layout') || get(this, 'template'); if (template) { - var context = get(this, '_context'); + var context = get(this, 'context'); var keywords = this.cloneKeywords(); var data = { @@ -12426,6 +13229,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, In general, if the display of your view changes, you should modify the DOM element directly instead of manually calling `rerender`, which can be slow. + + @method rerender */ rerender: function() { return this.invokeForState('rerender'); @@ -12453,6 +13258,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, of the specified property into the `classNames` array, then creates an observer to update the view's element if the bound property ever changes in the future. + + @method _applyClassNameBindings */ _applyClassNameBindings: function() { var classBindings = get(this, 'classNameBindings'), @@ -12470,6 +13277,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, // closes over this variable, so it knows which string to remove when // the property changes. var oldClass; + // Extract just the property name from bindings like 'foo:bar' + var parsedPath = Ember.View._parsePropertyPath(binding); // Set up an observer on the context. If the property changes, toggle the // class name. @@ -12477,6 +13286,10 @@ Ember.View = Ember.Object.extend(Ember.Evented, // Get the current value of the property newClass = this._classStringForProperty(binding); elem = this.$(); + if (!elem) { + removeObserver(this, parsedPath.path, observer); + return; + } // If we had previously added a class to the element, remove it. if (oldClass) { @@ -12510,16 +13323,17 @@ Ember.View = Ember.Object.extend(Ember.Evented, oldClass = dasherizedClass; } - // Extract just the property name from bindings like 'foo:bar' - var parsedPath = Ember.View._parsePropertyPath(binding); addObserver(this, parsedPath.path, observer); }, this); }, /** + @private + Iterates through the view's attribute bindings, sets up observers for each, then applies the current value of the attributes to the passed render buffer. + @method _applyAttributeBindings @param {Ember.RenderBuffer} buffer */ _applyAttributeBindings: function(buffer) { @@ -12561,6 +13375,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, For example, if the view has property `isUrgent` that evaluates to true, passing `isUrgent` to this method will return `"is-urgent"`. + + @method _classStringForProperty + @param property */ _classStringForProperty: function(property) { var parsedPath = Ember.View._parsePropertyPath(property); @@ -12581,7 +13398,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Returns the current DOM element for the view. - @field + @property element @type DOMElement */ element: Ember.computed(function(key, value) { @@ -12600,14 +13417,14 @@ Ember.View = Ember.Object.extend(Ember.Evented, For example, calling `view.$('li')` will return a jQuery object containing all of the `li` elements inside the DOM element of this view. + @property $ @param {String} [selector] a jQuery-compatible selector string - @returns {Ember.CoreQuery} the CoreQuery object for the DOM node + @return {jQuery} the CoreQuery object for the DOM node */ $: function(sel) { return this.invokeForState('$', sel); }, - /** @private */ mutateChildViews: function(callback) { var childViews = this._childViews, idx = childViews.length, @@ -12621,7 +13438,6 @@ Ember.View = Ember.Object.extend(Ember.Evented, return this; }, - /** @private */ forEachChildView: function(callback) { var childViews = this._childViews; @@ -12654,8 +13470,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, are providing is associated with an Ember.Application and does not have an ancestor element that is associated with an Ember view. + @method appendTo @param {String|DOMElement|jQuery} A selector, element, HTML string, or jQuery object - @returns {Ember.View} receiver + @return {Ember.View} receiver */ appendTo: function(target) { // Schedule the DOM element to be created and appended to the given @@ -12677,8 +13494,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, element will not be appended to the given element until all bindings have finished synchronizing + @method replaceIn @param {String|DOMElement|jQuery} A selector, element, HTML string, or jQuery object - @returns {Ember.View} received + @return {Ember.View} received */ replaceIn: function(target) { Ember.assert("You cannot replace an existing Ember.View. Consider using Ember.ContainerView instead.", !Ember.$(target).is('.ember-view') && !Ember.$(target).parents().is('.ember-view')); @@ -12709,11 +13527,19 @@ Ember.View = Ember.Object.extend(Ember.Evented, this.$().appendTo('body'); }); + @method _insertElementLater @param {Function} fn the function that inserts the element into the DOM */ _insertElementLater: function(fn) { - this._lastInsert = Ember.guidFor(fn); - Ember.run.schedule('render', this, this.invokeForState, 'insertElement', fn); + this._scheduledInsert = Ember.run.scheduleOnce('render', this, '_insertElement', fn); + }, + + /** + @private + */ + _insertElement: function (fn) { + this._scheduledInsert = null; + this.invokeForState('insertElement', fn); }, /** @@ -12725,7 +13551,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, element will not be appended to the document body until all bindings have finished synchronizing. - @returns {Ember.View} receiver + @method append + @return {Ember.View} receiver */ append: function() { return this.appendTo(document.body); @@ -12734,7 +13561,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Removes the view's element from the element to which it is attached. - @returns {Ember.View} receiver + @method remove + @return {Ember.View} receiver */ remove: function() { // What we should really do here is wait until the end of the run loop @@ -12753,18 +13581,14 @@ Ember.View = Ember.Object.extend(Ember.Evented, set the elementId explicitly, then the view's GUID will be used instead. This ID must be set at the time the view is created. + @property elementId @type String - @readOnly */ elementId: Ember.computed(function(key, value) { return value !== undefined ? value : Ember.guidFor(this); }).cacheable(), - /** - @private - - TODO: Perhaps this should be removed from the production build somehow. - */ + // TODO: Perhaps this should be removed from the production build somehow. _elementIdDidChange: Ember.beforeObserver(function() { throw "Changing a view's elementId after creation is not allowed."; }, 'elementId'), @@ -12776,8 +13600,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, own form of lookup. For example, if you want to discover your element using a CSS class name instead of an ID. + @method findElementInParentElement @param {DOMElement} parentElement The parent's DOM element - @returns {DOMElement} The discovered element + @return {DOMElement} The discovered element */ findElementInParentElement: function(parentElem) { var id = "#" + get(this, 'elementId'); @@ -12789,7 +13614,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, method to provide further customization to the buffer if needed. Normally you will not need to call or override this method. - @returns {Ember.RenderBuffer} + @method renderBuffer + @param [tagName] {String} + @return {Ember.RenderBuffer} */ renderBuffer: function(tagName) { tagName = tagName || get(this, 'tagName'); @@ -12810,7 +13637,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, After the element has been created, `didInsertElement` will be called on this view and all of its child views. - @returns {Ember.View} receiver + @method createElement + @return {Ember.View} receiver */ createElement: function() { if (get(this, 'element')) { return this; } @@ -12823,6 +13651,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Called when a view is going to insert an element into the DOM. + + @event willInsertElement */ willInsertElement: Ember.K, @@ -12830,6 +13660,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Called when the element of the view has been inserted into the DOM. Override this function to do any set up that requires an element in the document body. + + @event didInsertElement */ didInsertElement: Ember.K, @@ -12837,13 +13669,18 @@ Ember.View = Ember.Object.extend(Ember.Evented, Called when the view is about to rerender, but before anything has been torn down. This is a good opportunity to tear down any manual observers you have installed based on the DOM state + + @event willRerender */ willRerender: Ember.K, /** + @private + Run this callback on the current view and recursively on child views. - @private + @method invokeRecursively + @param fn {Function} */ invokeRecursively: function(fn) { fn.call(this, this); @@ -12855,6 +13692,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Invalidates the cache for a property on all child views. + + @method invalidateRecursively */ invalidateRecursively: function(key) { this.forEachChildView(function(view) { @@ -12870,6 +13709,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, NOTE: In some cases this was called when the element existed. This no longer works so we let people know. We can remove this warning code later. + + @method _notifyWillInsertElement */ _notifyWillInsertElement: function() { this.invokeRecursively(function(view) { @@ -12882,6 +13723,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Invokes the receiver's didInsertElement() method if it exists and then invokes the same on all child views. + + @method _notifyDidInsertElement */ _notifyDidInsertElement: function() { this.invokeRecursively(function(view) { @@ -12894,6 +13737,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Invokes the receiver's willRerender() method if it exists and then invokes the same on all child views. + + @method _notifyWillRerender */ _notifyWillRerender: function() { this.invokeRecursively(function(view) { @@ -12916,7 +13761,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Normally you will not call or override this method yourself, but you may want to implement the above callbacks when it is run. - @returns {Ember.View} receiver + @method destroyElement + @return {Ember.View} receiver */ destroyElement: function() { return this.invokeForState('destroyElement'); @@ -12926,6 +13772,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Called when the element of the view is going to be destroyed. Override this function to do any teardown that requires an element, like removing event listeners. + + @event willDestroyElement */ willDestroyElement: function() {}, @@ -12933,6 +13781,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, @private Invokes the `willDestroyElement` callback on the view and child views. + + @method _notifyWillDestroyElement */ _notifyWillDestroyElement: function() { this.invokeRecursively(function(view) { @@ -12940,7 +13790,6 @@ Ember.View = Ember.Object.extend(Ember.Evented, }); }, - /** @private (nodoc) */ _elementWillChange: Ember.beforeObserver(function() { this.forEachChildView(function(view) { Ember.propertyWillChange(view, 'element'); @@ -12954,7 +13803,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, child views so that we do not retain references to DOM elements that are no longer needed. - @observes element + @method _elementDidChange */ _elementDidChange: Ember.observer(function() { this.forEachChildView(function(view) { @@ -12965,7 +13814,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Called when the parentView property has changed. - @function + @event parentViewDidChange */ parentViewDidChange: Ember.K, @@ -12982,6 +13831,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, `template` property, or if you need more control, override the `render` method. + @method renderToBuffer @param {Ember.RenderBuffer} buffer the render buffer. If no buffer is passed, a default buffer, using the current view's `tagName`, will be used. @@ -13026,15 +13876,16 @@ Ember.View = Ember.Object.extend(Ember.Evented, return buffer; }, + renderToBufferIfNeeded: function () { + return this.invokeForState('renderToBufferIfNeeded', this); + }, + beforeRender: function(buffer) { this.applyAttributesToBuffer(buffer); }, afterRender: Ember.K, - /** - @private - */ applyAttributesToBuffer: function(buffer) { // Creates observers for all registered class name and attribute bindings, // then adds them to the element. @@ -13070,6 +13921,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, By default, the render buffer will use a `
` tag for views. + @property tagName @type String @default null */ @@ -13087,6 +13939,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, The full list of valid WAI-ARIA roles is available at: http://www.w3.org/TR/wai-aria/roles#roles_categorization + @property ariaRole @type String @default null */ @@ -13097,6 +13950,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, property automatically inherits any class names defined by the view's superclasses as well. + @property classNames @type Array @default ['ember-view'] */ @@ -13133,6 +13987,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, This list of properties is inherited from the view's superclasses as well. + @property classNameBindings @type Array @default [] */ @@ -13157,6 +14012,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, attributeBindings: ['enabled'], enabled: true }); + + @property attributeBindings */ attributeBindings: [], @@ -13173,6 +14030,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, - configure childViews - register the view with the global views hash, which is used for event dispatch + + @method init */ init: function() { this._super(); @@ -13206,8 +14065,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Removes the child view from the parent view. + @method removeChild @param {Ember.View} view - @returns {Ember.View} receiver + @return {Ember.View} receiver */ removeChild: function(view) { // If we're destroying, the entire subtree will be @@ -13231,7 +14091,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Removes all children from the parentView. - @returns {Ember.View} receiver + @method removeAllChildren + @return {Ember.View} receiver */ removeAllChildren: function() { return this.mutateChildViews(function(view) { @@ -13249,7 +14110,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, Removes the view from its parentView, if one is found. Otherwise does nothing. - @returns {Ember.View} receiver + @method removeFromParent + @return {Ember.View} receiver */ removeFromParent: function() { var parent = get(this, '_parentView'); @@ -13266,6 +14128,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, child views). This will remove the view from any parent node, then make sure that the DOM element managed by the view can be released by the memory manager. + + @method willDestroy */ willDestroy: function() { // calling this._super() will nuke computed properties and observers, @@ -13310,10 +14174,10 @@ Ember.View = Ember.Object.extend(Ember.Evented, automatically configure the correct settings on the new view instance to act as a child of the parent. + @method createChildView @param {Class} viewClass @param {Hash} [attrs] Attributes to add - @returns {Ember.View} new instance - @test in createChildViews + @return {Ember.View} new instance */ createChildView: function(view, attrs) { if (Ember.View.detect(view)) { @@ -13348,6 +14212,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, When the view's `isVisible` property changes, toggle the visibility element of the actual DOM element. + + @method _isVisibleDidChange */ _isVisibleDidChange: Ember.observer(function() { var $el = this.$(); @@ -13422,6 +14288,9 @@ Ember.View = Ember.Object.extend(Ember.Evented, Override the default event firing from Ember.Evented to also call methods with the given name. + + @method trigger + @param name {String} */ trigger: function(name) { this._super.apply(this, arguments); @@ -13447,6 +14316,10 @@ Ember.View = Ember.Object.extend(Ember.Evented, @private Handle events from `Ember.EventDispatcher` + + @method handleEvent + @param eventName {String} + @param evt {Event} */ handleEvent: function(eventName, evt) { return this.invokeForState('handleEvent', eventName, evt); @@ -13454,7 +14327,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, }); -/** +/* Describe how the specified actions should behave in the various states that a view can exist in. Possible states: @@ -13479,20 +14352,17 @@ Ember.View = Ember.Object.extend(Ember.Evented, // once the view has been inserted into the DOM, legal manipulations // are done on the DOM element. -/** @private */ var DOMManager = { - prepend: function(view, childView) { - childView._insertElementLater(function() { - var element = view.$(); - element.prepend(childView.$()); - }); + prepend: function(view, html) { + view.$().prepend(html); }, - after: function(view, nextView) { - nextView._insertElementLater(function() { - var element = view.$(); - element.after(nextView.$()); - }); + after: function(view, html) { + view.$().after(html); + }, + + html: function(view, html) { + view.$().html(html); }, replace: function(view) { @@ -13506,12 +14376,7 @@ var DOMManager = { }, remove: function(view) { - var elem = get(view, 'element'); - - set(view, 'element', null); - view._lastInsert = null; - - Ember.$(elem).remove(); + view.$().remove(); }, empty: function(view) { @@ -13541,9 +14406,11 @@ Ember.View.reopenClass({ classNames: ":enabled:disabled" } + @method _parsePropertyPath + @static */ _parsePropertyPath: function(path) { - var split = path.split(/:/), + var split = path.split(':'), propertyPath = split[0], classNames = "", className, @@ -13572,35 +14439,44 @@ Ember.View.reopenClass({ Get the class name for a given value, based on the path, optional className and optional falsyClassName. - - if the value is truthy and a className is defined, the className is returned + - if a className or falsyClassName has been specified: + - if the value is truthy and className has been specified, className is returned + - if the value is falsy and falsyClassName has been specified, falsyClassName is returned + - otherwise null is returned - if the value is true, the dasherized last part of the supplied path is returned - - if the value is false and a falsyClassName is supplied, the falsyClassName is returned - - if the value is truthy, the value is returned + - if the value is not false, undefined or null, the value is returned - if none of the above rules apply, null is returned + @method _classStringForValue + @param path + @param val + @param className + @param falsyClassName + @static */ _classStringForValue: function(path, val, className, falsyClassName) { - // If the value is truthy and we're using the colon syntax, - // we should return the className directly - if (!!val && className) { - return className; + // When using the colon syntax, evaluate the truthiness or falsiness + // of the value to determine which className to return + if (className || falsyClassName) { + if (className && !!val) { + return className; + + } else if (falsyClassName && !val) { + return falsyClassName; + + } else { + return null; + } // If value is a Boolean and true, return the dasherized property // name. } else if (val === true) { - // catch syntax like isEnabled::not-enabled - if (val === true && !className && falsyClassName) { return null; } - // Normalize property path to be suitable for use // as a class name. For exaple, content.foo.barBaz // becomes bar-baz. var parts = path.split('.'); return Ember.String.dasherize(parts[parts.length-1]); - // If the value is false and a falsyClassName is specified, return it - } else if (val === false && falsyClassName) { - return falsyClassName; - // If the value is not false, undefined, or null, return the current // value of the property. } else if (val !== false && val !== undefined && val !== null) { @@ -13614,7 +14490,13 @@ Ember.View.reopenClass({ } }); -// Create a global view hash. +/** + Global views hash + + @property views + @static + @type Hash +*/ Ember.View.views = {}; // If someone overrides the child views computed property when @@ -13643,12 +14525,11 @@ Ember.View.applyAttributeBindings = function(elem, name, value) { (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ + var get = Ember.get, set = Ember.set; Ember.View.states = { @@ -13673,8 +14554,15 @@ Ember.View.states = { destroyElement: function(view) { set(view, 'element', null); - view._lastInsert = null; + if (view._scheduledInsert) { + Ember.run.cancel(view._scheduledInsert); + view._scheduledInsert = null; + } return view; + }, + + renderToBufferIfNeeded: function () { + return false; } } }; @@ -13688,21 +14576,17 @@ Ember.View.reopen({ (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ + Ember.View.states.preRender = { parentState: Ember.View.states._default, // a view leaves the preRender state once its element has been // created (createElement). insertElement: function(view, fn) { - if (view._lastInsert !== Ember.guidFor(fn)){ - return; - } view.createElement(); view._notifyWillInsertElement(); // after createElement, the view will be in the hasElement state. @@ -13711,6 +14595,10 @@ Ember.View.states.preRender = { view._notifyDidInsertElement(); }, + renderToBufferIfNeeded: function(view) { + return view.renderToBuffer(); + }, + empty: Ember.K, setElement: function(view, value) { @@ -13726,12 +14614,11 @@ Ember.View.states.preRender = { (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ + var get = Ember.get, set = Ember.set, meta = Ember.meta; Ember.View.states.inBuffer = { @@ -13749,7 +14636,7 @@ Ember.View.states.inBuffer = { // when a view is rendered in a buffer, rerendering it simply // replaces the existing buffer with a new one rerender: function(view) { - // Ember.deprecate("Something you did caused a view to re-render after it rendered but before it was inserted into the DOM. Because this is avoidable and the cause of significant performance issues in applications, this behavior is deprecated. If you want to use the debugger to find out what caused this, you can set ENV.RAISE_ON_DEPRECATION to true."); + Ember.deprecate("Something you did caused a view to re-render after it rendered but before it was inserted into the DOM. Because this is avoidable and the cause of significant performance issues in applications, this behavior is deprecated. If you want to use the debugger to find out what caused this, you can set ENV.RAISE_ON_DEPRECATION to true."); view._notifyWillRerender(); @@ -13788,6 +14675,10 @@ Ember.View.states.inBuffer = { Ember.assert("Emptying a view in the inBuffer state is not allowed and should not happen under normal circumstances. Most likely there is a bug in your application. This may be due to excessive property change notifications."); }, + renderToBufferIfNeeded: function (view) { + return view.buffer; + }, + // It should be impossible for a rendered view to be scheduled for // insertion. insertElement: function() { @@ -13812,12 +14703,11 @@ Ember.View.states.inBuffer = { (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ + var get = Ember.get, set = Ember.set, meta = Ember.meta; Ember.View.states.hasElement = { @@ -13863,6 +14753,11 @@ Ember.View.states.hasElement = { destroyElement: function(view) { view._notifyWillDestroyElement(); view.domManager.remove(view); + set(view, 'element', null); + if (view._scheduledInsert) { + Ember.run.cancel(view._scheduledInsert); + view._scheduledInsert = null; + } return view; }, @@ -13893,9 +14788,6 @@ Ember.View.states.inDOM = { parentState: Ember.View.states.hasElement, insertElement: function(view, fn) { - if (view._lastInsert !== Ember.guidFor(fn)){ - return; - } throw "You can't insert an element into the DOM that has already been inserted"; } }; @@ -13905,12 +14797,11 @@ Ember.View.states.inDOM = { (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ + var destroyedError = "You can't call %@ on a destroyed view", fmt = Ember.String.fmt; Ember.View.states.destroyed = { @@ -13933,6 +14824,10 @@ Ember.View.states.destroyed = { throw fmt(destroyedError, ["set('element', ...)"]); }, + renderToBufferIfNeeded: function() { + throw fmt(destroyedError, ["renderToBufferIfNeeded"]); + }, + // Since element insertion is scheduled, don't do anything if // the view has been destroyed between scheduling and execution insertElement: Ember.K @@ -13944,24 +14839,17 @@ Ember.View.states.destroyed = { (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-views +*/ + var get = Ember.get, set = Ember.set, meta = Ember.meta; var forEach = Ember.EnumerableUtils.forEach; @@ -13970,8 +14858,6 @@ var childViewsProperty = Ember.computed(function() { }).property('_childViews').cacheable(); /** - @class - A `ContainerView` is an `Ember.View` subclass that allows for manual or programatic management of a view's `childViews` array that will correctly update the `ContainerView` instance's rendered DOM representation. @@ -13980,26 +14866,31 @@ var childViewsProperty = Ember.computed(function() { The initial array of child views can be set in one of two ways. You can provide a `childViews` property at creation time that contains instance of `Ember.View`: - - aContainer = Ember.ContainerView.create({ - childViews: [Ember.View.create(), Ember.View.create()] - }) + ``` javascript + aContainer = Ember.ContainerView.create({ + childViews: [Ember.View.create(), Ember.View.create()] + }); + ``` You can also provide a list of property names whose values are instances of `Ember.View`: - aContainer = Ember.ContainerView.create({ - childViews: ['aView', 'bView', 'cView'], - aView: Ember.View.create(), - bView: Ember.View.create() - cView: Ember.View.create() - }) + ``` javascript + aContainer = Ember.ContainerView.create({ + childViews: ['aView', 'bView', 'cView'], + aView: Ember.View.create(), + bView: Ember.View.create() + cView: Ember.View.create() + }); + ``` The two strategies can be combined: - aContainer = Ember.ContainerView.create({ - childViews: ['aView', Ember.View.create()], - aView: Ember.View.create() - }) + ``` javascript + aContainer = Ember.ContainerView.create({ + childViews: ['aView', Ember.View.create()], + aView: Ember.View.create() + }); + ``` Each child view's rendering will be inserted into the container's rendered HTML in the same order as its position in the `childViews` property. @@ -14012,37 +14903,45 @@ var childViewsProperty = Ember.computed(function() { Given an empty `` the following code - aContainer = Ember.ContainerView.create({ - classNames: ['the-container'], - childViews: ['aView', 'bView'], - aView: Ember.View.create({ - template: Ember.Handlebars.compile("A") - }), - bView: Ember.View.create({ - template: Ember.Handlebars.compile("B") - }) - }) + ``` javascript + aContainer = Ember.ContainerView.create({ + classNames: ['the-container'], + childViews: ['aView', 'bView'], + aView: Ember.View.create({ + template: Ember.Handlebars.compile("A") + }), + bView: Ember.View.create({ + template: Ember.Handlebars.compile("B") + }) + }); - aContainer.appendTo('body') + aContainer.appendTo('body'); + ``` Results in the HTML -
-
A
-
B
-
+ ``` html +
+
A
+
B
+
+ ``` Removing a view - aContainer.get('childViews') // [aContainer.aView, aContainer.bView] - aContainer.get('childViews').removeObject(aContainer.get('bView')) - aContainer.get('childViews') // [aContainer.aView] + ``` javascript + aContainer.get('childViews'); // [aContainer.aView, aContainer.bView] + aContainer.get('childViews').removeObject(aContainer.get('bView')); + aContainer.get('childViews'); // [aContainer.aView] + ``` Will result in the following HTML -
-
A
-
+ ``` html +
+
A
+
+ ``` Similarly, adding a child view is accomplished by adding `Ember.View` instances to the @@ -14050,43 +14949,51 @@ var childViewsProperty = Ember.computed(function() { Given an empty `` the following code - aContainer = Ember.ContainerView.create({ - classNames: ['the-container'], - childViews: ['aView', 'bView'], - aView: Ember.View.create({ - template: Ember.Handlebars.compile("A") - }), - bView: Ember.View.create({ - template: Ember.Handlebars.compile("B") - }) - }) + ``` javascript + aContainer = Ember.ContainerView.create({ + classNames: ['the-container'], + childViews: ['aView', 'bView'], + aView: Ember.View.create({ + template: Ember.Handlebars.compile("A") + }), + bView: Ember.View.create({ + template: Ember.Handlebars.compile("B") + }) + }); - aContainer.appendTo('body') + aContainer.appendTo('body'); + ``` Results in the HTML -
-
A
-
B
-
+ ``` html +
+
A
+
B
+
+ ``` Adding a view - AnotherViewClass = Ember.View.extend({ - template: Ember.Handlebars.compile("Another view") - }) + ``` javascript + AnotherViewClass = Ember.View.extend({ + template: Ember.Handlebars.compile("Another view") + }); - aContainer.get('childViews') // [aContainer.aView, aContainer.bView] - aContainer.get('childViews').pushObject(AnotherViewClass.create()) - aContainer.get('childViews') // [aContainer.aView, aContainer.bView, ] + aContainer.get('childViews'); // [aContainer.aView, aContainer.bView] + aContainer.get('childViews').pushObject(AnotherViewClass.create()); + aContainer.get('childViews'); // [aContainer.aView, aContainer.bView, ] + ``` Will result in the following HTML -
-
A
-
B
-
Another view
-
+ ``` html +
+
A
+
B
+
Another view
+
+ ``` Direct manipulation of childViews presence or absence in the DOM via calls to @@ -14102,36 +15009,43 @@ var childViewsProperty = Ember.computed(function() { Calling `removeFromParent()` behaves as expected but should be avoided in favor of direct manipulation of a container's `childViews` property. - aContainer = Ember.ContainerView.create({ - classNames: ['the-container'], - childViews: ['aView', 'bView'], - aView: Ember.View.create({ - template: Ember.Handlebars.compile("A") - }), - bView: Ember.View.create({ - template: Ember.Handlebars.compile("B") - }) - }) + ``` javascript + aContainer = Ember.ContainerView.create({ + classNames: ['the-container'], + childViews: ['aView', 'bView'], + aView: Ember.View.create({ + template: Ember.Handlebars.compile("A") + }), + bView: Ember.View.create({ + template: Ember.Handlebars.compile("B") + }) + }); - aContainer.appendTo('body') + aContainer.appendTo('body'); + ``` Results in the HTML -
-
A
-
B
-
+ ``` html +
+
A
+
B
+
+ ``` Calling `aContainer.get('aView').removeFromParent()` will result in the following HTML -
-
B
-
+ ``` html +
+
B
+
+ ``` And the `Ember.View` instance stored in `aContainer.aView` will be removed from `aContainer`'s `childViews` array. ## Templates and Layout + A `template`, `templateName`, `defaultTemplate`, `layout`, `layoutName` or `defaultLayout` property on a container view will not result in the template or layout being rendered. The HTML contents of a `Ember.ContainerView`'s DOM representation will only be the rendered HTML @@ -14149,16 +15063,20 @@ var childViewsProperty = Ember.computed(function() { a controller or state manager. For example, you can bind the `currentView` of a container to a controller like this: - // Controller - App.appController = Ember.Object.create({ - view: Ember.View.create({ - templateName: 'person_template' - }) - }); + ``` javascript + App.appController = Ember.Object.create({ + view: Ember.View.create({ + templateName: 'person_template' + }) + }); + ``` - // Handlebars template - {{view Ember.ContainerView currentViewBinding="App.appController.view"}} + ``` handlebars + {{view Ember.ContainerView currentViewBinding="App.appController.view"}} + ``` + @class ContainerView + @namespace Ember @extends Ember.View */ @@ -14202,10 +15120,12 @@ Ember.ContainerView = Ember.View.extend({ }, /** + @private + Instructs each child view to render to the passed render buffer. + @method render @param {Ember.RenderBuffer} buffer the buffer to render to - @private */ render: function(buffer) { this.forEachChildView(function(view) { @@ -14214,10 +15134,12 @@ Ember.ContainerView = Ember.View.extend({ }, /** + @private + When the container view is destroyed, tear down the child views array observer. - @private + @method willDestroy */ willDestroy: function() { get(this, 'childViews').removeArrayObserver(this, { @@ -14229,13 +15151,15 @@ Ember.ContainerView = Ember.View.extend({ }, /** + @private + When a child view is removed, destroy its element so that it is removed from the DOM. The array observer that triggers this action is set up in the `renderToBuffer` method. - @private + @method childViewsWillChange @param {Ember.Array} views the child views array before mutation @param {Number} start the start position of the mutation @param {Number} removed the number of child views removed @@ -14250,6 +15174,8 @@ Ember.ContainerView = Ember.View.extend({ }, /** + @private + When a child view is added, make sure the DOM gets updated appropriately. If the view has already rendered an element, we tell the child view to @@ -14258,7 +15184,7 @@ Ember.ContainerView = Ember.View.extend({ element, we insert the string representation of the child into the appropriate place in the buffer. - @private + @method childViewsDidChange @param {Ember.Array} views the array of child views afte the mutation has occurred @param {Number} start the start position of the mutation @param {Number} removed the number of child views removed @@ -14287,23 +15213,6 @@ Ember.ContainerView = Ember.View.extend({ }); }, - /** - Schedules a child view to be inserted into the DOM after bindings have - finished syncing for this run loop. - - @param {Ember.View} view the child view to insert - @param {Ember.View} prev the child view after which the specified view should - be inserted - @private - */ - _scheduleInsertion: function(view, prev) { - if (prev) { - prev.domManager.after(prev, view); - } else { - this.domManager.prepend(this, view); - } - }, - currentView: null, _currentViewWillChange: Ember.beforeObserver(function() { @@ -14323,7 +15232,11 @@ Ember.ContainerView = Ember.View.extend({ if (currentView) { childViews.pushObject(currentView); } - }, 'currentView') + }, 'currentView'), + + _ensureChildrenAreInDOM: function () { + this.invokeForState('ensureChildrenAreInDOM', this); + } }); // Ember.ContainerView extends the default view states to provide different @@ -14369,15 +15282,26 @@ Ember.ContainerView.states = { }, childViewsDidChange: function(view, views, start, added) { - // If the DOM element for this container view already exists, - // schedule each child view to insert its DOM representation after - // bindings have finished syncing. - var prev = start === 0 ? null : views[start-1]; + Ember.run.scheduleOnce('render', this, '_ensureChildrenAreInDOM'); + }, - for (var i=start; i` and the following code: + ``` javascript + someItemsView = Ember.CollectionView.create({ + classNames: ['a-collection'], + content: ['A','B','C'], + itemViewClass: Ember.View.extend({ + template: Ember.Handlebars.compile("the letter: {{view.content}}") + }) + }); - someItemsView = Ember.CollectionView.create({ - classNames: ['a-collection'], - content: ['A','B','C'], - itemViewClass: Ember.View.extend({ - template: Ember.Handlebars.compile("the letter: {{view.content}}") - }) - }) - - someItemsView.appendTo('body') + someItemsView.appendTo('body'); + ``` Will result in the following HTML structure -
-
the letter: A
-
the letter: B
-
the letter: C
-
+ ``` html +
+
the letter: A
+
the letter: B
+
the letter: C
+
+ ``` ## Automatic matching of parent/child tagNames - Setting the `tagName` property of a `CollectionView` to any of + Setting the `tagName` property of a `CollectionView` to any of "ul", "ol", "table", "thead", "tbody", "tfoot", "tr", or "select" will result in the item views receiving an appropriately matched `tagName` property. Given an empty `` and the following code: - anUndorderedListView = Ember.CollectionView.create({ - tagName: 'ul', - content: ['A','B','C'], - itemViewClass: Ember.View.extend({ - template: Ember.Handlebars.compile("the letter: {{view.content}}") - }) - }) + ``` javascript + anUndorderedListView = Ember.CollectionView.create({ + tagName: 'ul', + content: ['A','B','C'], + itemViewClass: Ember.View.extend({ + template: Ember.Handlebars.compile("the letter: {{view.content}}") + }) + }); - anUndorderedListView.appendTo('body') + anUndorderedListView.appendTo('body'); + ``` Will result in the following HTML structure -
    -
  • the letter: A
    • -
  • the letter: B
    • -
  • the letter: C
    • -
+ ``` html +
    +
  • the letter: A
    • +
  • the letter: B
    • +
  • the letter: C
    • +
+ ``` Additional tagName pairs can be provided by adding to `Ember.CollectionView.CONTAINER_MAP ` - Ember.CollectionView.CONTAINER_MAP['article'] = 'section' + ``` javascript + Ember.CollectionView.CONTAINER_MAP['article'] = 'section' + ``` ## Empty View @@ -14487,23 +15419,27 @@ var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; `emptyView` property. If the `content` property of a `CollectionView` is set to `null` or an empty array, an instance of this view will be the `CollectionView`s only child. - aListWithNothing = Ember.CollectionView.create({ - classNames: ['nothing'] - content: null, - emptyView: Ember.View.extend({ - template: Ember.Handlebars.compile("The collection is empty") - }) - }) + ``` javascript + aListWithNothing = Ember.CollectionView.create({ + classNames: ['nothing'] + content: null, + emptyView: Ember.View.extend({ + template: Ember.Handlebars.compile("The collection is empty") + }) + }); - aListWithNothing.appendTo('body') + aListWithNothing.appendTo('body'); + ``` Will result in the following HTML structure -
-
- The collection is empty -
-
+ ``` html +
+
+ The collection is empty +
+
+ ``` ## Adding and Removing items The `childViews` property of a `CollectionView` should not be directly manipulated. Instead, @@ -14514,8 +15450,10 @@ var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; Ember.Handlebars provides a helper specifically for adding `CollectionView`s to templates. See `Ember.Handlebars.collection` for more details - @since Ember 0.9 + @class CollectionView + @namespace Ember @extends Ember.ContainerView + @since Ember 0.9 */ Ember.CollectionView = Ember.ContainerView.extend( /** @scope Ember.CollectionView.prototype */ { @@ -14523,6 +15461,7 @@ Ember.CollectionView = Ember.ContainerView.extend( /** A list of items to be displayed by the Ember.CollectionView. + @property content @type Ember.Array @default null */ @@ -14534,24 +15473,27 @@ Ember.CollectionView = Ember.ContainerView.extend( This provides metadata about what kind of empty view class this collection would like if it is being instantiated from another system (like Handlebars) + + @property emptyViewClass */ emptyViewClass: Ember.View, /** An optional view to display if content is set to an empty array. + @property emptyView @type Ember.View @default null */ emptyView: null, /** + @property itemViewClass @type Ember.View @default Ember.View */ itemViewClass: Ember.View, - /** @private */ init: function() { var ret = this._super(); this._contentDidChange(); @@ -14573,6 +15515,8 @@ Ember.CollectionView = Ember.ContainerView.extend( update the children directly. This is always scheduled asynchronously, to allow the element to be created before bindings have synchronized and vice versa. + + @method _contentDidChange */ _contentDidChange: Ember.observer(function() { var content = get(this, 'content'); @@ -14629,14 +15573,10 @@ Ember.CollectionView = Ember.ContainerView.extend( This array observer is added in contentDidChange. - @param {Array} addedObjects - the objects that were added to the content - - @param {Array} removedObjects - the objects that were removed from the content - - @param {Number} changeIndex - the index at which the changes occurred + @method arrayDidChange + @param {Array} addedObjects the objects that were added to the content + @param {Array} removedObjects the objects that were removed from the content + @param {Number} changeIndex the index at which the changes occurred */ arrayDidChange: function(content, start, removed, added) { var itemViewClass = get(this, 'itemViewClass'), @@ -14685,14 +15625,14 @@ Ember.CollectionView = Ember.ContainerView.extend( }); /** - @static - A map of parent tags to their default child tags. You can add additional parent tags if you want collection views that use a particular parent tag to default to a child tag. + @property CONTAINER_MAP @type Hash - @constant + @static + @final */ Ember.CollectionView.CONTAINER_MAP = { ul: 'li', @@ -14710,26 +15650,21 @@ Ember.CollectionView.CONTAINER_MAP = { (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { -// ========================================================================== -// Project: Ember - JavaScript Application Framework -// Copyright: ©2006-2011 Strobe Inc. and contributors. -// Portions ©2008-2011 Apple Inc. All rights reserved. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - /*globals jQuery*/ +/** +Ember Views + +@module ember +@submodule ember-views +@require ember-runtime +@main ember-views +*/ })(); @@ -14737,9 +15672,15 @@ Ember.CollectionView.CONTAINER_MAP = { var get = Ember.get, set = Ember.set; /** - @class +@module ember +@submodule ember-states +*/ +/** + @class State + @namespace Ember @extends Ember.Object + @uses Ember.Evented */ Ember.State = Ember.Object.extend(Ember.Evented, /** @scope Ember.State.prototype */{ @@ -14748,6 +15689,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** A reference to the parent state. + @property parentState @type Ember.State */ parentState: null, @@ -14756,6 +15698,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** The name of this state. + @property name @type String */ name: null, @@ -14763,8 +15706,8 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** The full path to this state. + @property path @type String - @readOnly */ path: Ember.computed(function() { var parentPath = get(this, 'parentState.path'), @@ -14782,6 +15725,9 @@ Ember.State = Ember.Object.extend(Ember.Evented, Override the default event firing from Ember.Evented to also call methods with the given name. + + @method trigger + @param name */ trigger: function(name) { if (this[name]) { @@ -14790,7 +15736,6 @@ Ember.State = Ember.Object.extend(Ember.Evented, this._super.apply(this, arguments); }, - /** @private */ init: function() { var states = get(this, 'states'), foundStates; set(this, 'childStates', Ember.A()); @@ -14830,7 +15775,6 @@ Ember.State = Ember.Object.extend(Ember.Evented, set(this, 'pathsCacheNoContext', {}); }, - /** @private */ setupChild: function(states, name, value) { if (!value) { return false; } @@ -14865,6 +15809,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, in the state hierarchy. This is false if the state has child states; otherwise it is true. + @property isLeaf @type Boolean */ isLeaf: Ember.computed(function() { @@ -14874,13 +15819,16 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** A boolean value indicating whether the state takes a context. By default we assume all states take contexts. + + @property hasContext + @default true */ hasContext: true, /** This is the default transition event. - @event + @event setup @param {Ember.StateManager} manager @param context @see Ember.StateManager#transitionEvent @@ -14890,7 +15838,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** This event fires when the state is entered. - @event + @event enter @param {Ember.StateManager} manager */ enter: Ember.K, @@ -14898,20 +15846,16 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** This event fires when the state is exited. - @event + @event exit @param {Ember.StateManager} manager */ exit: Ember.K }); -var Event = Ember.$ && Ember.$.Event; - Ember.State.reopenClass( /** @scope Ember.State */{ /** - @static - Creates an action function for transitioning to the named state while preserving context. The following example StateManagers are equivalent: @@ -14932,28 +15876,32 @@ Ember.State.reopenClass( stateTwo: Ember.State.create({}) }) + @method transitionTo + @static @param {String} target */ + transitionTo: function(target) { - var event = function(stateManager, context) { - if (Event && context instanceof Event) { - if (context.hasOwnProperty('context')) { - context = context.context; - } else { - // If we received an event and it doesn't contain - // a context, don't pass along a superfluous - // context to the target of the event. - return stateManager.transitionTo(target); - } + + var transitionFunction = function(stateManager, contextOrEvent) { + var contexts, transitionArgs; + + if (contextOrEvent && (contextOrEvent instanceof Ember.$.Event) && contextOrEvent.hasOwnProperty('contexts')) { + contexts = contextOrEvent.contexts.slice(); + } + else { + contexts = [].slice.call(arguments, 1); } - stateManager.transitionTo(target, context); + contexts.unshift(target); + stateManager.transitionTo.apply(stateManager, contexts); }; - event.transitionTarget = target; + transitionFunction.transitionTarget = target; - return event; + return transitionFunction; } + }); })(); @@ -14961,16 +15909,22 @@ Ember.State.reopenClass( (function() { +/** +@module ember +@submodule ember-states +*/ + var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; var arrayForEach = Ember.ArrayPolyfills.forEach; /** - @private - A Transition takes the enter, exit and resolve states and normalizes them: * takes any passed in contexts into consideration * adds in `initialState`s + + @class Transition + @private */ var Transition = function(raw) { this.enterStates = raw.enterStates.slice(); @@ -14982,12 +15936,11 @@ var Transition = function(raw) { Transition.prototype = { /** - @private - Normalize the passed in enter, exit and resolve states. This process also adds `finalState` and `contexts` to the Transition object. + @method normalize @param {Ember.StateManager} manager the state manager running the transition @param {Array} contexts a list of contexts passed into `transitionTo` */ @@ -14999,12 +15952,11 @@ Transition.prototype = { }, /** - @private - Match each of the contexts passed to `transitionTo` to a state. This process may also require adding additional enter and exit states if there are more contexts than enter states. + @method matchContextsToStates @param {Array} contexts a list of contexts passed into `transitionTo` */ matchContextsToStates: function(contexts) { @@ -15077,9 +16029,9 @@ Transition.prototype = { }, /** - @private - Add any `initialState`s to the list of enter states. + + @method addInitialStates */ addInitialStates: function() { var finalState = this.finalState, initialState; @@ -15097,12 +16049,11 @@ Transition.prototype = { }, /** - @private - Remove any states that were added because the number of contexts exceeded the number of explicit enter states, but the context has not changed since the last time the state was entered. + @method removeUnchangedContexts @param {Ember.StateManager} manager passed in to look up the last context for a states */ @@ -15125,8 +16076,6 @@ Transition.prototype = { }; /** - @class - StateManager is part of Ember's implementation of a finite state machine. A StateManager instance manages a number of properties that are instances of `Ember.State`, tracks the current active state, and triggers callbacks when states have changed. @@ -15490,14 +16439,20 @@ Transition.prototype = { }), stateTwo: Ember.State.create({}) }) -**/ -Ember.StateManager = Ember.State.extend( -/** @scope Ember.StateManager.prototype */ { + @class StateManager + @namespace Ember + @extends Ember.State +**/ +Ember.StateManager = Ember.State.extend({ /** + @private + When creating a new statemanager, look for a default state to transition into. This state can either be named `start`, or can be specified using the `initialState` property. + + @method init */ init: function() { this._super(); @@ -15540,15 +16495,27 @@ Ember.StateManager = Ember.State.extend( The current state from among the manager's possible states. This property should not be set directly. Use `transitionTo` to move between states by name. + @property currentState @type Ember.State - @readOnly */ currentState: null, + /** + The path of the current state. Returns a string representation of the current + state. + + @property currentPath + @type String + */ + currentPath: Ember.computed('currentState', function() { + return get(this, 'currentState.path'); + }).cacheable(), + /** The name of transitionEvent that this stateManager will dispatch - @property {String} + @property transitionEvent + @type String @default 'setup' */ transitionEvent: 'setup', @@ -15558,19 +16525,30 @@ Ember.StateManager = Ember.State.extend( raised if you attempt to send an event to a state manager that is not handled by the current state or any of its parent states. + @property errorOnUnhandledEvents @type Boolean @default true */ errorOnUnhandledEvent: true, - send: function(event, context) { + send: function(event) { + var contexts, sendRecursiveArguments; + Ember.assert('Cannot send event "' + event + '" while currentState is ' + get(this, 'currentState'), get(this, 'currentState')); - return this.sendRecursively(event, get(this, 'currentState'), context); + + contexts = [].slice.call(arguments, 1); + sendRecursiveArguments = contexts; + sendRecursiveArguments.unshift(event, get(this, 'currentState')); + + return this.sendRecursively.apply(this, sendRecursiveArguments); }, - sendRecursively: function(event, currentState, context) { + sendRecursively: function(event, currentState) { var log = this.enableLogging, - action = currentState[event]; + action = currentState[event], + contexts, sendRecursiveArguments, actionArguments; + + contexts = [].slice.call(arguments, 2); // Test to see if the action is a method that // can be invoked. Don't blindly check just for @@ -15580,11 +16558,19 @@ Ember.StateManager = Ember.State.extend( // case. if (typeof action === 'function') { if (log) { Ember.Logger.log(fmt("STATEMANAGER: Sending event '%@' to state %@.", [event, get(currentState, 'path')])); } - return action.call(currentState, this, context); + + actionArguments = contexts; + actionArguments.unshift(this); + + return action.apply(currentState, actionArguments); } else { var parentState = get(currentState, 'parentState'); if (parentState) { - return this.sendRecursively(event, parentState, context); + + sendRecursiveArguments = contexts; + sendRecursiveArguments.unshift(event, parentState); + + return this.sendRecursively.apply(this, sendRecursiveArguments); } else if (get(this, 'errorOnUnhandledEvent')) { throw new Ember.Error(this.toString() + " could not respond to event " + event + " in state " + get(this, 'currentState.path') + "."); } @@ -15606,9 +16592,10 @@ Ember.StateManager = Ember.State.extend( // returns the dashboard state + @method getStateByPath @param {Ember.State} root the state to start searching from @param {String} path the state path to follow - @returns {Ember.State} the state at the end of the path + @return {Ember.State} the state at the end of the path */ getStateByPath: function(root, path) { var parts = path.split('.'), @@ -15634,8 +16621,6 @@ Ember.StateManager = Ember.State.extend( }, /** - @private - A state stores its child states in its `states` hash. This code takes a path like `posts.show` and looks up `origin.states.posts.states.show`. @@ -15643,6 +16628,10 @@ Ember.StateManager = Ember.State.extend( It returns a list of all of the states from the origin, which is the list of states to call `enter` on. + + @method findStateByPath + @param origin + @param path */ findStatesByPath: function(origin, path) { if (!path || path === "") { return undefined; } @@ -15829,11 +16818,13 @@ Ember.StateManager = Ember.State.extend( (function() { -// ========================================================================== -// Project: Ember Statecharts -// Copyright: ©2011 Living Social Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +Ember States + +@module ember +@submodule ember-states +@requires ember-runtime +*/ })(); @@ -15889,6 +16880,11 @@ Ember._ResolvedState = Ember.Object.extend({ (function() { +/** +@module ember +@submodule ember-routing +*/ + var get = Ember.get; // The Ember Routable mixin assumes the existance of a simple @@ -15918,7 +16914,8 @@ var merge = function(original, hash) { }; /** - @class + @class Routable + @namespace Ember @extends Ember.Mixin */ Ember.Routable = Ember.Mixin.create({ @@ -15951,6 +16948,10 @@ Ember.Routable = Ember.Mixin.create({ Whenever a routable state is entered, the context it was entered with is stashed so that we can regenerate the state's `absoluteURL` on demand. + + @method stashContext + @param manager {Ember.StateManager} + @param context */ stashContext: function(manager, context) { var serialized = this.serialize(manager, context); @@ -15971,6 +16972,10 @@ Ember.Routable = Ember.Mixin.create({ is notified to set the URL to the current absolute path. In general, this will update the browser's URL. + + @method updateRoute + @param manager {Ember.StateManager} + @param location {Ember.Location} */ updateRoute: function(manager, location) { if (get(this, 'isLeafRoute')) { @@ -15987,6 +16992,10 @@ Ember.Routable = Ember.Mixin.create({ This method is private, as it expects a serialized hash, not the original context object. + + @method absoluteRoute + @param manager {Ember.StateManager} + @param hash {Hash} */ absoluteRoute: function(manager, hash) { var parentState = get(this, 'parentState'); @@ -16020,6 +17029,9 @@ Ember.Routable = Ember.Mixin.create({ At the moment, a state is routable if it has a string `route` property. This heuristic may change. + + @property isRoutable + @type Boolean */ isRoutable: Ember.computed(function() { return typeof get(this, 'route') === 'string'; @@ -16029,6 +17041,9 @@ Ember.Routable = Ember.Mixin.create({ @private Determine if this is the last routeable state + + @property isLeafRoute + @type Boolean */ isLeafRoute: Ember.computed(function() { if (get(this, 'isLeaf')) { return true; } @@ -16040,6 +17055,9 @@ Ember.Routable = Ember.Mixin.create({ A _RouteMatcher object generated from the current route's `route` string property. + + @property routeMatcher + @type Ember._RouteMatcher */ routeMatcher: Ember.computed(function() { var route = get(this, 'route'); @@ -16053,6 +17071,9 @@ Ember.Routable = Ember.Mixin.create({ Check whether the route has dynamic segments and therefore takes a context. + + @property hasContext + @type Boolean */ hasContext: Ember.computed(function() { var routeMatcher = get(this, 'routeMatcher'); @@ -16067,6 +17088,9 @@ Ember.Routable = Ember.Mixin.create({ The model class associated with the current state. This property uses the `modelType` property, in order to allow it to be specified as a String. + + @property modelClass + @type Ember.Object */ modelClass: Ember.computed(function() { var modelType = get(this, 'modelType'); @@ -16091,6 +17115,9 @@ Ember.Routable = Ember.Mixin.create({ The process of initializing an application with a router will pass the application's namespace into the router, which will be used here. + + @method modelClassFor + @param namespace {Ember.Namespace} */ modelClassFor: function(namespace) { var modelClass, routeMatcher, identifiers, match, className; @@ -16131,6 +17158,10 @@ Ember.Routable = Ember.Mixin.create({ will be looked up as `namespace.Post.find(1)`. This is designed to work seamlessly with Ember Data, but will work fine with any class that has a `find` method. + + @method deserialize + @param manager {Ember.StateManager} + @param params {Hash} */ deserialize: function(manager, params) { var modelClass, routeMatcher, param; @@ -16152,6 +17183,10 @@ Ember.Routable = Ember.Mixin.create({ `id` of `12`, the serialize method will produce: { blog_post_id: 12 } + + @method serialize + @param manager {Ember.StateManager} + @param context */ serialize: function(manager, context) { var modelClass, routeMatcher, namespace, param, id; @@ -16170,6 +17205,9 @@ Ember.Routable = Ember.Mixin.create({ /** @private + @method resolvePath + @param manager {Ember.StateManager} + @param path {String} */ resolvePath: function(manager, path) { if (get(this, 'isLeafRoute')) { return Ember.A(); } @@ -16224,6 +17262,10 @@ Ember.Routable = Ember.Mixin.create({ For example, if you were in the /posts/1/comments state, and you moved into the /posts/2/comments state, `routePath` will be called on the state whose path is `/posts` with the path `/2/comments`. + + @method routePath + @param manager {Ember.StateManager} + @param path {String} */ routePath: function(manager, path) { if (get(this, 'isLeafRoute')) { return; } @@ -16255,6 +17297,10 @@ Ember.Routable = Ember.Mixin.create({ Its job is to move the state manager into a parent state of the state it will eventually move into. + + @method unroutePath + @param router {Ember.Router} + @param path {String} */ unroutePath: function(router, path) { var parentState = get(this, 'parentState'); @@ -16296,12 +17342,18 @@ Ember.Routable = Ember.Mixin.create({ The `connectOutlets` event will be triggered once a state has been entered. It will be called with the route's context. + + @event connectOutlets + @param router {Ember.Router} + @param [context*] */ connectOutlets: Ember.K, /** The `navigateAway` event will be triggered when the URL changes due to the back/forward button + + @event navigateAway */ navigateAway: Ember.K }); @@ -16312,8 +17364,15 @@ Ember.Routable = Ember.Mixin.create({ (function() { /** - @class - @extends Ember.Routable +@module ember +@submodule ember-routing +*/ + +/** + @class Route + @namespace Ember + @extends Ember.State + @uses Ember.Routable */ Ember.Route = Ember.State.extend(Ember.Routable); @@ -16326,6 +17385,12 @@ var escapeForRegex = function(text) { return text.replace(/[\-\[\]{}()*+?.,\\\^\$|#\s]/g, "\\$&"); }; +/** + @class _RouteMatcher + @namespace Ember + @private + @extends Ember.Object +*/ Ember._RouteMatcher = Ember.Object.extend({ state: null, @@ -16384,6 +17449,341 @@ Ember._RouteMatcher = Ember.Object.extend({ (function() { +/** +@module ember +@submodule ember-routing +*/ + +var get = Ember.get, set = Ember.set; + +/* + This file implements the `location` API used by Ember's router. + + That API is: + + getURL: returns the current URL + setURL(path): sets the current URL + onUpdateURL(callback): triggers the callback when the URL changes + formatURL(url): formats `url` to be placed into `href` attribute + + Calling setURL will not trigger onUpdateURL callbacks. + + TODO: This should perhaps be moved so that it's visible in the doc output. +*/ + +/** + Ember.Location returns an instance of the correct implementation of + the `location` API. + + You can pass it a `implementation` ('hash', 'history', 'none') to force a + particular implementation. + + @class Location + @namespace Ember + @static +*/ +Ember.Location = { + create: function(options) { + var implementation = options && options.implementation; + Ember.assert("Ember.Location.create: you must specify a 'implementation' option", !!implementation); + + var implementationClass = this.implementations[implementation]; + Ember.assert("Ember.Location.create: " + implementation + " is not a valid implementation", !!implementationClass); + + return implementationClass.create.apply(implementationClass, arguments); + }, + + registerImplementation: function(name, implementation) { + this.implementations[name] = implementation; + }, + + implementations: {} +}; + +})(); + + + +(function() { +/** +@module ember +@submodule ember-routing +*/ + +var get = Ember.get, set = Ember.set; + +/** + Ember.NoneLocation does not interact with the browser. It is useful for + testing, or when you need to manage state with your Router, but temporarily + don't want it to muck with the URL (for example when you embed your + application in a larger page). + + @class NoneLocation + @namespace Ember + @extends Ember.Object +*/ +Ember.NoneLocation = Ember.Object.extend({ + path: '', + + getURL: function() { + return get(this, 'path'); + }, + + setURL: function(path) { + set(this, 'path', path); + }, + + onUpdateURL: function(callback) { + // We are not wired up to the browser, so we'll never trigger the callback. + }, + + formatURL: function(url) { + // The return value is not overly meaningful, but we do not want to throw + // errors when test code renders templates containing {{action href=true}} + // helpers. + return url; + } +}); + +Ember.Location.registerImplementation('none', Ember.NoneLocation); + +})(); + + + +(function() { +/** +@module ember +@submodule ember-routing +*/ + +var get = Ember.get, set = Ember.set; + +/** + Ember.HashLocation implements the location API using the browser's + hash. At present, it relies on a hashchange event existing in the + browser. + + @class HashLocation + @namespace Ember + @extends Ember.Object +*/ +Ember.HashLocation = Ember.Object.extend({ + + init: function() { + set(this, 'location', get(this, 'location') || window.location); + }, + + /** + @private + + Returns the current `location.hash`, minus the '#' at the front. + + @method getURL + */ + getURL: function() { + return get(this, 'location').hash.substr(1); + }, + + /** + @private + + Set the `location.hash` and remembers what was set. This prevents + `onUpdateURL` callbacks from triggering when the hash was set by + `HashLocation`. + + @method setURL + @param path {String} + */ + setURL: function(path) { + get(this, 'location').hash = path; + set(this, 'lastSetURL', path); + }, + + /** + @private + + Register a callback to be invoked when the hash changes. These + callbacks will execute when the user presses the back or forward + button, but not after `setURL` is invoked. + + @method onUpdateURL + @param callback {Function} + */ + onUpdateURL: function(callback) { + var self = this; + var guid = Ember.guidFor(this); + + Ember.$(window).bind('hashchange.ember-location-'+guid, function() { + var path = location.hash.substr(1); + if (get(self, 'lastSetURL') === path) { return; } + + set(self, 'lastSetURL', null); + + callback(location.hash.substr(1)); + }); + }, + + /** + @private + + Given a URL, formats it to be placed into the page as part + of an element's `href` attribute. + + This is used, for example, when using the {{action}} helper + to generate a URL based on an event. + + @method formatURL + @param url {String} + */ + formatURL: function(url) { + return '#'+url; + }, + + willDestroy: function() { + var guid = Ember.guidFor(this); + + Ember.$(window).unbind('hashchange.ember-location-'+guid); + } +}); + +Ember.Location.registerImplementation('hash', Ember.HashLocation); + +})(); + + + +(function() { +/** +@module ember +@submodule ember-routing +*/ + +var get = Ember.get, set = Ember.set; + +/** + Ember.HistoryLocation implements the location API using the browser's + history.pushState API. + + @class HistoryLocation + @namespace Ember + @extends Ember.Object +*/ +Ember.HistoryLocation = Ember.Object.extend({ + + init: function() { + set(this, 'location', get(this, 'location') || window.location); + set(this, '_initialURL', get(this, 'location').pathname); + }, + + /** + Will be pre-pended to path upon state change + + @property rootURL + @default '/' + */ + rootURL: '/', + + /** + @private + + Used to give history a starting reference + + @property _initialURL + @default null + */ + _initialURL: null, + + /** + @private + + Returns the current `location.pathname`. + + @method getURL + */ + getURL: function() { + return get(this, 'location').pathname; + }, + + /** + @private + + Uses `history.pushState` to update the url without a page reload. + + @method setURL + @param path {String} + */ + setURL: function(path) { + var state = window.history.state, + initialURL = get(this, '_initialURL'); + + path = this.formatURL(path); + + if ((initialURL !== path && !state) || (state && state.path !== path)) { + window.history.pushState({ path: path }, null, path); + } + }, + + /** + @private + + Register a callback to be invoked whenever the browser + history changes, including using forward and back buttons. + + @method onUpdateURL + @param callback {Function} + */ + onUpdateURL: function(callback) { + var guid = Ember.guidFor(this); + + Ember.$(window).bind('popstate.ember-location-'+guid, function(e) { + callback(location.pathname); + }); + }, + + /** + @private + + Used when using `{{action}}` helper. The url is always appended to the rootURL. + + @method formatURL + @param url {String} + */ + formatURL: function(url) { + var rootURL = get(this, 'rootURL'); + + if (url !== '') { + rootURL = rootURL.replace(/\/$/, ''); + } + + return rootURL + url; + }, + + willDestroy: function() { + var guid = Ember.guidFor(this); + + Ember.$(window).unbind('popstate.ember-location-'+guid); + } +}); + +Ember.Location.registerImplementation('history', Ember.HistoryLocation); + +})(); + + + +(function() { + +})(); + + + +(function() { +/** +@module ember +@submodule ember-routing +*/ + var get = Ember.get, set = Ember.set; var merge = function(original, hash) { @@ -16396,8 +17796,6 @@ var merge = function(original, hash) { }; /** - @class - `Ember.Router` is the subclass of `Ember.StateManager` responsible for providing URL-based application state detection. The `Ember.Router` instance of an application detects the browser URL at application load time and attempts to match it to a specific application state. Additionally @@ -16490,11 +17888,11 @@ var merge = function(original, hash) { route: '/theBaseRouteForThisSet', indexSubRoute: Ember.Route.extend({ - route: '/', + route: '/' }), subRouteOne: Ember.Route.extend({ - route: '/subroute1 + route: '/subroute1' }), subRouteTwo: Ember.Route.extend({ @@ -16559,7 +17957,7 @@ var merge = function(original, hash) { ### Deserializing A URL's Dynamic Segments When an application is first loaded or the URL is changed manually (e.g. through the browser's back button) the `deserialize` method of the URL's matching Ember.Route will be called with - the application's router as its first argument and a hash of the URLs dynamic segments and values + the application's router as its first argument and a hash of the URL's dynamic segments and values as its second argument. The following route structure when loaded with the URL "#/fixed/thefirstvalue/anotherFixed/thesecondvalue": @@ -16595,8 +17993,8 @@ var merge = function(original, hash) { ### Serializing An Object For URLs with Dynamic Segments When transitioning into a Route whose `route` property contains dynamic segments the Route's `serialize` method is called with the Route's router as the first argument and the Route's - context as the second argument. The return value of `serialize` will be use to populate the - dynamic segments and should be a object with keys that match the names of the dynamic sections. + context as the second argument. The return value of `serialize` will be used to populate the + dynamic segments and should be an object with keys that match the names of the dynamic sections. Given the following route structure: @@ -16685,21 +18083,23 @@ var merge = function(original, hash) { ## Injection of Controller Singletons During application initialization Ember will detect properties of the application ending in 'Controller', - create singleton instances of each class, and assign them as a properties on the router. The property name + create singleton instances of each class, and assign them as properties on the router. The property name will be the UpperCamel name converted to lowerCamel format. These controller classes should be subclasses of Ember.ObjectController, Ember.ArrayController, Ember.Controller, or a custom Ember.Object that includes the Ember.ControllerMixin mixin. - App = Ember.Application.create({ - FooController: Ember.Object.create(Ember.ControllerMixin), - Router: Ember.Router.extend({ ... }) - }); + ``` javascript + App = Ember.Application.create({ + FooController: Ember.Object.create(Ember.ControllerMixin), + Router: Ember.Router.extend({ ... }) + }); - App.get('router.fooController'); // instance of App.FooController + App.get('router.fooController'); // instance of App.FooController + ``` The controller singletons will have their `namespace` property set to the application and their `target` property set to the application's router singleton for easy integration with Ember's user event system. - See 'Changing View Hierarchy in Response To State Change' and 'Responding to User-initiated Events' + See 'Changing View Hierarchy in Response To State Change' and 'Responding to User-initiated Events.' ## Responding to User-initiated Events Controller instances injected into the router at application initialization have their `target` property @@ -16708,31 +18108,35 @@ var merge = function(original, hash) { Given the following application entered at the URL '#/': - App = Ember.Application.create({ - Router: Ember.Router.extend({ - root: Ember.Route.extend({ - aRoute: Ember.Route.extend({ - route: '/', - anActionOnTheRouter: function(router, context) { - router.transitionTo('anotherState', context); - } - }) - anotherState: Ember.Route.extend({ - route: '/differentUrl', - connectOutlets: function(router, context) { - - } - }) - }) + ``` javascript + App = Ember.Application.create({ + Router: Ember.Router.extend({ + root: Ember.Route.extend({ + aRoute: Ember.Route.extend({ + route: '/', + anActionOnTheRouter: function(router, context) { + router.transitionTo('anotherState', context); + } }) - }); - App.initialize(); + anotherState: Ember.Route.extend({ + route: '/differentUrl', + connectOutlets: function(router, context) { + + } + }) + }) + }) + }); + App.initialize(); + ``` The following template: - + ``` handlebars + + ``` Will delegate `click` events on the rendered `h1` to the application's router instance. In this case the `anActionOnTheRouter` method of the state at 'root.aRoute' will be called with the view's controller @@ -16741,39 +18145,44 @@ var merge = function(original, hash) { Different `context` can be supplied from within the `{{action}}` helper, allowing specific context passing between application states: - + ``` handlebars + + ``` - See Handlebars.helpers.action for additional usage examples. + See `Handlebars.helpers.action` for additional usage examples. ## Changing View Hierarchy in Response To State Change + Changes in application state that change the URL should be accompanied by associated changes in view hierarchy. This can be accomplished by calling 'connectOutlet' on the injected controller singletons from within the 'connectOutlets' event of an Ember.Route: - App = Ember.Application.create({ - OneController: Ember.ObjectController.extend(), - OneView: Ember.View.extend(), + ``` javascript + App = Ember.Application.create({ + OneController: Ember.ObjectController.extend(), + OneView: Ember.View.extend(), - AnotherController: Ember.ObjectController.extend(), - AnotherView: Ember.View.extend(), + AnotherController: Ember.ObjectController.extend(), + AnotherView: Ember.View.extend(), - Router: Ember.Router.extend({ - root: Ember.Route.extend({ - aRoute: Ember.Route.extend({ - route: '/', - connectOutlets: function(router, context) { - router.get('oneController').connectOutlet('another'); - }, - }) - }) + Router: Ember.Router.extend({ + root: Ember.Route.extend({ + aRoute: Ember.Route.extend({ + route: '/', + connectOutlets: function(router, context) { + router.get('oneController').connectOutlet('another'); + }, }) - }); - App.initialize(); + }) + }) + }); + App.initialize(); + ``` This will detect the '{{outlet}}' portion of `oneController`'s view (an instance of `App.OneView`) and @@ -16785,13 +18194,16 @@ var merge = function(original, hash) { controller injections, see `Ember.Application#initialize()`. For additional information about view context, see `Ember.View`. + @class Router + @namespace Ember @extends Ember.StateManager */ Ember.Router = Ember.StateManager.extend( /** @scope Ember.Router.prototype */ { /** - @property {String} + @property initialState + @type String @default 'root' */ initialState: 'root', @@ -16801,9 +18213,12 @@ Ember.Router = Ember.StateManager.extend( URL state. The following values are supported: * 'hash': Uses URL fragment identifiers (like #/blog/1) for routing. + * 'history': Uses the browser's history.pushstate API for routing. Only works in + modern browsers with pushstate support. * 'none': Does not read or set the browser URL, but still allows for routing to happen. Useful for testing. + @property location @type String @default 'hash' */ @@ -16813,6 +18228,7 @@ Ember.Router = Ember.StateManager.extend( This is only used when a history location is used so that applications that don't live at the root of the domain can append paths to their root. + @property rootURL @type String @default '/' */ @@ -16822,7 +18238,8 @@ Ember.Router = Ember.StateManager.extend( /** On router, transitionEvent should be called connectOutlets - @property {String} + @property transitionEvent + @type String @default 'connectOutlets' */ transitionEvent: 'connectOutlets', @@ -16840,6 +18257,7 @@ Ember.Router = Ember.StateManager.extend( var routableState; try { + path = path.replace(get(this, 'rootURL'), ''); path = path.replace(/^(?=[^\/])/, "/"); this.send('navigateAway'); @@ -16896,7 +18314,6 @@ Ember.Router = Ember.StateManager.extend( return this.urlFor(targetStateName, hash); }, - /** @private */ serializeRecursively: function(state, contexts, hash) { var parentState, context = get(state, 'hasContext') ? contexts.pop() : null; @@ -16916,9 +18333,6 @@ Ember.Router = Ember.StateManager.extend( } }, - /** - @private - */ handleStatePromises: function(states, complete) { this.abortRoutingPromises(); @@ -16948,7 +18362,6 @@ Ember.Router = Ember.StateManager.extend( }).start(); }, - /** @private */ init: function() { this._super(); @@ -16963,7 +18376,6 @@ Ember.Router = Ember.StateManager.extend( } }, - /** @private */ willDestroy: function() { get(this, 'location').destroy(); } @@ -16974,356 +18386,13 @@ Ember.Router = Ember.StateManager.extend( (function() { -// ========================================================================== -// Project: Ember Routing -// Copyright: ©2012 Tilde Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - -})(); - -(function() { -var get = Ember.get; - -Ember.StateManager.reopen( -/** @scope Ember.StateManager.prototype */ { - - /** - If the current state is a view state or the descendent of a view state, - this property will be the view associated with it. If there is no - view state active in this state manager, this value will be null. - - @type Ember.View - */ - currentView: Ember.computed(function() { - var currentState = get(this, 'currentState'), - view; - - while (currentState) { - // TODO: Remove this when view state is removed - if (get(currentState, 'isViewState')) { - view = get(currentState, 'view'); - if (view) { return view; } - } - - currentState = get(currentState, 'parentState'); - } - - return null; - }).property('currentState').cacheable() - -}); - -})(); - - - -(function() { -var get = Ember.get, set = Ember.set; /** - @class - @deprecated +Ember Routing - Ember.ViewState extends Ember.State to control the presence of a childView within a - container based on the current state of the ViewState's StateManager. - - ## Interactions with Ember's View System. - When combined with instances of `Ember.StateManager`, ViewState is designed to - interact with Ember's view system to control which views are added to - and removed from the DOM based on the manager's current state. - - By default, a StateManager will manage views inside the 'body' element. This can be - customized by setting the `rootElement` property to a CSS selector of an existing - HTML element you would prefer to receive view rendering. - - - viewStates = Ember.StateManager.create({ - rootElement: '#some-other-element' - }) - - You can also specify a particular instance of `Ember.ContainerView` you would like to receive - view rendering by setting the `rootView` property. You will be responsible for placing - this element into the DOM yourself. - - aLayoutView = Ember.ContainerView.create() - - // make sure this view instance is added to the browser - aLayoutView.appendTo('body') - - App.viewStates = Ember.StateManager.create({ - rootView: aLayoutView - }) - - - Once you have an instance of StateManager controlling a view, you can provide states - that are instances of `Ember.ViewState`. When the StateManager enters a state - that is an instance of `Ember.ViewState` that `ViewState`'s `view` property will be - instantiated and inserted into the StateManager's `rootView` or `rootElement`. - When a state is exited, the `ViewState`'s view will be removed from the StateManager's - view. - - ContactListView = Ember.View.extend({ - classNames: ['my-contacts-css-class'], - template: Ember.Handlebars.compile('

People

') - }) - - PhotoListView = Ember.View.extend({ - classNames: ['my-photos-css-class'], - template: Ember.Handlebars.compile('

Photos

') - }) - - viewStates = Ember.StateManager.create({ - showingPeople: Ember.ViewState.create({ - view: ContactListView - }), - showingPhotos: Ember.ViewState.create({ - view: PhotoListView - }) - }) - - viewStates.transitionTo('showingPeople') - - The above code will change the rendered HTML from - - - - to - - -
-

People

-
- - - Changing the current state via `transitionTo` from `showingPeople` to - `showingPhotos` will remove the `showingPeople` view and add the `showingPhotos` view: - - viewStates.transitionTo('showingPhotos') - - will change the rendered HTML to - - -
-

Photos

-
- - - - When entering nested `ViewState`s, each state's view will be draw into the the StateManager's - `rootView` or `rootElement` as siblings. - - - ContactListView = Ember.View.extend({ - classNames: ['my-contacts-css-class'], - template: Ember.Handlebars.compile('

People

') - }) - - EditAContactView = Ember.View.extend({ - classNames: ['editing-a-contact-css-class'], - template: Ember.Handlebars.compile('Editing...') - }) - - viewStates = Ember.StateManager.create({ - showingPeople: Ember.ViewState.create({ - view: ContactListView, - - withEditingPanel: Ember.ViewState.create({ - view: EditAContactView - }) - }) - }) - - - viewStates.transitionTo('showingPeople.withEditingPanel') - - - Will result in the following rendered HTML: - - -
-

People

-
- -
- Editing... -
- - - - ViewState views are added and removed from their StateManager's view via their - `enter` and `exit` methods. If you need to override these methods, be sure to call - `_super` to maintain the adding and removing behavior: - - viewStates = Ember.StateManager.create({ - aState: Ember.ViewState.create({ - view: Ember.View.extend({}), - enter: function(manager){ - // calling _super ensures this view will be - // properly inserted - this._super(manager); - - // now you can do other things - } - }) - }) - - ## Managing Multiple Sections of A Page With States - Multiple StateManagers can be combined to control multiple areas of an application's rendered views. - Given the following HTML body: - - - -
-
- - - You could separately manage view state for each section with two StateManagers - - navigationStates = Ember.StateManager.create({ - rootElement: '#sidebar-nav', - userAuthenticated: Em.ViewState.create({ - view: Ember.View.extend({}) - }), - userNotAuthenticated: Em.ViewState.create({ - view: Ember.View.extend({}) - }) - }) - - contentStates = Ember.StateManager.create({ - rootElement: '#content-area', - books: Em.ViewState.create({ - view: Ember.View.extend({}) - }), - music: Em.ViewState.create({ - view: Ember.View.extend({}) - }) - }) - - - If you prefer to start with an empty body and manage state programmatically you - can also take advantage of StateManager's `rootView` property and the ability of - `Ember.ContainerView`s to manually manage their child views. - - - dashboard = Ember.ContainerView.create({ - childViews: ['navigationAreaView', 'contentAreaView'], - navigationAreaView: Ember.ContainerView.create({}), - contentAreaView: Ember.ContainerView.create({}) - }) - - navigationStates = Ember.StateManager.create({ - rootView: dashboard.get('navigationAreaView'), - userAuthenticated: Em.ViewState.create({ - view: Ember.View.extend({}) - }), - userNotAuthenticated: Em.ViewState.create({ - view: Ember.View.extend({}) - }) - }) - - contentStates = Ember.StateManager.create({ - rootView: dashboard.get('contentAreaView'), - books: Em.ViewState.create({ - view: Ember.View.extend({}) - }), - music: Em.ViewState.create({ - view: Ember.View.extend({}) - }) - }) - - dashboard.appendTo('body') - - ## User Manipulation of State via `{{action}}` Helpers - The Handlebars `{{action}}` helper is StateManager-aware and will use StateManager action sending - to connect user interaction to action-based state transitions. - - Given the following body and handlebars template - - - - - - And application code - - App = Ember.Application.create() - App.appStates = Ember.StateManager.create({ - initialState: 'aState', - aState: Ember.State.create({ - anAction: function(manager, context){} - }), - bState: Ember.State.create({}) - }) - - A user initiated click or touch event on "Go" will trigger the 'anAction' method of - `App.appStates.aState` with `App.appStates` as the first argument and a - `jQuery.Event` object as the second object. The `jQuery.Event` will include a property - `view` that references the `Ember.View` object that was interacted with. - -**/ -Ember.ViewState = Ember.State.extend( -/** @scope Ember.ViewState.prototype */ { - isViewState: true, - - init: function() { - Ember.deprecate("Ember.ViewState is deprecated and will be removed from future releases. Consider using the outlet pattern to display nested views instead. For more information, see http://emberjs.com/guides/outlets/."); - return this._super(); - }, - - enter: function(stateManager) { - var view = get(this, 'view'), root, childViews; - - if (view) { - if (Ember.View.detect(view)) { - view = view.create(); - set(this, 'view', view); - } - - Ember.assert('view must be an Ember.View', view instanceof Ember.View); - - root = stateManager.get('rootView'); - - if (root) { - childViews = get(root, 'childViews'); - childViews.pushObject(view); - } else { - root = stateManager.get('rootElement') || 'body'; - view.appendTo(root); - } - } - }, - - exit: function(stateManager) { - var view = get(this, 'view'); - - if (view) { - // If the view has a parent view, then it is - // part of a view hierarchy and should be removed - // from its parent. - if (get(view, 'parentView')) { - view.removeFromParent(); - } else { - - // Otherwise, the view is a "root view" and - // was appended directly to the DOM. - view.remove(); - } - } - } -}); - -})(); - - - -(function() { -// ========================================================================== -// Project: Ember Statecharts -// Copyright: ©2011 Living Social Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +@module ember +@submodule ember-routing +@requires ember-states +*/ })(); @@ -17731,31 +18800,18 @@ Ember.ViewState = Ember.State.extend( })(); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Handlebars */ +/** +@module ember +@submodule ember-handlebars +*/ + var objectCreate = Ember.create; -/** - @namespace - @name Handlebars - @private -*/ - -/** - @namespace - @name Handlebars.helpers - @description Helpers for Handlebars templates -*/ Ember.assert("Ember Handlebars requires Handlebars 1.0.beta.5 or greater", window.Handlebars && window.Handlebars.VERSION.match(/^1\.0\.beta\.[56789]$|^1\.0\.rc\.[123456789]+/)); /** - @class - Prepares the Handlebars templating library for use inside Ember's view system. @@ -17765,20 +18821,36 @@ Ember.assert("Ember Handlebars requires Handlebars 1.0.beta.5 or greater", windo To create an Ember.Handlebars template, call Ember.Handlebars.compile(). This will return a function that can be used by Ember.View for rendering. + + @class Handlebars + @namespace Ember */ Ember.Handlebars = objectCreate(Handlebars); +/** +@class helpers +@namespace Ember.Handlebars +*/ Ember.Handlebars.helpers = objectCreate(Handlebars.helpers); /** Override the the opcode compiler and JavaScript compiler for Handlebars. + + @class Compiler + @namespace Ember.Handlebars @private + @constructor */ Ember.Handlebars.Compiler = function() {}; Ember.Handlebars.Compiler.prototype = objectCreate(Handlebars.Compiler.prototype); Ember.Handlebars.Compiler.prototype.compiler = Ember.Handlebars.Compiler; -/** @private */ +/** + @class JavaScriptCompiler + @namespace Ember.Handlebars + @private + @constructor +*/ Ember.Handlebars.JavaScriptCompiler = function() {}; Ember.Handlebars.JavaScriptCompiler.prototype = objectCreate(Handlebars.JavaScriptCompiler.prototype); Ember.Handlebars.JavaScriptCompiler.prototype.compiler = Ember.Handlebars.JavaScriptCompiler; @@ -17790,22 +18862,29 @@ Ember.Handlebars.JavaScriptCompiler.prototype.initializeBuffer = function() { }; /** + @private + Override the default buffer for Ember Handlebars. By default, Handlebars creates an empty String at the beginning of each invocation and appends to it. Ember's Handlebars overrides this to append to a single shared buffer. - @private + @method appendToBuffer + @param string {String} */ Ember.Handlebars.JavaScriptCompiler.prototype.appendToBuffer = function(string) { return "data.buffer.push("+string+");"; }; /** - Rewrite simple mustaches from {{foo}} to {{bind "foo"}}. This means that all simple + @private + + Rewrite simple mustaches from `{{foo}}` to `{{bind "foo"}}`. This means that all simple mustaches in Ember's Handlebars will also set up an observer to keep the DOM up to date when the underlying property changes. - @private + @method mustache + @for Ember.Handlebars.Compiler + @param mustache */ Ember.Handlebars.Compiler.prototype.mustache = function(mustache) { if (mustache.params.length || mustache.hash) { @@ -17829,6 +18908,9 @@ Ember.Handlebars.Compiler.prototype.mustache = function(mustache) { Used for precompilation of Ember Handlebars templates. This will not be used during normal app execution. + @method precompile + @for Ember.Handlebars + @static @param {String} string The template to precompile */ Ember.Handlebars.precompile = function(string) { @@ -17855,7 +18937,11 @@ Ember.Handlebars.precompile = function(string) { The entry point for Ember Handlebars. This replaces the default Handlebars.compile and turns on template-local data and String parameters. + @method compile + @for Ember.Handlebars + @static @param {String} string The template to compile + @return {Function} */ Ember.Handlebars.compile = function(string) { var ast = Handlebars.parse(string); @@ -17867,10 +18953,16 @@ Ember.Handlebars.compile = function(string) { }; /** + @private + If a path starts with a reserved keyword, returns the root that should be used. - @private + @method normalizePath + @for Ember + @param root {Object} + @param path {String} + @param data {Hash} */ var normalizePath = Ember.Handlebars.normalizePath = function(root, path, data) { var keywords = (data && data.keywords) || {}, @@ -17901,16 +18993,19 @@ var normalizePath = Ember.Handlebars.normalizePath = function(root, path, data) return { root: root, path: path, isKeyword: isKeyword }; }; + + /** Lookup both on root and on window. If the path starts with a keyword, the corresponding object will be looked up in the template's data hash and used to resolve the path. + @method getPath + @for Ember.Handlebars @param {Object} root The object to look up the property on @param {String} path The path to be lookedup @param {Object} options The template's option hash */ - Ember.Handlebars.getPath = function(root, path, options) { var data = options && options.data, normalizedPath = normalizePath(root, path, data), @@ -17931,6 +19026,8 @@ Ember.Handlebars.getPath = function(root, path, options) { }; /** + @private + Registers a helper in Handlebars that will be called if no property with the given name can be found on the current context object, and no helper with that name is registered. @@ -17938,7 +19035,8 @@ Ember.Handlebars.getPath = function(root, path, options) { This throws an exception with a more helpful error message so the user can track down where the problem is happening. - @name Handlebars.helpers.helperMissing + @method helperMissing + @for Ember.Handlebars.helpers @param {String} path @param {Hash} options */ @@ -17958,7 +19056,11 @@ Ember.Handlebars.registerHelper('helperMissing', function(path, options) { (function() { - +/** + @method htmlSafe + @for Ember.String + @static +*/ Ember.String.htmlSafe = function(str) { return new Handlebars.SafeString(str); }; @@ -17968,7 +19070,10 @@ var htmlSafe = Ember.String.htmlSafe; if (Ember.EXTEND_PROTOTYPES) { /** - @see Ember.String.htmlSafe + See {{#crossLink "Ember.String/htmlSafe"}}{{/crossLink}} + + @method htmlSafe + @for String */ String.prototype.htmlSafe = function() { return htmlSafe(this); @@ -17982,33 +19087,32 @@ if (Ember.EXTEND_PROTOTYPES) { (function() { /*jshint newcap:false*/ +/** +@module ember +@submodule ember-handlebars +*/ + var set = Ember.set, get = Ember.get; +// DOMManager should just abstract dom manipulation between jquery and metamorph var DOMManager = { remove: function(view) { - var morph = view.morph; - if (morph.isRemoved()) { return; } - set(view, 'element', null); - view._lastInsert = null; - morph.remove(); + view.morph.remove(); }, - prepend: function(view, childView) { - childView._insertElementLater(function() { - var morph = view.morph; - morph.prepend(childView.outerHTML); - childView.outerHTML = null; - }); + prepend: function(view, html) { + view.morph.prepend(html); }, - after: function(view, nextView) { - nextView._insertElementLater(function() { - var morph = view.morph; - morph.after(nextView.outerHTML); - nextView.outerHTML = null; - }); + after: function(view, html) { + view.morph.after(html); }, + html: function(view, html) { + view.morph.html(html); + }, + + // This is messed up. replace: function(view) { var morph = view.morph; @@ -18034,6 +19138,12 @@ var DOMManager = { // The `morph` and `outerHTML` properties are internal only // and not observable. +/** + @class _Metamorph + @namespace Ember + @extends Ember.Mixin + @private +*/ Ember._Metamorph = Ember.Mixin.create({ isVirtual: true, tagName: '', @@ -18060,6 +19170,13 @@ Ember._Metamorph = Ember.Mixin.create({ domManager: DOMManager }); +/** + @class _MetamorphView + @namespace Ember + @extends Ember.View + @uses Ember._Metamorph + @private +*/ Ember._MetamorphView = Ember.View.extend(Ember._Metamorph); @@ -18068,19 +19185,15 @@ Ember._MetamorphView = Ember.View.extend(Ember._Metamorph); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Handlebars */ +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set, getPath = Ember.Handlebars.getPath; /** - @ignore - @private - @class - Ember._HandlebarsBoundView is a private view created by the Handlebars `{{bind}}` helpers that is used to keep track of bound properties. @@ -18088,15 +19201,20 @@ var get = Ember.get, set = Ember.set, getPath = Ember.Handlebars.getPath; of Ember._HandlebarsBoundView is created with the appropriate sub-template and context set up. When the associated property changes, just the template for this view will re-render. + + @class _HandlebarsBoundView + @namespace Ember + @extends Ember._MetamorphView + @private */ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ -/** @scope Ember._HandlebarsBoundView.prototype */ /** The function used to determine if the `displayTemplate` or `inverseTemplate` should be rendered. This should be a function that takes a value and returns a Boolean. + @property shouldDisplayFunc @type Function @default null */ @@ -18113,6 +19231,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ foo}}` because the template should receive the object found by evaluating `foo`. + @property preserveContext @type Boolean @default false */ @@ -18122,6 +19241,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ If `preserveContext` is true, this is the object that will be used to render the template. + @property previousContext @type Object */ previousContext: null, @@ -18129,6 +19249,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ /** The template to render when `shouldDisplayFunc` evaluates to true. + @property displayTemplate @type Function @default null */ @@ -18137,6 +19258,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ /** The template to render when `shouldDisplayFunc` evaluates to false. + @property inverseTemplate @type Function @default null */ @@ -18150,6 +19272,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ In addition, if `preserveContext` is false, the object at this path will be passed to the template when rendering. + @property path @type String @default null */ @@ -18161,6 +19284,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ for paths that start with a keyword such as `view` or `controller`, the path root will be that resolved object. + @property pathRoot @type Object */ pathRoot: null, @@ -18200,11 +19324,12 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ true, the `displayTemplate` function will be rendered to DOM. Otherwise, `inverseTemplate`, if specified, will be rendered. - For example, if this Ember._HandlebarsBoundView represented the {{#with foo}} + For example, if this Ember._HandlebarsBoundView represented the `{{#with foo}}` helper, it would look up the `foo` property of its context, and `shouldDisplayFunc` would always return true. The object found by looking up `foo` would be passed to `displayTemplate`. + @method render @param {Ember.RenderBuffer} buffer */ render: function(buffer) { @@ -18271,11 +19396,11 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; var getPath = Ember.Handlebars.getPath, normalizePath = Ember.Handlebars.normalizePath; var forEach = Ember.ArrayPolyfills.forEach; @@ -18284,7 +19409,6 @@ var EmberHandlebars = Ember.Handlebars, helpers = EmberHandlebars.helpers; // Binds a property into the DOM. This will create a hook in DOM that the // KVO system will look for and update if the property changes. -/** @private */ function bind(property, options, preserveContext, shouldDisplay, valueNormalizer) { var data = options.data, fn = options.fn, @@ -18318,9 +19442,8 @@ function bind(property, options, preserveContext, shouldDisplay, valueNormalizer view.appendChild(bindView); - /** @private */ var observer = function() { - Ember.run.once(bindView, 'rerenderIfNeeded'); + Ember.run.scheduleOnce('render', bindView, 'rerenderIfNeeded'); }; // Observes the given property on the context and @@ -18338,6 +19461,8 @@ function bind(property, options, preserveContext, shouldDisplay, valueNormalizer } /** + @private + '_triageMustache' is used internally select between a binding and helper for the given context. Until this point, it would be hard to determine if the mustache is a property reference or a regular helper reference. This triage @@ -18345,11 +19470,11 @@ function bind(property, options, preserveContext, shouldDisplay, valueNormalizer This would not be typically invoked by directly. - @private - @name Handlebars.helpers._triageMustache + @method _triageMustache + @for Ember.Handlebars.helpers @param {String} property Property/helperID to triage @param {Function} fn Context to provide for rendering - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('_triageMustache', function(property, fn) { Ember.assert("You cannot pass more than one argument to the _triageMustache helper", arguments.length <= 2); @@ -18362,11 +19487,15 @@ EmberHandlebars.registerHelper('_triageMustache', function(property, fn) { }); /** + @private + `bind` can be used to display a value, then update that value if it changes. For example, if you wanted to print the `title` property of `content`: - {{bind "content.title"}} + ``` handlebars + {{bind "content.title"}} + ``` This will return the `title` property as a string, then create a new observer at the specified path. If it changes, it will update the value in @@ -18375,11 +19504,11 @@ EmberHandlebars.registerHelper('_triageMustache', function(property, fn) { it relies on Ember's KVO system. For all other browsers this will be handled for you automatically. - @private - @name Handlebars.helpers.bind + @method bind + @for Ember.Handlebars.helpers @param {String} property Property to bind @param {Function} fn Context to provide for rendering - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('bind', function(property, fn) { Ember.assert("You cannot pass more than one argument to the bind helper", arguments.length <= 2); @@ -18392,18 +19521,22 @@ EmberHandlebars.registerHelper('bind', function(property, fn) { }); /** + @private + Use the `boundIf` helper to create a conditional that re-evaluates whenever the bound value changes. - {{#boundIf "content.shouldDisplayTitle"}} - {{content.title}} - {{/boundIf}} + ``` handlebars + {{#boundIf "content.shouldDisplayTitle"}} + {{content.title}} + {{/boundIf}} + ``` - @private - @name Handlebars.helpers.boundIf + @method boundIf + @for Ember.Handlebars.helpers @param {String} property Property to bind @param {Function} fn Context to provide for rendering - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('boundIf', function(property, fn) { var context = (fn.contexts && fn.contexts[0]) || this; @@ -18419,10 +19552,11 @@ EmberHandlebars.registerHelper('boundIf', function(property, fn) { }); /** - @name Handlebars.helpers.with + @method with + @for Ember.Handlebars.helpers @param {Function} context @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('with', function(context, options) { if (arguments.length === 4) { @@ -18464,10 +19598,11 @@ EmberHandlebars.registerHelper('with', function(context, options) { /** - @name Handlebars.helpers.if + @method if + @for Ember.Handlebars.helpers @param {Function} context @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('if', function(context, options) { Ember.assert("You must pass exactly one argument to the if helper", arguments.length === 2); @@ -18477,10 +19612,11 @@ EmberHandlebars.registerHelper('if', function(context, options) { }); /** - @name Handlebars.helpers.unless + @method unless + @for Ember.Handlebars.helpers @param {Function} context @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('unless', function(context, options) { Ember.assert("You must pass exactly one argument to the unless helper", arguments.length === 2); @@ -18498,11 +19634,14 @@ EmberHandlebars.registerHelper('unless', function(context, options) { `bindAttr` allows you to create a binding between DOM element attributes and Ember objects. For example: - imageTitle + ``` handlebars + imageTitle + ``` - @name Handlebars.helpers.bindAttr + @method bindAttr + @for Ember.Handlebars.helpers @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('bindAttr', function(options) { @@ -18549,7 +19688,6 @@ EmberHandlebars.registerHelper('bindAttr', function(options) { var observer, invoker; - /** @private */ observer = function observer() { var result = getPath(pathRoot, path, options); @@ -18569,9 +19707,8 @@ EmberHandlebars.registerHelper('bindAttr', function(options) { Ember.View.applyAttributeBindings(elem, attr, result); }; - /** @private */ invoker = function() { - Ember.run.once(observer); + Ember.run.scheduleOnce('render', observer); }; // Add an observer to the view for when the property changes. @@ -18597,6 +19734,8 @@ EmberHandlebars.registerHelper('bindAttr', function(options) { }); /** + @private + Helper that, given a space-separated string of property paths and a context, returns an array of class names. Calling this method also has the side effect of setting up observers at those property paths, such that if they @@ -18608,19 +19747,13 @@ EmberHandlebars.registerHelper('bindAttr', function(options) { "fooBar"). If the value is a string, it will add that string as the class. Otherwise, it will not add any new class name. - @param {Ember.Object} context - The context from which to lookup properties - - @param {String} classBindings - A string, space-separated, of class bindings to use - - @param {Ember.View} view - The view in which observers should look for the element to update - - @param {Srting} bindAttrId - Optional bindAttr id used to lookup elements - - @returns {Array} An array of class names to add + @method bindClasses + @for Ember.Handlebars + @param {Ember.Object} context The context from which to lookup properties + @param {String} classBindings A string, space-separated, of class bindings to use + @param {Ember.View} view The view in which observers should look for the element to update + @param {Srting} bindAttrId Optional bindAttr id used to lookup elements + @return {Array} An array of class names to add */ EmberHandlebars.bindClasses = function(context, classBindings, view, bindAttrId, options) { var ret = [], newClass, value, elem; @@ -18668,7 +19801,6 @@ EmberHandlebars.bindClasses = function(context, classBindings, view, bindAttrId, // Set up an observer on the context. If the property changes, toggle the // class name. - /** @private */ observer = function() { // Get the current value of the property newClass = classStringForPath(pathRoot, parsedPath, options); @@ -18695,9 +19827,8 @@ EmberHandlebars.bindClasses = function(context, classBindings, view, bindAttrId, } }; - /** @private */ invoker = function() { - Ember.run.once(observer); + Ember.run.scheduleOnce('render', observer); }; if (path !== '' && path !== 'this') { @@ -18726,20 +19857,19 @@ EmberHandlebars.bindClasses = function(context, classBindings, view, bindAttrId, (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Handlebars */ // TODO: Don't require the entire module +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; var PARENT_VIEW_PATH = /^parentView\./; var EmberHandlebars = Ember.Handlebars; var VIEW_PRESERVES_CONTEXT = Ember.VIEW_PRESERVES_CONTEXT; -/** @private */ EmberHandlebars.ViewHelper = Ember.Object.create({ propertiesFromHTMLOptions: function(options, thisContext) { @@ -18884,65 +20014,77 @@ EmberHandlebars.ViewHelper = Ember.Object.create({ An empty `` and the following template: - + ``` handlebars + + ``` Will result in HTML structure: - - + ``` html + + -
- A span: - - Hello. - -
- +
+ A span: + + Hello. + +
+ + ``` ### parentView setting The `parentView` property of the new `Ember.View` instance created through `{{view}}` will be set to the `Ember.View` instance of the template where `{{view}}` was called. - aView = Ember.View.create({ - template: Ember.Handlebars.compile("{{#view}} my parent: {{parentView.elementId}} {{/view}}") - }) - - aView.appendTo('body') + ``` javascript + aView = Ember.View.create({ + template: Ember.Handlebars.compile("{{#view}} my parent: {{parentView.elementId}} {{/view}}") + }); + aView.appendTo('body'); + ``` + Will result in HTML structure: -
-
- my parent: ember1 -
-
+ ``` html +
+
+ my parent: ember1 +
+
+ ``` ### Setting CSS id and class attributes The HTML `id` attribute can be set on the `{{view}}`'s resulting element with the `id` option. This option will _not_ be passed to `Ember.View.create`. - + ``` handlebars + + ``` Results in the following HTML structure: -
- - hello. - -
+ ``` html +
+ + hello. + +
+ ``` The HTML `class` attribute can be set on the `{{view}}`'s resulting element with the `class` or `classNameBindings` options. The `class` option @@ -18950,50 +20092,61 @@ EmberHandlebars.ViewHelper = Ember.Object.create({ `Ember.View.create`. `classNameBindings` will be passed to `create` and use `Ember.View`'s class name binding functionality: - + ``` handlebars + + ``` Results in the following HTML structure: -
- - hello. - -
+ ``` html +
+ + hello. + +
+ ``` ### Supplying a different view class + `{{view}}` can take an optional first argument before its supplied options to specify a path to a custom view class. - + ``` handlebars + + ``` The first argument can also be a relative path. Ember will search for the view class starting at the `Ember.View` of the template where `{{view}}` was used as the root object: - MyApp = Ember.Application.create({}) - MyApp.OuterView = Ember.View.extend({ - innerViewClass: Ember.View.extend({ - classNames: ['a-custom-view-class-as-property'] - }), - template: Ember.Handlebars.compile('{{#view "innerViewClass"}} hi {{/view}}') - }) + ``` javascript + MyApp = Ember.Application.create({}); + MyApp.OuterView = Ember.View.extend({ + innerViewClass: Ember.View.extend({ + classNames: ['a-custom-view-class-as-property'] + }), + template: Ember.Handlebars.compile('{{#view "innerViewClass"}} hi {{/view}}') + }); - MyApp.OuterView.create().appendTo('body') + MyApp.OuterView.create().appendTo('body'); + ``` -Will result in the following HTML: + Will result in the following HTML: -
-
- hi -
-
+ ``` html +
+
+ hi +
+
+ ``` ### Blockless use @@ -19001,26 +20154,31 @@ Will result in the following HTML: or provide a `templateName` option to `{{view}}` it can be used without supplying a block. Attempts to use both a `templateName` option and supply a block will throw an error. - + ``` handlebars + + ``` ### viewName property You can supply a `viewName` option to `{{view}}`. The `Ember.View` instance will be referenced as a property of its parent view by this name. - aView = Ember.View.create({ - template: Ember.Handlebars.compile('{{#view viewName="aChildByName"}} hi {{/view}}') - }) + ``` javascript + aView = Ember.View.create({ + template: Ember.Handlebars.compile('{{#view viewName="aChildByName"}} hi {{/view}}') + }); - aView.appendTo('body') - aView.get('aChildByName') // the instance of Ember.View created by {{view}} helper + aView.appendTo('body'); + aView.get('aChildByName') // the instance of Ember.View created by {{view}} helper + ``` - @name Handlebars.helpers.view + @method view + @for Ember.Handlebars.helpers @param {String} path @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ EmberHandlebars.registerHelper('view', function(path, options) { Ember.assert("The view helper only takes a single argument", arguments.length <= 2); @@ -19040,14 +20198,14 @@ EmberHandlebars.registerHelper('view', function(path, options) { (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Handlebars */ // TODO: Don't require all of this module +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, getPath = Ember.Handlebars.getPath, fmt = Ember.String.fmt; /** @@ -19064,28 +20222,34 @@ var get = Ember.get, getPath = Ember.Handlebars.getPath, fmt = Ember.String.fmt; Given an empty `` the following template: - + ``` handlebars + + ``` And the following application code - App = Ember.Application.create() - App.items = [ - Ember.Object.create({name: 'Dave'}), - Ember.Object.create({name: 'Mary'}), - Ember.Object.create({name: 'Sara'}) - ] + ``` javascript + App = Ember.Application.create() + App.items = [ + Ember.Object.create({name: 'Dave'}), + Ember.Object.create({name: 'Mary'}), + Ember.Object.create({name: 'Sara'}) + ] + ``` Will result in the HTML structure below -
-
Hi Dave
-
Hi Mary
-
Hi Sara
-
+ ``` html +
+
Hi Dave
+
Hi Mary
+
Hi Sara
+
+ ``` ### Blockless Use If you provide an `itemViewClass` option that has its own `template` you can omit @@ -19093,68 +20257,83 @@ var get = Ember.get, getPath = Ember.Handlebars.getPath, fmt = Ember.String.fmt; The following template: - + ``` handlebars + + ``` And application code - App = Ember.Application.create() - App.items = [ - Ember.Object.create({name: 'Dave'}), - Ember.Object.create({name: 'Mary'}), - Ember.Object.create({name: 'Sara'}) - ] + ``` javascript + App = Ember.Application.create(); + App.items = [ + Ember.Object.create({name: 'Dave'}), + Ember.Object.create({name: 'Mary'}), + Ember.Object.create({name: 'Sara'}) + ]; - App.AnItemView = Ember.View.extend({ - template: Ember.Handlebars.compile("Greetings {{content.name}}") - }) + App.AnItemView = Ember.View.extend({ + template: Ember.Handlebars.compile("Greetings {{view.content.name}}") + }); + ``` Will result in the HTML structure below -
-
Greetings Dave
-
Greetings Mary
-
Greetings Sara
-
+ ``` html +
+
Greetings Dave
+
Greetings Mary
+
Greetings Sara
+
+ ``` ### Specifying a CollectionView subclass + By default the `{{collection}}` helper will create an instance of `Ember.CollectionView`. You can supply a `Ember.CollectionView` subclass to the helper by passing it as the first argument: - + ``` handlebars + + ``` ### Forwarded `item.*`-named Options + As with the `{{view}}`, helper options passed to the `{{collection}}` will be set on the resulting `Ember.CollectionView` as properties. Additionally, options prefixed with `item` will be applied to the views rendered for each item (note the camelcasing): - + ``` handlebars + + ``` Will result in the following HTML structure: -
-

Howdy Dave

-

Howdy Mary

-

Howdy Sara

-
+ ``` html +
+

Howdy Dave

+

Howdy Mary

+

Howdy Sara

+
+ ``` - @name Handlebars.helpers.collection + @method collection + @for Ember.Handlebars.helpers @param {String} path @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ Ember.Handlebars.registerHelper('collection', function(path, options) { // If no path is provided, treat path param as options. @@ -19234,30 +20413,31 @@ Ember.Handlebars.registerHelper('collection', function(path, options) { }); - - })(); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Handlebars */ +/** +@module ember +@submodule ember-handlebars +*/ + var getPath = Ember.Handlebars.getPath; /** `unbound` allows you to output a property without binding. *Important:* The output will not be updated if the property changes. Use with caution. -
{{unbound somePropertyThatDoesntChange}}
+ ``` handlebars +
{{unbound somePropertyThatDoesntChange}}
+ ``` - @name Handlebars.helpers.unbound + @method unbound + @for Ember.Handlebars.helpers @param {String} property - @returns {String} HTML string + @return {String} HTML string */ Ember.Handlebars.registerHelper('unbound', function(property, fn) { var context = (fn.contexts && fn.contexts[0]) || this; @@ -19269,22 +20449,24 @@ Ember.Handlebars.registerHelper('unbound', function(property, fn) { (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - /*jshint debug:true*/ +/** +@module ember +@submodule ember-handlebars +*/ + var getPath = Ember.Handlebars.getPath, normalizePath = Ember.Handlebars.normalizePath; /** `log` allows you to output the value of a value in the current rendering context. - {{log myVariable}} + ``` handlebars + {{log myVariable}} + ``` - @name Handlebars.helpers.log + @method log + @for Ember.Handlebars.helpers @param {String} property */ Ember.Handlebars.registerHelper('log', function(property, options) { @@ -19300,9 +20482,12 @@ Ember.Handlebars.registerHelper('log', function(property, options) { The `debugger` helper executes the `debugger` statement in the current context. - {{debugger}} + ``` handlebars + {{debugger}} + ``` - @name Handlebars.helpers.debugger + @method debugger + @for Ember.Handlebars.helpers @param {String} property */ Ember.Handlebars.registerHelper('debugger', function() { @@ -19314,6 +20499,11 @@ Ember.Handlebars.registerHelper('debugger', function() { (function() { +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; Ember.Handlebars.EachView = Ember.CollectionView.extend(Ember._Metamorph, { @@ -19346,6 +20536,90 @@ Ember.Handlebars.EachView = Ember.CollectionView.extend(Ember._Metamorph, { } }); +/** + The `{{#each}}` helper loops over elements in a collection, rendering its block once for each item: + + ``` javascript + Developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}]; + ``` + + ``` handlebars + {{#each Developers}} + {{name}} + {{/each}} + ``` + + `{{each}}` supports an alternative syntax with element naming: + + ``` handlebars + {{#each person in Developers}} + {{person.name}} + {{/each}} + ``` + + When looping over objects that do not have properties, `{{this}}` can be used to render the object: + + ``` javascript + DeveloperNames = ['Yehuda', 'Tom', 'Paul'] + ``` + + ``` handlebars + {{#each DeveloperNames}} + {{this}} + {{/each}} + ``` + + ### Blockless Use + + If you provide an `itemViewClass` option that has its own `template` you can omit + the block in a similar way to how it can be done with the collection helper. + + The following template: + + ``` handlebars + + ``` + + And application code + + ``` javascript + App = Ember.Application.create({ + MyView: Ember.View.extend({ + items: [ + Ember.Object.create({name: 'Dave'}), + Ember.Object.create({name: 'Mary'}), + Ember.Object.create({name: 'Sara'}) + ] + }) + }); + + App.AnItemView = Ember.View.extend({ + template: Ember.Handlebars.compile("Greetings {{name}}") + }); + + App.initialize(); + ``` + + Will result in the HTML structure below + + ``` html +
+
Greetings Dave
+
Greetings Mary
+
Greetings Sara
+
+ ``` + + + @method each + @for Ember.Handlebars.helpers + @param [name] {String} name for item (used with `in`) + @param path {String} path +*/ Ember.Handlebars.registerHelper('each', function(path, options) { if (arguments.length === 4) { Ember.assert("If you pass more than one argument to the each helper, it must be in the form #each foo in bar", arguments[1] === "in"); @@ -19361,8 +20635,6 @@ Ember.Handlebars.registerHelper('each', function(path, options) { options.hash.eachHelper = 'each'; } - Ember.assert("You must pass a block to the each helper", options.fn && options.fn !== Handlebars.VM.noop); - options.hash.contentBinding = path; // Set up emptyView as a metamorph with no tag //options.hash.emptyViewClass = Ember._MetamorphView; @@ -19375,21 +20647,28 @@ Ember.Handlebars.registerHelper('each', function(path, options) { (function() { +/** +@module ember +@submodule ember-handlebars +*/ + /** `template` allows you to render a template from inside another template. This allows you to re-use the same template in multiple places. For example: - + ``` handlebars + - + + ``` This helper looks for templates in the global Ember.TEMPLATES hash. If you add <script> tags to your page with the `data-template-name` attribute set, @@ -19397,9 +20676,12 @@ Ember.Handlebars.registerHelper('each', function(path, options) { You can also manually register templates by adding them to the hash: - Ember.TEMPLATES["my_cool_template"] = Ember.Handlebars.compile('{{user}}'); + ``` javascript + Ember.TEMPLATES["my_cool_template"] = Ember.Handlebars.compile('{{user}}'); + ``` - @name Handlebars.helpers.template + @method template + @for Ember.Handlebars.helpers @param {String} templateName the template to render */ @@ -19416,6 +20698,11 @@ Ember.Handlebars.registerHelper('template', function(name, options) { (function() { +/** +@module ember +@submodule ember-handlebars +*/ + var EmberHandlebars = Ember.Handlebars, getPath = EmberHandlebars.getPath, get = Ember.get, @@ -19474,36 +20761,42 @@ ActionHelper.registerAction = function(actionName, options) { /** The `{{action}}` helper registers an HTML element within a template for DOM event handling and forwards that interaction to the Application's router, - the template's `Ember.View` instance, or supplied `target` option (see 'Specifiying a Target'). - + the template's `Ember.View` instance, or supplied `target` option (see 'Specifying a Target'). + User interaction with that element will invoke the supplied action name on the appropriate target. Given the following Handlebars template on the page - + ``` handlebars + + ``` And application code - AView = Ember.View.extend({ - templateName; 'a-template', - anActionName: function(event){} - }); + ``` javascript + AView = Ember.View.extend({ + templateName; 'a-template', + anActionName: function(event){} + }); - aView = AView.create(); - aView.appendTo('body'); + aView = AView.create(); + aView.appendTo('body'); + ``` Will results in the following rendered HTML -
-
- click me -
-
+ ``` html +
+
+ click me +
+
+ ``` Clicking "click me" will trigger the `anActionName` method of the `aView` object with a `jQuery.Event` object as its argument. The `jQuery.Event` @@ -19520,17 +20813,19 @@ ActionHelper.registerAction = function(actionName, options) { If you need the default handler to trigger you should either register your own event handler, or use event methods on your view class. See Ember.View 'Responding to Browser Events' for more information. - + ### Specifying DOM event type By default the `{{action}}` helper registers for DOM `click` events. You can supply an `on` option to the helper to specify a different DOM event name: - + ``` handlebars + + ``` See Ember.View 'Responding to Browser Events' for a list of acceptable DOM event names. @@ -19540,32 +20835,34 @@ ActionHelper.registerAction = function(actionName, options) { `Ember.EventDispatcher` instance will be created when a new `Ember.Application` is created. Having an instance of `Ember.Application` will satisfy this requirement. - - + + ### Specifying a Target There are several possible target objects for `{{action}}` helpers: - + In a typical `Ember.Router`-backed Application where views are managed through use of the `{{outlet}}` helper, actions will be forwarded to the current state of the Applications's Router. See Ember.Router 'Responding to User-initiated Events' for more information. - - If you manaully set the `target` property on the controller of a template's + + If you manually set the `target` property on the controller of a template's `Ember.View` instance, the specifed `controller.target` will become the target for any actions. Likely custom values for a controller's `target` are the controller itself or a StateManager other than the Application's Router. - + If the templates's view lacks a controller property the view itself is the target. - + Finally, a `target` option can be provided to the helper to change which object will receive the method call. This option must be a string representing a path to an object: - + ``` handlebars + + ``` Clicking "click me" in the rendered HTML of the above template will trigger the `anActionName` method of the object at `MyApplication.someObject`. @@ -19575,11 +20872,13 @@ ActionHelper.registerAction = function(actionName, options) { A path relative to the template's `Ember.View` instance can also be used as a target: - + ``` handlebars + + ``` Clicking "click me" in the rendered HTML of the above template will trigger the `anActionName` method of the view's parent view. @@ -19592,41 +20891,48 @@ ActionHelper.registerAction = function(actionName, options) { If an action's target does not implement a method that matches the supplied action name an error will be thrown. - + ``` handlebars + + ``` With the following application code - AView = Ember.View.extend({ - templateName; 'a-template', - // note: no method 'aMethodNameThatIsMissing' - anActionName: function(event){} - }); + ``` javascript + AView = Ember.View.extend({ + templateName; 'a-template', + // note: no method 'aMethodNameThatIsMissing' + anActionName: function(event){} + }); - aView = AView.create(); - aView.appendTo('body'); + aView = AView.create(); + aView.appendTo('body'); + ``` Will throw `Uncaught TypeError: Cannot call method 'call' of undefined` when "click me" is clicked. - + ### Specifying a context By default the `{{action}}` helper passes the current Handlebars context along in the `jQuery.Event` object. You may specify an alternate object to pass as the context by providing a property path: - + ``` handlebars + + ``` - @name Handlebars.helpers.action + @method action + @for Ember.Handlebars.helpers @param {String} actionName @param {Object...} contexts @param {Hash} options @@ -19680,6 +20986,11 @@ EmberHandlebars.registerHelper('action', function(actionName) { (function() { +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; /** @@ -19690,42 +21001,49 @@ var get = Ember.get, set = Ember.set; An empty `` and the following application code: - AView = Ember.View.extend({ - classNames: ['a-view-with-layout'], - layout: Ember.Handlebars.compile('
{{ yield }}
'), - template: Ember.Handlebars.compile('I am wrapped') - }) + ``` javascript + AView = Ember.View.extend({ + classNames: ['a-view-with-layout'], + layout: Ember.Handlebars.compile('
{{ yield }}
'), + template: Ember.Handlebars.compile('I am wrapped') + }); - aView = AView.create() - aView.appendTo('body') + aView = AView.create(); + aView.appendTo('body'); + ``` Will result in the following HTML output: - -
-
- I am wrapped -
-
- + ``` html + +
+
+ I am wrapped +
+
+ + ``` The yield helper cannot be used outside of a template assigned to an `Ember.View`'s `layout` property and will throw an error if attempted. - BView = Ember.View.extend({ - classNames: ['a-view-with-layout'], - template: Ember.Handlebars.compile('{{yield}}') - }) + ``` javascript + BView = Ember.View.extend({ + classNames: ['a-view-with-layout'], + template: Ember.Handlebars.compile('{{yield}}') + }); - bView = BView.create() - bView.appendTo('body') + bView = BView.create(); + bView.appendTo('body'); - // throws - // Uncaught Error: assertion failed: You called yield in a template that was not a layout + // throws + // Uncaught Error: assertion failed: You called yield in a template that was not a layout + ``` - @name Handlebars.helpers.yield + @method yield + @for Ember.Handlebars.helpers @param {Hash} options - @returns {String} HTML string + @return {String} HTML string */ Ember.Handlebars.registerHelper('yield', function(options) { var view = options.data.view, template; @@ -19746,30 +21064,46 @@ Ember.Handlebars.registerHelper('yield', function(options) { (function() { +/** +@module ember +@submodule ember-handlebars +*/ + +Ember.Handlebars.OutletView = Ember.ContainerView.extend(Ember._Metamorph); + /** The `outlet` helper allows you to specify that the current view's controller will fill in the view for a given area. - {{outlet}} + ``` handlebars + {{outlet}} + ``` By default, when the the current controller's `view` property changes, the outlet will replace its current view with the new view. - controller.set('view', someView); + ``` javascript + controller.set('view', someView); + ``` You can also specify a particular name, other than view: - {{outlet masterView}} - {{outlet detailView}} + ``` handlebars + {{outlet masterView}} + {{outlet detailView}} + ``` Then, you can control several outlets from a single controller: - controller.set('masterView', postsView); - controller.set('detailView', postView); + ``` javascript + controller.set('masterView', postsView); + controller.set('detailView', postView); + ``` - @name Handlebars.helpers.outlet + @method outlet + @for Ember.Handlebars.helpers @param {String} property the property on the controller that holds the view for this outlet */ @@ -19781,7 +21115,7 @@ Ember.Handlebars.registerHelper('outlet', function(property, options) { options.hash.currentViewBinding = "controller." + property; - return Ember.Handlebars.helpers.view.call(this, Ember.ContainerView, options); + return Ember.Handlebars.helpers.view.call(this, Ember.Handlebars.OutletView, options); }); })(); @@ -19789,51 +21123,43 @@ Ember.Handlebars.registerHelper('outlet', function(property, options) { (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-handlebars +*/ + var set = Ember.set, get = Ember.get; /** - @class + The `Ember.Checkbox` view class renders a checkbox [input](https://developer.mozilla.org/en/HTML/Element/Input) + element. It allows for binding an Ember property (`checked`) to the status of the checkbox. - Creates an HTML input of type 'checkbox' with HTML related properties - applied directly to the input. + Example: - {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}} - - + ``` handlebars + {{view Ember.Checkbox checkedBinding="receiveEmail"}} + ``` You can add a `label` tag yourself in the template where the Ember.Checkbox is being used. - + ``` html + + ``` The `checked` attribute of an Ember.Checkbox object should always be set @@ -19845,6 +21171,8 @@ var set = Ember.set, get = Ember.get; Because HTML `input` elements are self closing `layout` and `layoutName` properties will not be applied. See `Ember.View`'s layout section for more information. + @class Checkbox + @namespace Ember @extends Ember.View */ Ember.Checkbox = Ember.View.extend({ @@ -19863,9 +21191,6 @@ Ember.Checkbox = Ember.View.extend({ this.on("change", this, this._updateElementValue); }, - /** - @private - */ _updateElementValue: function() { set(this, 'checked', this.$().prop('checked')); } @@ -19876,17 +21201,22 @@ Ember.Checkbox = Ember.View.extend({ (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; -/** @class */ -Ember.TextSupport = Ember.Mixin.create( -/** @scope Ember.TextSupport.prototype */ { +/** + Shared mixin used by Ember.TextField and Ember.TextArea. + @class TextSupport + @namespace Ember + @extends Ember.Mixin + @private +*/ +Ember.TextSupport = Ember.Mixin.create({ value: "", attributeBindings: ['placeholder', 'disabled', 'maxlength', 'tabindex'], @@ -19897,7 +21227,6 @@ Ember.TextSupport = Ember.Mixin.create( insertNewline: Ember.K, cancel: Ember.K, - /** @private */ init: function() { this._super(); this.on("focusOut", this, this._elementValueDidChange); @@ -19905,9 +21234,6 @@ Ember.TextSupport = Ember.Mixin.create( this.on("keyUp", this, this.interpretKeyEvents); }, - /** - @private - */ interpretKeyEvents: function(event) { var map = Ember.TextSupport.KEY_EVENTS; var method = map[event.keyCode]; @@ -19932,16 +21258,14 @@ Ember.TextSupport.KEY_EVENTS = { (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; /** - @class - The `Ember.TextField` view class renders a text [input](https://developer.mozilla.org/en/HTML/Element/Input) element. It allows for binding Ember properties to the text field contents (`value`), @@ -19949,14 +21273,18 @@ var get = Ember.get, set = Ember.set; Example: - {{view Ember.TextField valueBinding="firstName"}} + ``` handlebars + {{view Ember.TextField valueBinding="firstName"}} + ``` ## Layout and LayoutName properties Because HTML `input` elements are self closing `layout` and `layoutName` properties will not be applied. See `Ember.View`'s layout section for more information. + @class TextField + @namespace Ember @extends Ember.View - @extends Ember.TextSupport + @uses Ember.TextSupport */ Ember.TextField = Ember.View.extend(Ember.TextSupport, /** @scope Ember.TextField.prototype */ { @@ -19969,6 +21297,7 @@ Ember.TextField = Ember.View.extend(Ember.TextSupport, The value attribute of the input element. As the user inputs text, this property is updated live. + @property value @type String @default "" */ @@ -19977,6 +21306,7 @@ Ember.TextField = Ember.View.extend(Ember.TextSupport, /** The type attribute of the input element. + @property type @type String @default "text" */ @@ -19985,6 +21315,7 @@ Ember.TextField = Ember.View.extend(Ember.TextSupport, /** The size of the text field in characters. + @property size @type String @default null */ @@ -19996,13 +21327,20 @@ Ember.TextField = Ember.View.extend(Ember.TextSupport, (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; +/** + @class Button + @namespace Ember + @extends Ember.View + @uses Ember.TargetActionSupport + @deprecated +*/ Ember.Button = Ember.View.extend(Ember.TargetActionSupport, { classNames: ['ember-button'], classNameBindings: ['isActive'], @@ -20013,9 +21351,13 @@ Ember.Button = Ember.View.extend(Ember.TargetActionSupport, { attributeBindings: ['type', 'disabled', 'href', 'tabindex'], - /** @private + /** + @private + Overrides TargetActionSupport's targetObject computed property to use Handlebars-specific path resolution. + + @property targetObject */ targetObject: Ember.computed(function() { var target = get(this, 'target'), @@ -20115,16 +21457,14 @@ Ember.Button = Ember.View.extend(Ember.TargetActionSupport, { (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; /** - @class - The `Ember.TextArea` view class renders a [textarea](https://developer.mozilla.org/en/HTML/Element/textarea) element. It allows for binding Ember properties to the text area contents (`value`), @@ -20132,15 +21472,15 @@ var get = Ember.get, set = Ember.set; ## Layout and LayoutName properties - Because HTML `textarea` elements do not contain inner HTML the `layout` and `layoutName` + Because HTML `textarea` elements do not contain inner HTML the `layout` and `layoutName` properties will not be applied. See `Ember.View`'s layout section for more information. + @class TextArea + @namespace Ember @extends Ember.View - @extends Ember.TextSupport + @uses Ember.TextSupport */ -Ember.TextArea = Ember.View.extend(Ember.TextSupport, -/** @scope Ember.TextArea.prototype */ { - +Ember.TextArea = Ember.View.extend(Ember.TextSupport, { classNames: ['ember-text-area'], tagName: "textarea", @@ -20157,7 +21497,6 @@ Ember.TextArea = Ember.View.extend(Ember.TextSupport, } }, 'value'), - /** @private */ init: function() { this._super(); this.on("didInsertElement", this, this._updateElementValue); @@ -20170,6 +21509,17 @@ Ember.TextArea = Ember.View.extend(Ember.TextSupport, (function() { +/** +@module ember +@submodule ember-handlebars +*/ + +/** +@class TabContainerView +@namespace Ember +@deprecated +@extends Ember.View +*/ Ember.TabContainerView = Ember.View.extend({ init: function() { Ember.deprecate("Ember.TabContainerView is deprecated and will be removed from future releases."); @@ -20182,8 +21532,19 @@ Ember.TabContainerView = Ember.View.extend({ (function() { +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get; +/** + @class TabPaneView + @namespace Ember + @extends Ember.View + @deprecated +*/ Ember.TabPaneView = Ember.View.extend({ tabsContainer: Ember.computed(function() { return this.nearestInstanceOf(Ember.TabContainerView); @@ -20204,8 +21565,19 @@ Ember.TabPaneView = Ember.View.extend({ (function() { +/** +@module ember +@submodule ember-handlebars +*/ + var get = Ember.get, setPath = Ember.setPath; +/** +@class TabView +@namespace Ember +@extends Ember.View +@deprecated +*/ Ember.TabView = Ember.View.extend({ tabsContainer: Ember.computed(function() { return this.nearestInstanceOf(Ember.TabContainerView); @@ -20234,95 +21606,259 @@ Ember.TabView = Ember.View.extend({ (function() { /*jshint eqeqeq:false */ +/** +@module ember +@submodule ember-handlebars +*/ + var set = Ember.set, get = Ember.get; var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.indexesOf; /** - @class - The Ember.Select view class renders a [select](https://developer.mozilla.org/en/HTML/Element/select) HTML element, - allowing the user to choose from a list of options. The selected option(s) - are updated live in the `selection` property, while the corresponding value - is updated in the `value` property. + allowing the user to choose from a list of options. - ### Using Strings - The simplest version of an Ember.Select takes an array of strings for the options - of a select box and a valueBinding to set the value. + The text and `value` property of each ` - - - + The `optionValuePath` option is used to specify the path on each object to + the desired property for the `value` attribute. The `optionLabelPath` + specifies the path on each object to the desired property for the + element's text. Both paths must reference each object itself as 'content': - Selecting Yehuda here will set `App.controller.selectedPerson` to - the Yehuda object. + ``` javascript + App.Programmers = [ + Ember.Object.create({firstName: "Yehuda", id: 1}), + Ember.Object.create({firstName: "Tom", id: 2}) + ]; + ``` - Example using valueBinding: + ``` handlebars + {{view Ember.Select + contentBinding="App.Programmers" + optionValuePath="content.id" + optionLabelPath="content.firstName"}} + ``` - {{view Ember.Select - contentBinding="App.controller.content" - optionLabelPath="content.firstName" - optionValuePath="content.id" - valueBinding="App.controller.selectedPersonId" - prompt="Please Select"}} + Would result in the following HTML: - Selecting Yehuda in this case will set `App.controller.selectedPersonId` to 1. + ``` html + + ``` + + The `value` attribute of the selected `