Yoji SHIDARA
null+****@clear*****
Wed Sep 19 12:57:38 JST 2012
Yoji SHIDARA 2012-09-19 12:57:38 +0900 (Wed, 19 Sep 2012) New Revision: 259292a6cf1963dd8b7ff1e23ae97b9ff4b69466 https://github.com/groonga/gcs/commit/259292a6cf1963dd8b7ff1e23ae97b9ff4b69466 Log: Upgrade ember.js to the latest version Modified files: public/js/ember-latest.js Modified: public/js/ember-latest.js (+4166 -2586) =================================================================== --- public/js/ember-latest.js 2012-09-19 12:15:20 +0900 (1e3c3b0) +++ public/js/ember-latest.js 2012-09-19 12:57:38 +0900 (0d11f8f) @@ -1,10 +1,21 @@ -// Version: v1.0.pre-68-ge60e818 -// Last commit: e60e818 (2012-08-24 14:59:34 -0700) +// Version: v1.0.pre-149-g117655b +// Last commit: 117655b (2012-09-18 10:22:34 -0700) (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-68-ge60e818 -// Last commit: e60e818 (2012-08-24 14:59:34 -0700) +// Version: v1.0.pre-149-g117655b +// Last commit: 117655b (2012-09-18 10:22:34 -0700) (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 = {}; -} - /** - @namespace - @name Ember - @version 1.0.pre + �� module ember + �� submodule ember-metal +*/ +/** 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. -*/ -Ember.CP_DEFAULT_CACHEABLE = (Ember.ENV.CP_DEFAULT_CACHEABLE !== false); -/** - @static + @property CP_DEFAULT_CACHEABLE @type Boolean @default true - @constant +*/ +Ember.CP_DEFAULT_CACHEABLE = (Ember.ENV.CP_DEFAULT_CACHEABLE !== false); +/** 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}} - - // After: - {{#each App.photosController}} - Photo Title: {{title}} - {{#view App.InfoView}} - {{date}} - {{cameraType}} - {{view.otherViewProperty}} - {{/view}} - {{/each}} + Before: + + ``` 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; @@ -603,23 +625,27 @@ 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 {Object} obj The object to retrieve meta for - @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 {Boolean} [writable=true] Pass false if you do not intend to modify + the meta hash, allowing the method to avoid making an unnecessary copy. - @returns {Hash} + @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,19 @@ 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; @@ -1137,6 +1205,11 @@ OrderedSet.prototype = { return guid in presenceSet; }, + /** + @method forEach + @param {Function} function + @param target + */ forEach: function(fn, self) { // allow mutation during iteration var list = this.list.slice(); @@ -1146,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(); @@ -1175,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(); }; @@ -1191,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 */ @@ -1205,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 */ @@ -1220,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 @@ -1244,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, @@ -1260,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. @@ -1274,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); @@ -1294,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); @@ -1306,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 @@ -1317,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[\.\*]/; @@ -1339,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 === '') { @@ -1376,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)); @@ -1432,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), @@ -1459,7 +1624,6 @@ function normalizeTuple(target, path) { return [ target, path ]; } -/** @private */ function getPath(root, path) { var hasThis, parts, tuple, idx, len; @@ -1487,7 +1651,6 @@ function getPath(root, path) { return root; } -/** @private */ function setPath(root, path, value, tolerant) { var keyName; @@ -1523,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); @@ -1543,75 +1704,24 @@ Ember.getWithDefault = function(root, key, defaultValue) { }; -/** - @function +Ember.get = get; +Ember.getPath = Ember.deprecateFunc('getPath is deprecated since get now supports paths', Ember.get); - 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. +Ember.set = set; +Ember.setPath = Ember.deprecateFunc('setPath is deprecated since set now supports paths', Ember.set); - 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.) +/** + Error-tolerant form of Ember.set. Will not blow up if any part of the + chain is undefined, null, or destroyed. - 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. + This is primarily used when syncing bindings, which may try to update after + an object has been destroyed. - 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); - -/** - Error-tolerant form of Ember.set. Will not blow up if any part of the - chain is undefined, null, or destroyed. - - 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); @@ -1622,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); @@ -1642,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, @@ -1661,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() {}; @@ -1708,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); @@ -1796,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; @@ -1808,7 +1917,6 @@ var guidFor = Ember.guidFor; var deferred = 0; var array_Slice = [].slice; -/** @private */ var ObserverSet = function () { this.targetSet = {}; }; @@ -1829,7 +1937,6 @@ ObserverSet.prototype.clear = function () { this.targetSet = {}; }; -/** @private */ var DeferredEventQueue = function() { this.targetSet = {}; this.queue = []; @@ -1864,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); @@ -1873,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(); @@ -1898,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(); @@ -1912,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(){ @@ -1923,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); @@ -1960,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); }; @@ -1981,25 +2119,29 @@ Ember._suspendObservers = function(obj, paths, target, method, callback) { return Ember._suspendListeners(obj, events, target, method, callback); }; -/** @private */ 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; } @@ -2022,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 @@ -2044,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); } @@ -2061,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); @@ -2074,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); } } @@ -2083,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; } @@ -2094,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; } @@ -2108,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); @@ -2122,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), @@ -2137,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 @@ -2149,7 +2284,6 @@ function flushPendingChains() { 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; } @@ -2157,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; @@ -2385,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) { @@ -2396,7 +2528,6 @@ function chainsFor(obj) { return ret; } -/** @private */ function notifyChains(obj, m, keyName, methodName, arg) { var nodes = m.chainWatchers; @@ -2415,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'); } @@ -2437,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... @@ -2486,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; } @@ -2530,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; @@ -2570,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), @@ -2605,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), @@ -2640,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; @@ -2680,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); @@ -2710,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. */ @@ -2731,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... @@ -2752,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. @@ -2772,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. @@ -2796,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; /** @@ -2832,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; @@ -2853,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); @@ -2875,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 = []; @@ -2908,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) { @@ -2924,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]; @@ -2943,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 @@ -2958,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) { @@ -2975,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]) { @@ -3013,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); @@ -3026,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 @@ -3036,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; @@ -3064,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; @@ -3077,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); @@ -3090,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); @@ -3101,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. @@ -3137,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; } @@ -3156,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; } @@ -3182,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 @@ -3197,9 +3329,14 @@ function invokeAction(action, params, sender) { } /** - The sendEvent arguments > 2 are passed to an event listener. - - @memberOf Ember + Add an event listener + + @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); @@ -3221,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); @@ -3242,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; @@ -3267,6 +3426,24 @@ function suspendListener(obj, eventName, target, method, callback) { } } +/** + @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; @@ -3298,8 +3475,15 @@ function suspendListeners(obj, eventNames, target, method, callback) { } } -// returns a list of currently watched events -/** @memberOf Ember */ +/** + @private + + Return a list of currently watched events + + @method watchedEvents + @for Ember + @param obj +*/ function watchedEvents(obj) { var listeners = meta(obj, false).listeners, ret = []; @@ -3313,7 +3497,14 @@ function watchedEvents(obj) { return ret; } -/** @memberOf Ember */ +/** + @method sendEvent + @for Ember + @param obj + @param {String} eventName + @param {Array} params + @return true +*/ function sendEvent(obj, eventName, params) { // first give object a chance to handle it if (obj !== Ember && 'function' === typeof obj.sendEvent) { @@ -3324,7 +3515,14 @@ function sendEvent(obj, eventName, params) { return true; } -/** @memberOf Ember */ +/** + @private + @method deferEvent + @for Ember + @param obj + @param {String} eventName + @param {Array} params +*/ function deferEvent(obj, eventName, params) { var actions = []; iterateSet(obj, eventName, function (action) { @@ -3344,7 +3542,13 @@ function deferEvent(obj, eventName, params) { }; } -/** @memberOf Ember */ +/** + @private + @method hasListeners + @for Ember + @param obj + @param {String} eventName +*/ function hasListeners(obj, eventName) { if (iterateSet(obj, eventName, function() { return true; })) { return true; @@ -3357,7 +3561,13 @@ function hasListeners(obj, eventName) { return false; } -/** @memberOf Ember */ +/** + @private + @method listenersFor + @for Ember + @param obj + @param {String} eventName +*/ function listenersFor(obj, eventName) { var ret = []; iterateSet(obj, eventName, function (action) { @@ -3381,17 +3591,15 @@ Ember.deferEvent = deferEvent; (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) -// ========================================================================== // Ember.Logger // Ember.watch.flushPending // Ember.beginPropertyChanges, Ember.endPropertyChanges // Ember.guidFor +/** + �� module ember-metal +*/ + // .......................................................... // HELPERS // @@ -3401,7 +3609,6 @@ var slice = [].slice, // invokes passed params - normalizing so you can pass target/func, // target/string or just func -/** @private */ function invoke(target, method, args, ignore) { if (method === undefined) { @@ -3414,19 +3621,10 @@ function invoke(target, method, args, ignore) { args = args.length > 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); } @@ -3436,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; }, @@ -3455,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 = {}; } @@ -3466,6 +3683,10 @@ RunLoop.prototype = { return this; }, + /** + @method flush + @param {String} queueName + */ flush: function(queueName) { var queueNames, idx, len, queue, log; @@ -3557,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 @@ -3577,19 +3793,16 @@ Ember.RunLoop = 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; @@ -3602,7 +3815,6 @@ Ember.run = function(target, method) { return ret; }; -/** @private */ var run = Ember.run; @@ -3615,8 +3827,8 @@ var run = Ember.run; // 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); @@ -3631,7 +3843,8 @@ Ember.run.begin = function() { // 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); @@ -3649,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'] */ @@ -3676,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(); @@ -3699,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); @@ -3735,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) { @@ -3763,7 +3973,8 @@ Ember.run.autorun = function() { Ember.run.sync(); - @returns {void} + @method sync + @return {void} */ Ember.run.sync = function() { run.autorun(); @@ -3777,7 +3988,6 @@ Ember.run.sync = function() { var timers = {}; // active timers... var scheduledLater; -/** @private */ function invokeLaterTimers() { scheduledLater = null; var now = (+ new Date()), earliest = -1; @@ -3812,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; @@ -3849,10 +4059,9 @@ 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]; } @@ -3900,29 +4109,27 @@ function scheduleOnce(queue, target, method, args) { // 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) { - return scheduleOnce('actions', target, method, slice.call(arguments)); + return scheduleOnce('actions', target, method, slice.call(arguments, 2)); }; -Ember.run.scheduleOnce = function(queue, target, method) { - return scheduleOnce(queue, target, method, slice.call(arguments)); +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) { @@ -3943,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, @@ -3990,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]; @@ -4004,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 */ @@ -4036,7 +4240,6 @@ var get = Ember.get, isGlobalPath = Ember.isGlobalPath; -/** @private */ function getWithGlobals(obj, path) { return get(isGlobalPath(path) ? window : obj, path); } @@ -4045,7 +4248,6 @@ function getWithGlobals(obj, path) { // BINDING // -/** @private */ var Binding = function(toPath, fromPath) { this._direction = 'fwd'; this._from = fromPath; @@ -4053,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); @@ -4077,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; @@ -4094,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; @@ -4108,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; @@ -4130,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); @@ -4154,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); @@ -4179,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); @@ -4207,7 +4417,6 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { } }, - /** @private */ _sync: function(obj) { var log = Ember.LOG_BINDINGS; @@ -4250,7 +4459,6 @@ Binding.prototype = /** @scope Ember.Binding.prototype */ { }; -/** @private */ function mixinProperties(to, from) { for (var key in from) { if (from.hasOwnProperty(key)) { @@ -4259,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(); @@ -4271,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(); @@ -4280,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); @@ -4299,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. @@ -4398,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); }; @@ -4431,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, @@ -4448,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) { @@ -4460,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) { @@ -4477,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]; @@ -4556,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) { @@ -4568,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; @@ -4582,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; @@ -4611,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; @@ -4716,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); @@ -4723,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, @@ -4747,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) { @@ -4763,6 +4987,11 @@ Mixin.applyPartial = function(obj) { Mixin.finishPartial = finishPartial; +/** + @method create + @static + @param arguments* +*/ Mixin.create = function() { classToString.processed = false; var M = this; @@ -4771,6 +5000,10 @@ Mixin.create = function() { var MixinPrototype = Mixin.prototype; +/** + @method reopen + @param arguments* +*/ MixinPrototype.reopen = function() { var mixin, tmp; @@ -4801,6 +5034,11 @@ MixinPrototype.reopen = function() { return this; }; +/** + @method apply + @param obj + @return applied object +*/ MixinPrototype.apply = function(obj) { return applyMixin(obj, [this], false); }; @@ -4809,7 +5047,6 @@ MixinPrototype.applyPartial = function(obj) { return applyMixin(obj, [this], true); }; -/** @private */ function _detect(curMixin, targetMixin, seen) { var guid = guidFor(curMixin); @@ -4824,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, {}); } @@ -4840,7 +5082,6 @@ MixinPrototype.without = function() { return ret; }; -/** @private */ function _keys(ret, mixin, seen) { if (seen[guidFor(mixin)]) { return; } seen[guidFor(mixin)] = true; @@ -4864,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) { @@ -4888,7 +5128,6 @@ function processNames(paths, root, seen) { paths.length = idx; // cut out last item } -/** @private */ function findNamespaces() { var Namespace = Ember.Namespace, obj, isNamespace; @@ -4917,9 +5156,13 @@ function findNamespaces() { } } +/** + @private + @method identifyNamespaces + @for Ember +*/ Ember.identifyNamespaces = findNamespaces; -/** @private */ superClassString = function(mixin) { var superclass = mixin.superclass; if (superclass) { @@ -4930,7 +5173,6 @@ superClassString = function(mixin) { } }; -/** @private */ classToString = function() { var Namespace = Ember.Namespace, namespace; @@ -4985,11 +5227,16 @@ 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; }; @@ -5010,8 +5257,10 @@ Alias.prototype = new Ember.Descriptor(); paintSample.get('colour'); //=> 'red' paintSample.moniker(); //=> 'Zed' + @method alias + @for Ember @param {String} methodName name of the method or property to alias - @returns {Ember.Descriptor} + @return {Ember.Descriptor} */ Ember.alias = function(methodName) { return new Alias(methodName); @@ -5021,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; @@ -5029,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<l; i++) { var arg = arguments[i]; @@ -5038,6 +5301,13 @@ Ember.immediateObserver = function() { return Ember.observer.apply(this, arguments); }; +/** + @method beforeObserver + @for Ember + @param {Function} func + @param {String} propertyNames* + @return func +*/ Ember.beforeObserver = function(func) { var paths = a_slice.call(arguments, 1); func.__ember_observesBefore__ = paths; @@ -5049,56 +5319,22 @@ Ember.beforeObserver = function(func) { (function() { -// ========================================================================== -// Project: Ember Metal -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== - -})(); - -(function() { /** - * @license - * ========================================================================== - * Ember - * Copyright ©2006-2011, Strobe Inc. and contributors. - * Portions copyright ©2008-2011 Apple Inc. All rights reserved. - * - * Permission is hereby granted, free of charge, to any person obtaining a - * copy of this software and associated documentation files (the "Software"), - * to deal in the Software without restriction, including without limitation - * the rights to use, copy, modify, merge, publish, distribute, sublicense, - * and/or sell copies of the Software, and to permit persons to whom the - * Software is furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - * DEALINGS IN THE SOFTWARE. - * - * For more information about Ember, visit http://www.emberjs.com - * - * ========================================================================== - */ - -})(); +Ember Metal + �� module ember + �� submodule ember-metal +*/ +})(); (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals ENV */ +/** + �� module ember + �� submodule ember-runtime +*/ + var indexOf = Ember.EnumerableUtils.indexOf; // ........................................ @@ -5116,7 +5352,7 @@ var toString = Object.prototype.toString; /** Returns a consistent type for the passed item. - Use this instead of the built-in Ember.typeOf() to get the type of an item. + Use this instead of the built-in `typeof` to get the type of an item. It will return the same result across all browsers and includes a bit more detail. Here is what will be returned: @@ -5151,8 +5387,10 @@ var toString = Object.prototype.toString; // "normal" JavaScript object Ember.typeOf({a: 'b'}); => '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; @@ -5182,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; @@ -5203,8 +5443,10 @@ 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') || (typeof obj === 'object' && Ember.get(obj, 'length') === 0); @@ -5225,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; } @@ -5318,7 +5562,6 @@ Ember.compare = function compare(v, w) { } }; -/** @private */ function _copy(obj, deep, seen, copies) { var ret, loc, key; @@ -5364,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 @@ -5379,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 = []; @@ -5405,19 +5652,18 @@ Ember.inspect = function(obj) { 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', @@ -5437,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; @@ -5457,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); @@ -5478,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); @@ -5497,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 = {}; @@ -5506,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 = { @@ -5523,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. @@ -5556,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; @@ -5581,10 +5833,9 @@ 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+/); }, @@ -5596,10 +5847,9 @@ Ember.String = { '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(); @@ -5613,10 +5863,9 @@ Ember.String = { '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, @@ -5640,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) { @@ -5657,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); @@ -5673,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'). @@ -5689,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, @@ -5706,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); @@ -5762,19 +6035,18 @@ 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) { /** The `property` extension of Javascript's Function prototype is available - when Ember.EXTEND_PROTOTYPES is true, which is the default. + when Ember.EXTEND_PROTOTYPES is true, which is the default. Computed properties allow you to treat a function like a property: @@ -5817,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); @@ -5829,7 +6102,7 @@ if (Ember.EXTEND_PROTOTYPES) { /** The `observes` extension of Javascript's Function prototype is available - when Ember.EXTEND_PROTOTYPES is true, which is the default. + when Ember.EXTEND_PROTOTYPES is true, which is the default. You can observe property changes simply by adding the `observes` call to the end of your method declarations in classes that you write. @@ -5840,8 +6113,11 @@ if (Ember.EXTEND_PROTOTYPES) { // Executes whenever the "value" property changes }.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); @@ -5850,7 +6126,7 @@ if (Ember.EXTEND_PROTOTYPES) { /** The `observesBefore` extension of Javascript's Function prototype is - available when Ember.EXTEND_PROTOTYPES is true, which is the default. + available when Ember.EXTEND_PROTOTYPES is true, which is the default. You can get notified when a property changes is about to happen by by adding the `observesBefore` call to the end of your method @@ -5861,8 +6137,11 @@ if (Ember.EXTEND_PROTOTYPES) { // Executes whenever the "value" property is about to change }.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); @@ -5877,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 @@ -5907,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; @@ -5930,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 @@ -5964,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, /** @@ -5999,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), @@ -6022,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 ; @@ -6045,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'); @@ -6068,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; @@ -6095,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() ; @@ -6118,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); @@ -6131,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) { @@ -6160,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 = []; @@ -6176,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) { @@ -6205,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 = []; @@ -6222,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)); @@ -6250,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') ; @@ -6277,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)); @@ -6308,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) { @@ -6322,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)); @@ -6354,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) { @@ -6368,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)); @@ -6401,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(); } @@ -6423,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 = []; @@ -6445,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 = []; @@ -6459,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); }, @@ -6471,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 @@ -6490,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 = []; @@ -6508,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) { @@ -6521,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', @@ -6536,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', @@ -6553,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() { @@ -6565,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) { @@ -6606,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; @@ -6653,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. @@ -6699,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(), @@ -6731,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. */ @@ -6746,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. */ @@ -6754,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) ; @@ -6781,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; }, @@ -6797,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 = []; @@ -6826,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'); @@ -6856,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'); @@ -6894,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', @@ -6920,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', @@ -6941,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'); @@ -6953,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) { @@ -7041,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); @@ -7054,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 */ @@ -7076,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, @@ -7092,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) @@ -7106,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. @@ -7126,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 */ @@ -7136,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), @@ -7153,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)) { @@ -7172,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. @@ -7239,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 */ @@ -7249,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, @@ -7257,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; @@ -7269,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. @@ -7317,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 */ { @@ -7333,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); @@ -7365,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), @@ -7378,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); @@ -7395,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 // @@ -7414,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. @@ -7423,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 */ { @@ -7437,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(), @@ -7462,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'); @@ -7479,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 */ @@ -7500,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'))) { @@ -7530,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) ; @@ -7544,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); @@ -7560,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') ; @@ -7578,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 ; @@ -7594,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) ; @@ -7608,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); @@ -7620,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() { @@ -7630,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) { @@ -7644,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 ; @@ -7658,27 +7962,24 @@ 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 features of the Ember object model. - + Properties and observers allow one object to observe changes to a property on another object. This is one of the fundamental ways that models, controllers and views communicate with each other in an Ember application. - + Any object that has this mixin applied can be used in observer operations. That includes Ember.Object and most objects you will interact with as you write your Ember application. @@ -7686,16 +7987,16 @@ var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty; Note that you will not generally apply this mixin to classes yourself, but you will use the features provided by this module frequently, so it is important to understand how to use it. - + ## Using get() and set() - + Because of Ember's support for bindings and observers, you will always access properties using the get method, and set properties using the set method. This allows the observing objects to be notified and computed properties to be handled properly. - + More documentation about `get` and `set` are below. - + ## Observing Property Changes You typically observe property changes simply by adding the `observes` @@ -7707,7 +8008,7 @@ var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty; // Executes whenever the "value" property changes }.observes('value') }); - + Although this is the most common way to add an observer, this capability is actually built into the Ember.Object class on top of two methods defined in this mixin: `addObserver` and `removeObserver`. You can use @@ -7720,17 +8021,19 @@ var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty; This will call the `targetAction` method on the `targetObject` to be called whenever the value of the `propertyKey` changes. - - Note that if `propertyKey` is a computed property, the observer will be - called when any of the property dependencies are changed, even if the + + Note that if `propertyKey` is a computed property, the observer will be + called when any of the property dependencies are changed, even if the 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, /** @@ -7739,7 +8042,7 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { This method is usually similar to using object[keyName] or object.keyName, however it supports both computed properties and the unknownProperty handler. - + Because `get` unifies the syntax for accessing all these kinds of properties, it can make many refactorings easier, such as replacing a simple property with a computed property, or vice versa. @@ -7765,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); @@ -7782,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 = {}; @@ -7838,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); @@ -7853,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); @@ -7870,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(); @@ -7887,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(); @@ -7907,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); @@ -7928,20 +8238,22 @@ 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); return this; }, - + /** 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); @@ -7991,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); @@ -8005,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); @@ -8020,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'); @@ -8031,9 +8346,10 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { This method will be called when a client attempts to get the value of a 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; @@ -8043,7 +8359,8 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { This method will be called when a client attempts to set the value of a 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. */ @@ -8054,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"); @@ -8064,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"); @@ -8076,12 +8395,13 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { /** Retrieves the value of a property, or a default value in the case that the property returns undefined. - + 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); @@ -8089,29 +8409,31 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { /** Set the value of a property to the current value plus some amount. - + 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; } set(this, keyName, (get(this, keyName) || 0)+increment); return get(this, keyName); }, - + /** Set the value of a property to the current value minus some amount. - + 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; } @@ -8122,11 +8444,12 @@ Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ { /** Set the value of a boolean property to the opposite of it's current value. - + 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)); @@ -8139,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, @@ -8208,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); }, @@ -8267,23 +8603,16 @@ 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. @@ -8315,7 +8644,6 @@ var undefinedDescriptor = { value: undefined }; -/** @private */ function makeCtor() { // Note: avoid accessing any properties on the object since it makes the @@ -8371,8 +8699,7 @@ function makeCtor() { var CoreObject = makeCtor(); -CoreObject.PrototypeMixin = Mixin.create( -/** @scope Ember.CoreObject.prototype */ { +CoreObject.PrototypeMixin = Mixin.create({ reopen: function() { applyMixin(this, arguments, true); @@ -8381,13 +8708,18 @@ CoreObject.PrototypeMixin = Mixin.create( isInstance: true, - /** @private */ init: function() {}, - /** @field */ + /** + @property isDestroyed + @default false + */ isDestroyed: false, - /** @field */ + /** + @property isDestroying + @default false + */ isDestroying: false, /** @@ -8400,7 +8732,8 @@ CoreObject.PrototypeMixin = 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; } @@ -8415,10 +8748,12 @@ CoreObject.PrototypeMixin = Mixin.create( }, /** + @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() { destroy(this); @@ -8442,8 +8777,7 @@ if (Ember.config.overridePrototypeMixin) { CoreObject.__super__ = null; -var ClassMixin = Mixin.create( -/** @scope Ember.ClassMixin.prototype */ { +var ClassMixin = Mixin.create({ ClassMixin: Ember.required(), @@ -8525,6 +8859,9 @@ var ClassMixin = 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]; @@ -8536,6 +8873,10 @@ var ClassMixin = 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(), @@ -8562,7 +8903,8 @@ CoreObject.ClassMixin = ClassMixin; ClassMixin.apply(CoreObject); /** - @class + @class CoreObject + @namespace Ember */ Ember.CoreObject = CoreObject; @@ -8574,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. @@ -8671,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, @@ -8688,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 */ @@ -8702,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); } @@ -8740,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 @@ -8771,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'), @@ -8787,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'), @@ -8801,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); @@ -8821,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'), @@ -8836,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'), @@ -8852,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'), @@ -8865,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'), @@ -8879,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'), @@ -8889,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 @@ -8938,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 @@ -8977,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); @@ -8993,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++) { @@ -9009,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); @@ -9031,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. @@ -9050,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, @@ -9080,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. @@ -9107,6 +9449,9 @@ Ember.Namespace.PROCESSED = false; //..init code goes here... } + @class Application + @namespace Ember + @extends Ember.Namespace */ Ember.Application = Ember.Namespace.extend(); @@ -9116,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 @@ -9153,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 */ { @@ -9164,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, @@ -9172,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'); @@ -9184,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); @@ -9200,24 +9547,23 @@ 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(); @@ -9238,8 +9584,12 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, 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'); @@ -9307,35 +9657,29 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, 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._setupContent(); @@ -9354,6 +9698,11 @@ Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray, (function() { +/** + �� module ember + �� submodule ember-runtime +*/ + var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt, @@ -9377,8 +9726,6 @@ function contentPropertyDidChange(content, contentKey) { } /** - @class - `Ember.ObjectProxy` forwards all properties not defined by the proxy itself to a proxied `content` object. @@ -9429,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 */ @@ -9442,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); @@ -9474,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; @@ -9505,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 = {}; @@ -9525,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 = {}; @@ -9545,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({ @@ -9571,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; @@ -9679,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 @@ -9785,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; @@ -9799,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 = []; } @@ -9810,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); @@ -9827,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({ @@ -9841,9 +10202,6 @@ Ember._PromiseChain = Ember.Object.extend({ abortCallback: Ember.K, promiseSuccessCallback: Ember.K, - /** - @private - */ runNextPromise: function() { if (get(this, 'isDestroyed')) { return; } @@ -9889,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; @@ -9903,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; @@ -9920,11 +10295,6 @@ Ember.runLoadHooks = function(name, object) { (function() { -// ========================================================================== -// Project: Ember Runtime -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== })(); @@ -9932,30 +10302,35 @@ Ember.runLoadHooks = function(name, object) { (function() { /** - @class - + �� 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({ @@ -9967,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); })(); @@ -9979,38 +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: - - songs = [ + 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: + + 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'} - - - @extends Ember.Mixin - @extends Ember.MutableEnumerable + + + @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, @@ -10160,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) { @@ -10195,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. @@ -10216,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 @@ -10238,9 +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 - @extends Ember.SortableMixin - @extends Ember.ControllerMixin + @uses Ember.SortableMixin + @uses Ember.ControllerMixin */ Ember.ArrayController = Ember.ArrayProxy.extend(Ember.ControllerMixin, @@ -10252,18 +10648,23 @@ Ember.ArrayController = Ember.ArrayProxy.extend(Ember.ControllerMixin, (function() { /** - @class - + �� 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 - @extends Ember.ControllerMixin + @uses Ember.ControllerMixin **/ Ember.ObjectController = Ember.ObjectProxy.extend(Ember.ControllerMixin); @@ -10278,94 +10679,407 @@ 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 to a CSS selector. + 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 */ + autoinit: !Ember.testing, + + isInitialized: false, + init: function() { if (!this.$) { this.$ = Ember.$; } - var eventDispatcher, - rootElement = get(this, 'rootElement'); this._super(); - eventDispatcher = Ember.EventDispatcher.create({ - rootElement: rootElement - }); - - set(this, 'eventDispatcher', eventDispatcher); + this.createEventDispatcher(); // Start off the number of deferrals at 1. This will be // decremented by the Application's own `initialize` method. this._readinessDeferrals = 1; this.waitForDOMContentLoaded(); + + if (this.autoinit) { + var self = this; + this.$().ready(function() { + if (self.isDestroyed || self.isInitialized) return; + self.initialize(); + }); + } + }, + + /** @private */ + createEventDispatcher: function() { + var rootElement = get(this, 'rootElement'), + eventDispatcher = Ember.EventDispatcher.create({ + rootElement: rootElement + }); + + set(this, 'eventDispatcher', eventDispatcher); }, waitForDOMContentLoaded: function() { @@ -10409,14 +11123,54 @@ Ember.Application = Ember.Namespace.extend( router.get('commentsController') // <App.CommentsController:ember1235> 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; + Ember.assert("Application initialize may only be call once", !this.isInitialized); + Ember.assert("Application not destroyed", !this.isDestroyed); + + router = this.setupRouter(router); + + this.runInjections(router); + + Ember.runLoadHooks('application', this); + + this.isInitialized = true; - if (!router && Ember.Router.detect(namespace['Router'])) { - router = namespace['Router'].create(); + // At this point, any injections or load hooks that would have wanted + // to defer readiness have fired. + this.advanceReadiness(); + + return this; + }, + + /** @private */ + runInjections: function(router) { + var injections = get(this.constructor, 'injections'), + graph = new Ember.DAG(), + namespace = this, + properties, i, injection; + + for (i=0; i<injections.length; i++) { + injection = injections[i]; + graph.addEdges(injection.name, injection.injection, injection.before, injection.after); + } + + graph.topsort(function (vertex) { + var injection = vertex.value, + properties = Ember.A(Ember.keys(namespace)); + properties.forEach(function(property) { + injection(namespace, router, property); + }); + }); + }, + + /** @private */ + setupRouter: function(router) { + if (!router && Ember.Router.detect(this.Router)) { + router = this.Router.create(); this._createdRouter = router; } @@ -10432,19 +11186,7 @@ Ember.Application = Ember.Namespace.extend( set(router, 'namespace', this); } - injections.forEach(function(injection) { - properties.forEach(function(property) { - injection[1](namespace, router, property); - }); - }); - - Ember.runLoadHooks('application', this); - - // At this point, any injections or load hooks that would have wanted - // to defer readiness have fired. - this.advanceReadiness(); - - return this; + return router; }, /** @private */ @@ -10457,32 +11199,66 @@ Ember.Application = Ember.Namespace.extend( this.ready(); + router = get(this, 'router'); + this.createApplicationView(router); + if (router && router instanceof Ember.Router) { this.startRouting(router); } }, + createApplicationView: function (router) { + var rootElement = get(this, 'rootElement'), + applicationViewOptions = {}, + applicationViewClass = this.ApplicationView, + applicationTemplate = Ember.TEMPLATES.application, + applicationController, applicationView; + + // don't do anything unless there is an ApplicationView or application template + if (!applicationViewClass && !applicationTemplate) return; + + if (router) { + applicationController = get(router, 'applicationController'); + if (applicationController) { + applicationViewOptions.controller = applicationController; + } + } + + if (applicationTemplate) { + applicationViewOptions.template = applicationTemplate; + } + + if (!applicationViewClass) { + applicationViewClass = Ember.View; + } + + applicationView = applicationViewClass.create(applicationViewOptions); + + this._createdApplicationView = applicationView; + + if (router) { + set(router, 'applicationView', applicationView); + } + + applicationView.appendTo(rootElement); + }, + /** @private If the application has a router, use it to route to the current URL, and trigger a new call to `route` whenever the URL changes. + + @method startRouting + @property router {Ember.Router} */ startRouting: function(router) { - var location = get(router, 'location'), - rootElement = get(this, 'rootElement'), - applicationController = get(router, 'applicationController'); + var location = get(router, 'location'); - Ember.assert("ApplicationView and ApplicationController must be defined on your application", (this.ApplicationView && applicationController) ); - - var applicationView = this.ApplicationView.create({ - controller: applicationController - }); - this._createdApplicationView = applicationView; - - applicationView.appendTo(rootElement); + Ember.assert("You must have an application template or ApplicationView defined on your application", get(router, 'applicationView') ); + Ember.assert("You must have an ApplicationController defined on your application", get(router, 'applicationController') ); router.route(location.getURL()); location.onUpdateURL(function(url) { @@ -10493,10 +11269,11 @@ Ember.Application = Ember.Namespace.extend( /** Called when the Application has become ready. The call will be delayed until the DOM has become ready. + + @event ready */ ready: Ember.K, - /** @private */ willDestroy: function() { get(this, 'eventDispatcher').destroy(); if (this._createdRouter) { this._createdRouter.destroy(); } @@ -10511,23 +11288,14 @@ Ember.Application = Ember.Namespace.extend( Ember.Application.reopenClass({ concatenatedProperties: ['injections'], injections: Ember.A(), - registerInjection: function(options) { - var injections = get(this, 'injections'), - before = options.before, - name = options.name, - injection = options.injection, - location; - - if (before) { - location = injections.find(function(item) { - if (item[0] === before) { return true; } - }); - location = injections.indexOf(location); - } else { - location = get(injections, 'length'); - } + registerInjection: function(injection) { + var injections = get(this, 'injections'); - injections.splice(location, 0, [name, injection]); + Ember.assert("The injection '" + injection.name + "' has already been registered", !injections.findProperty('name', injection.name)); + Ember.assert("An injection cannot be registered with both a before and an after", !(injection.before && injection.after)); + Ember.assert("An injection cannot be registered without an injection function", Ember.canInvoke(injection, 'injection')); + + injections.push(injection); } }); @@ -10537,7 +11305,10 @@ Ember.Application.registerInjection({ if (!/^[A-Z].*Controller$/.test(property)) { return; } var name = property.charAt(0).toLowerCase() + property.substr(1), - controller = app[property].create(); + controllerClass = app[property], controller; + + if(!Ember.Object.detect(controllerClass)){ return; } + controller = app[property].create(); router.set(name, controller); @@ -10563,18 +11334,30 @@ Ember.runLoadHooks('Ember.Application', Ember.Application); (function() { +/** +Ember Application + + �� module ember + �� submodule ember-application + �� requires ember-views, ember-states, ember-routing +*/ })(); (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.assert("Ember Views require jQuery 1.7 or 1.8", window.jQuery && (window.jQuery().jquery.match(/^1\.[78](\.\d+)?(pre|rc\d?)?/) || Ember.ENV.FORCE_JQUERY)); + +/** + Alias for jQuery + + @method $ + @for Ember +*/ Ember.$ = window.jQuery; })(); @@ -10582,12 +11365,10 @@ Ember.$ = window.jQuery; (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 +*/ // http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#dndevents var dragEvents = Ember.String.w('dragstart drag dragenter dragleave dragover drop dragend'); @@ -10603,17 +11384,14 @@ Ember.EnumerableUtils.forEach(dragEvents, function(eventName) { (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; var indexOf = Ember.ArrayPolyfills.indexOf; -/** @private */ var ClassSet = function() { this.seen = {}; this.list = []; @@ -10633,13 +11411,13 @@ ClassSet.prototype = { }; /** - @class - Ember.RenderBuffer gathers information regarding the a view and generates the final representation. Ember.RenderBuffer will generate HTML which can be pushed to the DOM. - @extends Ember.Object + @class RenderBuffer + @namespace Ember + @constructor */ Ember.RenderBuffer = function(tagName) { return new Ember._RenderBuffer(tagName); @@ -10659,6 +11437,7 @@ Ember._RenderBuffer.prototype = You should not maintain this array yourself, rather, you should use the addClass() method of Ember.RenderBuffer. + @property elementClasses @type Array @default [] */ @@ -10670,6 +11449,7 @@ Ember._RenderBuffer.prototype = You should not set this property yourself, rather, you should use the id() method of Ember.RenderBuffer. + @property elementId @type String @default null */ @@ -10684,6 +11464,7 @@ Ember._RenderBuffer.prototype = You should not maintain this hash yourself, rather, you should use the attr() method of Ember.RenderBuffer. + @property elementAttributes @type Hash @default {} */ @@ -10697,6 +11478,7 @@ Ember._RenderBuffer.prototype = Ember.RenderBuffer('p') + @property elementTag @type String @default null */ @@ -10711,6 +11493,7 @@ Ember._RenderBuffer.prototype = You should not maintain this hash yourself, rather, you should use the style() method of Ember.RenderBuffer. + @property elementStyle @type Hash @default {} */ @@ -10720,6 +11503,7 @@ Ember._RenderBuffer.prototype = Nested RenderBuffers will set this to their parent RenderBuffer instance. + @property parentBuffer @type Ember._RenderBuffer */ parentBuffer: null, @@ -10727,8 +11511,9 @@ Ember._RenderBuffer.prototype = /** Adds a string of HTML to the RenderBuffer. + @method push @param {String} string HTML to push into the buffer - @returns {Ember.RenderBuffer} this + @chainable */ push: function(string) { this.childBuffers.push(String(string)); @@ -10738,8 +11523,9 @@ Ember._RenderBuffer.prototype = /** Adds a class to the buffer, which will be rendered to the class attribute. + @method addClass @param {String} className Class name to add to the buffer - @returns {Ember.RenderBuffer} this + @chainable */ addClass: function(className) { // lazily create elementClasses @@ -10752,8 +11538,9 @@ Ember._RenderBuffer.prototype = /** Sets the elementID to be used for the element. + @method id @param {String} id - @returns {Ember.RenderBuffer} this + @chainable */ id: function(id) { this.elementId = id; @@ -10766,9 +11553,11 @@ Ember._RenderBuffer.prototype = /** Adds an attribute which will be rendered to the element. + @method attr @param {String} name The name of the attribute @param {String} value The value to add to the attribute - @returns {Ember.RenderBuffer|String} this or the current attribute value + @chainable + @return {Ember.RenderBuffer|String} this or the current attribute value */ attr: function(name, value) { var attributes = this.elementAttributes = (this.elementAttributes || {}); @@ -10785,8 +11574,9 @@ Ember._RenderBuffer.prototype = /** Remove an attribute from the list of attributes to render. + @method removeAttr @param {String} name The name of the attribute - @returns {Ember.RenderBuffer} this + @chainable */ removeAttr: function(name) { var attributes = this.elementAttributes; @@ -10798,9 +11588,10 @@ Ember._RenderBuffer.prototype = /** Adds a style to the style attribute which will be rendered to the element. + @method style @param {String} name Name of the style @param {String} value - @returns {Ember.RenderBuffer} this + @chainable */ style: function(name, value) { var style = this.elementStyle = (this.elementStyle || {}); @@ -10810,6 +11601,8 @@ Ember._RenderBuffer.prototype = }, /** + @private + Create a new child render buffer from a parent buffer. Optionally set additional properties on the buffer. Optionally invoke a callback with the newly created buffer. @@ -10817,7 +11610,7 @@ Ember._RenderBuffer.prototype = This is a primitive method used by other public methods: `begin`, `prepend`, `replaceWith`, `insertAfter`. - @private + @method newBuffer @param {String} tagName Tag name to use for the child buffer's element @param {Ember._RenderBuffer} parent The parent render buffer that this buffer should be appended to. @@ -10836,11 +11629,13 @@ Ember._RenderBuffer.prototype = }, /** + @private + Replace the current buffer with a new buffer. This is a primitive used by `remove`, which passes `null` for `newBuffer`, and `replaceWith`, which passes the new buffer it created. - @private + @method replaceWithBuffer @param {Ember._RenderBuffer} buffer The buffer to insert in place of the existing buffer. */ @@ -10864,8 +11659,9 @@ Ember._RenderBuffer.prototype = the element tag and with its parentBuffer property set to the current Ember.RenderBuffer. + @method begin @param {String} tagName Tag name to use for the child buffer's element - @returns {Ember.RenderBuffer} A new RenderBuffer object + @return {Ember.RenderBuffer} A new RenderBuffer object */ begin: function(tagName) { return this.newBuffer(tagName, this, function(buffer) { @@ -10876,6 +11672,7 @@ Ember._RenderBuffer.prototype = /** Prepend a new child buffer to the current render buffer. + @method prepend @param {String} tagName Tag name to use for the child buffer's element */ prepend: function(tagName) { @@ -10887,6 +11684,7 @@ Ember._RenderBuffer.prototype = /** Replace the current buffer with a new render buffer. + @method replaceWith @param {String} tagName Tag name to use for the new buffer's element */ replaceWith: function(tagName) { @@ -10900,6 +11698,7 @@ Ember._RenderBuffer.prototype = /** Insert a new render buffer after the current render buffer. + @method insertAfter @param {String} tagName Tag name to use for the new buffer's element */ insertAfter: function(tagName) { @@ -10915,7 +11714,8 @@ Ember._RenderBuffer.prototype = /** Closes the current buffer and adds its content to the parentBuffer. - @returns {Ember.RenderBuffer} The parentBuffer, if one exists. Otherwise, this + @method end + @return {Ember.RenderBuffer} The parentBuffer, if one exists. Otherwise, this */ end: function() { var parent = this.parentBuffer; @@ -10927,7 +11727,8 @@ Ember._RenderBuffer.prototype = }, /** - @returns {DOMElement} The element corresponding to the generated HTML + @method element + @return {DOMElement} The element corresponding to the generated HTML of this buffer */ element: function() { @@ -10937,7 +11738,8 @@ Ember._RenderBuffer.prototype = /** Generates the HTML content for this buffer. - @returns {String} The generated HTMl + @method string + @return {String} The generated HTMl */ string: function() { var content = '', tag = this.elementTag, openTag; @@ -11020,21 +11822,22 @@ Ember._RenderBuffer.prototype = (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, fmt = Ember.String.fmt; /** - @ignore - Ember.EventDispatcher handles delegating browser events to their corresponding Ember.Views. For example, when you click on a view, Ember.EventDispatcher ensures that that view's `mouseDown` method gets called. + + @class EventDispatcher + @namespace Ember + @private + @extends Ember.Object */ Ember.EventDispatcher = Ember.Object.extend( /** @scope Ember.EventDispatcher.prototype */{ @@ -11050,6 +11853,7 @@ Ember.EventDispatcher = Ember.Object.extend( The default body is a string since this may be evaluated before document.body exists in the DOM. + @property rootElement @type DOMElement @default 'body' */ @@ -11064,6 +11868,9 @@ Ember.EventDispatcher = Ember.Object.extend( default, it will set up all of the listeners on the document body. If you would like to register the listeners on a different element, set the event dispatcher's `root` property. + + @method setup + @param addedEvents {Hash} */ setup: function(addedEvents) { var event, events = { @@ -11131,6 +11938,8 @@ Ember.EventDispatcher = Ember.Object.extend( setupHandler('mousedown', 'mouseDown'); + @method setupHandler + @param {Element} rootElement @param {String} event the browser-originated event to listen to @param {String} eventName the name of the method to call on the view */ @@ -11138,35 +11947,37 @@ Ember.EventDispatcher = Ember.Object.extend( var self = this; rootElement.delegate('.ember-view', event + '.ember', function(evt, triggeringManager) { + return Ember.handleErrors(function() { + var view = Ember.View.views[this.id], + result = true, manager = null; - var view = Ember.View.views[this.id], - result = true, manager = null; - - manager = self._findNearestEventManager(view,eventName); + manager = self._findNearestEventManager(view,eventName); - if (manager && manager !== triggeringManager) { - result = self._dispatchEvent(manager, evt, eventName, view); - } else if (view) { - result = self._bubbleEvent(view,evt,eventName); - } else { - evt.stopPropagation(); - } + if (manager && manager !== triggeringManager) { + result = self._dispatchEvent(manager, evt, eventName, view); + } else if (view) { + result = self._bubbleEvent(view,evt,eventName); + } else { + evt.stopPropagation(); + } - return result; + return result; + }, this); }); rootElement.delegate('[data-ember-action]', event + '.ember', function(evt) { - var actionId = Ember.$(evt.currentTarget).attr('data-ember-action'), - action = Ember.Handlebars.ActionHelper.registeredActions[actionId], - handler = action.handler; + return Ember.handleErrors(function() { + var actionId = Ember.$(evt.currentTarget).attr('data-ember-action'), + action = Ember.Handlebars.ActionHelper.registeredActions[actionId], + handler = action.handler; - if (action.eventName === eventName) { - return handler(evt); - } + if (action.eventName === eventName) { + return handler(evt); + } + }, this); }); }, - /** @private */ _findNearestEventManager: function(view, eventName) { var manager = null; @@ -11180,7 +11991,6 @@ Ember.EventDispatcher = Ember.Object.extend( return manager; }, - /** @private */ _dispatchEvent: function(object, evt, eventName, view) { var result = true; @@ -11197,14 +12007,12 @@ Ember.EventDispatcher = Ember.Object.extend( return result; }, - /** @private */ _bubbleEvent: function(view, evt, eventName) { return Ember.run(function() { return view.handleEvent(eventName, evt); }); }, - /** @private */ destroy: function() { var rootElement = get(this, 'rootElement'); Ember.$(rootElement).undelegate('.ember').removeClass('ember-application'); @@ -11217,12 +12025,10 @@ Ember.EventDispatcher = Ember.Object.extend( (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 +*/ // Add a new named queue for rendering views that happens // after bindings have synced. @@ -11234,10 +12040,23 @@ queues.splice(Ember.$.inArray('actions', queues)+1, 0, 'render'); (function() { +/** + �� module ember + �� submodule ember-views +*/ + var get = Ember.get, set = Ember.set; -// @class declaration and documentation in runtime/lib/controllers/controller.js -Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { +// Original class declaration and documentation in runtime/lib/controllers/controller.js +// NOTE: It may be possible with YUIDoc to combine docs in two locations + +/** +Additional methods for the ControllerMixin + + �� class ControllerMixin + �� namespace Ember +*/ +Ember.ControllerMixin.reopen({ target: null, controllers: null, @@ -11255,15 +12074,19 @@ Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { For example, an application view's template may look like this: - <h1>My Blog</h1> - {{outlet}} + ``` handlebars + <h1>My Blog</h1> + {{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 @@ -11281,27 +12104,37 @@ Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { 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: - <h1>My Blog</h1> - {{outlet master}} - {{outlet detail}} + ``` handlebars + <h1>My Blog</h1> + {{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 @@ -11387,6 +12220,7 @@ Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { overviewController.connectControllers('person', 'post'); + @method connectControllers @param {String...} controllerNames the controllers to make available */ connectControllers: function() { @@ -11403,6 +12237,7 @@ Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { /** `disconnectOutlet` removes previously attached view from given outlet. + @method disconnectOutlet @param {String} outletName the outlet name. (optional) */ disconnectOutlet: function(outletName) { @@ -11415,6 +12250,10 @@ Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { `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(); @@ -11426,25 +12265,18 @@ Ember.ControllerMixin.reopen(/** @scope Ember.ControllerMixin.prototype */ { (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) -// ========================================================================== -var get = Ember.get, set = Ember.set, addObserver = Ember.addObserver; +/** + �� module ember + �� submodule ember-views +*/ + +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; @@ -11469,12 +12301,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 = {}; @@ -11488,8 +12320,6 @@ 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. @@ -11498,132 +12328,172 @@ var invokeForState = { 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: - <em id="ember1" class="ember-view"></em> + ``` html + <em id="ember1" class="ember-view"></em> + ``` ## 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: - <div id="ember1" class="ember-view my-class my-other-class"></div> + ``` html + <div id="ember1" class="ember-view my-class my-other-class"></div> + ``` `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 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: - <div id="ember1" class="ember-view from-a from-b"></div> + ``` html + <div id="ember1" class="ember-view from-a from-b"></div> + ``` 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: - <div id="ember1" class="ember-view hovered"></div> + ``` html + <div id="ember1" class="ember-view hovered"></div> + ``` 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: - <div id="ember1" class="ember-view so-very-cool"></div> + ``` html + <div id="ember1" class="ember-view so-very-cool"></div> + ``` 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: - <div id="ember1" class="ember-view is-urgent"></div> + ``` html + <div id="ember1" class="ember-view is-urgent"></div> + ``` 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: - <div id="ember1" class="ember-view empty"></div> + ``` html + <div id="ember1" class="ember-view empty"></div> + ``` 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: - <div id="ember1" class="ember-view enabled"></div> + ``` html + <div id="ember1" class="ember-view enabled"></div> + ``` When isEnabled is `false`, the resulting HTML reprensentation looks like this: - <div id="ember1" class="ember-view disabled"></div> + ``` html + <div id="ember1" class="ember-view disabled"></div> + ``` 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: - <div id="ember1" class="ember-view"></div> + ``` html + <div id="ember1" class="ember-view"></div> + ``` When the `isEnabled` property on the view is set to `false`, it will result in view instances with an HTML representation of: - <div id="ember1" class="ember-view disabled"></div> + ``` html + <div id="ember1" class="ember-view disabled"></div> + ``` 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. @@ -11633,47 +12503,58 @@ var invokeForState = { 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: - <a id="ember1" class="ember-view" href="http://google.com"></a> + ``` html + <a id="ember1" class="ember-view" href="http://google.com"></a> + ``` 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: - <input id="ember1" class="ember-view" disabled="disabled" /> + ``` html + <input id="ember1" class="ember-view" disabled="disabled" /> + ``` `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 of the HTML attribute in the view's rendered HTML representation. @@ -11687,45 +12568,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: - <div id="ember1" class="ember-view">I am the template</div> + ``` html + <div id="ember1" class="ember-view">I am the template</div> + ``` 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: - <div id="ember1" class="ember-view">Hello Barry!!!</div> + ``` html + <div id="ember1" class="ember-view">Hello Barry!!!</div> + ``` Within an Ember application is more common to define a Handlebars templates as part of a page: - <script type='text/x-handlebars' data-template-name='some-template'> - Hello - </script> + ``` handlebars + <script type='text/x-handlebars' data-template-name='some-template'> + Hello + </script> + ``` 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. @@ -11737,31 +12630,40 @@ 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: - <div id="ember1" class="ember-view">I was the default</div> + ``` html + <div id="ember1" class="ember-view">I was the default</div> + ``` 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: - <div id="ember1" class="ember-view">I was the template, not default</div> + ``` html + <div id="ember1" class="ember-view">I was the template, not default</div> + ``` ## 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 @@ -11775,37 +12677,46 @@ 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("<div class='my-decorative-class'>{{yield}}</div>") - template: Ember.Handlebars.compile("I got wrapped"), - }) + ``` javascript + AViewWithLayout = Ember.View.extend({ + layout: Ember.Handlebars.compile("<div class='my-decorative-class'>{{yield}}</div>") + template: Ember.Handlebars.compile("I got wrapped"), + }); + ``` Will result in view instances with an HTML representation of: - <div id="ember1" class="ember-view"> - <div class="my-decorative-class"> - I got wrapped - </div> - </div> + ``` html + <div id="ember1" class="ember-view"> + <div class="my-decorative-class"> + I got wrapped + </div> + </div> + ``` 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, 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 @@ -11814,32 +12725,35 @@ var invokeForState = { 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 @@ -11847,33 +12761,37 @@ var invokeForState = { 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' @@ -11888,22 +12806,25 @@ var invokeForState = { 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, @@ -11918,6 +12839,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 */ @@ -11930,6 +12852,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 */ @@ -11938,6 +12861,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** The hash in which to look for `templateName`. + @property templates @type Ember.Object @default Ember.TEMPLATES */ @@ -11951,7 +12875,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) { @@ -11967,6 +12891,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) { @@ -11991,7 +12916,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) { @@ -12025,6 +12950,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) { @@ -12052,9 +12978,11 @@ 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; + var parentView, controller; if (arguments.length === 2) { return value; @@ -12075,10 +13003,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(); @@ -12088,6 +13018,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 */ @@ -12112,16 +13043,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 [] */ @@ -12129,10 +13063,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'); @@ -12140,10 +13072,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'); @@ -12155,8 +13085,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'); @@ -12170,8 +13101,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'); @@ -12186,8 +13118,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'); @@ -12201,7 +13134,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); @@ -12211,7 +13145,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); @@ -12221,7 +13156,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'); @@ -12232,6 +13168,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; } @@ -12274,6 +13212,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) { @@ -12357,6 +13296,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'); @@ -12384,6 +13325,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'), @@ -12401,6 +13344,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. @@ -12408,6 +13353,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) { @@ -12441,16 +13390,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) { @@ -12492,6 +13442,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); @@ -12512,7 +13465,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) { @@ -12531,14 +13484,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, @@ -12552,7 +13505,6 @@ Ember.View = Ember.Object.extend(Ember.Evented, return this; }, - /** @private */ forEachChildView: function(callback) { var childViews = this._childViews; @@ -12585,8 +13537,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 @@ -12608,8 +13561,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')); @@ -12640,11 +13594,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); }, /** @@ -12656,7 +13618,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); @@ -12665,7 +13628,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 @@ -12684,18 +13648,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'), @@ -12707,8 +13667,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'); @@ -12720,7 +13681,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'); @@ -12741,7 +13704,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; } @@ -12754,6 +13718,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, @@ -12761,6 +13727,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, @@ -12768,13 +13736,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); @@ -12786,6 +13759,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) { @@ -12801,6 +13776,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) { @@ -12813,6 +13790,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) { @@ -12825,6 +13804,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) { @@ -12847,7 +13828,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'); @@ -12857,6 +13839,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() {}, @@ -12864,6 +13848,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) { @@ -12871,7 +13857,6 @@ Ember.View = Ember.Object.extend(Ember.Evented, }); }, - /** @private (nodoc) */ _elementWillChange: Ember.beforeObserver(function() { this.forEachChildView(function(view) { Ember.propertyWillChange(view, 'element'); @@ -12885,7 +13870,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) { @@ -12896,7 +13881,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, /** Called when the parentView property has changed. - @function + @event parentViewDidChange */ parentViewDidChange: Ember.K, @@ -12913,6 +13898,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. @@ -12967,9 +13953,6 @@ Ember.View = Ember.Object.extend(Ember.Evented, afterRender: Ember.K, - /** - @private - */ applyAttributesToBuffer: function(buffer) { // Creates observers for all registered class name and attribute bindings, // then adds them to the element. @@ -13005,6 +13988,7 @@ Ember.View = Ember.Object.extend(Ember.Evented, By default, the render buffer will use a `<div>` tag for views. + @property tagName @type String @default null */ @@ -13022,6 +14006,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 */ @@ -13032,6 +14017,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'] */ @@ -13068,6 +14054,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 [] */ @@ -13092,6 +14079,8 @@ Ember.View = Ember.Object.extend(Ember.Evented, attributeBindings: ['enabled'], enabled: true }); + + @property attributeBindings */ attributeBindings: [], @@ -13108,6 +14097,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(); @@ -13141,8 +14132,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 @@ -13166,7 +14158,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) { @@ -13184,7 +14177,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'); @@ -13201,6 +14195,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, @@ -13245,10 +14241,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)) { @@ -13283,6 +14279,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.$(); @@ -13357,6 +14355,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); @@ -13382,6 +14383,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); @@ -13389,7 +14394,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: @@ -13414,7 +14419,6 @@ 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, html) { view.$().prepend(html); @@ -13469,6 +14473,8 @@ Ember.View.reopenClass({ classNames: ":enabled:disabled" } + @method _parsePropertyPath + @static */ _parsePropertyPath: function(path) { var split = path.split(':'), @@ -13500,35 +14506,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) { @@ -13542,7 +14557,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 @@ -13571,12 +14592,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 = { @@ -13601,7 +14621,10 @@ 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; }, @@ -13620,21 +14643,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. @@ -13662,12 +14681,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 = { @@ -13752,12 +14770,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 = { @@ -13803,8 +14820,11 @@ Ember.View.states.hasElement = { destroyElement: function(view) { view._notifyWillDestroyElement(); view.domManager.remove(view); - view._lastInsert = null; set(view, 'element', null); + if (view._scheduledInsert) { + Ember.run.cancel(view._scheduledInsert); + view._scheduledInsert = null; + } return view; }, @@ -13835,9 +14855,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"; } }; @@ -13847,12 +14864,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 = { @@ -13890,24 +14906,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; @@ -13916,8 +14925,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. @@ -13926,26 +14933,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. @@ -13958,37 +14970,45 @@ var childViewsProperty = Ember.computed(function() { Given an empty `<body>` 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 - <div class="ember-view the-container"> - <div class="ember-view">A</div> - <div class="ember-view">B</div> - </div> + ``` html + <div class="ember-view the-container"> + <div class="ember-view">A</div> + <div class="ember-view">B</div> + </div> + ``` 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 - <div class="ember-view the-container"> - <div class="ember-view">A</div> - </div> + ``` html + <div class="ember-view the-container"> + <div class="ember-view">A</div> + </div> + ``` Similarly, adding a child view is accomplished by adding `Ember.View` instances to the @@ -13996,43 +15016,51 @@ var childViewsProperty = Ember.computed(function() { Given an empty `<body>` 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 - <div class="ember-view the-container"> - <div class="ember-view">A</div> - <div class="ember-view">B</div> - </div> + ``` html + <div class="ember-view the-container"> + <div class="ember-view">A</div> + <div class="ember-view">B</div> + </div> + ``` 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, <AnotherViewClass instance>] + aContainer.get('childViews'); // [aContainer.aView, aContainer.bView] + aContainer.get('childViews').pushObject(AnotherViewClass.create()); + aContainer.get('childViews'); // [aContainer.aView, aContainer.bView, <AnotherViewClass instance>] + ``` Will result in the following HTML - <div class="ember-view the-container"> - <div class="ember-view">A</div> - <div class="ember-view">B</div> - <div class="ember-view">Another view</div> - </div> + ``` html + <div class="ember-view the-container"> + <div class="ember-view">A</div> + <div class="ember-view">B</div> + <div class="ember-view">Another view</div> + </div> + ``` Direct manipulation of childViews presence or absence in the DOM via calls to @@ -14048,36 +15076,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 - <div class="ember-view the-container"> - <div class="ember-view">A</div> - <div class="ember-view">B</div> - </div> + ``` html + <div class="ember-view the-container"> + <div class="ember-view">A</div> + <div class="ember-view">B</div> + </div> + ``` Calling `aContainer.get('aView').removeFromParent()` will result in the following HTML - <div class="ember-view the-container"> - <div class="ember-view">B</div> - </div> + ``` html + <div class="ember-view the-container"> + <div class="ember-view">B</div> + </div> + ``` 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 @@ -14095,16 +15130,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 */ @@ -14148,10 +15187,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) { @@ -14160,10 +15201,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, { @@ -14175,13 +15218,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 @@ -14196,6 +15241,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 @@ -14204,7 +15251,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 @@ -14318,7 +15365,7 @@ Ember.ContainerView.states = { view.domManager.prepend(view, buffer.string()); } childView.transitionTo('inDOM'); - childView.invalidateRecursively('element'); + childView.propertyDidChange('element'); childView._notifyDidInsertElement(); } previous = childView; @@ -14340,17 +15387,14 @@ Ember.ContainerView.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 +*/ + var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; /** - @class - `Ember.CollectionView` is an `Ember.View` descendent responsible for managing a collection (an array or array-like object) by maintaing a child view object and associated DOM representation for each item in the array and ensuring that child @@ -14361,9 +15405,11 @@ var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; The managed collection of objects is referenced as the `Ember.CollectionView` instance's `content` property. - someItemsView = Ember.CollectionView.create({ - content: ['A', 'B','C'] - }) + ``` javascript + someItemsView = Ember.CollectionView.create({ + content: ['A', 'B','C'] + }) + ``` The view for each item in the collection will have its `content` property set to the item. @@ -14375,24 +15421,27 @@ var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; Given an empty `<body>` 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 - <div class="ember-view a-collection"> - <div class="ember-view">the letter: A</div> - <div class="ember-view">the letter: B</div> - <div class="ember-view">the letter: C</div> - </div> + ``` html + <div class="ember-view a-collection"> + <div class="ember-view">the letter: A</div> + <div class="ember-view">the letter: B</div> + <div class="ember-view">the letter: C</div> + </div> + ``` ## Automatic matching of parent/child tagNames @@ -14403,27 +15452,33 @@ var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt; Given an empty `<body>` 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 - <ul class="ember-view a-collection"> - <li class="ember-view">the letter: A</li> - <li class="ember-view">the letter: B</li> - <li class="ember-view">the letter: C</li> - </ul> + ``` html + <ul class="ember-view a-collection"> + <li class="ember-view">the letter: A</li> + <li class="ember-view">the letter: B</li> + <li class="ember-view">the letter: C</li> + </ul> + ``` 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 @@ -14431,23 +15486,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 - <div class="ember-view nothing"> - <div class="ember-view"> - The collection is empty - </div> - </div> + ``` html + <div class="ember-view nothing"> + <div class="ember-view"> + The collection is empty + </div> + </div> + ``` ## Adding and Removing items The `childViews` property of a `CollectionView` should not be directly manipulated. Instead, @@ -14458,8 +15517,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 */ { @@ -14467,6 +15528,7 @@ Ember.CollectionView = Ember.ContainerView.extend( /** A list of items to be displayed by the Ember.CollectionView. + @property content @type Ember.Array @default null */ @@ -14478,24 +15540,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(); @@ -14517,6 +15582,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'); @@ -14573,14 +15640,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'), @@ -14629,14 +15692,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', @@ -14654,26 +15717,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 +*/ })(); @@ -14681,9 +15739,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 */{ @@ -14692,6 +15756,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** A reference to the parent state. + @property parentState @type Ember.State */ parentState: null, @@ -14700,6 +15765,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, /** The name of this state. + @property name @type String */ name: null, @@ -14707,8 +15773,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'), @@ -14726,6 +15792,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]) { @@ -14734,7 +15803,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()); @@ -14774,7 +15842,6 @@ Ember.State = Ember.Object.extend(Ember.Evented, set(this, 'pathsCacheNoContext', {}); }, - /** @private */ setupChild: function(states, name, value) { if (!value) { return false; } @@ -14790,6 +15857,7 @@ Ember.State = Ember.Object.extend(Ember.Evented, set(value, 'parentState', this); get(this, 'childStates').pushObject(value); states[name] = value; + return value; } }, @@ -14809,6 +15877,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() { @@ -14818,13 +15887,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 @@ -14834,7 +15906,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, @@ -14842,7 +15914,7 @@ 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 @@ -14854,8 +15926,6 @@ 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: @@ -14876,6 +15946,8 @@ Ember.State.reopenClass( stateTwo: Ember.State.create({}) }) + @method transitionTo + @static @param {String} target */ transitionTo: function(target) { @@ -14905,16 +15977,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(); @@ -14926,12 +16004,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` */ @@ -14943,12 +16020,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) { @@ -15021,9 +16097,9 @@ Transition.prototype = { }, /** - @private - Add any `initialState`s to the list of enter states. + + @method addInitialStates */ addInitialStates: function() { var finalState = this.finalState, initialState; @@ -15041,12 +16117,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 */ @@ -15069,8 +16144,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. @@ -15434,14 +16507,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(); @@ -15484,15 +16563,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', @@ -15502,6 +16593,7 @@ 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 */ @@ -15550,9 +16642,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('.'), @@ -15578,8 +16671,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`. @@ -15587,6 +16678,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; } @@ -15773,11 +16868,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 +*/ })(); @@ -15833,6 +16930,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 @@ -15862,13 +16964,14 @@ var merge = function(original, hash) { }; /** - @class + @class Routable + @namespace Ember @extends Ember.Mixin */ Ember.Routable = Ember.Mixin.create({ init: function() { var redirection; - this.on('connectOutlets', this, this.stashContext); + this.on('setup', this, this.stashContext); if (redirection = get(this, 'redirectsTo')) { Ember.assert("You cannot use `redirectsTo` if you already have a `connectOutlets` method", this.connectOutlets === Ember.K); @@ -15889,14 +16992,24 @@ Ember.Routable = Ember.Mixin.create({ Ember.assert("You cannot use `redirectsTo` on a state that has child states", !redirection || (!!redirection && !!get(this, 'isLeaf'))); }, + setup: function() { + return this.connectOutlets.apply(this, arguments); + }, + /** @private 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) { + this.router = manager; + var serialized = this.serialize(manager, context); Ember.assert('serialize must return a hash', !serialized || typeof serialized === 'object'); @@ -15915,6 +17028,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')) { @@ -15931,6 +17048,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'); @@ -15964,6 +17085,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'; @@ -15973,6 +17097,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; } @@ -15984,6 +17111,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'); @@ -15997,6 +17127,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'); @@ -16011,6 +17144,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'); @@ -16035,6 +17171,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; @@ -16075,6 +17214,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; @@ -16096,6 +17239,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; @@ -16114,6 +17261,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(); } @@ -16168,6 +17318,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; } @@ -16199,6 +17353,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'); @@ -16236,16 +17394,69 @@ Ember.Routable = Ember.Mixin.create({ router.send('unroutePath', path); }, + parentTemplate: Ember.computed(function() { + var state = this, parentState, template; + + while (state = get(state, 'parentState')) { + if (template = get(state, 'template')) { + return template; + } + } + + return 'application'; + }).cacheable(), + + _template: Ember.computed(function(key, value) { + if (arguments.length > 1) { return value; } + + if (value = get(this, 'template')) { + return value; + } + + // If no template was explicitly supplied convert + // the class name into a template name. For example, + // App.PostRoute will return `post`. + var className = this.constructor.toString(), baseName; + if (/^[^\[].*Route$/.test(className)) { + baseName = className.match(/([^\.]+\.)*([^\.]+)/)[2]; + baseName = baseName.replace(/Route$/, ''); + return baseName.charAt(0).toLowerCase() + baseName.substr(1); + } + }).cacheable(), + + render: function(options) { + options = options || {}; + + var template = options.template || get(this, '_template'), + parentTemplate = options.into || get(this, 'parentTemplate'), + controller = get(this.router, parentTemplate + "Controller"); + + var viewName = Ember.String.classify(template) + "View", + viewClass = get(get(this.router, 'namespace'), viewName); + + viewClass = (viewClass || Ember.View).extend({ + templateName: template + }); + + controller.set('view', viewClass.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 }); @@ -16256,9 +17467,15 @@ Ember.Routable = Ember.Mixin.create({ (function() { /** - @class + �� module ember + �� submodule ember-routing +*/ + +/** + @class Route + @namespace Ember @extends Ember.State - @extends Ember.Routable + @uses Ember.Routable */ Ember.Route = Ember.State.extend(Ember.Routable); @@ -16271,6 +17488,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, @@ -16329,9 +17552,14 @@ 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: @@ -16343,17 +17571,19 @@ var get = Ember.get, set = Ember.set; Calling setURL will not trigger onUpdateURL callbacks. - TODO: This, as well as the Ember.Location documentation below, should - perhaps be moved so that it's visible in the JsDoc output. + TODO: This should perhaps be moved so that it's visible in the doc output. */ -/** - @class +/** 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) { @@ -16378,20 +17608,24 @@ Ember.Location = { (function() { +/** + �� module ember + �� submodule ember-routing +*/ + var get = Ember.get, set = Ember.set; /** - @class - 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( -/** @scope Ember.NoneLocation.prototype */ { +Ember.NoneLocation = Ember.Object.extend({ path: '', getURL: function() { @@ -16421,21 +17655,24 @@ Ember.Location.registerImplementation('none', Ember.NoneLocation); (function() { +/** + �� module ember + �� submodule ember-routing +*/ + var get = Ember.get, set = Ember.set; /** - @class - 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( -/** @scope Ember.HashLocation.prototype */ { +Ember.HashLocation = Ember.Object.extend({ - /** @private */ init: function() { set(this, 'location', get(this, 'location') || window.location); }, @@ -16444,6 +17681,8 @@ Ember.HashLocation = Ember.Object.extend( @private Returns the current `location.hash`, minus the '#' at the front. + + @method getURL */ getURL: function() { return get(this, 'location').hash.substr(1); @@ -16455,6 +17694,9 @@ Ember.HashLocation = Ember.Object.extend( 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; @@ -16467,6 +17709,9 @@ Ember.HashLocation = Ember.Object.extend( 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; @@ -16490,12 +17735,14 @@ Ember.HashLocation = Ember.Object.extend( 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; }, - /** @private */ willDestroy: function() { var guid = Ember.guidFor(this); @@ -16510,20 +17757,23 @@ Ember.Location.registerImplementation('hash', Ember.HashLocation); (function() { +/** + �� module ember + �� submodule ember-routing +*/ + var get = Ember.get, set = Ember.set; /** - @class - 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( -/** @scope Ember.HistoryLocation.prototype */ { +Ember.HistoryLocation = Ember.Object.extend({ - /** @private */ init: function() { set(this, 'location', get(this, 'location') || window.location); set(this, '_initialURL', get(this, 'location').pathname); @@ -16531,20 +17781,28 @@ Ember.HistoryLocation = Ember.Object.extend( /** 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; @@ -16554,12 +17812,15 @@ Ember.HistoryLocation = Ember.Object.extend( @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.formatPath(path); + path = this.formatURL(path); if ((initialURL !== path && !state) || (state && state.path !== path)) { window.history.pushState({ path: path }, null, path); @@ -16571,6 +17832,9 @@ Ember.HistoryLocation = Ember.Object.extend( 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); @@ -16583,29 +17847,21 @@ Ember.HistoryLocation = Ember.Object.extend( /** @private - returns the given path appended to rootURL - */ - formatPath: function(path) { + 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 (path !== '') { + if (url !== '') { rootURL = rootURL.replace(/\/$/, ''); } - return rootURL + path; - }, - - /** - @private - - Used when using {{action}} helper. Since no formatting - is required we just return the url given. - */ - formatURL: function(url) { - return url; + return rootURL + url; }, - /** @private */ willDestroy: function() { var guid = Ember.guidFor(this); @@ -16626,6 +17882,11 @@ Ember.Location.registerImplementation('history', Ember.HistoryLocation); (function() { +/** + �� module ember + �� submodule ember-routing +*/ + var get = Ember.get, set = Ember.set; var merge = function(original, hash) { @@ -16638,8 +17899,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 @@ -16932,12 +18191,14 @@ var merge = function(original, hash) { 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. @@ -16950,31 +18211,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); + } + }) + anotherState: Ember.Route.extend({ + route: '/differentUrl', + connectOutlets: function(router, context) { - } - }) - }) + } }) - }); - App.initialize(); + }) + }) + }); + App.initialize(); + ``` The following template: - <script type="text/x-handlebars" data-template-name="aView"> - <h1><a {{action anActionOnTheRouter}}>{{title}}</a></h1> - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name="aView"> + <h1><a {{action anActionOnTheRouter}}>{{title}}</a></h1> + </script> + ``` 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 @@ -16983,39 +18248,44 @@ var merge = function(original, hash) { Different `context` can be supplied from within the `{{action}}` helper, allowing specific context passing between application states: - <script type="text/x-handlebars" data-template-name="photos"> - {{#each photo in controller}} - <h1><a {{action showPhoto photo}}>{{title}}</a></h1> - {{/each}} - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name="photos"> + {{#each photo in controller}} + <h1><a {{action showPhoto photo}}>{{title}}</a></h1> + {{/each}} + </script> + ``` - 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 @@ -17027,13 +18297,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', @@ -17043,9 +18316,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' */ @@ -17055,20 +18331,13 @@ 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 '/' */ rootURL: '/', - /** - On router, transitionEvent should be called connectOutlets - - @property {String} - @default 'connectOutlets' - */ - transitionEvent: 'connectOutlets', - transitionTo: function() { this.abortRoutingPromises(); this._super.apply(this, arguments); @@ -17082,6 +18351,7 @@ Ember.Router = Ember.StateManager.extend( var routableState; try { + path = path.replace(get(this, 'rootURL'), ''); path = path.replace(/^(?=[^\/])/, "/"); this.send('navigateAway'); @@ -17138,7 +18408,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; @@ -17158,9 +18427,6 @@ Ember.Router = Ember.StateManager.extend( } }, - /** - @private - */ handleStatePromises: function(states, complete) { this.abortRoutingPromises(); @@ -17190,7 +18456,6 @@ Ember.Router = Ember.StateManager.extend( }).start(); }, - /** @private */ init: function() { this._super(); @@ -17203,9 +18468,23 @@ Ember.Router = Ember.StateManager.extend( rootURL: rootURL })); } + + this.assignRouter(this, this); + }, + + assignRouter: function(state, router) { + state.router = router; + + var childStates = state.states; + + if (childStates) { + for (var stateName in childStates) { + if (!childStates.hasOwnProperty(stateName)) { continue; } + this.assignRouter(childStates[stateName], router); + } + } }, - /** @private */ willDestroy: function() { get(this, 'location').destroy(); } @@ -17216,11 +18495,13 @@ Ember.Router = Ember.StateManager.extend( (function() { -// ========================================================================== -// Project: Ember Routing -// Copyright: ©2012 Tilde Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +Ember Routing + + �� module ember + �� submodule ember-routing + �� requires ember-states +*/ })(); @@ -17628,31 +18909,18 @@ Ember.Router = Ember.StateManager.extend( })(); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== /*globals Handlebars */ -var objectCreate = Ember.create; - /** - @namespace - @name Handlebars - @private + �� module ember + �� submodule ember-handlebars */ -/** - @namespace - @name Handlebars.helpers - @description Helpers for Handlebars templates -*/ +var objectCreate = Ember.create; + 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. @@ -17662,20 +18930,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; @@ -17687,22 +18971,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) { @@ -17726,6 +19017,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) { @@ -17752,7 +19046,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); @@ -17764,10 +19062,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) || {}, @@ -17798,16 +19102,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), @@ -17828,6 +19135,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. @@ -17835,7 +19144,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 */ @@ -17855,7 +19165,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); }; @@ -17865,7 +19179,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); @@ -17879,6 +19196,11 @@ 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 @@ -17925,6 +19247,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: '', @@ -17951,6 +19279,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); @@ -17959,19 +19294,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 */ -var get = Ember.get, set = Ember.set, getPath = Ember.Handlebars.getPath; /** - @ignore - @private - @class + �� module ember + �� submodule ember-handlebars +*/ +var get = Ember.get, set = Ember.set, getPath = Ember.Handlebars.getPath; +/** Ember._HandlebarsBoundView is a private view created by the Handlebars `{{bind}}` helpers that is used to keep track of bound properties. @@ -17979,15 +19310,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 */ @@ -18004,6 +19340,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ foo}}` because the template should receive the object found by evaluating `foo`. + @property preserveContext @type Boolean @default false */ @@ -18013,6 +19350,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, @@ -18020,6 +19358,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ /** The template to render when `shouldDisplayFunc` evaluates to true. + @property displayTemplate @type Function @default null */ @@ -18028,6 +19367,7 @@ Ember._HandlebarsBoundView = Ember._MetamorphView.extend({ /** The template to render when `shouldDisplayFunc` evaluates to false. + @property inverseTemplate @type Function @default null */ @@ -18041,6 +19381,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 */ @@ -18052,6 +19393,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, @@ -18091,11 +19433,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) { @@ -18162,11 +19505,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; @@ -18175,7 +19518,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, @@ -18209,9 +19551,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 @@ -18229,6 +19570,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 @@ -18236,11 +19579,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); @@ -18253,11 +19596,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 @@ -18266,11 +19613,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); @@ -18283,18 +19630,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; @@ -18310,10 +19661,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) { @@ -18343,7 +19695,7 @@ EmberHandlebars.registerHelper('with', function(context, options) { Ember.bind(options.data.keywords, keywordName, contextPath); } - return bind.call(this, path, options.fn, true, function(result) { + return bind.call(this, path, options, true, function(result) { return !Ember.none(result); }); } else { @@ -18355,10 +19707,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); @@ -18368,10 +19721,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); @@ -18389,11 +19743,14 @@ EmberHandlebars.registerHelper('unless', function(context, options) { `bindAttr` allows you to create a binding between DOM element attributes and Ember objects. For example: - <img {{bindAttr src="imageUrl" alt="imageTitle"}}> + ``` handlebars + <img {{bindAttr src="imageUrl" alt="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) { @@ -18440,7 +19797,6 @@ EmberHandlebars.registerHelper('bindAttr', function(options) { var observer, invoker; - /** @private */ observer = function observer() { var result = getPath(pathRoot, path, options); @@ -18460,9 +19816,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. @@ -18488,6 +19843,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 @@ -18499,19 +19856,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; @@ -18559,7 +19910,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); @@ -18586,9 +19936,8 @@ EmberHandlebars.bindClasses = function(context, classBindings, view, bindAttrId, } }; - /** @private */ invoker = function() { - Ember.run.once(observer); + Ember.run.scheduleOnce('render', observer); }; if (path !== '' && path !== 'this') { @@ -18617,20 +19966,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) { @@ -18775,65 +20123,77 @@ EmberHandlebars.ViewHelper = Ember.Object.create({ An empty `<body>` and the following template: - <script type="text/x-handlebars"> - A span: - {{#view tagName="span"}} - hello. - {{/view}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + A span: + {{#view tagName="span"}} + hello. + {{/view}} + </script> + ``` Will result in HTML structure: - <body> - <!-- Note: the handlebars template script - also results in a rendered Ember.View - which is the outer <div> here --> - - <div class="ember-view"> - A span: - <span id="ember1" class="ember-view"> - Hello. - </span> - </div> - </body> + ``` html + <body> + <!-- Note: the handlebars template script + also results in a rendered Ember.View + which is the outer <div> here --> + + <div class="ember-view"> + A span: + <span id="ember1" class="ember-view"> + Hello. + </span> + </div> + </body> + ``` ### 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}}") - }) + ``` javascript + aView = Ember.View.create({ + template: Ember.Handlebars.compile("{{#view}} my parent: {{parentView.elementId}} {{/view}}") + }); - aView.appendTo('body') + aView.appendTo('body'); + ``` Will result in HTML structure: - <div id="ember1" class="ember-view"> - <div id="ember2" class="ember-view"> - my parent: ember1 - </div> - </div> + ``` html + <div id="ember1" class="ember-view"> + <div id="ember2" class="ember-view"> + my parent: ember1 + </div> + </div> + ``` ### 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`. - <script type="text/x-handlebars"> - {{#view tagName="span" id="a-custom-id"}} - hello. - {{/view}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#view tagName="span" id="a-custom-id"}} + hello. + {{/view}} + </script> + ``` Results in the following HTML structure: - <div class="ember-view"> - <span id="a-custom-id" class="ember-view"> - hello. - </span> - </div> + ``` html + <div class="ember-view"> + <span id="a-custom-id" class="ember-view"> + hello. + </span> + </div> + ``` The HTML `class` attribute can be set on the `{{view}}`'s resulting element with the `class` or `classNameBindings` options. The `class` option @@ -18841,50 +20201,61 @@ EmberHandlebars.ViewHelper = Ember.Object.create({ `Ember.View.create`. `classNameBindings` will be passed to `create` and use `Ember.View`'s class name binding functionality: - <script type="text/x-handlebars"> - {{#view tagName="span" class="a-custom-class"}} - hello. - {{/view}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#view tagName="span" class="a-custom-class"}} + hello. + {{/view}} + </script> + ``` Results in the following HTML structure: - <div class="ember-view"> - <span id="ember2" class="ember-view a-custom-class"> - hello. - </span> - </div> + ``` html + <div class="ember-view"> + <span id="ember2" class="ember-view a-custom-class"> + hello. + </span> + </div> + ``` ### 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. - <script type="text/x-handlebars"> - {{#view "MyApp.CustomView"}} - hello. - {{/view}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#view "MyApp.CustomView"}} + hello. + {{/view}} + </script> + ``` 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: - <div id="ember1" class="ember-view"> - <div id="ember2" class="ember-view a-custom-view-class-as-property"> - hi - </div> - </div> + ``` html + <div id="ember1" class="ember-view"> + <div id="ember2" class="ember-view a-custom-view-class-as-property"> + hi + </div> + </div> + ``` ### Blockless use @@ -18892,26 +20263,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. - <script type="text/x-handlebars"> - {{view "MyApp.ViewWithATemplateDefined"}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{view "MyApp.ViewWithATemplateDefined"}} + </script> + ``` ### 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); @@ -18931,14 +20307,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; /** @@ -18955,28 +20331,34 @@ var get = Ember.get, getPath = Ember.Handlebars.getPath, fmt = Ember.String.fmt; Given an empty `<body>` the following template: - <script type="text/x-handlebars"> - {{#collection contentBinding="App.items"}} - Hi {{content.name}} - {{/collection}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#collection contentBinding="App.items"}} + Hi {{view.content.name}} + {{/collection}} + </script> + ``` 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 - <div class="ember-view"> - <div class="ember-view">Hi Dave</div> - <div class="ember-view">Hi Mary</div> - <div class="ember-view">Hi Sara</div> - </div> + ``` html + <div class="ember-view"> + <div class="ember-view">Hi Dave</div> + <div class="ember-view">Hi Mary</div> + <div class="ember-view">Hi Sara</div> + </div> + ``` ### Blockless Use If you provide an `itemViewClass` option that has its own `template` you can omit @@ -18984,68 +20366,83 @@ var get = Ember.get, getPath = Ember.Handlebars.getPath, fmt = Ember.String.fmt; The following template: - <script type="text/x-handlebars"> - {{collection contentBinding="App.items" itemViewClass="App.AnItemView"}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{collection contentBinding="App.items" itemViewClass="App.AnItemView"}} + </script> + ``` 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 - <div class="ember-view"> - <div class="ember-view">Greetings Dave</div> - <div class="ember-view">Greetings Mary</div> - <div class="ember-view">Greetings Sara</div> - </div> + ``` html + <div class="ember-view"> + <div class="ember-view">Greetings Dave</div> + <div class="ember-view">Greetings Mary</div> + <div class="ember-view">Greetings Sara</div> + </div> + ``` ### 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: - <script type="text/x-handlebars"> - {{#collection App.MyCustomCollectionClass contentBinding="App.items"}} - Hi {{content.name}} - {{/collection}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#collection App.MyCustomCollectionClass contentBinding="App.items"}} + Hi {{view.content.name}} + {{/collection}} + </script> + ``` ### 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): - <script type="text/x-handlebars"> - {{#collection contentBinding="App.items" - itemTagName="p" - itemClassNames="greeting"}} - Howdy {{content.name}} - {{/collection}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#collection contentBinding="App.items" + itemTagName="p" + itemClassNames="greeting"}} + Howdy {{view.content.name}} + {{/collection}} + </script> + ``` Will result in the following HTML structure: - <div class="ember-view"> - <p class="ember-view greeting">Howdy Dave</p> - <p class="ember-view greeting">Howdy Mary</p> - <p class="ember-view greeting">Howdy Sara</p> - </div> - - @name Handlebars.helpers.collection + ``` html + <div class="ember-view"> + <p class="ember-view greeting">Howdy Dave</p> + <p class="ember-view greeting">Howdy Mary</p> + <p class="ember-view greeting">Howdy Sara</p> + </div> + ``` + + @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. @@ -19125,30 +20522,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. - <div>{{unbound somePropertyThatDoesntChange}}</div> + ``` handlebars + <div>{{unbound somePropertyThatDoesntChange}}</div> + ``` - @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; @@ -19160,22 +20558,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) { @@ -19191,9 +20591,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() { @@ -19205,6 +20608,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, { @@ -19238,32 +20646,88 @@ Ember.Handlebars.EachView = Ember.CollectionView.extend(Ember._Metamorph, { }); /** - The `{{#each}}` helper loops over elements in a collection, rendering its block once for each item: - - Developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}]; - - {{#each Developers}} - {{name}} - {{/each}} - - + + ``` javascript + Developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}]; + ``` + + ``` handlebars + {{#each Developers}} + {{name}} + {{/each}} + ``` + `{{each}}` supports an alternative syntax with element naming: - - {{#each person in Developers}} - {{person.name}} - {{/each}} - + + ``` 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: - - DeveloperNames = ['Yehuda', 'Tom', 'Paul'] - - {{#each DeveloperNames}} - {{this}} - {{/each}} - - - @name Handlebars.helpers.each + + ``` 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 + <script type="text/x-handlebars"> + {{#view App.MyView }} + {{each view.items itemViewClass="App.AnItemView"}} + {{/view}} + </script> + ``` + + 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 + <div class="ember-view"> + <div class="ember-view">Greetings Dave</div> + <div class="ember-view">Greetings Mary</div> + <div class="ember-view">Greetings Sara</div> + </div> + ``` + + + @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) { @@ -19280,8 +20744,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; @@ -19295,20 +20757,27 @@ 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: - <script type="text/x-handlebars"> - {{#with loggedInUser}} - Last Login: {{lastLogin}} - User Info: {{template "user_info"}} - {{/with}} - </script> + ``` handlebars + <script type="text/x-handlebars"> + {{#with loggedInUser}} + Last Login: {{lastLogin}} + User Info: {{template "user_info"}} + {{/with}} + </script> - <script type="text/x-handlebars" data-template-name="user_info"> - Name: <em>{{name}}</em> - Karma: <em>{{karma}}</em> - </script> + <script type="text/x-handlebars" data-template-name="user_info"> + Name: <em>{{name}}</em> + Karma: <em>{{karma}}</em> + </script> + ``` 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, @@ -19316,9 +20785,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('<b>{{user}}</b>'); + ``` javascript + Ember.TEMPLATES["my_cool_template"] = Ember.Handlebars.compile('<b>{{user}}</b>'); + ``` - @name Handlebars.helpers.template + @method template + @for Ember.Handlebars.helpers @param {String} templateName the template to render */ @@ -19335,6 +20807,11 @@ Ember.Handlebars.registerHelper('template', function(name, options) { (function() { +/** + �� module ember + �� submodule ember-handlebars +*/ + var EmberHandlebars = Ember.Handlebars, getPath = EmberHandlebars.getPath, get = Ember.get, @@ -19393,36 +20870,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 - <script type="text/x-handlebars" data-template-name='a-template'> - <div {{action anActionName}}> - click me - </div> - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name='a-template'> + <div {{action anActionName}}> + click me + </div> + </script> + ``` 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 - <div class="ember-view"> - <div data-ember-action="1"> - click me - </div> - </div> + ``` html + <div class="ember-view"> + <div data-ember-action="1"> + click me + </div> + </div> + ``` Clicking "click me" will trigger the `anActionName` method of the `aView` object with a `jQuery.Event` object as its argument. The `jQuery.Event` @@ -19445,11 +20928,13 @@ ActionHelper.registerAction = function(actionName, options) { 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: - <script type="text/x-handlebars" data-template-name='a-template'> - <div {{action anActionName on="doubleClick"}}> - click me - </div> - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name='a-template'> + <div {{action anActionName on="doubleClick"}}> + click me + </div> + </script> + ``` See Ember.View 'Responding to Browser Events' for a list of acceptable DOM event names. @@ -19469,7 +20954,7 @@ ActionHelper.registerAction = function(actionName, options) { 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. @@ -19480,11 +20965,13 @@ ActionHelper.registerAction = function(actionName, options) { will receive the method call. This option must be a string representing a path to an object: - <script type="text/x-handlebars" data-template-name='a-template'> - <div {{action anActionName target="MyApplication.someObject"}}> - click me - </div> - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name='a-template'> + <div {{action anActionName target="MyApplication.someObject"}}> + click me + </div> + </script> + ``` Clicking "click me" in the rendered HTML of the above template will trigger the `anActionName` method of the object at `MyApplication.someObject`. @@ -19494,11 +20981,13 @@ ActionHelper.registerAction = function(actionName, options) { A path relative to the template's `Ember.View` instance can also be used as a target: - <script type="text/x-handlebars" data-template-name='a-template'> - <div {{action anActionName target="parentView"}}> - click me - </div> - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name='a-template'> + <div {{action anActionName target="parentView"}}> + click me + </div> + </script> + ``` Clicking "click me" in the rendered HTML of the above template will trigger the `anActionName` method of the view's parent view. @@ -19511,22 +21000,26 @@ 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. - <script type="text/x-handlebars" data-template-name='a-template'> - <div {{action aMethodNameThatIsMissing}}> - click me - </div> - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name='a-template'> + <div {{action aMethodNameThatIsMissing}}> + click me + </div> + </script> + ``` 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. @@ -19537,15 +21030,18 @@ ActionHelper.registerAction = function(actionName, options) { along in the `jQuery.Event` object. You may specify an alternate object to pass as the context by providing a property path: - <script type="text/x-handlebars" data-template-name='a-template'> - {{#each person in people}} - <div {{action edit person}}> - click me - </div> - {{/each}} - </script> + ``` handlebars + <script type="text/x-handlebars" data-template-name='a-template'> + {{#each person in people}} + <div {{action edit person}}> + click me + </div> + {{/each}} + </script> + ``` - @name Handlebars.helpers.action + @method action + @for Ember.Handlebars.helpers @param {String} actionName @param {Object...} contexts @param {Hash} options @@ -19599,6 +21095,11 @@ EmberHandlebars.registerHelper('action', function(actionName) { (function() { +/** + �� module ember + �� submodule ember-handlebars +*/ + var get = Ember.get, set = Ember.set; /** @@ -19609,42 +21110,49 @@ var get = Ember.get, set = Ember.set; An empty `<body>` and the following application code: - AView = Ember.View.extend({ - classNames: ['a-view-with-layout'], - layout: Ember.Handlebars.compile('<div class="wrapper">{{ yield }}</div>'), - template: Ember.Handlebars.compile('<span>I am wrapped</span>') - }) + ``` javascript + AView = Ember.View.extend({ + classNames: ['a-view-with-layout'], + layout: Ember.Handlebars.compile('<div class="wrapper">{{ yield }}</div>'), + template: Ember.Handlebars.compile('<span>I am wrapped</span>') + }); - aView = AView.create() - aView.appendTo('body') + aView = AView.create(); + aView.appendTo('body'); + ``` Will result in the following HTML output: - <body> - <div class='ember-view a-view-with-layout'> - <div class="wrapper"> - <span>I am wrapped</span> - </div> - </div> - </body> + ``` html + <body> + <div class='ember-view a-view-with-layout'> + <div class="wrapper"> + <span>I am wrapped</span> + </div> + </div> + </body> + ``` 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; @@ -19665,32 +21173,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 */ @@ -19710,51 +21232,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 - - Creates an HTML input of type 'checkbox' with HTML related properties - applied directly to the input. + 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. - {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}} + Example: - <input id="ember1" class="ember-view ember-checkbox applicaton-specific-checkbox" type="checkbox"> + ``` handlebars + {{view Ember.Checkbox checkedBinding="receiveEmail"}} + ``` You can add a `label` tag yourself in the template where the Ember.Checkbox is being used. - <label> - Some Title - {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}} - </label> + ``` html + <label> + {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}} + Some Title + </label> + ``` The `checked` attribute of an Ember.Checkbox object should always be set @@ -19766,6 +21280,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({ @@ -19784,9 +21300,6 @@ Ember.Checkbox = Ember.View.extend({ this.on("change", this, this._updateElementValue); }, - /** - @private - */ _updateElementValue: function() { set(this, 'checked', this.$().prop('checked')); } @@ -19797,17 +21310,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'], @@ -19818,7 +21336,6 @@ Ember.TextSupport = Ember.Mixin.create( insertNewline: Ember.K, cancel: Ember.K, - /** @private */ init: function() { this._super(); this.on("focusOut", this, this._elementValueDidChange); @@ -19826,9 +21343,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]; @@ -19853,16 +21367,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`), @@ -19870,14 +21382,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 */ { @@ -19890,6 +21406,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 "" */ @@ -19898,6 +21415,7 @@ Ember.TextField = Ember.View.extend(Ember.TextSupport, /** The type attribute of the input element. + @property type @type String @default "text" */ @@ -19906,6 +21424,7 @@ Ember.TextField = Ember.View.extend(Ember.TextSupport, /** The size of the text field in characters. + @property size @type String @default null */ @@ -19917,13 +21436,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'], @@ -19934,9 +21460,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'), @@ -20036,16 +21566,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`), @@ -20056,12 +21584,12 @@ var get = Ember.get, set = Ember.set; 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", @@ -20078,7 +21606,6 @@ Ember.TextArea = Ember.View.extend(Ember.TextSupport, } }, 'value'), - /** @private */ init: function() { this._super(); this.on("didInsertElement", this, this._updateElementValue); @@ -20091,6 +21618,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."); @@ -20103,8 +21641,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); @@ -20125,8 +21674,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); @@ -20155,12 +21715,15 @@ 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. @@ -20177,37 +21740,48 @@ var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.i Example: - App.Names = ["Yehuda", "Tom"] + ``` javascript + App.Names = ["Yehuda", "Tom"]; + ``` - {{view Ember.Select contentBinding="App.Names"}} + ``` handlebars + {{view Ember.Select contentBinding="App.Names"}} + ``` Would result in the following HTML: - <select class="ember-select"> - <option value="Yehuda">Yehuda</option> - <option value="Tom">Tom</option> - </select> + ``` html + <select class="ember-select"> + <option value="Yehuda">Yehuda</option> + <option value="Tom">Tom</option> + </select> + ``` You can control which `<option>` is selected through the Ember.Select's `value` property directly or as a binding: - App.Names = Ember.Object.create({ - selected: 'Tom', - content: ["Yehuda", "Tom"] - }) + ``` javascript + App.Names = Ember.Object.create({ + selected: 'Tom', + content: ["Yehuda", "Tom"] + }); + ``` - {{view Ember.Select - contentBinding="App.controller.content" - valueBinding="App.controller.selected" - }} + ``` handlebars + {{view Ember.Select + contentBinding="App.controller.content" + valueBinding="App.controller.selected" + }} + ``` Would result in the following HTML with the `<option>` for 'Tom' selected: - <select class="ember-select"> - <option value="Yehuda">Yehuda</option> - <option value="Tom" selected="selected">Tom</option> - </select> - + ``` html + <select class="ember-select"> + <option value="Yehuda">Yehuda</option> + <option value="Tom" selected="selected">Tom</option> + </select> + ``` A user interacting with the rendered `<select>` to choose "Yehuda" would update the value of `App.controller.selected` to "Yehuda". @@ -20225,53 +21799,63 @@ var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.i specifies the path on each object to the desired property for the element's text. Both paths must reference each object itself as 'content': + ``` javascript + App.Programmers = [ + Ember.Object.create({firstName: "Yehuda", id: 1}), + Ember.Object.create({firstName: "Tom", id: 2}) + ]; + ``` - App.Programmers = [ - Ember.Object.create({firstName: "Yehuda", id: 1}), - Ember.Object.create({firstName: "Tom", id: 2}) - ]; - - {{view Ember.Select - contentBinding="App.Programmers" - optionValuePath="content.id" - optionLabelPath="content.firstName"}} + ``` handlebars + {{view Ember.Select + contentBinding="App.Programmers" + optionValuePath="content.id" + optionLabelPath="content.firstName"}} + ``` Would result in the following HTML: - <select class="ember-select"> - <option value>Please Select</option> - <option value="1">Yehuda</option> - <option value="2">Tom</option> - </select> + ``` html + <select class="ember-select"> + <option value>Please Select</option> + <option value="1">Yehuda</option> + <option value="2">Tom</option> + </select> + ``` The `value` attribute of the selected `<option>` within an Ember.Select can be bound to a property on another object by providing a `valueBinding` option: + ``` javascript + App.Programmers = [ + Ember.Object.create({firstName: "Yehuda", id: 1}), + Ember.Object.create({firstName: "Tom", id: 2}) + ]; - App.Programmers = [ - Ember.Object.create({firstName: "Yehuda", id: 1}), - Ember.Object.create({firstName: "Tom", id: 2}) - ]; - - App.currentProgrammer = Ember.Object.create({ - id: 2 - }) + App.currentProgrammer = Ember.Object.create({ + id: 2 + }); + ``` - {{view Ember.Select - contentBinding="App.controller.content" - optionValuePath="content.id" - optionLabelPath="content.firstName" - valueBinding="App.currentProgrammer.id"}} + ``` handlebars + {{view Ember.Select + contentBinding="App.controller.content" + optionValuePath="content.id" + optionLabelPath="content.firstName" + valueBinding="App.currentProgrammer.id"}} + ``` Would result in the following HTML with a selected option: - <select class="ember-select"> - <option value>Please Select</option> - <option value="1">Yehuda</option> - <option value="2" selected="selected">Tom</option> - </select> + ``` html + <select class="ember-select"> + <option value>Please Select</option> + <option value="1">Yehuda</option> + <option value="2" selected="selected">Tom</option> + </select> + ``` Interacting with the rendered element by selecting the first option ('Yehuda') will update the `id` value of `App.currentProgrammer` @@ -20283,27 +21867,33 @@ var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.i will be updated to match the content object of the rendered `<option>` element: - App.controller = Ember.Object.create({ - selectedPerson: null, - content: [ - Ember.Object.create({firstName: "Yehuda", id: 1}), - Ember.Object.create({firstName: "Tom", id: 2}) - ] - }) + ``` javascript + App.controller = Ember.Object.create({ + selectedPerson: null, + content: [ + Ember.Object.create({firstName: "Yehuda", id: 1}), + Ember.Object.create({firstName: "Tom", id: 2}) + ] + }); + ``` - {{view Ember.Select - contentBinding="App.controller.content" - optionValuePath="content.id" - optionLabelPath="content.firstName" - selectionBinding="App.controller.selectedPerson"}} + ``` handlebars + {{view Ember.Select + contentBinding="App.controller.content" + optionValuePath="content.id" + optionLabelPath="content.firstName" + selectionBinding="App.controller.selectedPerson"}} + ``` Would result in the following HTML with a selected option: - <select class="ember-select"> - <option value>Please Select</option> - <option value="1">Yehuda</option> - <option value="2" selected="selected">Tom</option> - </select> + ``` html + <select class="ember-select"> + <option value>Please Select</option> + <option value="1">Yehuda</option> + <option value="2" selected="selected">Tom</option> + </select> + ``` Interacting with the rendered element by selecting the first option @@ -20312,28 +21902,35 @@ var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.i case it is the first object in the `App.content.content` ### Supplying a Prompt + A `null` value for the Ember.Select's `value` or `selection` property results in there being no `<option>` with a `selected` attribute: - App.controller = Ember.Object.create({ - selected: null, - content: [ - "Yehuda", - "Tom" - ] - }) + ``` javascript + App.controller = Ember.Object.create({ + selected: null, + content: [ + "Yehuda", + "Tom" + ] + }); + ``` - {{view Ember.Select - contentBinding="App.controller.content" - valueBinding="App.controller.selected" - }} + ``` handlebars + {{view Ember.Select + contentBinding="App.controller.content" + valueBinding="App.controller.selected" + }} + ``` Would result in the following HTML: - <select class="ember-select"> - <option value="Yehuda">Yehuda</option> - <option value="Tom">Tom</option> - </select> + ``` html + <select class="ember-select"> + <option value="Yehuda">Yehuda</option> + <option value="Tom">Tom</option> + </select> + ``` Although `App.controller.selected` is `null` and no `<option>` has a `selected` attribute the rendered HTML will display the @@ -20341,28 +21938,36 @@ var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.i value for the Ember.Select to display when there is no selection with the `prompt` option: - App.controller = Ember.Object.create({ - selected: null, - content: [ - "Yehuda", - "Tom" - ] - }) + ``` javascript + App.controller = Ember.Object.create({ + selected: null, + content: [ + "Yehuda", + "Tom" + ] + }); + ``` - {{view Ember.Select - contentBinding="App.controller.content" - valueBinding="App.controller.selected" - prompt="Please select a name" - }} + ``` handlebars + {{view Ember.Select + contentBinding="App.controller.content" + valueBinding="App.controller.selected" + prompt="Please select a name" + }} + ``` Would result in the following HTML: - <select class="ember-select"> - <option>Please select a name</option> - <option value="Yehuda">Yehuda</option> - <option value="Tom">Tom</option> - </select> + ``` html + <select class="ember-select"> + <option>Please select a name</option> + <option value="Yehuda">Yehuda</option> + <option value="Tom">Tom</option> + </select> + ``` + @class Select + @namespace Ember @extends Ember.View */ Ember.Select = Ember.View.extend( @@ -20377,6 +21982,7 @@ Ember.Select = Ember.View.extend( The `multiple` attribute of the select element. Indicates whether multiple options can be selected. + @property multiple @type Boolean @default false */ @@ -20397,6 +22003,7 @@ Ember.Select = Ember.View.extend( optionLabelPath: 'content.firstName', optionValuePath: 'content.id' + @property content @type Array @default null */ @@ -20408,6 +22015,7 @@ Ember.Select = Ember.View.extend( When `multiple` is true, an array of such elements. + @property selection @type Object or Array @default null */ @@ -20419,6 +22027,7 @@ Ember.Select = Ember.View.extend( It is not currently supported in multiple selection mode. + @property value @type String @default null */ @@ -20433,6 +22042,7 @@ Ember.Select = Ember.View.extend( If given, a top-most dummy option will be rendered to serve as a user prompt. + @property prompt @type String @default null */ @@ -20441,6 +22051,7 @@ Ember.Select = Ember.View.extend( /** The path of the option labels. See `content`. + @property optionLabelPath @type String @default 'content' */ @@ -20449,6 +22060,7 @@ Ember.Select = Ember.View.extend( /** The path of the option values. See `content`. + @property optionValuePath @type String @default 'content' */ @@ -20554,7 +22166,7 @@ Ember.Select = Ember.View.extend( if (options) { options.each(function() { - adjusted = this.index > -1 ? this.index + offset : -1; + adjusted = this.index > -1 ? this.index - offset : -1; this.selected = indexOf(selectedIndexes, adjusted) > -1; }); } @@ -20587,7 +22199,7 @@ Ember.SelectOption = Ember.View.extend({ var content = get(this, 'content'), selection = get(this, 'parentView.selection'); if (get(this, 'parentView.multiple')) { - return selection && indexOf(selection, content) > -1; + return selection && indexOf(selection, content.valueOf()) > -1; } else { // Primitives get passed through bindings as objects... since // `new Number(4) !== 4`, we use `==` below @@ -20616,37 +22228,40 @@ Ember.SelectOption = Ember.View.extend({ }, 'parentView.optionValuePath') }); - })(); (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) -// ========================================================================== /*globals Handlebars */ -// Find templates stored in the head tag as script tags and make them available -// to Ember.CoreView in the global Ember.TEMPLATES object. This will be run as as -// jQuery DOM-ready callback. -// -// Script tags with "text/x-handlebars" will be compiled -// with Ember's Handlebars and are suitable for use as a view's template. -// Those with type="text/x-raw-handlebars" will be compiled with regular -// Handlebars and are suitable for use in views' computed properties. +/** + �� module ember + �� submodule ember-handlebars +*/ + +/** + @private + + Find templates stored in the head tag as script tags and make them available + to Ember.CoreView in the global Ember.TEMPLATES object. This will be run as as + jQuery DOM-ready callback. + + Script tags with "text/x-handlebars" will be compiled + with Ember's Handlebars and are suitable for use as a view's template. + Those with type="text/x-raw-handlebars" will be compiled with regular + Handlebars and are suitable for use in views' computed properties. + + @method bootstrap + @for Ember.Handlebars + @static + @param ctx +*/ Ember.Handlebars.bootstrap = function(ctx) { var selectors = 'script[type="text/x-handlebars"], script[type="text/x-raw-handlebars"]'; @@ -20662,53 +22277,17 @@ Ember.Handlebars.bootstrap = function(ctx) { // Get the name of the script, used by Ember.View's templateName property. // First look for data-template-name attribute, then fall back to its // id if no name is found. - templateName = script.attr('data-template-name') || script.attr('id'), - template = compile(script.html()), - view, viewPath, elementId, options; - - if (templateName) { - // For templates which have a name, we save them and then remove them from the DOM - Ember.TEMPLATES[templateName] = template; - - // Remove script tag from DOM - script.remove(); - } else { - if (script.parents('head').length !== 0) { - // don't allow inline templates in the head - throw new Ember.Error("Template found in <head> without a name specified. " + - "Please provide a data-template-name attribute.\n" + - script.html()); - } - - // For templates which will be evaluated inline in the HTML document, instantiates a new - // view, and replaces the script tag holding the template with the new - // view's DOM representation. - // - // Users can optionally specify a custom view subclass to use by setting the - // data-view attribute of the script tag. - viewPath = script.attr('data-view'); - view = viewPath ? Ember.get(viewPath) : Ember.View; - - // Get the id of the script, used by Ember.View's elementId property, - // Look for data-element-id attribute. - elementId = script.attr('data-element-id'); - - options = { template: template }; - if (elementId) { options.elementId = elementId; } - - view = view.create(options); + templateName = script.attr('data-template-name') || script.attr('id') || 'application', + template = compile(script.html()); - view._insertElementLater(function() { - script.replaceWith(this.$()); + // For templates which have a name, we save them and then remove them from the DOM + Ember.TEMPLATES[templateName] = template; - // Avoid memory leak in IE - script = null; - }); - } + // Remove script tag from DOM + script.remove(); }); }; -/** @private */ function bootstrap() { Ember.Handlebars.bootstrap( Ember.$(document) ); } @@ -20724,7 +22303,6 @@ function bootstrap() { from the DOM after processing. */ -Ember.$(document).ready(bootstrap); Ember.onLoad('application', bootstrap); })(); @@ -20732,24 +22310,26 @@ Ember.onLoad('application', bootstrap); (function() { -// ========================================================================== -// Project: Ember Handlebars Views -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +Ember Handlebars + + �� module ember + �� submodule ember-handlebars + �� requires ember-views +*/ })(); -// Version: v1.0.pre-68-ge60e818 -// Last commit: e60e818 (2012-08-24 14:59:34 -0700) +// Version: v1.0.pre-149-g117655b +// Last commit: 117655b (2012-09-18 10:22:34 -0700) (function() { -// ========================================================================== -// Project: Ember -// Copyright: ©2011 Strobe Inc. and contributors. -// License: Licensed under MIT license (see license.js) -// ========================================================================== +/** +Ember + + �� module ember +*/ })();
