-// Version: v1.0.pre-160-g7d62790
-// Last commit: 7d62790 (2012-09-26 15:59:36 -0700)
-
+// Version: v1.0.0-pre.4
+// Last commit: 855db1a (2013-01-17 23:06:53 -0800)
(function() {
/*global __fail__*/
/**
Define an assertion that will throw an exception if the condition is not
- met. Ember build tools will remove any calls to Ember.assert() when
+ met. Ember build tools will remove any calls to `Ember.assert()` when
doing a production build. Example:
- // Test for truthiness
- Ember.assert('Must pass a valid object', obj);
- // Fail unconditionally
- Ember.assert('This code path should never be run')
+ ```javascript
+ // Test for truthiness
+ Ember.assert('Must pass a valid object', obj);
+ // Fail unconditionally
+ Ember.assert('This code path should never be run')
+ ```
@method assert
- @param {String} desc A description of the assertion. This will become
+ @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.
*/
/**
Display a warning with the provided message. Ember build tools will
- remove any calls to Ember.warn() when doing a production build.
+ remove any calls to `Ember.warn()` when doing a production build.
@method warn
@param {String} message A warning to display.
/**
Display a deprecation warning with the provided message and a stack trace
(Chrome and Firefox only). Ember build tools will remove any calls to
- Ember.deprecate() when doing a production build.
+ `Ember.deprecate()` when doing a production build.
@method deprecate
@param {String} message A description of the deprecation.
Display a deprecation warning with the provided message and a stack trace
(Chrome and Firefox only) when the wrapped method is called.
- Ember build tools will not remove calls to Ember.deprecateFunc(), though
+ Ember build tools will not remove calls to `Ember.deprecateFunc()`, though
no warnings will be shown in production.
@method deprecateFunc
};
};
-
-window.ember_assert = Ember.deprecateFunc("ember_assert is deprecated. Please use Ember.assert instead.", Ember.assert);
-window.ember_warn = Ember.deprecateFunc("ember_warn is deprecated. Please use Ember.warn instead.", Ember.warn);
-window.ember_deprecate = Ember.deprecateFunc("ember_deprecate is deprecated. Please use Ember.deprecate instead.", Ember.deprecate);
-window.ember_deprecateFunc = Ember.deprecateFunc("ember_deprecateFunc is deprecated. Please use Ember.deprecateFunc instead.", Ember.deprecateFunc);
+if ('undefined' !== typeof window) {
+ window.ember_assert = Ember.deprecateFunc("ember_assert is deprecated. Please use Ember.assert instead.", Ember.assert);
+ window.ember_warn = Ember.deprecateFunc("ember_warn is deprecated. Please use Ember.warn instead.", Ember.warn);
+ window.ember_deprecate = Ember.deprecateFunc("ember_deprecate is deprecated. Please use Ember.deprecate instead.", Ember.deprecate);
+ window.ember_deprecateFunc = Ember.deprecateFunc("ember_deprecateFunc is deprecated. Please use Ember.deprecateFunc instead.", Ember.deprecateFunc);
+}
})();
-// Version: v1.0.pre-160-g7d62790
-// Last commit: 7d62790 (2012-09-26 15:59:36 -0700)
+// Version: v1.0.0-pre.3-19-g015138e
+// Last commit: 015138e (2013-01-17 23:02:17 -0800)
+
+
+(function() {
+var define, requireModule;
+
+(function() {
+ var registry = {}, seen = {};
+
+ define = function(name, deps, callback) {
+ registry[name] = { deps: deps, callback: callback };
+ };
+
+ requireModule = function(name) {
+ if (seen[name]) { return seen[name]; }
+ seen[name] = {};
+
+ var mod = registry[name],
+ deps = mod.deps,
+ callback = mod.callback,
+ reified = [],
+ exports;
+ for (var i=0, l=deps.length; i<l; i++) {
+ if (deps[i] === 'exports') {
+ reified.push(exports = {});
+ } else {
+ reified.push(requireModule(deps[i]));
+ }
+ }
+ var value = callback.apply(this, reified);
+ return seen[name] = exports || value;
+ };
+})();
(function() {
/*globals Em:true ENV */
*/
/**
- 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
+ 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.
- You can also use the shorthand "Em" instead of "Ember".
+ You can also use the shorthand `Em` instead of `Ember`.
- Ember-Runtime is a framework that provides core functions for
- Ember including cross-platform functions, support for property
- observing and objects. Its focus is on small size and performance. You can
- use this in place of or along-side other cross-platform libraries such as
- jQuery.
+ Ember-Runtime is a framework that provides core functions for Ember including
+ cross-platform functions, support for property observing and objects. Its
+ focus is on small size and performance. You can use this in place of or
+ along-side other cross-platform libraries such as jQuery.
The core Runtime framework is based on the jQuery API with a number of
performance optimizations.
@class Ember
@static
- @version 1.0.pre
+ @version 1.0.0-pre.4
*/
if ('undefined' === typeof Ember) {
Ember = {};
}
+// Default imports, exports and lookup to the global object;
+var imports = Ember.imports = Ember.imports || this;
+var exports = Ember.exports = Ember.exports || this;
+var lookup = Ember.lookup = Ember.lookup || this;
+
// aliases needed to keep minifiers from removing the global context
-if ('undefined' !== typeof window) {
- window.Em = window.Ember = Em = Ember;
-}
+exports.Em = exports.Ember = Em = Ember;
// Make sure these are set whether Ember was already defined or not
/**
@property VERSION
@type String
- @default '1.0.pre'
+ @default '1.0.0-pre.4'
@final
*/
-Ember.VERSION = '1.0.pre';
+Ember.VERSION = '1.0.0-pre.4';
/**
- Standard environmental variables. You can define these in a global `ENV`
+ Standard environmental variables. You can define these in a global `ENV`
variable before loading Ember to control various configuration
settings.
//
/**
- 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
- enhanced, which is the one that causes most troubles for people.
+ 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 enhanced,
+ which is the one that causes most trouble for people.
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.
+ 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);
+Ember.EXTEND_PROTOTYPES = Ember.ENV.EXTEND_PROTOTYPES;
+
+if (typeof Ember.EXTEND_PROTOTYPES === 'undefined') {
+ Ember.EXTEND_PROTOTYPES = true;
+}
/**
Determines whether Ember logs a full stack trace during deprecation warnings
*/
Ember.SHIM_ES5 = (Ember.ENV.SHIM_ES5 === false) ? false : Ember.EXTEND_PROTOTYPES;
-
-/**
- Determines whether computed properties are cacheable by default.
- This option will be removed for the 1.1 release.
-
- When caching is enabled by default, you can use `volatile()` to disable
- caching on individual computed properties.
-
- @property CP_DEFAULT_CACHEABLE
- @type Boolean
- @default true
-*/
-Ember.CP_DEFAULT_CACHEABLE = (Ember.ENV.CP_DEFAULT_CACHEABLE !== false);
-
-/**
- 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.
-
- If you need to update your application to use the new context rules, simply
- prefix property access with `view.`:
-
- 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.
+ Empty function. Useful for some operations.
@method K
@private
// These are deprecated but still supported
-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_assert) { exports.ember_assert = Ember.K; }
+if ('undefined' === typeof ember_warn) { exports.ember_warn = Ember.K; }
+if ('undefined' === typeof ember_deprecate) { exports.ember_deprecate = Ember.K; }
if ('undefined' === typeof ember_deprecateFunc) {
- window.ember_deprecateFunc = function(_, func) { return func; };
+ exports.ember_deprecateFunc = function(_, func) { return func; };
}
+/**
+ Previously we used `Ember.$.uuid`, however `$.uuid` has been removed from
+ jQuery master. We'll just bootstrap our own uuid now.
+
+ @property uuid
+ @type Number
+ @private
+*/
+Ember.uuid = 0;
// ..........................................................
// LOGGER
//
/**
- Inside Ember-Metal, simply uses the window.console object.
+ Inside Ember-Metal, simply uses the `imports.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 };
+Ember.Logger = imports.console || { log: Ember.K, warn: Ember.K, error: Ember.K, info: Ember.K, debug: Ember.K };
// ..........................................................
//
/**
- 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.
+ 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
}
};
-})();
-
-
-
-(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
-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
-var arrayMap = isNativeFunc(Array.prototype.map) ? Array.prototype.map : function(fun /*, thisp */) {
- //"use strict";
-
- if (this === void 0 || this === null) {
- throw new TypeError();
- }
-
- var t = Object(this);
- var len = t.length >>> 0;
- if (typeof fun !== "function") {
- throw new TypeError();
- }
-
- var res = new Array(len);
- var thisp = arguments[1];
- for (var i = 0; i < len; i++) {
- if (i in t) {
- res[i] = fun.call(thisp, t[i], i, t);
- }
- }
-
- return res;
-};
-
-// From: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/array/foreach
-var arrayForEach = isNativeFunc(Array.prototype.forEach) ? Array.prototype.forEach : function(fun /*, thisp */) {
- //"use strict";
-
- if (this === void 0 || this === null) {
- throw new TypeError();
- }
-
- var t = Object(this);
- var len = t.length >>> 0;
- if (typeof fun !== "function") {
- throw new TypeError();
- }
-
- var thisp = arguments[1];
- for (var i = 0; i < len; i++) {
- if (i in t) {
- fun.call(thisp, t[i], i, t);
- }
- }
-};
-
-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); }
- for (var i = fromIndex, j = this.length; i < j; i++) {
- if (this[i] === obj) { return i; }
- }
- return -1;
-};
-
-Ember.ArrayPolyfills = {
- map: arrayMap,
- forEach: arrayForEach,
- indexOf: arrayIndexOf
-};
-
-var utils = Ember.EnumerableUtils = {
- map: function(obj, callback, thisArg) {
- return obj.map ? obj.map.call(obj, callback, thisArg) : arrayMap.call(obj, callback, thisArg);
- },
-
- forEach: function(obj, callback, thisArg) {
- return obj.forEach ? obj.forEach.call(obj, callback, thisArg) : arrayForEach.call(obj, callback, thisArg);
- },
-
- indexOf: function(obj, element, index) {
- return obj.indexOf ? obj.indexOf.call(obj, element, index) : arrayIndexOf.call(obj, element, index);
- },
-
- indexesOf: function(obj, elements) {
- return elements === undefined ? [] : utils.map(elements, function(item) {
- return utils.indexOf(obj, item);
- });
- },
-
- removeObject: function(array, item) {
- var index = utils.indexOf(array, item);
- if (index !== -1) { array.splice(index, 1); }
+Ember.merge = function(original, updates) {
+ for (var prop in updates) {
+ if (!updates.hasOwnProperty(prop)) { continue; }
+ original[prop] = updates[prop];
}
};
-
-if (Ember.SHIM_ES5) {
- if (!Array.prototype.map) {
- Array.prototype.map = arrayMap;
- }
-
- if (!Array.prototype.forEach) {
- Array.prototype.forEach = arrayForEach;
- }
-
- if (!Array.prototype.indexOf) {
- Array.prototype.indexOf = arrayIndexOf;
- }
-}
-
})();
/**
- Identical to Object.create(). Implements if not available natively.
+ Identical to `Object.create()`. Implements if not available natively.
+
@method create
@for Ember
*/
Ember.create = Object.create;
-if (!Ember.create) {
+// STUB_OBJECT_CREATE allows us to override other libraries that stub
+// Object.create different than we would prefer
+if (!Ember.create || Ember.ENV.STUB_OBJECT_CREATE) {
var K = function() {};
Ember.create = function(obj, props) {
*/
/**
- Identical to Object.defineProperty(). Implements as much functionality
+ Identical to `Object.defineProperty()`. Implements as much functionality
as possible if not available natively.
@method defineProperty
@module ember-metal
*/
+
var o_defineProperty = Ember.platform.defineProperty,
o_create = Ember.create,
// Used for guid generation...
@private
Generates a new guid, optionally saving the guid to the object that you
- pass in. You will rarely need to use this method. Instead you should
- call Ember.guidFor(obj), which return an existing guid if available.
+ pass in. You will rarely need to use this method. Instead you should
+ call `Ember.guidFor(obj)`, which return an existing guid if available.
@method generateGuid
@for Ember
- @param {Object} [obj] Object the guid will be used for. If passed in, the guid will
+ @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] 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.
-
@return {String} the guid
*/
Ember.generateGuid = function generateGuid(obj, prefix) {
/**
@private
- Returns a unique id for the object. If the object does not yet have
- a guid, one will be assigned to it. You can call this on any object,
- Ember.Object-based or not, but be aware that it will add a _guid property.
+ Returns a unique id for the object. If the object does not yet have a guid,
+ one will be assigned to it. You can call this on any object,
+ `Ember.Object`-based or not, but be aware that it will add a `_guid`
+ property.
You can also use this method on DOM Element objects.
// jQuery.extend() by having a property that fails
// hasOwnProperty check.
Meta.prototype.__preventPlainObject__ = true;
+
+ // Without non-enumerable properties, meta objects will be output in JSON
+ // unless explicitly suppressed
+ Meta.prototype.toJSON = function () { };
}
/**
- Retrieves the meta hash for an object. If 'writable' is true ensures the
+ Retrieves the meta hash for an object. If `writable` is true ensures the
hash is writable for this object as well.
The meta object contains information about computed property descriptors as
- well as any watched properties and other information. You generally will
+ well as any watched properties and other information. You generally will
not access this information directly but instead work with higher level
methods that manipulate this hash indirectly.
@private
@param {Object} obj The object to retrieve meta for
-
- @param {Boolean} [writable=true] Pass false if you do not intend to modify
+ @param {Boolean} [writable=true] Pass `false` if you do not intend to modify
the meta hash, allowing the method to avoid making an unnecessary copy.
-
@return {Hash}
*/
Ember.meta = function meta(obj, writable) {
This method allows extensions to deeply clone a series of nested hashes or
other complex objects. For instance, the event system might pass
- ['listeners', 'foo:change', 'ember157'] to `prepareMetaPath`, which will
+ `['listeners', 'foo:change', 'ember157']` to `prepareMetaPath`, which will
walk down the keys provided.
For each key, if the key does not exist, it is created. If it already
@private
Wraps the passed function so that `this._super` will point to the superFunc
- when the function is invoked. This is the primitive we use to implement
+ when the function is invoked. This is the primitive we use to implement
calls to super.
@method wrap
@return {Function} wrapped function.
*/
Ember.wrap = function(func, superFunc) {
-
function K() {}
- var newFunc = function() {
+ function superWrapper() {
var ret, sup = this._super;
this._super = superFunc || K;
ret = func.apply(this, arguments);
this._super = sup;
return ret;
- };
+ }
- newFunc.base = func;
- return newFunc;
+ superWrapper.wrappedFunction = func;
+ superWrapper.__ember_observes__ = func.__ember_observes__;
+ superWrapper.__ember_observesBefore__ = func.__ember_observesBefore__;
+
+ return superWrapper;
};
/**
- the object is a native Array
- the object is an Object, and has a length property
- Unlike Ember.typeOf this method returns true even if the passed object is
- not formally array but appears to be array-like (i.e. implements Ember.Array)
+ Unlike `Ember.typeOf` this method returns true even if the passed object is
+ not formally array but appears to be array-like (i.e. implements `Ember.Array`)
- Ember.isArray(); // false
- Ember.isArray([]); // true
- Ember.isArray( Ember.ArrayProxy.create({ content: [] }) ); // true
+ ```javascript
+ Ember.isArray(); // false
+ Ember.isArray([]); // true
+ Ember.isArray( Ember.ArrayProxy.create({ content: [] }) ); // true
+ ```
@method isArray
@for Ember
};
/**
- Forces the passed object to be part of an array. If the object is already
- an array or array-like, returns the object. Otherwise adds the object to
- an array. If obj is null or undefined, returns an empty array.
-
- Ember.makeArray(); => []
- Ember.makeArray(null); => []
- Ember.makeArray(undefined); => []
- Ember.makeArray('lindsay'); => ['lindsay']
- Ember.makeArray([1,2,42]); => [1,2,42]
+ Forces the passed object to be part of an array. If the object is already
+ an array or array-like, returns the object. Otherwise adds the object to
+ an array. If obj is `null` or `undefined`, returns an empty array.
- var controller = Ember.ArrayProxy.create({ content: [] });
- Ember.makeArray(controller) === controller; => true
+ ```javascript
+ Ember.makeArray(); // []
+ Ember.makeArray(null); // []
+ Ember.makeArray(undefined); // []
+ Ember.makeArray('lindsay'); // ['lindsay']
+ Ember.makeArray([1,2,42]); // [1,2,42]
+
+ var controller = Ember.ArrayProxy.create({ content: [] });
+ Ember.makeArray(controller) === controller; // true
+ ```
@method makeArray
@for Ember
}
};
-})();
-
+// https://github.com/emberjs/ember.js/pull/1617
+var needsFinallyFix = (function() {
+ var count = 0;
+ try{
+ try { }
+ finally {
+ count++;
+ throw new Error('needsFinallyFixTest');
+ }
+ } catch (e) {}
+ return count !== 1;
+})();
-(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.
+ Provides try { } finally { } functionality, while working
+ around Safari's double finally bug.
- Because Ember has a way to get a unique identifier for every object
- via `Ember.guidFor`, we can implement a performant Map with arbitrary
- keys. Because it is commonly used in low-level bookkeeping, Map is
- implemented as a pure JavaScript object for performance.
+ @method tryFinally
+ @for Ember
+ @param {Function} function The function to run the try callback
+ @param {Function} function The function to run the finally callback
+ @param [binding]
+ @return {anything} The return value is the that of the finalizer,
+ unless that valueis undefined, in which case it is the return value
+ of the tryable
+*/
- This implementation follows the current iteration of the ES6 proposal
- for maps (http://wiki.ecmascript.org/doku.php?id=harmony:simple_maps_and_sets),
- with two exceptions. First, because we need our implementation to be
- pleasant on older browsers, we do not use the `delete` name (using
- `remove` instead). Second, as we do not have the luxury of in-VM
- iteration, we implement a forEach method for iteration.
+if (needsFinallyFix) {
+ Ember.tryFinally = function(tryable, finalizer, binding) {
+ var result, finalResult, finalError;
- Map is mocked out to look like an Ember object, so you can do
- `Ember.Map.create()` for symmetry with other Ember classes.
-*/
-var guidFor = Ember.guidFor,
- indexOf = Ember.ArrayPolyfills.indexOf;
+ binding = binding || this;
-var copy = function(obj) {
- var output = {};
+ try {
+ result = tryable.call(binding);
+ } finally {
+ try {
+ finalResult = finalizer.call(binding);
+ } catch (e){
+ finalError = e;
+ }
+ }
- for (var prop in obj) {
- if (obj.hasOwnProperty(prop)) { output[prop] = obj[prop]; }
- }
+ if (finalError) { throw finalError; }
- return output;
-};
+ return (finalResult === undefined) ? result : finalResult;
+ };
+} else {
+ Ember.tryFinally = function(tryable, finalizer, binding) {
+ var result, finalResult;
-var copyMap = function(original, newObject) {
- var keys = original.keys.copy(),
- values = copy(original.values);
+ binding = binding || this;
- newObject.keys = keys;
- newObject.values = values;
+ try {
+ result = tryable.call(binding);
+ } finally {
+ finalResult = finalizer.call(binding);
+ }
- return newObject;
-};
+ return (finalResult === undefined) ? result : finalResult;
+ };
+}
/**
- 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.
+ Provides try { } catch finally { } functionality, while working
+ around Safari's double finally bug.
- @class OrderedSet
- @namespace Ember
- @constructor
- @private
+ @method tryCatchFinally
+ @for Ember
+ @param {Function} function The function to run the try callback
+ @param {Function} function The function to run the catchable callback
+ @param {Function} function The function to run the finally callback
+ @param [binding]
+ @return {anything} The return value is the that of the finalizer,
+ unless that value is undefined, in which case it is the return value
+ of the tryable.
*/
-var OrderedSet = Ember.OrderedSet = function() {
- this.clear();
-};
+if (needsFinallyFix) {
+ Ember.tryCatchFinally = function(tryable, catchable, finalizer, binding) {
+ var result, finalResult, finalError, finalReturn;
-/**
- @method create
- @static
- @return {Ember.OrderedSet}
-*/
-OrderedSet.create = function() {
- return new OrderedSet();
-};
+ binding = binding || this;
+ try {
+ result = tryable.call(binding);
+ } catch(error) {
+ result = catchable.call(binding, error);
+ } finally {
+ try {
+ finalResult = finalizer.call(binding);
+ } catch (e){
+ finalError = e;
+ }
+ }
-OrderedSet.prototype = {
- /**
- @method clear
- */
- clear: function() {
- this.presenceSet = {};
- this.list = [];
- },
+ if (finalError) { throw finalError; }
- /**
- @method add
- @param obj
- */
- add: function(obj) {
- var guid = guidFor(obj),
- presenceSet = this.presenceSet,
- list = this.list;
+ return (finalResult === undefined) ? result : finalResult;
+ };
+} else {
+ Ember.tryCatchFinally = function(tryable, catchable, finalizer, binding) {
+ var result, finalResult;
- if (guid in presenceSet) { return; }
+ binding = binding || this;
- presenceSet[guid] = true;
- list.push(obj);
- },
+ try {
+ result = tryable.call(binding);
+ } catch(error) {
+ result = catchable.call(binding, error);
+ } finally {
+ finalResult = finalizer.call(binding);
+ }
- /**
- @method remove
- @param obj
- */
- remove: function(obj) {
- var guid = guidFor(obj),
- presenceSet = this.presenceSet,
- list = this.list;
+ return (finalResult === undefined) ? result : finalResult;
+ };
+}
- delete presenceSet[guid];
+})();
- var index = indexOf.call(list, obj);
- if (index > -1) {
- list.splice(index, 1);
- }
- },
- /**
- @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;
+(function() {
+// Ember.tryCatchFinally
- return guid in presenceSet;
- },
+/**
+ The purpose of the Ember Instrumentation module is
+ to provide efficient, general-purpose instrumentation
+ for Ember.
- /**
- @method forEach
- @param {Function} function
- @param target
- */
- forEach: function(fn, self) {
- // allow mutation during iteration
- var list = this.list.slice();
+ Subscribe to a listener by using `Ember.subscribe`:
- for (var i = 0, j = list.length; i < j; i++) {
- fn.call(self, list[i]);
- }
- },
+ ```javascript
+ Ember.subscribe("render", {
+ before: function(name, timestamp, payload) {
- /**
- @method toArray
- @return {Array}
- */
- toArray: function() {
- return this.list.slice();
- },
+ },
- /**
- @method copy
- @return {Ember.OrderedSet}
- */
- copy: function() {
- var set = new OrderedSet();
+ after: function(name, timestamp, payload) {
- set.presenceSet = copy(this.presenceSet);
- set.list = this.list.slice();
+ }
+ });
+ ```
- return set;
- }
-};
+ If you return a value from the `before` callback, that same
+ value will be passed as a fourth parameter to the `after`
+ callback.
-/**
- A Map stores values indexed by keys. Unlike JavaScript's
- default Objects, the keys of a Map can be any JavaScript
- object.
+ Instrument a block of code by using `Ember.instrument`:
- Internally, a Map has two data structures:
+ ```javascript
+ Ember.instrument("render.handlebars", payload, function() {
+ // rendering logic
+ }, binding);
+ ```
- `keys`: an OrderedSet of all of the existing keys
- `values`: a JavaScript Object indexed by the
- Ember.guidFor(key)
+ Event names passed to `Ember.instrument` are namespaced
+ by periods, from more general to more specific. Subscribers
+ can listen for events by whatever level of granularity they
+ are interested in.
- When a key/value pair is added for the first time, we
- 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`.
+ In the above example, the event is `render.handlebars`,
+ and the subscriber listened for all events beginning with
+ `render`. It would receive callbacks for events named
+ `render`, `render.handlebars`, `render.container`, or
+ even `render.handlebars.layout`.
- @class Map
+ @class Instrumentation
@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();
+Ember.Instrumentation = {};
+
+var subscribers = [], cache = {};
+
+var populateListeners = function(name) {
+ var listeners = [], subscriber;
+
+ for (var i=0, l=subscribers.length; i<l; i++) {
+ subscriber = subscribers[i];
+ if (subscriber.regex.test(name)) {
+ listeners.push(subscriber.object);
+ }
+ }
+
+ cache[name] = listeners;
+ return listeners;
};
-Map.prototype = {
- /**
- Retrieve the value associated with a given key.
+var time = (function() {
+ var perf = 'undefined' !== typeof window ? window.performance || {} : {};
+ var fn = perf.now || perf.mozNow || perf.webkitNow || perf.msNow || perf.oNow;
+ // fn.bind will be available in all the browsers that support the advanced window.performance... ;-)
+ return fn ? fn.bind(perf) : function() { return +new Date(); };
+})();
- @method get
- @param {anything} key
- @return {anything} the value associated with the key, or undefined
- */
- get: function(key) {
- var values = this.values,
- guid = guidFor(key);
- return values[guid];
- },
+Ember.Instrumentation.instrument = function(name, payload, callback, binding) {
+ var listeners = cache[name], timeName, ret;
- /**
- 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.
+ if (Ember.STRUCTURED_PROFILE) {
+ timeName = name + ": " + payload.object;
+ console.time(timeName);
+ }
- @method set
- @param {anything} key
- @param {anything} value
- */
- set: function(key, value) {
- var keys = this.keys,
- values = this.values,
- guid = guidFor(key);
+ if (!listeners) {
+ listeners = populateListeners(name);
+ }
- keys.add(key);
- values[guid] = value;
- },
+ if (listeners.length === 0) {
+ ret = callback.call(binding);
+ if (Ember.STRUCTURED_PROFILE) { console.timeEnd(timeName); }
+ return ret;
+ }
- /**
- Removes a value from the map for an associated key.
+ var beforeValues = [], listener, i, l;
- @method remove
- @param {anything} key
- @return {Boolean} true if an item was removed, false otherwise
- */
- remove: function(key) {
- // don't use ES6 "delete" because it will be annoying
- // to use in browsers that are not ES6 friendly;
- var keys = this.keys,
- values = this.values,
- guid = guidFor(key),
- value;
+ function tryable(){
+ for (i=0, l=listeners.length; i<l; i++) {
+ listener = listeners[i];
+ beforeValues[i] = listener.before(name, time(), payload);
+ }
- if (values.hasOwnProperty(guid)) {
- keys.remove(key);
- value = values[guid];
- delete values[guid];
- return true;
- } else {
- return false;
+ return callback.call(binding);
+ }
+
+ function catchable(e){
+ payload = payload || {};
+ payload.exception = e;
+ }
+
+ function finalizer() {
+ for (i=0, l=listeners.length; i<l; i++) {
+ listener = listeners[i];
+ listener.after(name, time(), payload, beforeValues[i]);
}
- },
- /**
- Check whether a key is present.
+ if (Ember.STRUCTURED_PROFILE) {
+ console.timeEnd(timeName);
+ }
+ }
- @method has
- @param {anything} key
- @return {Boolean} true if the item was present, false otherwise
- */
- has: function(key) {
- var values = this.values,
- guid = guidFor(key);
+ return Ember.tryCatchFinally(tryable, catchable, finalizer);
+};
- return values.hasOwnProperty(guid);
- },
+Ember.Instrumentation.subscribe = function(pattern, object) {
+ var paths = pattern.split("."), path, regex = [];
- /**
- Iterate over all the keys and values. Calls the function once
- for each key, passing in the key and value, in that order.
+ for (var i=0, l=paths.length; i<l; i++) {
+ path = paths[i];
+ if (path === "*") {
+ regex.push("[^\\.]*");
+ } else {
+ regex.push(path);
+ }
+ }
- The keys are guaranteed to be iterated over in insertion order.
+ regex = regex.join("\\.");
+ regex = regex + "(\\..*)?";
- @method forEach
- @param {Function} callback
- @param {anything} self if passed, the `this` value inside the
- callback. By default, `this` is the map.
- */
- forEach: function(callback, self) {
- var keys = this.keys,
- values = this.values;
+ var subscriber = {
+ pattern: pattern,
+ regex: new RegExp("^" + regex + "$"),
+ object: object
+ };
- keys.forEach(function(key) {
- var guid = guidFor(key);
- callback.call(self, key, values[guid]);
- });
- },
+ subscribers.push(subscriber);
+ cache = {};
- /**
- @method copy
- @return {Ember.Map}
- */
- copy: function() {
- return copyMap(this, new Map());
- }
+ return subscriber;
};
-/**
- @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;
-};
+Ember.Instrumentation.unsubscribe = function(subscriber) {
+ var index;
-/**
- @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);
- } else {
- return new Map();
+ for (var i=0, l=subscribers.length; i<l; i++) {
+ if (subscribers[i] === subscriber) {
+ index = i;
+ }
}
+
+ subscribers.splice(index, 1);
+ cache = {};
};
-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);
-
- if (hasValue) {
- return Map.prototype.get.call(this, key);
- } else {
- var defaultValue = this.defaultValue(key);
- this.set(key, defaultValue);
- return defaultValue;
- }
+Ember.Instrumentation.reset = function() {
+ subscribers = [];
+ cache = {};
};
-/**
- @method copy
- @return {Ember.MapWithDefault}
-*/
-MapWithDefault.prototype.copy = function() {
- return copyMap(this, new MapWithDefault({
- defaultValue: this.defaultValue
- }));
-};
+Ember.instrument = Ember.Instrumentation.instrument;
+Ember.subscribe = Ember.Instrumentation.subscribe;
})();
(function() {
+/*jshint newcap:false*/
+
/**
@module ember-metal
*/
-var META_KEY = Ember.META_KEY, get, set;
-
-var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER;
+// 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
-var IS_GLOBAL = /^([A-Z$]|([0-9][A-Z$]))/;
-var IS_GLOBAL_PATH = /^([A-Z$]|([0-9][A-Z$])).*[\.\*]/;
-var HAS_THIS = /^this[\.\*]/;
-var FIRST_KEY = /^([^\.\*]+)/;
+// Testing this is not ideal, but we want to use native functions
+// if available, but not to use versions created by libraries like Prototype
+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;
+};
-// ..........................................................
-// GET AND SET
-//
-// If we are on a platform that supports accessors we can get use those.
-// Otherwise simulate accessors by looking up the property directly on the
-// object.
+// From: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/array/map
+var arrayMap = isNativeFunc(Array.prototype.map) ? Array.prototype.map : function(fun /*, thisp */) {
+ //"use strict";
-/**
- 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 (this === void 0 || this === null) {
+ throw new TypeError();
+ }
- 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.)
+ var t = Object(this);
+ var len = t.length >>> 0;
+ if (typeof fun !== "function") {
+ throw new TypeError();
+ }
- 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.
+ var res = new Array(len);
+ var thisp = arguments[1];
+ for (var i = 0; i < len; i++) {
+ if (i in t) {
+ res[i] = fun.call(thisp, t[i], i, t);
+ }
+ }
- Note that if the obj itself is null, this method will simply return
- undefined.
+ return res;
+};
- @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 === '') {
- return obj;
- }
+// From: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/array/foreach
+var arrayForEach = isNativeFunc(Array.prototype.forEach) ? Array.prototype.forEach : function(fun /*, thisp */) {
+ //"use strict";
- if (!keyName && 'string'===typeof obj) {
- keyName = obj;
- obj = null;
+ if (this === void 0 || this === null) {
+ throw new TypeError();
}
- if (!obj || keyName.indexOf('.') !== -1) {
- return getPath(obj, keyName);
+ var t = Object(this);
+ var len = t.length >>> 0;
+ if (typeof fun !== "function") {
+ throw new TypeError();
}
- Ember.assert("You need to provide an object and key to `get`.", !!obj && keyName);
-
- var meta = obj[META_KEY], desc = meta && meta.descs[keyName], ret;
- if (desc) {
- return desc.get(obj, keyName);
- } else {
- if (MANDATORY_SETTER && meta && meta.watching[keyName] > 0) {
- ret = meta.values[keyName];
- } else {
- ret = obj[keyName];
- }
-
- if (ret === undefined &&
- 'object' === typeof obj && !(keyName in obj) && 'function' === typeof obj.unknownProperty) {
- return obj.unknownProperty(keyName);
+ var thisp = arguments[1];
+ for (var i = 0; i < len; i++) {
+ if (i in t) {
+ fun.call(thisp, t[i], i, t);
}
+ }
+};
- return ret;
+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); }
+ for (var i = fromIndex, j = this.length; i < j; i++) {
+ if (this[i] === obj) { return i; }
}
+ return -1;
};
-/**
- 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.
+Ember.ArrayPolyfills = {
+ map: arrayMap,
+ forEach: arrayForEach,
+ indexOf: arrayIndexOf
+};
- 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.)
+var utils = Ember.EnumerableUtils = {
+ map: function(obj, callback, thisArg) {
+ return obj.map ? obj.map.call(obj, callback, thisArg) : arrayMap.call(obj, callback, thisArg);
+ },
- 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.
+ forEach: function(obj, callback, thisArg) {
+ return obj.forEach ? obj.forEach.call(obj, callback, thisArg) : arrayForEach.call(obj, callback, thisArg);
+ },
- @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));
- value = keyName;
- keyName = obj;
- obj = null;
- }
+ indexOf: function(obj, element, index) {
+ return obj.indexOf ? obj.indexOf.call(obj, element, index) : arrayIndexOf.call(obj, element, index);
+ },
- if (!obj || keyName.indexOf('.') !== -1) {
- return setPath(obj, keyName, value, tolerant);
- }
+ indexesOf: function(obj, elements) {
+ return elements === undefined ? [] : utils.map(elements, function(item) {
+ return utils.indexOf(obj, item);
+ });
+ },
- Ember.assert("You need to provide an object and key to `set`.", !!obj && keyName !== undefined);
- Ember.assert('calling set on destroyed object', !obj.isDestroyed);
+ addObject: function(array, item) {
+ var index = utils.indexOf(array, item);
+ if (index === -1) { array.push(item); }
+ },
- var meta = obj[META_KEY], desc = meta && meta.descs[keyName],
- isUnknown, currentValue;
- if (desc) {
- desc.set(obj, keyName, value);
- }
- else {
- isUnknown = 'object' === typeof obj && !(keyName in obj);
+ removeObject: function(array, item) {
+ var index = utils.indexOf(array, item);
+ if (index !== -1) { array.splice(index, 1); }
+ },
- // setUnknownProperty is called if `obj` is an object,
- // the property does not already exist, and the
- // `setUnknownProperty` method exists on the object
- if (isUnknown && 'function' === typeof obj.setUnknownProperty) {
- obj.setUnknownProperty(keyName, value);
- } else if (meta && meta.watching[keyName] > 0) {
- if (MANDATORY_SETTER) {
- currentValue = meta.values[keyName];
- } else {
- currentValue = obj[keyName];
- }
- // only trigger a change if the value has changed
- if (value !== currentValue) {
- Ember.propertyWillChange(obj, keyName);
- if (MANDATORY_SETTER) {
- if (currentValue === undefined && !(keyName in obj)) {
- Ember.defineProperty(obj, keyName, null, value); // setup mandatory setter
- } else {
- meta.values[keyName] = value;
- }
- } else {
- obj[keyName] = value;
- }
- Ember.propertyDidChange(obj, keyName);
- }
+ replace: function(array, idx, amt, objects) {
+ if (array.replace) {
+ return array.replace(idx, amt, objects);
} else {
- obj[keyName] = value;
+ var args = Array.prototype.concat.apply([idx, amt], objects);
+ return array.splice.apply(array, args);
}
}
- return value;
};
-function firstKey(path) {
- return path.match(FIRST_KEY)[0];
-}
-
-// assumes path is already normalized
-function normalizeTuple(target, path) {
- var hasThis = HAS_THIS.test(path),
- isGlobal = !hasThis && IS_GLOBAL_PATH.test(path),
- key;
-
- if (!target || isGlobal) target = window;
- if (hasThis) path = path.slice(5);
- if (target === window) {
- key = firstKey(path);
- target = get(target, key);
- path = path.slice(key.length+1);
+if (Ember.SHIM_ES5) {
+ if (!Array.prototype.map) {
+ Array.prototype.map = arrayMap;
}
- // must return some kind of path to be valid else other things will break.
- if (!path || path.length===0) throw new Error('Invalid Path');
+ if (!Array.prototype.forEach) {
+ Array.prototype.forEach = arrayForEach;
+ }
- return [ target, path ];
+ if (!Array.prototype.indexOf) {
+ Array.prototype.indexOf = arrayIndexOf;
+ }
}
-function getPath(root, path) {
- var hasThis, parts, tuple, idx, len;
+})();
- // If there is no root and path is a key name, return that
- // property from the global object.
- // E.g. get('Ember') -> Ember
- if (root === null && path.indexOf('.') === -1) { return get(window, path); }
- // detect complicated paths and normalize them
- hasThis = HAS_THIS.test(path);
- if (!root || hasThis) {
- tuple = normalizeTuple(root, path);
- root = tuple[0];
- path = tuple[1];
- tuple.length = 0;
- }
-
- parts = path.split(".");
- len = parts.length;
- for (idx=0; root && idx<len; idx++) {
- root = get(root, parts[idx], true);
- if (root && root.isDestroyed) { return undefined; }
- }
- return root;
-}
+(function() {
+/**
+@module ember-metal
+*/
-function setPath(root, path, value, tolerant) {
- var keyName;
+/*
+ JavaScript (before ES6) does not have a Map implementation. Objects,
+ which are often used as dictionaries, may only have Strings as keys.
- // get the last part of the path
- keyName = path.slice(path.lastIndexOf('.') + 1);
+ Because Ember has a way to get a unique identifier for every object
+ via `Ember.guidFor`, we can implement a performant Map with arbitrary
+ keys. Because it is commonly used in low-level bookkeeping, Map is
+ implemented as a pure JavaScript object for performance.
- // get the first part of the part
- path = path.slice(0, path.length-(keyName.length+1));
+ This implementation follows the current iteration of the ES6 proposal for
+ maps (http://wiki.ecmascript.org/doku.php?id=harmony:simple_maps_and_sets),
+ with two exceptions. First, because we need our implementation to be pleasant
+ on older browsers, we do not use the `delete` name (using `remove` instead).
+ Second, as we do not have the luxury of in-VM iteration, we implement a
+ forEach method for iteration.
- // unless the path is this, look up the first part to
- // get the root
- if (path !== 'this') {
- root = getPath(root, path);
- }
+ Map is mocked out to look like an Ember object, so you can do
+ `Ember.Map.create()` for symmetry with other Ember classes.
+*/
+var guidFor = Ember.guidFor,
+ indexOf = Ember.ArrayPolyfills.indexOf;
- if (!keyName || keyName.length === 0) {
- throw new Error('You passed an empty path');
- }
+var copy = function(obj) {
+ var output = {};
- if (!root) {
- if (tolerant) { return; }
- else { throw new Error('Object in path '+path+' could not be found or was destroyed.'); }
+ for (var prop in obj) {
+ if (obj.hasOwnProperty(prop)) { output[prop] = obj[prop]; }
}
- return set(root, keyName, value);
-}
+ return output;
+};
-/**
- @private
+var copyMap = function(original, newObject) {
+ var keys = original.keys.copy(),
+ values = copy(original.values);
- Normalizes a target/path pair to reflect that actual target/path that should
- be observed, etc. This takes into account passing in global property
- paths (i.e. a path beginning with a captial letter not defined on the
- target) and * separators.
+ newObject.keys = keys;
+ newObject.values = values;
- @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);
+ return newObject;
};
-Ember.getWithDefault = function(root, key, defaultValue) {
- var value = get(root, key);
+/**
+ This class is used internally by Ember and Ember Data.
+ Please do not use it at this time. We plan to clean it up
+ and add many tests soon.
- if (value === undefined) { return defaultValue; }
- return value;
+ @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();
+};
-Ember.get = get;
-Ember.getPath = Ember.deprecateFunc('getPath is deprecated since get now supports paths', Ember.get);
-Ember.set = set;
-Ember.setPath = Ember.deprecateFunc('setPath is deprecated since set now supports paths', Ember.set);
+OrderedSet.prototype = {
+ /**
+ @method clear
+ */
+ clear: function() {
+ this.presenceSet = {};
+ this.list = [];
+ },
-/**
- Error-tolerant form of Ember.set. Will not blow up if any part of the
- chain is undefined, null, or destroyed.
+ /**
+ @method add
+ @param obj
+ */
+ add: function(obj) {
+ var guid = guidFor(obj),
+ presenceSet = this.presenceSet,
+ list = this.list;
- This is primarily used when syncing bindings, which may try to update after
- an object has been destroyed.
+ if (guid in presenceSet) { return; }
- @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);
-};
-Ember.trySetPath = Ember.deprecateFunc('trySetPath has been renamed to trySet', Ember.trySet);
+ presenceSet[guid] = true;
+ list.push(obj);
+ },
-/**
- Returns true if the provided path is global (e.g., "MyApp.fooController.bar")
- instead of local ("foo.bar.baz").
+ /**
+ @method remove
+ @param obj
+ */
+ remove: function(obj) {
+ var guid = guidFor(obj),
+ presenceSet = this.presenceSet,
+ list = this.list;
- @method isGlobalPath
- @for Ember
- @private
- @param {String} path
- @return Boolean
-*/
-Ember.isGlobalPath = function(path) {
- return IS_GLOBAL.test(path);
-};
+ delete presenceSet[guid];
+ var index = indexOf.call(list, obj);
+ if (index > -1) {
+ list.splice(index, 1);
+ }
+ },
+ /**
+ @method isEmpty
+ @return {Boolean}
+ */
+ isEmpty: function() {
+ return this.list.length === 0;
+ },
-if (Ember.config.overrideAccessors) {
- Ember.config.overrideAccessors();
- get = Ember.get;
- set = Ember.set;
-}
+ /**
+ @method has
+ @param obj
+ @return {Boolean}
+ */
+ has: function(obj) {
+ var guid = guidFor(obj),
+ presenceSet = this.presenceSet;
-})();
+ return guid in presenceSet;
+ },
+ /**
+ @method forEach
+ @param {Function} function
+ @param target
+ */
+ forEach: function(fn, self) {
+ // allow mutation during iteration
+ var list = this.list.slice();
+ for (var i = 0, j = list.length; i < j; i++) {
+ fn.call(self, list[i]);
+ }
+ },
-(function() {
-/**
-@module ember-metal
-*/
+ /**
+ @method toArray
+ @return {Array}
+ */
+ toArray: function() {
+ return this.list.slice();
+ },
-var GUID_KEY = Ember.GUID_KEY,
- META_KEY = Ember.META_KEY,
- EMPTY_META = Ember.EMPTY_META,
- metaFor = Ember.meta,
- o_create = Ember.create,
- objectDefineProperty = Ember.platform.defineProperty;
+ /**
+ @method copy
+ @return {Ember.OrderedSet}
+ */
+ copy: function() {
+ var set = new OrderedSet();
-var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER;
+ set.presenceSet = copy(this.presenceSet);
+ set.list = this.list.slice();
-// ..........................................................
-// DESCRIPTOR
-//
+ return set;
+ }
+};
/**
- Objects of this type can implement an interface to responds requests to
- get and set. The default implementation handles simple properties.
+ A Map stores values indexed by keys. Unlike JavaScript's
+ default Objects, the keys of a Map can be any JavaScript
+ object.
- You generally won't need to create or subclass this directly.
+ Internally, a Map has two data structures:
- @class Descriptor
+ 1. `keys`: an OrderedSet of all of the existing keys
+ 2. `values`: a JavaScript Object indexed by the `Ember.guidFor(key)`
+
+ When a key/value pair is added for the first time, we
+ 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`.
+
+ @class Map
@namespace Ember
@private
@constructor
*/
-var Descriptor = Ember.Descriptor = function() {};
-
-// ..........................................................
-// DEFINING PROPERTIES API
-//
+var Map = Ember.Map = function() {
+ this.keys = Ember.OrderedSet.create();
+ this.values = {};
+};
/**
- @private
-
- NOTE: This is a low-level method used by other parts of the API. You almost
- never want to call this method directly. Instead you should use Ember.mixin()
- to define new properties.
-
- Defines a property on an object. This method works much like the ES5
- Object.defineProperty() method except that it can also accept computed
- properties and other special descriptors.
-
- Normally this method takes only three parameters. However if you pass an
- instance of Ember.Descriptor as the third param then you can pass an optional
- value as the fourth parameter. This is often more efficient than creating
- new descriptor hashes for each property.
+ @method create
+ @static
+*/
+Map.create = function() {
+ return new Map();
+};
- ## Examples
+Map.prototype = {
+ /**
+ Retrieve the value associated with a given key.
- // ES5 compatible mode
- Ember.defineProperty(contact, 'firstName', {
- writable: true,
- configurable: false,
- enumerable: true,
- value: 'Charles'
- });
+ @method get
+ @param {anything} key
+ @return {anything} the value associated with the key, or `undefined`
+ */
+ get: function(key) {
+ var values = this.values,
+ guid = guidFor(key);
- // define a simple property
- Ember.defineProperty(contact, 'lastName', undefined, 'Jolley');
+ return values[guid];
+ },
- // define a computed property
- Ember.defineProperty(contact, 'fullName', Ember.computed(function() {
- return this.firstName+' '+this.lastName;
- }).property('firstName', 'lastName').cacheable());
+ /**
+ 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 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) {
- var descs, existingDesc, watching, value;
+ @method set
+ @param {anything} key
+ @param {anything} value
+ */
+ set: function(key, value) {
+ var keys = this.keys,
+ values = this.values,
+ guid = guidFor(key);
- if (!meta) meta = metaFor(obj);
- descs = meta.descs;
- existingDesc = meta.descs[keyName];
- watching = meta.watching[keyName] > 0;
+ keys.add(key);
+ values[guid] = value;
+ },
- if (existingDesc instanceof Ember.Descriptor) {
- existingDesc.teardown(obj, keyName);
- }
+ /**
+ Removes a value from the map for an associated key.
- if (desc instanceof Ember.Descriptor) {
- value = desc;
+ @method remove
+ @param {anything} key
+ @return {Boolean} true if an item was removed, false otherwise
+ */
+ remove: function(key) {
+ // don't use ES6 "delete" because it will be annoying
+ // to use in browsers that are not ES6 friendly;
+ var keys = this.keys,
+ values = this.values,
+ guid = guidFor(key),
+ value;
- descs[keyName] = desc;
- if (MANDATORY_SETTER && watching) {
- objectDefineProperty(obj, keyName, {
- configurable: true,
- enumerable: true,
- writable: true,
- value: undefined // make enumerable
- });
+ if (values.hasOwnProperty(guid)) {
+ keys.remove(key);
+ value = values[guid];
+ delete values[guid];
+ return true;
} else {
- obj[keyName] = undefined; // make enumerable
+ return false;
}
- desc.setup(obj, keyName);
- } else {
- descs[keyName] = undefined; // shadow descriptor in proto
- if (desc == null) {
- value = data;
-
- if (MANDATORY_SETTER && watching) {
- meta.values[keyName] = data;
- objectDefineProperty(obj, keyName, {
- configurable: true,
- enumerable: true,
- set: function() {
- Ember.assert('Must use Ember.set() to access this property', false);
- },
- get: function() {
- var meta = this[META_KEY];
- return meta && meta.values[keyName];
- }
- });
- } else {
- obj[keyName] = data;
- }
- } else {
- value = desc;
+ },
- // compatibility with ES5
- objectDefineProperty(obj, keyName, desc);
- }
- }
+ /**
+ Check whether a key is present.
- // if key is being watched, override chains that
- // were initialized with the prototype
- if (watching) { Ember.overrideChains(obj, keyName, meta); }
+ @method has
+ @param {anything} key
+ @return {Boolean} true if the item was present, false otherwise
+ */
+ has: function(key) {
+ var values = this.values,
+ guid = guidFor(key);
- // The `value` passed to the `didDefineProperty` hook is
- // either the descriptor or data, whichever was passed.
- if (obj.didDefineProperty) { obj.didDefineProperty(obj, keyName, value); }
+ return values.hasOwnProperty(guid);
+ },
- return this;
-};
+ /**
+ Iterate over all the keys and values. Calls the function once
+ for each key, passing in the key and value, in that order.
+ 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.
+ */
+ forEach: function(callback, self) {
+ var keys = this.keys,
+ values = this.values;
+ keys.forEach(function(key) {
+ var guid = guidFor(key);
+ callback.call(self, key, values[guid]);
+ });
+ },
+ /**
+ @method copy
+ @return {Ember.Map}
+ */
+ copy: function() {
+ return copyMap(this, new Map());
+ }
+};
-(function() {
/**
-@module ember-metal
+ @class MapWithDefault
+ @namespace Ember
+ @extends Ember.Map
+ @private
+ @constructor
+ @param [options]
+ @param {anything} [options.defaultValue]
*/
-
-var AFTER_OBSERVERS = ':change';
-var BEFORE_OBSERVERS = ':before';
-var guidFor = Ember.guidFor;
-
-var deferred = 0;
-var array_Slice = [].slice;
-
-var ObserverSet = function () {
- this.targetSet = {};
+var MapWithDefault = Ember.MapWithDefault = function(options) {
+ Map.call(this);
+ this.defaultValue = options.defaultValue;
};
-ObserverSet.prototype.add = function (target, path) {
- var targetSet = this.targetSet,
- targetGuid = Ember.guidFor(target),
- pathSet = targetSet[targetGuid];
- if (!pathSet) {
- targetSet[targetGuid] = pathSet = {};
- }
- if (pathSet[path]) {
- return false;
+
+/**
+ @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);
} else {
- return pathSet[path] = true;
+ return new Map();
}
};
-ObserverSet.prototype.clear = function () {
- this.targetSet = {};
-};
-var DeferredEventQueue = function() {
- this.targetSet = {};
- this.queue = [];
-};
+MapWithDefault.prototype = Ember.create(Map.prototype);
-DeferredEventQueue.prototype.push = function(target, eventName, keyName) {
- var targetSet = this.targetSet,
- queue = this.queue,
- targetGuid = Ember.guidFor(target),
- eventNameSet = targetSet[targetGuid],
- index;
+/**
+ Retrieve the value associated with a given key.
- if (!eventNameSet) {
- targetSet[targetGuid] = eventNameSet = {};
- }
- index = eventNameSet[eventName];
- if (index === undefined) {
- eventNameSet[eventName] = queue.push(Ember.deferEvent(target, eventName, [target, keyName])) - 1;
+ @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);
+
+ if (hasValue) {
+ return Map.prototype.get.call(this, key);
} else {
- queue[index] = Ember.deferEvent(target, eventName, [target, keyName]);
+ var defaultValue = this.defaultValue(key);
+ this.set(key, defaultValue);
+ return defaultValue;
}
};
-DeferredEventQueue.prototype.flush = function() {
- var queue = this.queue;
- this.queue = [];
- this.targetSet = {};
- for (var i=0, len=queue.length; i < len; ++i) {
- queue[i]();
- }
+/**
+ @method copy
+ @return {Ember.MapWithDefault}
+*/
+MapWithDefault.prototype.copy = function() {
+ return copyMap(this, new MapWithDefault({
+ defaultValue: this.defaultValue
+ }));
};
-var queue = new DeferredEventQueue(), beforeObserverSet = new ObserverSet();
-
-function notifyObservers(obj, eventName, keyName, forceNotification) {
- if (deferred && !forceNotification) {
- queue.push(obj, eventName, keyName);
- } else {
- Ember.sendEvent(obj, eventName, [obj, keyName]);
- }
-}
+})();
-function flushObserverQueue() {
- beforeObserverSet.clear();
- queue.flush();
-}
+(function() {
/**
- @method beginPropertyChanges
- @chainable
+@module ember-metal
*/
-Ember.beginPropertyChanges = function() {
- deferred++;
- return this;
-};
-/**
- @method endPropertyChanges
-*/
-Ember.endPropertyChanges = function() {
- deferred--;
- if (deferred<=0) flushObserverQueue();
-};
+var META_KEY = Ember.META_KEY, get, set;
-/**
- Make a series of property changes together in an
- exception-safe way.
+var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER;
- Ember.changeProperties(function() {
- obj1.set('foo', mayBlowUpWhenSet);
- obj2.set('bar', baz);
- });
+var IS_GLOBAL = /^([A-Z$]|([0-9][A-Z$]))/;
+var IS_GLOBAL_PATH = /^([A-Z$]|([0-9][A-Z$])).*[\.\*]/;
+var HAS_THIS = /^this[\.\*]/;
+var FIRST_KEY = /^([^\.\*]+)/;
- @method changeProperties
- @param {Function} callback
- @param [binding]
-*/
-Ember.changeProperties = function(cb, binding){
- Ember.beginPropertyChanges();
- try {
- cb.call(binding);
- } finally {
- Ember.endPropertyChanges();
- }
-};
+// ..........................................................
+// GET AND SET
+//
+// If we are on a platform that supports accessors we can get use those.
+// Otherwise simulate accessors by looking up the property directly on the
+// object.
/**
- 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(){
- for(var prop in hash) {
- if (hash.hasOwnProperty(prop)) Ember.set(self, prop, hash[prop]);
- }
- });
- return self;
-};
+ 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. (Properties beginning with an underscore '_'
+ are considered private.)
-function changeEvent(keyName) {
- return keyName+AFTER_OBSERVERS;
-}
+ 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.
-function beforeEvent(keyName) {
- return keyName+BEFORE_OBSERVERS;
-}
+ Note that if the object itself is `undefined`, this method will throw
+ an error.
-/**
- @method addObserver
- @param obj
- @param {String} path
- @param {Object|Function} targetOrMethod
- @param {Function|String} [method]
+ @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`.
*/
-Ember.addObserver = function(obj, path, target, method) {
- Ember.addListener(obj, changeEvent(path), target, method);
- Ember.watch(obj, path);
- return this;
-};
-
-Ember.observersFor = function(obj, path) {
- return Ember.listenersFor(obj, changeEvent(path));
-};
+get = function get(obj, keyName) {
+ // Helpers that operate with 'this' within an #each
+ if (keyName === '') {
+ return obj;
+ }
-/**
- @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;
-};
+ if (!keyName && 'string'===typeof obj) {
+ keyName = obj;
+ obj = null;
+ }
-/**
- @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);
- return this;
-};
+ if (!obj || keyName.indexOf('.') !== -1) {
+ Ember.assert("Cannot call get with '"+ keyName +"' on an undefined object.", obj !== undefined);
+ return getPath(obj, keyName);
+ }
-// Suspend observer during callback.
-//
-// This should only be used by the target of the observer
-// while it is setting the observed path.
-Ember._suspendBeforeObserver = function(obj, path, target, method, callback) {
- return Ember._suspendListener(obj, beforeEvent(path), target, method, callback);
-};
+ Ember.assert("You need to provide an object and key to `get`.", !!obj && keyName);
-Ember._suspendObserver = function(obj, path, target, method, callback) {
- return Ember._suspendListener(obj, changeEvent(path), target, method, callback);
-};
+ var meta = obj[META_KEY], desc = meta && meta.descs[keyName], ret;
+ if (desc) {
+ return desc.get(obj, keyName);
+ } else {
+ if (MANDATORY_SETTER && meta && meta.watching[keyName] > 0) {
+ ret = meta.values[keyName];
+ } else {
+ ret = obj[keyName];
+ }
-var map = Ember.ArrayPolyfills.map;
+ if (ret === undefined &&
+ 'object' === typeof obj && !(keyName in obj) && 'function' === typeof obj.unknownProperty) {
+ return obj.unknownProperty(keyName);
+ }
-Ember._suspendBeforeObservers = function(obj, paths, target, method, callback) {
- var events = map.call(paths, beforeEvent);
- return Ember._suspendListeners(obj, events, target, method, callback);
+ return ret;
+ }
};
-Ember._suspendObservers = function(obj, paths, target, method, callback) {
- var events = map.call(paths, changeEvent);
- return Ember._suspendListeners(obj, events, target, method, callback);
-};
+/**
+ 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.
-Ember.beforeObserversFor = function(obj, path) {
- return Ember.listenersFor(obj, beforeEvent(path));
-};
+ 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. (Properties beginning with an underscore '_'
+ are considered private.)
-/**
- @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;
-};
+ 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.
-Ember.notifyObservers = function(obj, keyName) {
- if (obj.isDestroying) { return; }
+ @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));
+ value = keyName;
+ keyName = obj;
+ obj = null;
+ }
- notifyObservers(obj, changeEvent(keyName), keyName);
-};
+ if (!obj || keyName.indexOf('.') !== -1) {
+ return setPath(obj, keyName, value, tolerant);
+ }
-Ember.notifyBeforeObservers = function(obj, keyName) {
- if (obj.isDestroying) { return; }
+ Ember.assert("You need to provide an object and key to `set`.", !!obj && keyName !== undefined);
+ Ember.assert('calling set on destroyed object', !obj.isDestroyed);
- var guid, set, forceNotification = false;
+ var meta = obj[META_KEY], desc = meta && meta.descs[keyName],
+ isUnknown, currentValue;
+ if (desc) {
+ desc.set(obj, keyName, value);
+ } else {
+ isUnknown = 'object' === typeof obj && !(keyName in obj);
- if (deferred) {
- if (beforeObserverSet.add(obj, keyName)) {
- forceNotification = true;
+ // setUnknownProperty is called if `obj` is an object,
+ // the property does not already exist, and the
+ // `setUnknownProperty` method exists on the object
+ if (isUnknown && 'function' === typeof obj.setUnknownProperty) {
+ obj.setUnknownProperty(keyName, value);
+ } else if (meta && meta.watching[keyName] > 0) {
+ if (MANDATORY_SETTER) {
+ currentValue = meta.values[keyName];
+ } else {
+ currentValue = obj[keyName];
+ }
+ // only trigger a change if the value has changed
+ if (value !== currentValue) {
+ Ember.propertyWillChange(obj, keyName);
+ if (MANDATORY_SETTER) {
+ if (currentValue === undefined && !(keyName in obj)) {
+ Ember.defineProperty(obj, keyName, null, value); // setup mandatory setter
+ } else {
+ meta.values[keyName] = value;
+ }
+ } else {
+ obj[keyName] = value;
+ }
+ Ember.propertyDidChange(obj, keyName);
+ }
} else {
- return;
+ obj[keyName] = value;
}
}
-
- notifyObservers(obj, beforeEvent(keyName), keyName, forceNotification);
+ return value;
};
+// Currently used only by Ember Data tests
+if (Ember.config.overrideAccessors) {
+ Ember.get = get;
+ Ember.set = set;
+ Ember.config.overrideAccessors();
+ get = Ember.get;
+ set = Ember.set;
+}
-})();
-
+function firstKey(path) {
+ return path.match(FIRST_KEY)[0];
+}
+// assumes path is already normalized
+function normalizeTuple(target, path) {
+ var hasThis = HAS_THIS.test(path),
+ isGlobal = !hasThis && IS_GLOBAL_PATH.test(path),
+ key;
-(function() {
-/**
-@module ember-metal
-*/
+ if (!target || isGlobal) target = Ember.lookup;
+ if (hasThis) path = path.slice(5);
-var guidFor = Ember.guidFor, // utils.js
- metaFor = Ember.meta, // utils.js
- get = Ember.get, // accessors.js
- set = Ember.set, // accessors.js
- normalizeTuple = Ember.normalizeTuple, // accessors.js
- GUID_KEY = Ember.GUID_KEY, // utils.js
- META_KEY = Ember.META_KEY, // utils.js
- // circular reference observer depends on Ember.watch
- // we should move change events to this file or its own property_events.js
- notifyObservers = Ember.notifyObservers, // observer.js
- forEach = Ember.ArrayPolyfills.forEach, // array.js
- FIRST_KEY = /^([^\.\*]+)/,
- IS_PATH = /[\.\*]/;
+ if (target === Ember.lookup) {
+ key = firstKey(path);
+ target = get(target, key);
+ path = path.slice(key.length+1);
+ }
-var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER,
-o_defineProperty = Ember.platform.defineProperty;
+ // must return some kind of path to be valid else other things will break.
+ if (!path || path.length===0) throw new Error('Invalid Path');
-function firstKey(path) {
- return path.match(FIRST_KEY)[0];
+ return [ target, path ];
}
-// returns true if the passed path is just a keyName
-function isKeyName(path) {
- return path==='*' || !IS_PATH.test(path);
-}
+function getPath(root, path) {
+ var hasThis, parts, tuple, idx, len;
-// ..........................................................
-// DEPENDENT KEYS
-//
+ // If there is no root and path is a key name, return that
+ // property from the global object.
+ // E.g. get('Ember') -> Ember
+ if (root === null && path.indexOf('.') === -1) { return get(Ember.lookup, path); }
-var DEP_SKIP = { __emberproto__: true }; // skip some keys and toString
+ // detect complicated paths and normalize them
+ hasThis = HAS_THIS.test(path);
-function iterDeps(method, obj, depKey, seen, meta) {
-
- var guid = guidFor(obj);
- if (!seen[guid]) seen[guid] = {};
- if (seen[guid][depKey]) return;
- seen[guid][depKey] = true;
+ if (!root || hasThis) {
+ tuple = normalizeTuple(root, path);
+ root = tuple[0];
+ path = tuple[1];
+ tuple.length = 0;
+ }
- var deps = meta.deps;
- deps = deps && deps[depKey];
- 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);
- }
+ parts = path.split(".");
+ len = parts.length;
+ for (idx=0; root && idx<len; idx++) {
+ root = get(root, parts[idx], true);
+ if (root && root.isDestroyed) { return undefined; }
}
+ return root;
}
+function setPath(root, path, value, tolerant) {
+ var keyName;
-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...)
-function dependentKeysWillChange(obj, depKey, meta) {
- if (obj.isDestroying) { return; }
-
- var seen = WILL_SEEN, top = !seen;
- if (top) { seen = WILL_SEEN = {}; }
- iterDeps(propertyWillChange, obj, depKey, seen, meta);
- if (top) { WILL_SEEN = null; }
-}
+ // get the last part of the path
+ keyName = path.slice(path.lastIndexOf('.') + 1);
-// called whenever a property has just changed to update dependent keys
-function dependentKeysDidChange(obj, depKey, meta) {
- if (obj.isDestroying) { return; }
+ // get the first part of the part
+ path = path.slice(0, path.length-(keyName.length+1));
- var seen = DID_SEEN, top = !seen;
- if (top) { seen = DID_SEEN = {}; }
- iterDeps(propertyDidChange, obj, depKey, seen, meta);
- if (top) { DID_SEEN = null; }
-}
+ // unless the path is this, look up the first part to
+ // get the root
+ if (path !== 'this') {
+ root = getPath(root, path);
+ }
-// ..........................................................
-// CHAIN
-//
+ if (!keyName || keyName.length === 0) {
+ throw new Error('You passed an empty path');
+ }
-function addChainWatcher(obj, keyName, node) {
- if (!obj || ('object' !== typeof obj)) return; // nothing to do
- var m = metaFor(obj);
- var nodes = m.chainWatchers;
- if (!nodes || nodes.__emberproto__ !== obj) {
- nodes = m.chainWatchers = { __emberproto__: obj };
+ if (!root) {
+ if (tolerant) { return; }
+ else { throw new Error('Object in path '+path+' could not be found or was destroyed.'); }
}
- if (!nodes[keyName]) { nodes[keyName] = {}; }
- nodes[keyName][guidFor(node)] = node;
- Ember.watch(obj, keyName);
+ return set(root, keyName, value);
}
-function removeChainWatcher(obj, keyName, node) {
- if (!obj || 'object' !== typeof obj) { return; } // nothing to do
- var m = metaFor(obj, false),
- nodes = m.chainWatchers;
- if (!nodes || nodes.__emberproto__ !== obj) { return; } //nothing to do
- if (nodes[keyName]) { delete nodes[keyName][guidFor(node)]; }
- Ember.unwatch(obj, keyName);
-}
+/**
+ @private
-var pendingQueue = [];
+ Normalizes a target/path pair to reflect that actual target/path that should
+ be observed, etc. This takes into account passing in global property
+ paths (i.e. a path beginning with a captial letter not defined on the
+ target) and * separators.
-// 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.
-function flushPendingChains() {
- if (pendingQueue.length === 0) { return; } // nothing to do
+ @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);
+};
- var queue = pendingQueue;
- pendingQueue = [];
+Ember.getWithDefault = function(root, key, defaultValue) {
+ var value = get(root, key);
- forEach.call(queue, function(q) { q[0].add(q[1]); });
+ if (value === undefined) { return defaultValue; }
+ return value;
+};
- 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);
-}
-function isProto(pvalue) {
- return metaFor(pvalue, false).proto === pvalue;
-}
+Ember.get = get;
+Ember.getPath = Ember.deprecateFunc('getPath is deprecated since get now supports paths', Ember.get);
-// 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.
-var ChainNode = function(parent, key, value, separator) {
- var obj;
- this._parent = parent;
- this._key = key;
+Ember.set = set;
+Ember.setPath = Ember.deprecateFunc('setPath is deprecated since set now supports paths', Ember.set);
- // _watching is true when calling get(this._parent, this._key) will
- // return the value of this node.
- //
- // It is false for the root of a chain (because we have no parent)
- // and for global paths (because the parent node is the object with
- // the observer on it)
- this._watching = value===undefined;
+/**
+ Error-tolerant form of `Ember.set`. Will not blow up if any part of the
+ chain is `undefined`, `null`, or destroyed.
- this._value = value;
- this._separator = separator || '.';
- this._paths = {};
- if (this._watching) {
- this._object = parent.value();
- if (this._object) { addChainWatcher(this._object, this._key, this); }
- }
+ This is primarily used when syncing bindings, which may try to update after
+ an object has been destroyed.
- // Special-case: the EachProxy relies on immediate evaluation to
- // establish its observers.
- //
- // TODO: Replace this with an efficient callback that the EachProxy
- // can implement.
- if (this._parent && this._parent._key === '@each') {
- this.value();
- }
+ @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);
};
+Ember.trySetPath = Ember.deprecateFunc('trySetPath has been renamed to trySet', Ember.trySet);
-var ChainNodePrototype = ChainNode.prototype;
+/**
+ Returns true if the provided path is global (e.g., `MyApp.fooController.bar`)
+ instead of local (`foo.bar.baz`).
-ChainNodePrototype.value = function() {
- if (this._value === undefined && this._watching) {
- var obj = this._parent.value();
- this._value = (obj && !isProto(obj)) ? get(obj, this._key) : undefined;
- }
- return this._value;
+ @method isGlobalPath
+ @for Ember
+ @private
+ @param {String} path
+ @return Boolean
+*/
+Ember.isGlobalPath = function(path) {
+ return IS_GLOBAL.test(path);
};
-ChainNodePrototype.destroy = function() {
- if (this._watching) {
- var obj = this._object;
- if (obj) { removeChainWatcher(obj, this._key, this); }
- this._watching = false; // so future calls do nothing
- }
-};
-// copies a top level object only
-ChainNodePrototype.copy = function(obj) {
- var ret = new ChainNode(null, null, obj, this._separator),
- paths = this._paths, path;
- for (path in paths) {
- if (paths[path] <= 0) { continue; } // this check will also catch non-number vals.
- ret.add(path);
- }
- return ret;
-};
+})();
-// called on the root node of a chain to setup watchers on the specified
-// path.
-ChainNodePrototype.add = function(path) {
- var obj, tuple, key, src, separator, paths;
- paths = this._paths;
- paths[path] = (paths[path] || 0) + 1;
- obj = this.value();
- tuple = normalizeTuple(obj, path);
+(function() {
+/**
+@module ember-metal
+*/
- // the path was a local path
- if (tuple[0] && tuple[0] === obj) {
- path = tuple[1];
- key = firstKey(path);
- path = path.slice(key.length+1);
+var GUID_KEY = Ember.GUID_KEY,
+ META_KEY = Ember.META_KEY,
+ EMPTY_META = Ember.EMPTY_META,
+ metaFor = Ember.meta,
+ o_create = Ember.create,
+ objectDefineProperty = Ember.platform.defineProperty;
- // global path, but object does not exist yet.
- // put into a queue and try to connect later.
- } else if (!tuple[0]) {
- pendingQueue.push([this, path]);
- tuple.length = 0;
- return;
+var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER;
- // global path, and object already exists
- } else {
- src = tuple[0];
- key = path.slice(0, 0-(tuple[1].length+1));
- separator = path.slice(key.length, key.length+1);
- path = tuple[1];
- }
+// ..........................................................
+// DESCRIPTOR
+//
- tuple.length = 0;
- this.chain(key, path, src, separator);
-};
+/**
+ Objects of this type can implement an interface to responds requests to
+ get and set. The default implementation handles simple properties.
-// called on the root node of a chain to teardown watcher on the specified
-// path
-ChainNodePrototype.remove = function(path) {
- var obj, tuple, key, src, paths;
+ You generally won't need to create or subclass this directly.
- paths = this._paths;
- if (paths[path] > 0) { paths[path]--; }
+ @class Descriptor
+ @namespace Ember
+ @private
+ @constructor
+*/
+var Descriptor = Ember.Descriptor = function() {};
- obj = this.value();
- tuple = normalizeTuple(obj, path);
- if (tuple[0] === obj) {
- path = tuple[1];
- key = firstKey(path);
- path = path.slice(key.length+1);
- } else {
- src = tuple[0];
- key = path.slice(0, 0-(tuple[1].length+1));
- path = tuple[1];
- }
+// ..........................................................
+// DEFINING PROPERTIES API
+//
- tuple.length = 0;
- this.unchain(key, path);
-};
+/**
+ @private
-ChainNodePrototype.count = 0;
+ NOTE: This is a low-level method used by other parts of the API. You almost
+ never want to call this method directly. Instead you should use
+ `Ember.mixin()` to define new properties.
-ChainNodePrototype.chain = function(key, path, src, separator) {
- var chains = this._chains, node;
- if (!chains) { chains = this._chains = {}; }
-
- node = chains[key];
- if (!node) { node = chains[key] = new ChainNode(this, key, src, separator); }
- node.count++; // count chains...
-
- // chain rest of path if there is one
- if (path && path.length>0) {
- key = firstKey(path);
- path = path.slice(key.length+1);
- node.chain(key, path); // NOTE: no src means it will observe changes...
- }
-};
+ Defines a property on an object. This method works much like the ES5
+ `Object.defineProperty()` method except that it can also accept computed
+ properties and other special descriptors.
-ChainNodePrototype.unchain = function(key, path) {
- var chains = this._chains, node = chains[key];
+ Normally this method takes only three parameters. However if you pass an
+ instance of `Ember.Descriptor` as the third param then you can pass an
+ optional value as the fourth parameter. This is often more efficient than
+ creating new descriptor hashes for each property.
- // unchain rest of path first...
- if (path && path.length>1) {
- key = firstKey(path);
- path = path.slice(key.length+1);
- node.unchain(key, path);
- }
+ ## Examples
- // delete node if needed.
- node.count--;
- if (node.count<=0) {
- delete chains[node._key];
- node.destroy();
- }
+ ```javascript
+ // ES5 compatible mode
+ Ember.defineProperty(contact, 'firstName', {
+ writable: true,
+ configurable: false,
+ enumerable: true,
+ value: 'Charles'
+ });
-};
+ // define a simple property
+ Ember.defineProperty(contact, 'lastName', undefined, 'Jolley');
-ChainNodePrototype.willChange = function() {
- var chains = this._chains;
- if (chains) {
- for(var key in chains) {
- if (!chains.hasOwnProperty(key)) { continue; }
- chains[key].willChange();
- }
- }
+ // define a computed property
+ Ember.defineProperty(contact, 'fullName', Ember.computed(function() {
+ return this.firstName+' '+this.lastName;
+ }).property('firstName', 'lastName'));
+ ```
- if (this._parent) { this._parent.chainWillChange(this, this._key, 1); }
-};
+ @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) {
+ var descs, existingDesc, watching, value;
-ChainNodePrototype.chainWillChange = function(chain, path, depth) {
- if (this._key) { path = this._key + this._separator + path; }
+ if (!meta) meta = metaFor(obj);
+ descs = meta.descs;
+ existingDesc = meta.descs[keyName];
+ watching = meta.watching[keyName] > 0;
- if (this._parent) {
- this._parent.chainWillChange(this, path, depth+1);
- } else {
- if (depth > 1) { Ember.propertyWillChange(this.value(), path); }
- path = 'this.' + path;
- if (this._paths[path] > 0) { Ember.propertyWillChange(this.value(), path); }
+ if (existingDesc instanceof Ember.Descriptor) {
+ existingDesc.teardown(obj, keyName);
}
-};
-ChainNodePrototype.chainDidChange = function(chain, path, depth) {
- if (this._key) { path = this._key + this._separator + path; }
- if (this._parent) {
- this._parent.chainDidChange(this, path, depth+1);
- } else {
- if (depth > 1) { Ember.propertyDidChange(this.value(), path); }
- path = 'this.' + path;
- if (this._paths[path] > 0) { Ember.propertyDidChange(this.value(), path); }
- }
-};
+ if (desc instanceof Ember.Descriptor) {
+ value = desc;
-ChainNodePrototype.didChange = function(suppressEvent) {
- // invalidate my own value first.
- if (this._watching) {
- var obj = this._parent.value();
- if (obj !== this._object) {
- removeChainWatcher(this._object, this._key, this);
- this._object = obj;
- addChainWatcher(obj, this._key, this);
+ descs[keyName] = desc;
+ if (MANDATORY_SETTER && watching) {
+ objectDefineProperty(obj, keyName, {
+ configurable: true,
+ enumerable: true,
+ writable: true,
+ value: undefined // make enumerable
+ });
+ } else {
+ obj[keyName] = undefined; // make enumerable
}
- this._value = undefined;
+ desc.setup(obj, keyName);
+ } else {
+ descs[keyName] = undefined; // shadow descriptor in proto
+ if (desc == null) {
+ value = data;
- // Special-case: the EachProxy relies on immediate evaluation to
- // establish its observers.
- if (this._parent && this._parent._key === '@each')
- this.value();
- }
+ if (MANDATORY_SETTER && watching) {
+ meta.values[keyName] = data;
+ objectDefineProperty(obj, keyName, {
+ configurable: true,
+ enumerable: true,
+ set: function() {
+ Ember.assert('Must use Ember.set() to access this property', false);
+ },
+ get: function() {
+ var meta = this[META_KEY];
+ return meta && meta.values[keyName];
+ }
+ });
+ } else {
+ obj[keyName] = data;
+ }
+ } else {
+ value = desc;
- // then notify chains...
- var chains = this._chains;
- if (chains) {
- for(var key in chains) {
- if (!chains.hasOwnProperty(key)) { continue; }
- chains[key].didChange(suppressEvent);
+ // compatibility with ES5
+ objectDefineProperty(obj, keyName, desc);
}
}
- if (suppressEvent) { return; }
-
- // and finally tell parent about my path changing...
- if (this._parent) { this._parent.chainDidChange(this, this._key, 1); }
-};
-
-// 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.
-function chainsFor(obj) {
- var m = metaFor(obj), ret = m.chains;
- if (!ret) {
- ret = m.chains = new ChainNode(null, null, obj);
- } else if (ret.value() !== obj) {
- ret = m.chains = ret.copy(obj);
- }
- return ret;
-}
-
-function notifyChains(obj, m, keyName, methodName, arg) {
- var nodes = m.chainWatchers;
-
- if (!nodes || nodes.__emberproto__ !== obj) { return; } // nothing to do
-
- nodes = nodes[keyName];
- if (!nodes) { return; }
+ // if key is being watched, override chains that
+ // were initialized with the prototype
+ if (watching) { Ember.overrideChains(obj, keyName, meta); }
- for(var key in nodes) {
- if (!nodes.hasOwnProperty(key)) { continue; }
- nodes[key][methodName](arg);
- }
-}
+ // The `value` passed to the `didDefineProperty` hook is
+ // either the descriptor or data, whichever was passed.
+ if (obj.didDefineProperty) { obj.didDefineProperty(obj, keyName, value); }
-Ember.overrideChains = function(obj, keyName, m) {
- notifyChains(obj, m, keyName, 'didChange', true);
+ return this;
};
-function chainsWillChange(obj, keyName, m) {
- notifyChains(obj, m, keyName, 'willChange');
-}
-function chainsDidChange(obj, keyName, m) {
- notifyChains(obj, m, keyName, 'didChange');
-}
+})();
+
-// ..........................................................
-// WATCH
-//
+(function() {
+// Ember.tryFinally
/**
- @private
+@module ember-metal
+*/
- Starts watching a property on an object. Whenever the property changes,
- invokes Ember.propertyWillChange and Ember.propertyDidChange. This is the
- primitive used by observers and dependent keys; usually you will never call
- this method directly but instead use higher level methods like
- Ember.addObserver().
+var AFTER_OBSERVERS = ':change';
+var BEFORE_OBSERVERS = ':before';
- @method watch
- @for Ember
- @param obj
- @param {String} keyName
-*/
-Ember.watch = function(obj, keyName) {
- // can't watch length on Array - it is special...
- if (keyName === 'length' && Ember.typeOf(obj) === 'array') { return this; }
+var guidFor = Ember.guidFor;
- var m = metaFor(obj), watching = m.watching, desc;
+var deferred = 0;
- // activate watching first time
- if (!watching[keyName]) {
- watching[keyName] = 1;
- if (isKeyName(keyName)) {
- desc = m.descs[keyName];
- if (desc && desc.willWatch) { desc.willWatch(obj, keyName); }
+/*
+ this.observerSet = {
+ [senderGuid]: { // variable name: `keySet`
+ [keyName]: listIndex
+ }
+ },
+ this.observers = [
+ {
+ sender: obj,
+ keyName: keyName,
+ eventName: eventName,
+ listeners: [
+ [target, method, onceFlag, suspendedFlag]
+ ]
+ },
+ ...
+ ]
+*/
+function ObserverSet() {
+ this.clear();
+}
- if ('function' === typeof obj.willWatchProperty) {
- obj.willWatchProperty(keyName);
- }
+ObserverSet.prototype.add = function(sender, keyName, eventName) {
+ var observerSet = this.observerSet,
+ observers = this.observers,
+ senderGuid = Ember.guidFor(sender),
+ keySet = observerSet[senderGuid],
+ index;
- if (MANDATORY_SETTER && keyName in obj) {
- m.values[keyName] = obj[keyName];
- o_defineProperty(obj, keyName, {
- configurable: true,
- enumerable: true,
- set: function() {
- Ember.assert('Must use Ember.set() to access this property', false);
- },
- get: function() {
- var meta = this[META_KEY];
- return meta && meta.values[keyName];
- }
- });
- }
- } else {
- chainsFor(obj).add(keyName);
- }
+ if (!keySet) {
+ observerSet[senderGuid] = keySet = {};
+ }
+ index = keySet[keyName];
+ if (index === undefined) {
+ index = observers.push({
+ sender: sender,
+ keyName: keyName,
+ eventName: eventName,
+ listeners: []
+ }) - 1;
+ keySet[keyName] = index;
+ }
+ return observers[index].listeners;
+};
- } else {
- watching[keyName] = (watching[keyName] || 0) + 1;
+ObserverSet.prototype.flush = function() {
+ var observers = this.observers, i, len, observer, sender;
+ this.clear();
+ for (i=0, len=observers.length; i < len; ++i) {
+ observer = observers[i];
+ sender = observer.sender;
+ if (sender.isDestroying || sender.isDestroyed) { continue; }
+ Ember.sendEvent(sender, observer.eventName, [sender, observer.keyName], observer.listeners);
}
- return this;
};
-Ember.isWatching = function isWatching(obj, key) {
- var meta = obj[META_KEY];
- return (meta && meta.watching[key]) > 0;
+ObserverSet.prototype.clear = function() {
+ this.observerSet = {};
+ this.observers = [];
};
-Ember.watch.flushPending = flushPendingChains;
+var beforeObserverSet = new ObserverSet(), observerSet = new ObserverSet();
-Ember.unwatch = function(obj, keyName) {
- // can't watch length on Array - it is special...
- if (keyName === 'length' && Ember.typeOf(obj) === 'array') { return this; }
+/**
+ @method beginPropertyChanges
+ @chainable
+*/
+Ember.beginPropertyChanges = function() {
+ deferred++;
+};
- var m = metaFor(obj), watching = m.watching, desc;
+/**
+ @method endPropertyChanges
+*/
+Ember.endPropertyChanges = function() {
+ deferred--;
+ if (deferred<=0) {
+ beforeObserverSet.clear();
+ observerSet.flush();
+ }
+};
- if (watching[keyName] === 1) {
- watching[keyName] = 0;
-
- if (isKeyName(keyName)) {
- desc = m.descs[keyName];
- if (desc && desc.didUnwatch) { desc.didUnwatch(obj, keyName); }
+/**
+ Make a series of property changes together in an
+ exception-safe way.
- if ('function' === typeof obj.didUnwatchProperty) {
- obj.didUnwatchProperty(keyName);
- }
+ ```javascript
+ Ember.changeProperties(function() {
+ obj1.set('foo', mayBlowUpWhenSet);
+ obj2.set('bar', baz);
+ });
+ ```
- if (MANDATORY_SETTER && keyName in obj) {
- o_defineProperty(obj, keyName, {
- configurable: true,
- enumerable: true,
- writable: true,
- value: m.values[keyName]
- });
- delete m.values[keyName];
- }
- } else {
- chainsFor(obj).remove(keyName);
- }
+ @method changeProperties
+ @param {Function} callback
+ @param [binding]
+*/
+Ember.changeProperties = function(cb, binding){
+ Ember.beginPropertyChanges();
+ Ember.tryFinally(cb, Ember.endPropertyChanges, binding);
+};
- } else if (watching[keyName]>1) {
- watching[keyName]--;
- }
+/**
+ Set a list of properties on an object. These properties are set inside
+ a single `beginPropertyChanges` and `endPropertyChanges` batch, so
+ observers will be buffered.
- return this;
+ @method setProperties
+ @param target
+ @param {Hash} properties
+ @return target
+*/
+Ember.setProperties = function(self, hash) {
+ Ember.changeProperties(function(){
+ for(var prop in hash) {
+ if (hash.hasOwnProperty(prop)) Ember.set(self, prop, hash[prop]);
+ }
+ });
+ return self;
};
-/**
- @private
- 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.
+function changeEvent(keyName) {
+ return keyName+AFTER_OBSERVERS;
+}
- @method rewatch
- @for Ember
+function beforeEvent(keyName) {
+ return keyName+BEFORE_OBSERVERS;
+}
+
+/**
+ @method addObserver
@param obj
+ @param {String} path
+ @param {Object|Function} targetOrMethod
+ @param {Function|String} [method]
*/
-Ember.rewatch = function(obj) {
- var m = metaFor(obj, false), chains = m.chains;
-
- // make sure the object has its own guid.
- if (GUID_KEY in obj && !obj.hasOwnProperty(GUID_KEY)) {
- Ember.generateGuid(obj, 'ember');
- }
+Ember.addObserver = function(obj, path, target, method) {
+ Ember.addListener(obj, changeEvent(path), target, method);
+ Ember.watch(obj, path);
+ return this;
+};
- // make sure any chained watchers update.
- if (chains && chains.value() !== obj) {
- m.chains = chains.copy(obj);
- }
+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;
};
-Ember.finishChains = function(obj) {
- var m = metaFor(obj, false), chains = m.chains;
- if (chains) {
- if (chains.value() !== obj) {
- m.chains = chains = chains.copy(obj);
- }
- chains.didChange(true);
- }
+/**
+ @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);
+ return this;
};
-// ..........................................................
-// PROPERTY CHANGES
+// Suspend observer during callback.
//
+// This should only be used by the target of the observer
+// while it is setting the observed path.
+Ember._suspendBeforeObserver = function(obj, path, target, method, callback) {
+ return Ember._suspendListener(obj, beforeEvent(path), target, method, callback);
+};
-/**
- This function is called just before an object property is about to change.
- It will notify any before observers and prepare caches among other things.
+Ember._suspendObserver = function(obj, path, target, method, callback) {
+ return Ember._suspendListener(obj, changeEvent(path), target, method, callback);
+};
- Normally you will not need to call this method directly but if for some
- reason you can't directly watch a property you can invoke this method
- manually along with `Ember.propertyDidChange()` which you should call just
- after the property value changes.
+var map = Ember.ArrayPolyfills.map;
- @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),
- watching = m.watching[keyName] > 0 || keyName === 'length',
- proto = m.proto,
- desc = m.descs[keyName];
+Ember._suspendBeforeObservers = function(obj, paths, target, method, callback) {
+ var events = map.call(paths, beforeEvent);
+ return Ember._suspendListeners(obj, events, target, method, callback);
+};
- if (!watching) { return; }
- if (proto === obj) { return; }
- if (desc && desc.willChange) { desc.willChange(obj, keyName); }
- dependentKeysWillChange(obj, keyName, m);
- chainsWillChange(obj, keyName, m);
- Ember.notifyBeforeObservers(obj, keyName);
-}
+Ember._suspendObservers = function(obj, paths, target, method, callback) {
+ var events = map.call(paths, changeEvent);
+ return Ember._suspendListeners(obj, events, target, method, callback);
+};
-Ember.propertyWillChange = propertyWillChange;
+Ember.beforeObserversFor = function(obj, path) {
+ return Ember.listenersFor(obj, beforeEvent(path));
+};
/**
- This function is called just after an object property has changed.
- It will notify any observers and clear caches among other things.
-
- Normally you will not need to call this method directly but if for some
- reason you can't directly watch a property you can invoke this method
- manually along with `Ember.propertyWilLChange()` which you should call just
- before the property value changes.
-
- @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}
+ @method removeBeforeObserver
+ @param obj
+ @param {String} path
+ @param {Object|Function} targetOrMethod
+ @param {Function|String} [method]
*/
-function propertyDidChange(obj, keyName) {
- var m = metaFor(obj, false),
- watching = m.watching[keyName] > 0 || keyName === 'length',
- proto = m.proto,
- desc = m.descs[keyName];
-
- if (proto === obj) { return; }
-
- // shouldn't this mean that we're watching this key?
- if (desc && desc.didChange) { desc.didChange(obj, keyName); }
- if (!watching && keyName !== 'length') { return; }
-
- dependentKeysDidChange(obj, keyName, m);
- chainsDidChange(obj, keyName, m);
- Ember.notifyObservers(obj, keyName);
-}
+Ember.removeBeforeObserver = function(obj, path, target, method) {
+ Ember.unwatch(obj, path);
+ Ember.removeListener(obj, beforeEvent(path), target, method);
+ return this;
+};
-Ember.propertyDidChange = propertyDidChange;
+Ember.notifyBeforeObservers = function(obj, keyName) {
+ if (obj.isDestroying) { return; }
-var NODE_STACK = [];
+ var eventName = beforeEvent(keyName), listeners, listenersDiff;
+ if (deferred) {
+ listeners = beforeObserverSet.add(obj, keyName, eventName);
+ listenersDiff = Ember.listenersDiff(obj, eventName, listeners);
+ Ember.sendEvent(obj, eventName, [obj, keyName], listenersDiff);
+ } else {
+ Ember.sendEvent(obj, eventName, [obj, keyName]);
+ }
+};
-/**
- Tears down the meta on an object so that it can be garbage collected.
- Multiple calls will have no effect.
+Ember.notifyObservers = function(obj, keyName) {
+ if (obj.isDestroying) { return; }
- @method destroy
- @for Ember
- @param {Object} obj the object to destroy
- @return {void}
-*/
-Ember.destroy = function (obj) {
- var meta = obj[META_KEY], node, nodes, key, nodeObject;
- if (meta) {
- obj[META_KEY] = null;
- // remove chainWatchers to remove circular references that would prevent GC
- node = meta.chains;
- if (node) {
- NODE_STACK.push(node);
- // process tree
- while (NODE_STACK.length > 0) {
- node = NODE_STACK.pop();
- // push children
- nodes = node._chains;
- if (nodes) {
- for (key in nodes) {
- if (nodes.hasOwnProperty(key)) {
- NODE_STACK.push(nodes[key]);
- }
- }
- }
- // remove chainWatcher in node object
- if (node._watching) {
- nodeObject = node._object;
- if (nodeObject) {
- removeChainWatcher(nodeObject, node._key, node);
- }
- }
- }
- }
+ var eventName = changeEvent(keyName), listeners;
+ if (deferred) {
+ listeners = observerSet.add(obj, keyName, eventName);
+ Ember.listenersUnion(obj, eventName, listeners);
+ } else {
+ Ember.sendEvent(obj, eventName, [obj, keyName]);
}
};
@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);
+var guidFor = Ember.guidFor, // utils.js
+ metaFor = Ember.meta, // utils.js
+ get = Ember.get, // accessors.js
+ set = Ember.set, // accessors.js
+ normalizeTuple = Ember.normalizeTuple, // accessors.js
+ GUID_KEY = Ember.GUID_KEY, // utils.js
+ META_KEY = Ember.META_KEY, // utils.js
+ // circular reference observer depends on Ember.watch
+ // we should move change events to this file or its own property_events.js
+ notifyObservers = Ember.notifyObservers, // observer.js
+ forEach = Ember.ArrayPolyfills.forEach, // array.js
+ FIRST_KEY = /^([^\.\*]+)/,
+ IS_PATH = /[\.\*]/;
+var MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER,
+o_defineProperty = Ember.platform.defineProperty;
-var get = Ember.get,
- metaFor = Ember.meta,
- guidFor = Ember.guidFor,
- a_slice = [].slice,
- o_create = Ember.create,
- META_KEY = Ember.META_KEY,
- watch = Ember.watch,
- unwatch = Ember.unwatch;
+function firstKey(path) {
+ return path.match(FIRST_KEY)[0];
+}
+
+// returns true if the passed path is just a keyName
+function isKeyName(path) {
+ return path==='*' || !IS_PATH.test(path);
+}
// ..........................................................
// DEPENDENT KEYS
//
-// data structure:
-// meta.deps = {
-// 'depKey': {
-// 'keyName': count,
-// __emberproto__: SRC_OBJ [to detect clones]
-// },
-// __emberproto__: SRC_OBJ
-// }
+function iterDeps(method, obj, depKey, seen, meta) {
-/*
- This function returns a map of unique dependencies for a
- given object and key.
-*/
-function keysForDep(obj, depsMeta, depKey) {
- var keys = depsMeta[depKey];
- if (!keys) {
- // if there are no dependencies yet for a the given key
- // create a new empty list of dependencies for the key
- keys = depsMeta[depKey] = { __emberproto__: obj };
- } else if (keys.__emberproto__ !== obj) {
- // otherwise if the dependency list is inherited from
- // a superclass, clone the hash
- keys = depsMeta[depKey] = o_create(keys);
- keys.__emberproto__ = obj;
- }
- return keys;
-}
+ var guid = guidFor(obj);
+ if (!seen[guid]) seen[guid] = {};
+ if (seen[guid][depKey]) return;
+ seen[guid][depKey] = true;
-/* return obj[META_KEY].deps */
-function metaForDeps(obj, meta) {
var deps = meta.deps;
- // If the current object has no dependencies...
- if (!deps) {
- // initialize the dependencies with a pointer back to
- // the current object
- deps = meta.deps = { __emberproto__: obj };
- } else if (deps.__emberproto__ !== obj) {
- // otherwise if the dependencies are inherited from the
- // object's superclass, clone the deps
- deps = meta.deps = o_create(deps);
- deps.__emberproto__ = obj;
+ deps = deps && deps[depKey];
+ if (deps) {
+ for(var key in deps) {
+ var desc = meta.descs[key];
+ if (desc && desc._suspended === obj) continue;
+ method(obj, key);
+ }
}
- return deps;
}
-function addDependentKeys(desc, obj, keyName, meta) {
- // the descriptor has a list of dependent keys, so
- // add all of its dependent keys.
- var depKeys = desc._dependentKeys, depsMeta, idx, len, depKey, keys;
- if (!depKeys) return;
- depsMeta = metaForDeps(obj, meta);
+var WILL_SEEN, DID_SEEN;
- for(idx = 0, len = depKeys.length; idx < len; idx++) {
- depKey = depKeys[idx];
- // Lookup keys meta for depKey
- keys = keysForDep(obj, depsMeta, depKey);
- // Increment the number of times depKey depends on keyName.
- keys[keyName] = (keys[keyName] || 0) + 1;
- // Watch the depKey
- watch(obj, depKey);
- }
-}
+// called whenever a property is about to change to clear the cache of any dependent keys (and notify those properties of changes, etc...)
+function dependentKeysWillChange(obj, depKey, meta) {
+ if (obj.isDestroying) { return; }
-function removeDependentKeys(desc, obj, keyName, meta) {
- // the descriptor has a list of dependent keys, so
- // add all of its dependent keys.
- var depKeys = desc._dependentKeys, depsMeta, idx, len, depKey, keys;
- if (!depKeys) return;
+ var seen = WILL_SEEN, top = !seen;
+ if (top) { seen = WILL_SEEN = {}; }
+ iterDeps(propertyWillChange, obj, depKey, seen, meta);
+ if (top) { WILL_SEEN = null; }
+}
- depsMeta = metaForDeps(obj, meta);
+// called whenever a property has just changed to update dependent keys
+function dependentKeysDidChange(obj, depKey, meta) {
+ if (obj.isDestroying) { return; }
- for(idx = 0, len = depKeys.length; idx < len; idx++) {
- depKey = depKeys[idx];
- // Lookup keys meta for depKey
- keys = keysForDep(obj, depsMeta, depKey);
- // Increment the number of times depKey depends on keyName.
- keys[keyName] = (keys[keyName] || 0) - 1;
- // Watch the depKey
- unwatch(obj, depKey);
- }
+ var seen = DID_SEEN, top = !seen;
+ if (top) { seen = DID_SEEN = {}; }
+ iterDeps(propertyDidChange, obj, depKey, seen, meta);
+ if (top) { DID_SEEN = null; }
}
// ..........................................................
-// COMPUTED PROPERTY
+// CHAIN
//
-/**
- @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;
-}
-
-Ember.ComputedProperty = ComputedProperty;
-ComputedProperty.prototype = new Ember.Descriptor();
-
-var ComputedPropertyPrototype = ComputedProperty.prototype;
-
-/**
- Call on a computed property to set it into cacheable mode. When in this
- mode the computed property will automatically cache the return value of
- your function until one of the dependent keys changes.
+function addChainWatcher(obj, keyName, node) {
+ if (!obj || ('object' !== typeof obj)) { return; } // nothing to do
- MyApp.president = Ember.Object.create({
- fullName: function() {
- return this.get('firstName') + ' ' + this.get('lastName');
+ var m = metaFor(obj), nodes = m.chainWatchers;
- // After calculating the value of this function, Ember.js will
- // return that value without re-executing this function until
- // one of the dependent properties change.
- }.property('firstName', 'lastName').cacheable()
- });
+ if (!m.hasOwnProperty('chainWatchers')) {
+ nodes = m.chainWatchers = {};
+ }
- Properties are cacheable by default.
+ if (!nodes[keyName]) { nodes[keyName] = []; }
+ nodes[keyName].push(node);
+ Ember.watch(obj, keyName);
+}
- @method cacheable
- @param {Boolean} aFlag optional set to false to disable caching
- @chainable
-*/
-ComputedPropertyPrototype.cacheable = function(aFlag) {
- this._cacheable = aFlag !== false;
- return this;
-};
+function removeChainWatcher(obj, keyName, node) {
+ if (!obj || 'object' !== typeof obj) { return; } // nothing to do
-/**
- Call on a computed property to set it into non-cached mode. When in this
- mode the computed property will not automatically cache the return value.
+ var m = metaFor(obj, false);
+ if (!m.hasOwnProperty('chainWatchers')) { return; } // nothing to do
- MyApp.outsideService = Ember.Object.create({
- value: function() {
- return OutsideService.getValue();
- }.property().volatile()
- });
+ var nodes = m.chainWatchers;
- @method volatile
- @chainable
-*/
-ComputedPropertyPrototype.volatile = function() {
- return this.cacheable(false);
-};
+ if (nodes[keyName]) {
+ nodes = nodes[keyName];
+ for (var i = 0, l = nodes.length; i < l; i++) {
+ if (nodes[i] === node) { nodes.splice(i, 1); }
+ }
+ }
+ Ember.unwatch(obj, keyName);
+}
-/**
- Sets the dependent keys on this computed property. Pass any number of
- arguments containing key paths that this computed property depends on.
+var pendingQueue = [];
- MyApp.president = Ember.Object.create({
- fullName: Ember.computed(function() {
- return this.get('firstName') + ' ' + this.get('lastName');
+// 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.
+function flushPendingChains() {
+ if (pendingQueue.length === 0) { return; } // nothing to do
- // Tell Ember.js that this computed property depends on firstName
- // and lastName
- }).property('firstName', 'lastName')
- });
+ var queue = pendingQueue;
+ pendingQueue = [];
- @method property
- @param {String} path* zero or more property paths
- @chainable
-*/
-ComputedPropertyPrototype.property = function() {
- var args = [];
- for (var i = 0, l = arguments.length; i < l; i++) {
- args.push(arguments[i]);
- }
- this._dependentKeys = args;
- return this;
-};
+ forEach.call(queue, function(q) { q[0].add(q[1]); });
-/**
- In some cases, you may want to annotate computed properties with additional
- metadata about how they function or what values they operate on. For example,
- computed property functions may close over variables that are then no longer
- available for introspection.
+ 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);
+}
- You can pass a hash of these values to a computed property like this:
+function isProto(pvalue) {
+ return metaFor(pvalue, false).proto === pvalue;
+}
- person: function() {
- var personId = this.get('personId');
- return App.Person.create({ id: personId });
- }.property().meta({ type: App.Person })
+// 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.
+var ChainNode = function(parent, key, value) {
+ var obj;
+ this._parent = parent;
+ this._key = key;
- The hash that you pass to the `meta()` function will be saved on the
- computed property descriptor under the `_meta` key. Ember runtime
- exposes a public API for retrieving these values from classes,
- via the `metaForProperty()` function.
+ // _watching is true when calling get(this._parent, this._key) will
+ // return the value of this node.
+ //
+ // It is false for the root of a chain (because we have no parent)
+ // and for global paths (because the parent node is the object with
+ // the observer on it)
+ this._watching = value===undefined;
- @method meta
- @param {Hash} meta
- @chainable
-*/
+ this._value = value;
+ this._paths = {};
+ if (this._watching) {
+ this._object = parent.value();
+ if (this._object) { addChainWatcher(this._object, this._key, this); }
+ }
-ComputedPropertyPrototype.meta = function(meta) {
- if (arguments.length === 0) {
- return this._meta || {};
- } else {
- this._meta = meta;
- return this;
+ // Special-case: the EachProxy relies on immediate evaluation to
+ // establish its observers.
+ //
+ // TODO: Replace this with an efficient callback that the EachProxy
+ // can implement.
+ if (this._parent && this._parent._key === '@each') {
+ this.value();
}
};
-/* impl descriptor API */
-ComputedPropertyPrototype.willWatch = function(obj, keyName) {
- // watch already creates meta for this instance
- var meta = obj[META_KEY];
- Ember.assert('watch should have setup meta to be writable', meta.source === obj);
- if (!(keyName in meta.cache)) {
- addDependentKeys(this, obj, keyName, meta);
+var ChainNodePrototype = ChainNode.prototype;
+
+ChainNodePrototype.value = function() {
+ if (this._value === undefined && this._watching) {
+ var obj = this._parent.value();
+ this._value = (obj && !isProto(obj)) ? get(obj, this._key) : undefined;
}
+ return this._value;
};
-ComputedPropertyPrototype.didUnwatch = function(obj, keyName) {
- var meta = obj[META_KEY];
- Ember.assert('unwatch should have setup meta to be writable', meta.source === obj);
- if (!(keyName in meta.cache)) {
- // unwatch already creates meta for this instance
- removeDependentKeys(this, obj, keyName, meta);
- }
-};
-
-/* 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
- if (this._cacheable && this._suspended !== obj) {
- var meta = metaFor(obj);
- if (keyName in meta.cache) {
- delete meta.cache[keyName];
- if (!meta.watching[keyName]) {
- removeDependentKeys(this, obj, keyName, meta);
- }
- }
+ChainNodePrototype.destroy = function() {
+ if (this._watching) {
+ var obj = this._object;
+ if (obj) { removeChainWatcher(obj, this._key, this); }
+ this._watching = false; // so future calls do nothing
}
};
-/* impl descriptor API */
-ComputedPropertyPrototype.get = function(obj, keyName) {
- var ret, cache, meta;
- if (this._cacheable) {
- meta = metaFor(obj);
- cache = meta.cache;
- if (keyName in cache) { return cache[keyName]; }
- ret = cache[keyName] = this.func.call(obj, keyName);
- if (!meta.watching[keyName]) {
- addDependentKeys(this, obj, keyName, meta);
- }
- } else {
- ret = this.func.call(obj, keyName);
+// copies a top level object only
+ChainNodePrototype.copy = function(obj) {
+ var ret = new ChainNode(null, null, obj),
+ paths = this._paths, path;
+ for (path in paths) {
+ if (paths[path] <= 0) { continue; } // this check will also catch non-number vals.
+ ret.add(path);
}
return ret;
};
-/* 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 = false,
- ret;
- this._suspended = obj;
- try {
- ret = this.func.call(obj, keyName, value);
+// called on the root node of a chain to setup watchers on the specified
+// path.
+ChainNodePrototype.add = function(path) {
+ var obj, tuple, key, src, paths;
- if (cacheable && keyName in meta.cache) {
- if (meta.cache[keyName] === ret) {
- return;
- }
- hadCachedValue = true;
- }
+ paths = this._paths;
+ paths[path] = (paths[path] || 0) + 1;
- if (watched) { Ember.propertyWillChange(obj, keyName); }
+ obj = this.value();
+ tuple = normalizeTuple(obj, path);
- if (cacheable && hadCachedValue) {
- delete meta.cache[keyName];
- }
+ // the path was a local path
+ if (tuple[0] && tuple[0] === obj) {
+ path = tuple[1];
+ key = firstKey(path);
+ path = path.slice(key.length+1);
- if (cacheable) {
- if (!watched && !hadCachedValue) {
- addDependentKeys(this, obj, keyName, meta);
- }
- meta.cache[keyName] = ret;
- }
+ // global path, but object does not exist yet.
+ // put into a queue and try to connect later.
+ } else if (!tuple[0]) {
+ pendingQueue.push([this, path]);
+ tuple.length = 0;
+ return;
- if (watched) { Ember.propertyDidChange(obj, keyName); }
- } finally {
- this._suspended = oldSuspended;
+ // global path, and object already exists
+ } else {
+ src = tuple[0];
+ key = path.slice(0, 0-(tuple[1].length+1));
+ path = tuple[1];
}
- return ret;
-};
-/* called when property is defined */
-ComputedPropertyPrototype.setup = function(obj, keyName) {
- var meta = obj[META_KEY];
- if (meta && meta.watching[keyName]) {
- addDependentKeys(this, obj, keyName, metaFor(obj));
- }
+ tuple.length = 0;
+ this.chain(key, path, src);
};
-/* called before property is overridden */
-ComputedPropertyPrototype.teardown = function(obj, keyName) {
- var meta = metaFor(obj);
+// called on the root node of a chain to teardown watcher on the specified
+// path
+ChainNodePrototype.remove = function(path) {
+ var obj, tuple, key, src, paths;
- if (meta.watching[keyName] || keyName in meta.cache) {
- removeDependentKeys(this, obj, keyName, meta);
- }
+ paths = this._paths;
+ if (paths[path] > 0) { paths[path]--; }
- if (this._cacheable) { delete meta.cache[keyName]; }
+ obj = this.value();
+ tuple = normalizeTuple(obj, path);
+ if (tuple[0] === obj) {
+ path = tuple[1];
+ key = firstKey(path);
+ path = path.slice(key.length+1);
+ } else {
+ src = tuple[0];
+ key = path.slice(0, 0-(tuple[1].length+1));
+ path = tuple[1];
+ }
- return null; // no value to restore
+ tuple.length = 0;
+ this.unchain(key, path);
};
+ChainNodePrototype.count = 0;
-/**
- This helper returns a new property descriptor that wraps the passed
- computed property function. You can use this helper to define properties
- with mixins or via Ember.defineProperty().
-
- The function you pass will be used to both get and set property values.
- The function should accept two parameters, key and value. If value is not
- undefined you should set the value first. In either case return the
- current value of the property.
+ChainNodePrototype.chain = function(key, path, src) {
+ var chains = this._chains, node;
+ if (!chains) { chains = this._chains = {}; }
- @method computed
- @for Ember
- @param {Function} func The computed property function.
- @return {Ember.ComputedProperty} property descriptor instance
-*/
-Ember.computed = function(func) {
- var args;
+ node = chains[key];
+ if (!node) { node = chains[key] = new ChainNode(this, key, src); }
+ node.count++; // count chains...
- if (arguments.length > 1) {
- args = a_slice.call(arguments, 0, -1);
- func = a_slice.call(arguments, -1)[0];
+ // chain rest of path if there is one
+ if (path && path.length>0) {
+ key = firstKey(path);
+ path = path.slice(key.length+1);
+ node.chain(key, path); // NOTE: no src means it will observe changes...
}
+};
- var cp = new ComputedProperty(func);
+ChainNodePrototype.unchain = function(key, path) {
+ var chains = this._chains, node = chains[key];
- if (args) {
- cp.property.apply(cp, args);
+ // unchain rest of path first...
+ if (path && path.length>1) {
+ key = firstKey(path);
+ path = path.slice(key.length+1);
+ node.unchain(key, path);
}
- return cp;
-};
-
-/**
- Returns the cached value for a property, if one exists.
- This can be useful for peeking at the value of a computed
- property that is generated lazily, without accidentally causing
- it to be created.
+ // delete node if needed.
+ node.count--;
+ if (node.count<=0) {
+ delete chains[node._key];
+ node.destroy();
+ }
- @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;
+};
- if (cache && key in cache) {
- return cache[key];
+ChainNodePrototype.willChange = function() {
+ var chains = this._chains;
+ if (chains) {
+ for(var key in chains) {
+ if (!chains.hasOwnProperty(key)) { continue; }
+ chains[key].willChange();
+ }
}
-};
-/**
- @method computed.not
- @for Ember
- @param {String} dependentKey
-*/
-Ember.computed.not = function(dependentKey) {
- return Ember.computed(dependentKey, function(key) {
- return !get(this, dependentKey);
- }).cacheable();
+ if (this._parent) { this._parent.chainWillChange(this, this._key, 1); }
};
-/**
- @method computed.empty
- @for Ember
- @param {String} dependentKey
-*/
-Ember.computed.empty = function(dependentKey) {
- return Ember.computed(dependentKey, function(key) {
- var val = get(this, dependentKey);
- return val === undefined || val === null || val === '' || (Ember.isArray(val) && get(val, 'length') === 0);
- }).cacheable();
+ChainNodePrototype.chainWillChange = function(chain, path, depth) {
+ if (this._key) { path = this._key + '.' + path; }
+
+ if (this._parent) {
+ this._parent.chainWillChange(this, path, depth+1);
+ } else {
+ if (depth > 1) { Ember.propertyWillChange(this.value(), path); }
+ path = 'this.' + path;
+ if (this._paths[path] > 0) { Ember.propertyWillChange(this.value(), path); }
+ }
};
-/**
- @method computed.bool
- @for Ember
- @param {String} dependentKey
-*/
-Ember.computed.bool = function(dependentKey) {
- return Ember.computed(dependentKey, function(key) {
- return !!get(this, dependentKey);
- }).cacheable();
+ChainNodePrototype.chainDidChange = function(chain, path, depth) {
+ if (this._key) { path = this._key + '.' + path; }
+ if (this._parent) {
+ this._parent.chainDidChange(this, path, depth+1);
+ } else {
+ if (depth > 1) { Ember.propertyDidChange(this.value(), path); }
+ path = 'this.' + path;
+ if (this._paths[path] > 0) { Ember.propertyDidChange(this.value(), path); }
+ }
};
-})();
+ChainNodePrototype.didChange = function(suppressEvent) {
+ // invalidate my own value first.
+ if (this._watching) {
+ var obj = this._parent.value();
+ if (obj !== this._object) {
+ removeChainWatcher(this._object, this._key, this);
+ this._object = obj;
+ addChainWatcher(obj, this._key, this);
+ }
+ this._value = undefined;
+ // Special-case: the EachProxy relies on immediate evaluation to
+ // establish its observers.
+ if (this._parent && this._parent._key === '@each')
+ this.value();
+ }
+ // then notify chains...
+ var chains = this._chains;
+ if (chains) {
+ for(var key in chains) {
+ if (!chains.hasOwnProperty(key)) { continue; }
+ chains[key].didChange(suppressEvent);
+ }
+ }
-(function() {
-/**
-@module ember-metal
-*/
+ if (suppressEvent) { return; }
-var o_create = Ember.create,
- meta = Ember.meta,
- metaPath = Ember.metaPath,
- guidFor = Ember.guidFor,
- a_slice = [].slice;
+ // and finally tell parent about my path changing...
+ if (this._parent) { this._parent.chainDidChange(this, this._key, 1); }
+};
-/*
- 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.
+// 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.
+function chainsFor(obj) {
+ var m = metaFor(obj), ret = m.chains;
+ if (!ret) {
+ ret = m.chains = new ChainNode(null, null, obj);
+ } else if (ret.value() !== obj) {
+ ret = m.chains = ret.copy(obj);
+ }
+ return ret;
+}
- The hashes are stored in the object's meta hash, and look like this:
+Ember.overrideChains = function(obj, keyName, m) {
+ chainsDidChange(obj, keyName, m, true);
+};
- // Object's meta hash
- {
- listeners: { // variable name: `listenerSet`
- "foo:changed": { // variable name: `targetSet`
- [targetGuid]: { // variable name: `actionSet`
- [methodGuid]: { // variable name: `action`
- target: [Object object],
- method: [Function function]
- }
- }
- }
- }
- }
+function chainsWillChange(obj, keyName, m, arg) {
+ if (!m.hasOwnProperty('chainWatchers')) { return; } // nothing to do
-*/
+ var nodes = m.chainWatchers;
+
+ nodes = nodes[keyName];
+ if (!nodes) { return; }
-// Gets the set of all actions, keyed on the guid of each action's
-// method property.
-function actionSetFor(obj, eventName, target, writable) {
- return metaPath(obj, ['listeners', eventName, guidFor(target)], writable);
+ for(var i = 0, l = nodes.length; i < l; i++) {
+ nodes[i].willChange(arg);
+ }
}
-// Gets the set of all targets, keyed on the guid of each action's
-// target property.
-function targetSetFor(obj, eventName) {
- var listenerSet = meta(obj, false).listeners;
- if (!listenerSet) { return false; }
+function chainsDidChange(obj, keyName, m, arg) {
+ if (!m.hasOwnProperty('chainWatchers')) { return; } // nothing to do
- return listenerSet[eventName] || false;
-}
+ var nodes = m.chainWatchers;
-// TODO: This knowledge should really be a part of the
-// meta system.
-var SKIP_PROPERTIES = { __ember_source__: true };
-
-function iterateSet(obj, eventName, callback, params) {
- var targetSet = targetSetFor(obj, eventName);
- if (!targetSet) { return false; }
- // Iterate through all elements of the target set
- for(var targetGuid in targetSet) {
- if (SKIP_PROPERTIES[targetGuid]) { continue; }
-
- var actionSet = targetSet[targetGuid];
- if (actionSet) {
- // Iterate through the elements of the action set
- for(var methodGuid in actionSet) {
- if (SKIP_PROPERTIES[methodGuid]) { continue; }
-
- var action = actionSet[methodGuid];
- if (action) {
- if (callback(action, params, obj) === true) {
- return true;
- }
- }
- }
- }
- }
- return false;
-}
+ nodes = nodes[keyName];
+ if (!nodes) { return; }
-function invokeAction(action, params, sender) {
- var method = action.method, target = action.target;
- // If there is no target, the target is the object
- // on which the event was fired.
- if (!target) { target = sender; }
- if ('string' === typeof method) { method = target[method]; }
- if (params) {
- method.apply(target, params);
- } else {
- method.apply(target);
+ // looping in reverse because the chainWatchers array can be modified inside didChange
+ for (var i = nodes.length - 1; i >= 0; i--) {
+ nodes[i].didChange(arg);
}
}
+// ..........................................................
+// WATCH
+//
+
/**
- Add an event listener
+ @private
- @method addListener
+ Starts watching a property on an object. Whenever the property changes,
+ invokes `Ember.propertyWillChange` and `Ember.propertyDidChange`. This is the
+ 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} 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 {String} keyName
*/
-function addListener(obj, eventName, target, method) {
- Ember.assert("You must pass at least an object and event name to Ember.addListener", !!obj && !!eventName);
-
- if (!method && 'function' === typeof target) {
- method = target;
- target = null;
- }
-
- var actionSet = actionSetFor(obj, eventName, target, true),
- methodGuid = guidFor(method);
-
- if (!actionSet[methodGuid]) {
- actionSet[methodGuid] = { target: target, method: method };
- }
+Ember.watch = function(obj, keyName) {
+ // can't watch length on Array - it is special...
+ if (keyName === 'length' && Ember.typeOf(obj) === 'array') { return this; }
- if ('function' === typeof obj.didAddListener) {
- obj.didAddListener(eventName, target, method);
- }
-}
+ var m = metaFor(obj), watching = m.watching, desc;
-/**
- Remove an event listener
+ // activate watching first time
+ if (!watching[keyName]) {
+ watching[keyName] = 1;
+ if (isKeyName(keyName)) {
+ desc = m.descs[keyName];
+ if (desc && desc.willWatch) { desc.willWatch(obj, keyName); }
- Arguments should match those passed to {{#crossLink "Ember/addListener"}}{{/crossLink}}
+ if ('function' === typeof obj.willWatchProperty) {
+ obj.willWatchProperty(keyName);
+ }
- @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);
+ if (MANDATORY_SETTER && keyName in obj) {
+ m.values[keyName] = obj[keyName];
+ o_defineProperty(obj, keyName, {
+ configurable: true,
+ enumerable: true,
+ set: function() {
+ Ember.assert('Must use Ember.set() to access this property', false);
+ },
+ get: function() {
+ var meta = this[META_KEY];
+ return meta && meta.values[keyName];
+ }
+ });
+ }
+ } else {
+ chainsFor(obj).add(keyName);
+ }
- if (!method && 'function' === typeof target) {
- method = target;
- target = null;
+ } else {
+ watching[keyName] = (watching[keyName] || 0) + 1;
}
+ return this;
+};
- var actionSet = actionSetFor(obj, eventName, target, true),
- methodGuid = guidFor(method);
+Ember.isWatching = function isWatching(obj, key) {
+ var meta = obj[META_KEY];
+ return (meta && meta.watching[key]) > 0;
+};
- // we can't simply delete this parameter, because if we do, we might
- // re-expose the property from the prototype chain.
- if (actionSet && actionSet[methodGuid]) { actionSet[methodGuid] = null; }
+Ember.watch.flushPending = flushPendingChains;
- if ('function' === typeof obj.didRemoveListener) {
- obj.didRemoveListener(eventName, target, method);
- }
-}
+Ember.unwatch = function(obj, keyName) {
+ // can't watch length on Array - it is special...
+ if (keyName === 'length' && Ember.typeOf(obj) === 'array') { return this; }
-/**
- @private
+ var m = metaFor(obj), watching = m.watching, desc;
- Suspend listener during callback.
+ if (watching[keyName] === 1) {
+ watching[keyName] = 0;
- 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.
+ if (isKeyName(keyName)) {
+ desc = m.descs[keyName];
+ if (desc && desc.didUnwatch) { desc.didUnwatch(obj, keyName); }
- @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;
- target = null;
- }
+ if ('function' === typeof obj.didUnwatchProperty) {
+ obj.didUnwatchProperty(keyName);
+ }
- var actionSet = actionSetFor(obj, eventName, target, true),
- methodGuid = guidFor(method),
- action = actionSet && actionSet[methodGuid];
+ if (MANDATORY_SETTER && keyName in obj) {
+ o_defineProperty(obj, keyName, {
+ configurable: true,
+ enumerable: true,
+ writable: true,
+ value: m.values[keyName]
+ });
+ delete m.values[keyName];
+ }
+ } else {
+ chainsFor(obj).remove(keyName);
+ }
- actionSet[methodGuid] = null;
- try {
- return callback.call(target);
- } finally {
- actionSet[methodGuid] = action;
+ } else if (watching[keyName]>1) {
+ watching[keyName]--;
}
-}
+
+ return this;
+};
/**
@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.
+ 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 suspendListener
+ @method rewatch
@for Ember
@param obj
- @param {Array} eventName Array of event names
- @param {Object|Function} targetOrMethod A target object or a function
- @param {Function|String} method A function or the name of a function to be called on `target`
- @param {Function} callback
*/
-function suspendListeners(obj, eventNames, target, method, callback) {
- if (!method && 'function' === typeof target) {
- method = target;
- target = null;
- }
-
- var oldActions = [],
- actionSets = [],
- eventName, actionSet, methodGuid, action, i, l;
-
- for (i=0, l=eventNames.length; i<l; i++) {
- eventName = eventNames[i];
- actionSet = actionSetFor(obj, eventName, target, true),
- methodGuid = guidFor(method);
+Ember.rewatch = function(obj) {
+ var m = metaFor(obj, false), chains = m.chains;
- oldActions.push(actionSet && actionSet[methodGuid]);
- actionSets.push(actionSet);
+ // make sure the object has its own guid.
+ if (GUID_KEY in obj && !obj.hasOwnProperty(GUID_KEY)) {
+ Ember.generateGuid(obj, 'ember');
+ }
- actionSet[methodGuid] = null;
+ // make sure any chained watchers update.
+ if (chains && chains.value() !== obj) {
+ m.chains = chains.copy(obj);
}
- try {
- return callback.call(target);
- } finally {
- for (i=0, l=oldActions.length; i<l; i++) {
- eventName = eventNames[i];
- actionSets[i][methodGuid] = oldActions[i];
+ return this;
+};
+
+Ember.finishChains = function(obj) {
+ var m = metaFor(obj, false), chains = m.chains;
+ if (chains) {
+ if (chains.value() !== obj) {
+ m.chains = chains = chains.copy(obj);
}
+ chains.didChange(true);
}
-}
+};
+
+// ..........................................................
+// PROPERTY CHANGES
+//
/**
- @private
+ This function is called just before an object property is about to change.
+ It will notify any before observers and prepare caches among other things.
- Return a list of currently watched events
+ Normally you will not need to call this method directly but if for some
+ reason you can't directly watch a property you can invoke this method
+ manually along with `Ember.propertyDidChange()` which you should call just
+ after the property value changes.
- @method watchedEvents
+ @method propertyWillChange
@for Ember
- @param obj
+ @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 watchedEvents(obj) {
- var listeners = meta(obj, false).listeners, ret = [];
+function propertyWillChange(obj, keyName, value) {
+ var m = metaFor(obj, false),
+ watching = m.watching[keyName] > 0 || keyName === 'length',
+ proto = m.proto,
+ desc = m.descs[keyName];
- if (listeners) {
- for(var eventName in listeners) {
- if (!SKIP_PROPERTIES[eventName] && listeners[eventName]) {
- ret.push(eventName);
- }
- }
- }
- return ret;
+ if (!watching) { return; }
+ if (proto === obj) { return; }
+ if (desc && desc.willChange) { desc.willChange(obj, keyName); }
+ dependentKeysWillChange(obj, keyName, m);
+ chainsWillChange(obj, keyName, m);
+ Ember.notifyBeforeObservers(obj, keyName);
}
+Ember.propertyWillChange = propertyWillChange;
+
/**
- @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) {
- obj.sendEvent(eventName, params);
- }
+ This function is called just after an object property has changed.
+ It will notify any observers and clear caches among other things.
- iterateSet(obj, eventName, invokeAction, params);
- return true;
-}
+ Normally you will not need to call this method directly but if for some
+ reason you can't directly watch a property you can invoke this method
+ manually along with `Ember.propertyWilLChange()` which you should call just
+ before the property value changes.
-/**
- @private
- @method deferEvent
+ @method propertyDidChange
@for Ember
- @param obj
- @param {String} eventName
- @param {Array} params
+ @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 deferEvent(obj, eventName, params) {
- var actions = [];
- iterateSet(obj, eventName, function (action) {
- actions.push(action);
- });
+function propertyDidChange(obj, keyName) {
+ var m = metaFor(obj, false),
+ watching = m.watching[keyName] > 0 || keyName === 'length',
+ proto = m.proto,
+ desc = m.descs[keyName];
- return function() {
- if (obj.isDestroyed) { return; }
+ if (proto === obj) { return; }
- if (obj !== Ember && 'function' === typeof obj.sendEvent) {
- obj.sendEvent(eventName, params);
- }
+ // shouldn't this mean that we're watching this key?
+ if (desc && desc.didChange) { desc.didChange(obj, keyName); }
+ if (!watching && keyName !== 'length') { return; }
- for (var i=0, len=actions.length; i < len; ++i) {
- invokeAction(actions[i], params, obj);
- }
- };
+ dependentKeysDidChange(obj, keyName, m);
+ chainsDidChange(obj, keyName, m);
+ Ember.notifyObservers(obj, keyName);
}
-/**
- @private
- @method hasListeners
- @for Ember
- @param obj
- @param {String} eventName
-*/
-function hasListeners(obj, eventName) {
- if (iterateSet(obj, eventName, function() { return true; })) {
- return true;
- }
-
- // no listeners! might as well clean this up so it is faster later.
- var set = metaPath(obj, ['listeners'], true);
- set[eventName] = null;
+Ember.propertyDidChange = propertyDidChange;
- return false;
-}
+var NODE_STACK = [];
/**
- @private
- @method listenersFor
+ 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 obj
- @param {String} eventName
+ @param {Object} obj the object to destroy
+ @return {void}
*/
-function listenersFor(obj, eventName) {
- var ret = [];
- iterateSet(obj, eventName, function (action) {
- ret.push([action.target, action.method]);
- });
- return ret;
-}
-
-Ember.addListener = addListener;
-Ember.removeListener = removeListener;
-Ember._suspendListener = suspendListener;
-Ember._suspendListeners = suspendListeners;
-Ember.sendEvent = sendEvent;
-Ember.hasListeners = hasListeners;
-Ember.watchedEvents = watchedEvents;
-Ember.listenersFor = listenersFor;
-Ember.deferEvent = deferEvent;
+Ember.destroy = function (obj) {
+ var meta = obj[META_KEY], node, nodes, key, nodeObject;
+ if (meta) {
+ obj[META_KEY] = null;
+ // remove chainWatchers to remove circular references that would prevent GC
+ node = meta.chains;
+ if (node) {
+ NODE_STACK.push(node);
+ // process tree
+ while (NODE_STACK.length > 0) {
+ node = NODE_STACK.pop();
+ // push children
+ nodes = node._chains;
+ if (nodes) {
+ for (key in nodes) {
+ if (nodes.hasOwnProperty(key)) {
+ NODE_STACK.push(nodes[key]);
+ }
+ }
+ }
+ // remove chainWatcher in node object
+ if (node._watching) {
+ nodeObject = node._object;
+ if (nodeObject) {
+ removeChainWatcher(nodeObject, node._key, node);
+ }
+ }
+ }
+ }
+ }
+};
})();
(function() {
-// Ember.Logger
-// Ember.watch.flushPending
-// Ember.beginPropertyChanges, Ember.endPropertyChanges
-// Ember.guidFor
-
/**
@module ember-metal
*/
+Ember.warn("The CP_DEFAULT_CACHEABLE flag has been removed and computed properties are always cached by default. Use `volatile` if you don't want caching.", Ember.ENV.CP_DEFAULT_CACHEABLE !== false);
+
+
+var get = Ember.get,
+ set = Ember.set,
+ metaFor = Ember.meta,
+ guidFor = Ember.guidFor,
+ a_slice = [].slice,
+ o_create = Ember.create,
+ META_KEY = Ember.META_KEY,
+ watch = Ember.watch,
+ unwatch = Ember.unwatch;
+
// ..........................................................
-// HELPERS
+// DEPENDENT KEYS
//
-var slice = [].slice,
- forEach = Ember.ArrayPolyfills.forEach;
-
-// invokes passed params - normalizing so you can pass target/func,
-// target/string or just func
-function invoke(target, method, args, ignore) {
+// data structure:
+// meta.deps = {
+// 'depKey': {
+// 'keyName': count,
+// }
+// }
- if (method === undefined) {
- method = target;
- target = undefined;
+/*
+ This function returns a map of unique dependencies for a
+ given object and key.
+*/
+function keysForDep(obj, depsMeta, depKey) {
+ var keys = depsMeta[depKey];
+ if (!keys) {
+ // if there are no dependencies yet for a the given key
+ // create a new empty list of dependencies for the key
+ keys = depsMeta[depKey] = {};
+ } else if (!depsMeta.hasOwnProperty(depKey)) {
+ // otherwise if the dependency list is inherited from
+ // a superclass, clone the hash
+ keys = depsMeta[depKey] = o_create(keys);
}
+ return keys;
+}
- if ('string' === typeof method) { method = target[method]; }
- if (args && ignore > 0) {
- args = args.length > ignore ? slice.call(args, ignore) : null;
+/* return obj[META_KEY].deps */
+function metaForDeps(obj, meta) {
+ var deps = meta.deps;
+ // If the current object has no dependencies...
+ if (!deps) {
+ // initialize the dependencies with a pointer back to
+ // the current object
+ deps = meta.deps = {};
+ } else if (!meta.hasOwnProperty('deps')) {
+ // otherwise if the dependencies are inherited from the
+ // object's superclass, clone the deps
+ deps = meta.deps = o_create(deps);
}
+ return deps;
+}
- return Ember.handleErrors(function() {
- // IE8's Function.prototype.apply doesn't accept undefined/null arguments.
- return method.apply(target || this, args || []);
- }, this);
+function addDependentKeys(desc, obj, keyName, meta) {
+ // the descriptor has a list of dependent keys, so
+ // add all of its dependent keys.
+ var depKeys = desc._dependentKeys, depsMeta, idx, len, depKey, keys;
+ if (!depKeys) return;
+
+ depsMeta = metaForDeps(obj, meta);
+
+ for(idx = 0, len = depKeys.length; idx < len; idx++) {
+ depKey = depKeys[idx];
+ // Lookup keys meta for depKey
+ keys = keysForDep(obj, depsMeta, depKey);
+ // Increment the number of times depKey depends on keyName.
+ keys[keyName] = (keys[keyName] || 0) + 1;
+ // Watch the depKey
+ watch(obj, depKey);
+ }
}
+function removeDependentKeys(desc, obj, keyName, meta) {
+ // the descriptor has a list of dependent keys, so
+ // add all of its dependent keys.
+ var depKeys = desc._dependentKeys, depsMeta, idx, len, depKey, keys;
+ if (!depKeys) return;
+
+ depsMeta = metaForDeps(obj, meta);
+
+ for(idx = 0, len = depKeys.length; idx < len; idx++) {
+ depKey = depKeys[idx];
+ // Lookup keys meta for depKey
+ keys = keysForDep(obj, depsMeta, depKey);
+ // Increment the number of times depKey depends on keyName.
+ keys[keyName] = (keys[keyName] || 0) - 1;
+ // Watch the depKey
+ unwatch(obj, depKey);
+ }
+}
// ..........................................................
-// RUNLOOP
+// COMPUTED PROPERTY
//
-var timerMark; // used by timers...
-
/**
-Ember RunLoop (Private)
-
-@class RunLoop
-@namespace Ember
-@private
-@constructor
+ @class ComputedProperty
+ @namespace Ember
+ @extends Ember.Descriptor
+ @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;
- },
-
- // ..........................................................
- // 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 = {}; }
- queue = queues[queueName];
- if (!queue) { queue = queues[queueName] = []; }
+function ComputedProperty(func, opts) {
+ this.func = func;
+ this._cacheable = (opts && opts.cacheable !== undefined) ? opts.cacheable : true;
+ this._dependentKeys = opts && opts.dependentKeys;
+}
- var args = arguments.length > 3 ? slice.call(arguments, 3) : null;
- queue.push({ target: target, method: method, args: args });
- return this;
- },
+Ember.ComputedProperty = ComputedProperty;
+ComputedProperty.prototype = new Ember.Descriptor();
- /**
- @method flush
- @param {String} queueName
- */
- flush: function(queueName) {
- var queueNames, idx, len, queue, log;
+var ComputedPropertyPrototype = ComputedProperty.prototype;
- if (!this._queues) { return this; } // nothing to do
+/**
+ Call on a computed property to set it into cacheable mode. When in this
+ mode the computed property will automatically cache the return value of
+ your function until one of the dependent keys changes.
- function iter(item) {
- invoke(item.target, item.method, item.args);
- }
+ ```javascript
+ MyApp.president = Ember.Object.create({
+ fullName: function() {
+ return this.get('firstName') + ' ' + this.get('lastName');
+
+ // After calculating the value of this function, Ember will
+ // return that value without re-executing this function until
+ // one of the dependent properties change.
+ }.property('firstName', 'lastName')
+ });
+ ```
- Ember.watch.flushPending(); // make sure all chained watchers are setup
+ Properties are cacheable by default.
- if (queueName) {
- while (this._queues && (queue = this._queues[queueName])) {
- this._queues[queueName] = null;
+ @method cacheable
+ @param {Boolean} aFlag optional set to `false` to disable caching
+ @chainable
+*/
+ComputedPropertyPrototype.cacheable = function(aFlag) {
+ this._cacheable = aFlag !== false;
+ return this;
+};
- // the sync phase is to allow property changes to propagate. don't
- // invoke observers until that is finished.
- if (queueName === 'sync') {
- log = Ember.LOG_BINDINGS;
- if (log) { Ember.Logger.log('Begin: Flush Sync Queue'); }
+/**
+ Call on a computed property to set it into non-cached mode. When in this
+ mode the computed property will not automatically cache the return value.
- Ember.beginPropertyChanges();
- try {
- forEach.call(queue, iter);
- } finally {
- Ember.endPropertyChanges();
- }
+ ```javascript
+ MyApp.outsideService = Ember.Object.create({
+ value: function() {
+ return OutsideService.getValue();
+ }.property().volatile()
+ });
+ ```
- if (log) { Ember.Logger.log('End: Flush Sync Queue'); }
+ @method volatile
+ @chainable
+*/
+ComputedPropertyPrototype.volatile = function() {
+ return this.cacheable(false);
+};
- } else {
- forEach.call(queue, iter);
- }
- }
+/**
+ Sets the dependent keys on this computed property. Pass any number of
+ arguments containing key paths that this computed property depends on.
- } else {
- queueNames = Ember.run.queues;
- len = queueNames.length;
- idx = 0;
+ ```javascript
+ MyApp.president = Ember.Object.create({
+ fullName: Ember.computed(function() {
+ return this.get('firstName') + ' ' + this.get('lastName');
- outerloop:
- while (idx < len) {
- queueName = queueNames[idx];
- queue = this._queues && this._queues[queueName];
- delete this._queues[queueName];
+ // Tell Ember that this computed property depends on firstName
+ // and lastName
+ }).property('firstName', 'lastName')
+ });
+ ```
- if (queue) {
- // the sync phase is to allow property changes to propagate. don't
- // invoke observers until that is finished.
- if (queueName === 'sync') {
- log = Ember.LOG_BINDINGS;
- if (log) { Ember.Logger.log('Begin: Flush Sync Queue'); }
+ @method property
+ @param {String} path* zero or more property paths
+ @chainable
+*/
+ComputedPropertyPrototype.property = function() {
+ var args = [];
+ for (var i = 0, l = arguments.length; i < l; i++) {
+ args.push(arguments[i]);
+ }
+ this._dependentKeys = args;
+ return this;
+};
- Ember.beginPropertyChanges();
- try {
- forEach.call(queue, iter);
- } finally {
- Ember.endPropertyChanges();
- }
+/**
+ In some cases, you may want to annotate computed properties with additional
+ metadata about how they function or what values they operate on. For example,
+ computed property functions may close over variables that are then no longer
+ available for introspection.
- if (log) { Ember.Logger.log('End: Flush Sync Queue'); }
- } else {
- forEach.call(queue, iter);
- }
- }
+ You can pass a hash of these values to a computed property like this:
- // Loop through prior queues
- for (var i = 0; i <= idx; i++) {
- if (this._queues && this._queues[queueNames[i]]) {
- // Start over at the first queue with contents
- idx = i;
- continue outerloop;
- }
- }
+ ```
+ person: function() {
+ var personId = this.get('personId');
+ return App.Person.create({ id: personId });
+ }.property().meta({ type: App.Person })
+ ```
- idx++;
- }
- }
+ The hash that you pass to the `meta()` function will be saved on the
+ computed property descriptor under the `_meta` key. Ember runtime
+ exposes a public API for retrieving these values from classes,
+ via the `metaForProperty()` function.
- timerMark = null;
+ @method meta
+ @param {Hash} meta
+ @chainable
+*/
+ComputedPropertyPrototype.meta = function(meta) {
+ if (arguments.length === 0) {
+ return this._meta || {};
+ } else {
+ this._meta = meta;
return this;
}
-
};
-Ember.RunLoop = RunLoop;
-
-// ..........................................................
-// Ember.run - this is ideally the only public API the dev sees
-//
-
-/**
- Runs the passed target and method inside of a RunLoop, ensuring any
- deferred actions including bindings and views updates are flushed at the
- end.
+/* impl descriptor API */
+ComputedPropertyPrototype.willWatch = function(obj, keyName) {
+ // watch already creates meta for this instance
+ var meta = obj[META_KEY];
+ Ember.assert('watch should have setup meta to be writable', meta.source === obj);
+ if (!(keyName in meta.cache)) {
+ addDependentKeys(this, obj, keyName, meta);
+ }
+};
- Normally you should not need to invoke this method yourself. However if
- you are implementing raw event handlers when interfacing with other
- libraries or plugins, you should probably wrap all of your code inside this
- call.
+ComputedPropertyPrototype.didUnwatch = function(obj, keyName) {
+ var meta = obj[META_KEY];
+ Ember.assert('unwatch should have setup meta to be writable', meta.source === obj);
+ if (!(keyName in meta.cache)) {
+ // unwatch already creates meta for this instance
+ removeDependentKeys(this, obj, keyName, meta);
+ }
+};
- Ember.run(function(){
- // code to be execute within a RunLoop
- });
+/* 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
+ if (this._cacheable && this._suspended !== obj) {
+ var meta = metaFor(obj);
+ if (keyName in meta.cache) {
+ delete meta.cache[keyName];
+ if (!meta.watching[keyName]) {
+ removeDependentKeys(this, obj, keyName, meta);
+ }
+ }
+ }
+};
- @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.
- @return {Object} return value from invoking the passed function.
-*/
-Ember.run = function(target, method) {
- var ret, loop;
- run.begin();
- try {
- if (target || method) { ret = invoke(target, method, arguments, 2); }
- } finally {
- run.end();
+/* impl descriptor API */
+ComputedPropertyPrototype.get = function(obj, keyName) {
+ var ret, cache, meta;
+ if (this._cacheable) {
+ meta = metaFor(obj);
+ cache = meta.cache;
+ if (keyName in cache) { return cache[keyName]; }
+ ret = cache[keyName] = this.func.call(obj, keyName);
+ if (!meta.watching[keyName]) {
+ addDependentKeys(this, obj, keyName, meta);
+ }
+ } else {
+ ret = this.func.call(obj, keyName);
}
return ret;
};
-var run = Ember.run;
+/* impl descriptor API */
+ComputedPropertyPrototype.set = function(obj, keyName, value) {
+ var cacheable = this._cacheable,
+ func = this.func,
+ meta = metaFor(obj, cacheable),
+ watched = meta.watching[keyName],
+ oldSuspended = this._suspended,
+ hadCachedValue = false,
+ cache = meta.cache,
+ cachedValue, ret;
+ this._suspended = obj;
-/**
- Begins a new RunLoop. Any deferred actions invoked after the begin will
- be buffered until you invoke a matching call to Ember.run.end(). This is
- an lower-level way to use a RunLoop instead of using Ember.run().
+ try {
+ if (cacheable && cache.hasOwnProperty(keyName)) {
+ cachedValue = cache[keyName];
+ hadCachedValue = true;
+ }
- Ember.run.begin();
- // code to be execute within a RunLoop
- Ember.run.end();
+ // Check if the CP has been wrapped
+ if (func.wrappedFunction) { func = func.wrappedFunction; }
- @method begin
- @return {void}
-*/
-Ember.run.begin = function() {
- run.currentRunLoop = new RunLoop(run.currentRunLoop);
-};
+ // For backwards-compatibility with computed properties
+ // that check for arguments.length === 2 to determine if
+ // they are being get or set, only pass the old cached
+ // value if the computed property opts into a third
+ // argument.
+ if (func.length === 3) {
+ ret = func.call(obj, keyName, value, cachedValue);
+ } else if (func.length === 2) {
+ ret = func.call(obj, keyName, value);
+ } else {
+ Ember.defineProperty(obj, keyName, null, cachedValue);
+ Ember.set(obj, keyName, value);
+ return;
+ }
-/**
- Ends a RunLoop. This must be called sometime after you call Ember.run.begin()
- to flush any deferred actions. This is a lower-level way to use a RunLoop
- instead of using Ember.run().
+ if (hadCachedValue && cachedValue === ret) { return; }
+
+ if (watched) { Ember.propertyWillChange(obj, keyName); }
- Ember.run.begin();
- // code to be execute within a RunLoop
- Ember.run.end();
+ if (hadCachedValue) {
+ delete cache[keyName];
+ }
- @method end
- @return {void}
-*/
-Ember.run.end = function() {
- Ember.assert('must have a current run loop', run.currentRunLoop);
- try {
- run.currentRunLoop.end();
+ if (cacheable) {
+ if (!watched && !hadCachedValue) {
+ addDependentKeys(this, obj, keyName, meta);
+ }
+ cache[keyName] = ret;
+ }
+
+ if (watched) { Ember.propertyDidChange(obj, keyName); }
+ } finally {
+ this._suspended = oldSuspended;
}
- finally {
- run.currentRunLoop = run.currentRunLoop.prev();
+ return ret;
+};
+
+/* called when property is defined */
+ComputedPropertyPrototype.setup = function(obj, keyName) {
+ var meta = obj[META_KEY];
+ if (meta && meta.watching[keyName]) {
+ addDependentKeys(this, obj, keyName, metaFor(obj));
}
};
-/**
- Array of named queues. This array determines the order in which queues
- are flushed at the end of the RunLoop. You can define your own queues by
- simply adding the queue name to this array. Normally you should not need
- to inspect or modify this property.
+/* called before property is overridden */
+ComputedPropertyPrototype.teardown = function(obj, keyName) {
+ var meta = metaFor(obj);
- @property queues
- @type Array
- @default ['sync', 'actions', 'destroy', 'timers']
-*/
-Ember.run.queues = ['sync', 'actions', 'destroy', 'timers'];
+ if (meta.watching[keyName] || keyName in meta.cache) {
+ removeDependentKeys(this, obj, keyName, meta);
+ }
-/**
- Adds the passed target/method and any optional arguments to the named
- queue to be executed at the end of the RunLoop. If you have not already
- started a RunLoop when calling this method one will be started for you
- automatically.
+ if (this._cacheable) { delete meta.cache[keyName]; }
- At the end of a RunLoop, any methods scheduled in this way will be invoked.
- Methods will be invoked in an order matching the named queues defined in
- the run.queues property.
+ return null; // no value to restore
+};
- Ember.run.schedule('timers', this, function(){
- // this will be executed at the end of the RunLoop, when timers are run
- console.log("scheduled on timers queue");
- });
- Ember.run.schedule('sync', this, function(){
- // this will be executed at the end of the RunLoop, when bindings are synced
- console.log("scheduled on sync queue");
- });
- // Note the functions will be run in order based on the run queues order. Output would be:
- // scheduled on sync queue
- // scheduled on timers queue
- @method schedule
- @param {String} queue The name of the queue to schedule against.
- Default queues are 'sync' and 'actions'
+/**
+ This helper returns a new property descriptor that wraps the passed
+ computed property function. You can use this helper to define properties
+ with mixins or via `Ember.defineProperty()`.
- @param {Object} [target] target object to use as the context when invoking a method.
+ The function you pass will be used to both get and set property values.
+ The function should accept two parameters, key and value. If value is not
+ undefined you should set the value first. In either case return the
+ current value of the property.
- @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.
+ @method computed
+ @for Ember
+ @param {Function} func The computed property function.
+ @return {Ember.ComputedProperty} property descriptor instance
+*/
+Ember.computed = function(func) {
+ var args;
- @param {Object} [arguments*] Optional arguments to be passed to the queued method.
+ if (arguments.length > 1) {
+ args = a_slice.call(arguments, 0, -1);
+ func = a_slice.call(arguments, -1)[0];
+ }
- @return {void}
-*/
-Ember.run.schedule = function(queue, target, method) {
- var loop = run.autorun();
- loop.schedule.apply(loop, arguments);
-};
+ var cp = new ComputedProperty(func);
-var scheduledAutorun;
-function autorun() {
- scheduledAutorun = null;
- if (run.currentRunLoop) { run.end(); }
-}
+ if (args) {
+ cp.property.apply(cp, args);
+ }
-// Used by global test teardown
-Ember.run.hasScheduledTimers = function() {
- return !!(scheduledAutorun || scheduledLater || scheduledNext);
+ return cp;
};
-// Used by global test teardown
-Ember.run.cancelTimers = function () {
- if (scheduledAutorun) {
- clearTimeout(scheduledAutorun);
- scheduledAutorun = null;
- }
- if (scheduledLater) {
- clearTimeout(scheduledLater);
- scheduledLater = null;
- }
- if (scheduledNext) {
- clearTimeout(scheduledNext);
- scheduledNext = null;
+/**
+ Returns the cached value for a property, if one exists.
+ This can be useful for peeking at the value of a computed
+ 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;
+
+ if (cache && key in cache) {
+ return cache[key];
}
- timers = {};
};
/**
- Begins a new RunLoop if necessary and schedules a timer to flush the
- RunLoop at a later time. This method is used by parts of Ember to
- ensure the RunLoop always finishes. You normally do not need to call this
- method directly. Instead use Ember.run().
-
+ @method computed.not
+ @for Ember
+ @param {String} dependentKey
+*/
+Ember.computed.not = function(dependentKey) {
+ return Ember.computed(dependentKey, function(key) {
+ return !get(this, dependentKey);
+ });
+};
- @method autorun
- @example
- Ember.run.autorun();
- @return {Ember.RunLoop} the new current RunLoop
+/**
+ @method computed.empty
+ @for Ember
+ @param {String} dependentKey
*/
-Ember.run.autorun = function() {
- if (!run.currentRunLoop) {
- Ember.assert("You have turned on testing mode, which disabled the run-loop's autorun. You will need to wrap any code with asynchronous side-effects in an Ember.run", !Ember.testing);
+Ember.computed.empty = function(dependentKey) {
+ return Ember.computed(dependentKey, function(key) {
+ var val = get(this, dependentKey);
+ return val === undefined || val === null || val === '' || (Ember.isArray(val) && get(val, 'length') === 0);
+ });
+};
- run.begin();
+/**
+ @method computed.bool
+ @for Ember
+ @param {String} dependentKey
+*/
+Ember.computed.bool = function(dependentKey) {
+ return Ember.computed(dependentKey, function(key) {
+ return !!get(this, dependentKey);
+ });
+};
- if (!scheduledAutorun) {
- scheduledAutorun = setTimeout(autorun, 1);
+/**
+ @method computed.alias
+ @for Ember
+ @param {String} dependentKey
+*/
+Ember.computed.alias = function(dependentKey) {
+ return Ember.computed(dependentKey, function(key, value){
+ if (arguments.length === 1) {
+ return get(this, dependentKey);
+ } else {
+ set(this, dependentKey, value);
+ return value;
}
- }
-
- return run.currentRunLoop;
+ });
};
-/**
- Immediately flushes any events scheduled in the 'sync' queue. Bindings
- use this queue so this method is a useful way to immediately force all
- bindings in the application to sync.
+})();
- You should call this method anytime you need any changed state to propagate
- throughout the app immediately without repainting the UI.
- Ember.run.sync();
- @method sync
- @return {void}
+(function() {
+/**
+@module ember-metal
*/
-Ember.run.sync = function() {
- run.autorun();
- run.currentRunLoop.flush('sync');
-};
-// ..........................................................
-// TIMERS
-//
+var o_create = Ember.create,
+ metaFor = Ember.meta,
+ metaPath = Ember.metaPath,
+ META_KEY = Ember.META_KEY;
-var timers = {}; // active timers...
+/*
+ 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.
-var scheduledLater;
-function invokeLaterTimers() {
- scheduledLater = null;
- var now = (+ new Date()), earliest = -1;
- for (var key in timers) {
- if (!timers.hasOwnProperty(key)) { continue; }
- var timer = timers[key];
- if (timer && timer.expires) {
- if (now >= timer.expires) {
- delete timers[key];
- invoke(timer.target, timer.method, timer.args, 2);
- } else {
- if (earliest<0 || (timer.expires < earliest)) earliest=timer.expires;
+ The hashes are stored in the object's meta hash, and look like this:
+
+ // Object's meta hash
+ {
+ listeners: { // variable name: `listenerSet`
+ "foo:changed": [ // variable name: `actions`
+ [target, method, onceFlag, suspendedFlag]
+ ]
+ }
}
- }
- }
- // schedule next timeout to fire...
- if (earliest > 0) { scheduledLater = setTimeout(invokeLaterTimers, earliest-(+ new Date())); }
+*/
+
+function indexOf(array, target, method) {
+ var index = -1;
+ for (var i = 0, l = array.length; i < l; i++) {
+ if (target === array[i][0] && method === array[i][1]) { index = i; break; }
+ }
+ return index;
}
-/**
- Invokes the passed target/method and optional arguments after a specified
- period if time. The last parameter of this method must always be a number
- of milliseconds.
+function actionsFor(obj, eventName) {
+ var meta = metaFor(obj, true),
+ actions;
- You should use this method whenever you need to run some action after a
- period of time instead of using setTimeout(). This method will ensure that
- items that expire during the same script execution cycle all execute
- together, which is often more efficient than using a real setTimeout.
+ if (!meta.listeners) { meta.listeners = {}; }
- Ember.run.later(myContext, function(){
- // code here will execute within a RunLoop in about 500ms with this == myContext
- }, 500);
+ if (!meta.hasOwnProperty('listeners')) {
+ // setup inherited copy of the listeners object
+ meta.listeners = o_create(meta.listeners);
+ }
- @method later
- @param {Object} [target] target of method to invoke
+ actions = meta.listeners[eventName];
- @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.
+ // if there are actions, but the eventName doesn't exist in our listeners, then copy them from the prototype
+ if (actions && !meta.listeners.hasOwnProperty(eventName)) {
+ actions = meta.listeners[eventName] = meta.listeners[eventName].slice();
+ } else if (!actions) {
+ actions = meta.listeners[eventName] = [];
+ }
- @param {Object} [args*] Optional arguments to pass to the timeout.
+ return actions;
+}
- @param {Number} wait
- Number of milliseconds to wait.
+function actionsUnion(obj, eventName, otherActions) {
+ var meta = obj[META_KEY],
+ actions = meta && meta.listeners && meta.listeners[eventName];
- @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;
+ if (!actions) { return; }
+ for (var i = actions.length - 1; i >= 0; i--) {
+ var target = actions[i][0],
+ method = actions[i][1],
+ once = actions[i][2],
+ suspended = actions[i][3],
+ actionIndex = indexOf(otherActions, target, method);
- // setTimeout compatibility...
- if (arguments.length===2 && 'function' === typeof target) {
- wait = method;
- method = target;
- target = undefined;
- args = [target, method];
- } else {
- args = slice.call(arguments);
- wait = args.pop();
+ if (actionIndex === -1) {
+ otherActions.push([target, method, once, suspended]);
+ }
}
-
- expires = (+ new Date()) + wait;
- timer = { target: target, method: method, expires: expires, args: args };
- guid = Ember.guidFor(timer);
- timers[guid] = timer;
- run.once(timers, invokeLaterTimers);
- return guid;
-};
-
-function invokeOnceTimer(guid, onceTimers) {
- if (onceTimers[this.tguid]) { delete onceTimers[this.tguid][this.mguid]; }
- if (timers[guid]) { invoke(this.target, this.method, this.args); }
- delete timers[guid];
}
-function scheduleOnce(queue, target, method, args) {
- var tguid = Ember.guidFor(target),
- mguid = Ember.guidFor(method),
- onceTimers = run.autorun().onceTimers,
- guid = onceTimers[tguid] && onceTimers[tguid][mguid],
- timer;
+function actionsDiff(obj, eventName, otherActions) {
+ var meta = obj[META_KEY],
+ actions = meta && meta.listeners && meta.listeners[eventName],
+ diffActions = [];
- if (guid && timers[guid]) {
- timers[guid].args = args; // replace args
- } else {
- timer = {
- target: target,
- method: method,
- args: args,
- tguid: tguid,
- mguid: mguid
- };
+ if (!actions) { return; }
+ for (var i = actions.length - 1; i >= 0; i--) {
+ var target = actions[i][0],
+ method = actions[i][1],
+ once = actions[i][2],
+ suspended = actions[i][3],
+ actionIndex = indexOf(otherActions, target, method);
- guid = Ember.guidFor(timer);
- timers[guid] = timer;
- if (!onceTimers[tguid]) { onceTimers[tguid] = {}; }
- onceTimers[tguid][mguid] = guid; // so it isn't scheduled more than once
+ if (actionIndex !== -1) { continue; }
- run.schedule(queue, timer, invokeOnceTimer, guid, onceTimers);
+ otherActions.push([target, method, once, suspended]);
+ diffActions.push([target, method, once, suspended]);
}
- return guid;
+ return diffActions;
}
/**
- Schedules an item to run one time during the current RunLoop. Calling
- this method with the same target/method combination will have no effect.
+ Add an event listener
- Note that although you can pass optional arguments these will not be
- considered when looking for duplicates. New arguments will replace previous
- calls.
+ @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, once) {
+ Ember.assert("You must pass at least an object and event name to Ember.addListener", !!obj && !!eventName);
- Ember.run(function(){
- var doFoo = function() { foo(); }
- Ember.run.once(myContext, doFoo);
- Ember.run.once(myContext, doFoo);
- // doFoo will only be executed once at the end of the RunLoop
- });
+ if (!method && 'function' === typeof target) {
+ method = target;
+ target = null;
+ }
- @method once
- @param {Object} [target] target of method to invoke
+ var actions = actionsFor(obj, eventName),
+ actionIndex = indexOf(actions, target, method);
- @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.
+ if (actionIndex !== -1) { return; }
- @param {Object} [args*] Optional arguments to pass to the timeout.
+ actions.push([target, method, once, undefined]);
+ if ('function' === typeof obj.didAddListener) {
+ obj.didAddListener(eventName, target, method);
+ }
+}
- @return {Object} timer
+/**
+ 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`
*/
-Ember.run.once = function(target, method) {
- return scheduleOnce('actions', target, method, slice.call(arguments, 2));
-};
+function removeListener(obj, eventName, target, method) {
+ Ember.assert("You must pass at least an object and event name to Ember.removeListener", !!obj && !!eventName);
-Ember.run.scheduleOnce = function(queue, target, method, args) {
- return scheduleOnce(queue, target, method, slice.call(arguments, 3));
-};
+ if (!method && 'function' === typeof target) {
+ method = target;
+ target = null;
+ }
-var scheduledNext;
-function invokeNextTimers() {
- scheduledNext = null;
- for(var key in timers) {
- if (!timers.hasOwnProperty(key)) { continue; }
- var timer = timers[key];
- if (timer.next) {
- delete timers[key];
- invoke(timer.target, timer.method, timer.args, 2);
+ function _removeListener(target, method, once) {
+ var actions = actionsFor(obj, eventName),
+ actionIndex = indexOf(actions, target, method);
+
+ // action doesn't exist, give up silently
+ if (actionIndex === -1) { return; }
+
+ actions.splice(actionIndex, 1);
+
+ if ('function' === typeof obj.didRemoveListener) {
+ obj.didRemoveListener(eventName, target, method);
+ }
+ }
+
+ if (method) {
+ _removeListener(target, method);
+ } else {
+ var meta = obj[META_KEY],
+ actions = meta && meta.listeners && meta.listeners[eventName];
+
+ if (!actions) { return; }
+ for (var i = actions.length - 1; i >= 0; i--) {
+ _removeListener(actions[i][0], actions[i][1]);
}
}
}
/**
- Schedules an item to run after control has been returned to the system.
- This is often equivalent to calling setTimeout(function...,1).
+ @private
- Ember.run.next(myContext, function(){
- // code to be executed in the next RunLoop, which will be scheduled after the current one
- });
+ Suspend listener during callback.
- @method next
- @param {Object} [target] target of method to invoke
+ 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.
- @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.
+ @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;
+ target = null;
+ }
- @param {Object} [args*] Optional arguments to pass to the timeout.
+ var actions = actionsFor(obj, eventName),
+ actionIndex = indexOf(actions, target, method),
+ action;
- @return {Object} timer
-*/
-Ember.run.next = function(target, method) {
- var guid,
- timer = {
- target: target,
- method: method,
- args: slice.call(arguments),
- next: true
- };
+ if (actionIndex !== -1) {
+ action = actions[actionIndex].slice(); // copy it, otherwise we're modifying a shared object
+ action[3] = true; // mark the action as suspended
+ actions[actionIndex] = action; // replace the shared object with our copy
+ }
- guid = Ember.guidFor(timer);
- timers[guid] = timer;
+ function tryable() { return callback.call(target); }
+ function finalizer() { if (action) { action[3] = undefined; } }
- if (!scheduledNext) { scheduledNext = setTimeout(invokeNextTimers, 1); }
- return guid;
-};
+ return Ember.tryFinally(tryable, finalizer);
+}
/**
- Cancels a scheduled item. Must be a value returned by `Ember.run.later()`,
- `Ember.run.once()`, or `Ember.run.next()`.
-
- var runNext = Ember.run.next(myContext, function(){
- // will not be executed
- });
- Ember.run.cancel(runNext);
+ @private
- var runLater = Ember.run.later(myContext, function(){
- // will not be executed
- }, 500);
- Ember.run.cancel(runLater);
+ Suspend listener during callback.
- var runOnce = Ember.run.once(myContext, function(){
- // will not be executed
- });
- Ember.run.cancel(runOnce);
+ 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 cancel
- @param {Object} timer Timer object to cancel
- @return {void}
+ @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
*/
-Ember.run.cancel = function(timer) {
- delete timers[timer];
-};
+function suspendListeners(obj, eventNames, target, method, callback) {
+ if (!method && 'function' === typeof target) {
+ method = target;
+ target = null;
+ }
-})();
+ var suspendedActions = [],
+ eventName, actions, action, i, l;
+ for (i=0, l=eventNames.length; i<l; i++) {
+ eventName = eventNames[i];
+ actions = actionsFor(obj, eventName);
+ var actionIndex = indexOf(actions, target, method);
+ if (actionIndex !== -1) {
+ action = actions[actionIndex].slice();
+ action[3] = true;
+ actions[actionIndex] = action;
+ suspendedActions.push(action);
+ }
+ }
+
+ function tryable() { return callback.call(target); }
+
+ function finalizer() {
+ for (i = 0, l = suspendedActions.length; i < l; i++) {
+ suspendedActions[i][3] = undefined;
+ }
+ }
+
+ return Ember.tryFinally(tryable, finalizer);
+}
-(function() {
-// Ember.Logger
-// get, set, trySet
-// guidFor, isArray, meta
-// addObserver, removeObserver
-// Ember.run.schedule
/**
-@module ember-metal
+ @private
+
+ Return a list of currently watched events
+
+ @method watchedEvents
+ @for Ember
+ @param obj
*/
+function watchedEvents(obj) {
+ var listeners = obj[META_KEY].listeners, ret = [];
-// ..........................................................
-// CONSTANTS
-//
+ if (listeners) {
+ for(var eventName in listeners) {
+ if (listeners[eventName]) { ret.push(eventName); }
+ }
+ }
+ return ret;
+}
/**
- 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
+ @method sendEvent
@for Ember
- @type Boolean
- @default false
+ @param obj
+ @param {String} eventName
+ @param {Array} params
+ @return true
*/
-Ember.LOG_BINDINGS = false || !!Ember.ENV.LOG_BINDINGS;
+function sendEvent(obj, eventName, params, actions) {
+ // first give object a chance to handle it
+ if (obj !== Ember && 'function' === typeof obj.sendEvent) {
+ obj.sendEvent(eventName, params);
+ }
-var get = Ember.get,
- set = Ember.set,
- guidFor = Ember.guidFor,
- isGlobalPath = Ember.isGlobalPath;
+ if (!actions) {
+ var meta = obj[META_KEY];
+ actions = meta && meta.listeners && meta.listeners[eventName];
+ }
+ if (!actions) { return; }
-function getWithGlobals(obj, path) {
- return get(isGlobalPath(path) ? window : obj, path);
-}
+ for (var i = actions.length - 1; i >= 0; i--) { // looping in reverse for once listeners
+ if (!actions[i] || actions[i][3] === true) { continue; }
-// ..........................................................
-// BINDING
-//
+ var target = actions[i][0],
+ method = actions[i][1],
+ once = actions[i][2];
-var Binding = function(toPath, fromPath) {
- this._direction = 'fwd';
- this._from = fromPath;
- this._to = toPath;
- this._directionMap = Ember.Map.create();
-};
+ if (once) { removeListener(obj, eventName, target, method); }
+ if (!target) { target = obj; }
+ if ('string' === typeof method) { method = target[method]; }
+ if (params) {
+ method.apply(target, params);
+ } else {
+ method.apply(target);
+ }
+ }
+ return true;
+}
/**
-@class Binding
-@namespace Ember
+ @private
+ @method hasListeners
+ @for Ember
+ @param obj
+ @param {String} eventName
*/
+function hasListeners(obj, eventName) {
+ var meta = obj[META_KEY],
+ actions = meta && meta.listeners && meta.listeners[eventName];
-Binding.prototype = {
- /**
- This copies the Binding so it can be connected to another object.
-
- @method copy
- @return {Ember.Binding}
- */
- copy: function () {
- var copy = new Binding(this._to, this._from);
- if (this._oneWay) { copy._oneWay = true; }
- return copy;
- },
-
- // ..........................................................
- // CONFIG
- //
+ return !!(actions && actions.length);
+}
- /**
- This will set "from" property path to the specified value. It will not
- attempt to resolve this property path to an actual object until you
- connect the binding.
+/**
+ @private
+ @method listenersFor
+ @for Ember
+ @param obj
+ @param {String} eventName
+*/
+function listenersFor(obj, eventName) {
+ var ret = [];
+ var meta = obj[META_KEY],
+ actions = meta && meta.listeners && meta.listeners[eventName];
- The binding will search for the property path starting at the root object
- you pass when you connect() the binding. It follows the same rules as
- `get()` - see that method for more information.
+ if (!actions) { return ret; }
- @method from
- @param {String} propertyPath the property path to connect to
- @return {Ember.Binding} receiver
- */
- from: function(path) {
- this._from = path;
- return this;
- },
+ for (var i = 0, l = actions.length; i < l; i++) {
+ var target = actions[i][0],
+ method = actions[i][1];
+ ret.push([target, method]);
+ }
- /**
- This will set the "to" property path to the specified value. It will not
- attempt to resolve this property path to an actual object until you
- connect the binding.
+ return ret;
+}
- The binding will search for the property path starting at the root object
- you pass when you connect() the binding. It follows the same rules as
- `get()` - see that method for more information.
+Ember.addListener = addListener;
+Ember.removeListener = removeListener;
+Ember._suspendListener = suspendListener;
+Ember._suspendListeners = suspendListeners;
+Ember.sendEvent = sendEvent;
+Ember.hasListeners = hasListeners;
+Ember.watchedEvents = watchedEvents;
+Ember.listenersFor = listenersFor;
+Ember.listenersDiff = actionsDiff;
+Ember.listenersUnion = actionsUnion;
- @method to
- @param {String|Tuple} propertyPath A property path or tuple
- @return {Ember.Binding} this
- */
- to: function(path) {
- this._to = path;
- return this;
- },
+})();
- /**
- Configures the binding as one way. A one-way binding will relay changes
- on the "from" side to 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.
- @method oneWay
- @return {Ember.Binding} receiver
- */
- oneWay: function() {
- this._oneWay = true;
- return this;
- },
- toString: function() {
- var oneWay = this._oneWay ? '[oneWay]' : '';
- return "Ember.Binding<" + guidFor(this) + ">(" + this._from + " -> " + this._to + ")" + oneWay;
- },
+(function() {
+// Ember.Logger
+// Ember.watch.flushPending
+// Ember.beginPropertyChanges, Ember.endPropertyChanges
+// Ember.guidFor, Ember.tryFinally
- // ..........................................................
- // CONNECT AND SYNC
- //
+/**
+@module ember-metal
+*/
- /**
- Attempts to connect this binding instance so that it can receive and relay
- changes. This method will raise an exception if you have not set the
- from/to properties yet.
+// ..........................................................
+// HELPERS
+//
- @method connect
- @param {Object} obj The root object for this binding.
- @return {Ember.Binding} this
- */
- connect: function(obj) {
- Ember.assert('Must pass a valid object to Ember.Binding.connect()', !!obj);
+var slice = [].slice,
+ forEach = Ember.ArrayPolyfills.forEach;
- var fromPath = this._from, toPath = this._to;
- Ember.trySet(obj, toPath, getWithGlobals(obj, fromPath));
+// invokes passed params - normalizing so you can pass target/func,
+// target/string or just func
+function invoke(target, method, args, ignore) {
- // add an observer on the object to be notified when the binding should be updated
- Ember.addObserver(obj, fromPath, this, this.fromDidChange);
+ if (method === undefined) {
+ method = target;
+ target = undefined;
+ }
- // if the binding is a two-way binding, also set up an observer on the target
- if (!this._oneWay) { Ember.addObserver(obj, toPath, this, this.toDidChange); }
+ if ('string' === typeof method) { method = target[method]; }
+ if (args && ignore > 0) {
+ args = args.length > ignore ? slice.call(args, ignore) : null;
+ }
- this._readyToSync = true;
+ return Ember.handleErrors(function() {
+ // IE8's Function.prototype.apply doesn't accept undefined/null arguments.
+ return method.apply(target || this, args || []);
+ }, this);
+}
- return this;
- },
- /**
- Disconnects the binding instance. Changes will no longer be relayed. You
- will not usually need to call this method.
+// ..........................................................
+// RUNLOOP
+//
- @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);
+var timerMark; // used by timers...
- var twoWay = !this._oneWay;
+/**
+Ember RunLoop (Private)
- // remove an observer on the object so we're no longer notified of
- // changes that should update bindings.
- Ember.removeObserver(obj, this._from, this, this.fromDidChange);
+@class RunLoop
+@namespace Ember
+@private
+@constructor
+*/
+var RunLoop = function(prev) {
+ this._prev = prev || null;
+ this.onceTimers = {};
+};
- // if the binding is two-way, remove the observer from the target as well
- if (twoWay) { Ember.removeObserver(obj, this._to, this, this.toDidChange); }
+RunLoop.prototype = {
+ /**
+ @method end
+ */
+ end: function() {
+ this.flush();
+ },
- this._readyToSync = false; // disable scheduled syncs...
- return this;
+ /**
+ @method prev
+ */
+ prev: function() {
+ return this._prev;
},
// ..........................................................
- // PRIVATE
+ // Delayed Actions
//
- /* called when the from side changes */
- fromDidChange: function(target) {
- this._scheduleSync(target, 'fwd');
- },
+ /**
+ @method schedule
+ @param {String} queueName
+ @param target
+ @param method
+ */
+ schedule: function(queueName, target, method) {
+ var queues = this._queues, queue;
+ if (!queues) { queues = this._queues = {}; }
+ queue = queues[queueName];
+ if (!queue) { queue = queues[queueName] = []; }
- /* called when the to side changes */
- toDidChange: function(target) {
- this._scheduleSync(target, 'back');
+ var args = arguments.length > 3 ? slice.call(arguments, 3) : null;
+ queue.push({ target: target, method: method, args: args });
+ return this;
},
- _scheduleSync: function(obj, dir) {
- var directionMap = this._directionMap;
- var existingDir = directionMap.get(obj);
+ /**
+ @method flush
+ @param {String} queueName
+ */
+ flush: function(queueName) {
+ var queueNames, idx, len, queue, log;
- // if we haven't scheduled the binding yet, schedule it
- if (!existingDir) {
- Ember.run.schedule('sync', this, this._sync, obj);
- directionMap.set(obj, dir);
+ if (!this._queues) { return this; } // nothing to do
+
+ function iter(item) {
+ invoke(item.target, item.method, item.args);
}
- // If both a 'back' and 'fwd' sync have been scheduled on the same object,
- // default to a 'fwd' sync so that it remains deterministic.
- if (existingDir === 'back' && dir === 'fwd') {
- directionMap.set(obj, 'fwd');
+ function tryable() {
+ forEach.call(queue, iter);
}
- },
- _sync: function(obj) {
- var log = Ember.LOG_BINDINGS;
+ Ember.watch.flushPending(); // make sure all chained watchers are setup
- // don't synchronize destroyed objects or disconnected bindings
- if (obj.isDestroyed || !this._readyToSync) { return; }
+ if (queueName) {
+ while (this._queues && (queue = this._queues[queueName])) {
+ this._queues[queueName] = null;
- // get the direction of the binding for the object we are
- // synchronizing from
- var directionMap = this._directionMap;
- var direction = directionMap.get(obj);
+ // the sync phase is to allow property changes to propagate. don't
+ // invoke observers until that is finished.
+ if (queueName === 'sync') {
+ log = Ember.LOG_BINDINGS;
+ if (log) { Ember.Logger.log('Begin: Flush Sync Queue'); }
- var fromPath = this._from, toPath = this._to;
+ Ember.beginPropertyChanges();
- directionMap.remove(obj);
+ Ember.tryFinally(tryable, Ember.endPropertyChanges);
- // if we're synchronizing from the remote object...
- if (direction === 'fwd') {
- var fromValue = getWithGlobals(obj, this._from);
- if (log) {
- Ember.Logger.log(' ', this.toString(), '->', fromValue, obj);
- }
- if (this._oneWay) {
- Ember.trySet(obj, toPath, fromValue);
- } else {
- Ember._suspendObserver(obj, toPath, this, this.toDidChange, function () {
- Ember.trySet(obj, toPath, fromValue);
- });
+ if (log) { Ember.Logger.log('End: Flush Sync Queue'); }
+
+ } else {
+ forEach.call(queue, iter);
+ }
}
- // if we're synchronizing *to* the remote object
- } else if (direction === 'back') {
- var toValue = get(obj, this._to);
- if (log) {
- Ember.Logger.log(' ', this.toString(), '<-', toValue, obj);
- }
- Ember._suspendObserver(obj, fromPath, this, this.fromDidChange, function () {
- Ember.trySet(Ember.isGlobalPath(fromPath) ? window : obj, fromPath, toValue);
- });
- }
- }
-};
+ } else {
+ queueNames = Ember.run.queues;
+ len = queueNames.length;
+ idx = 0;
-function mixinProperties(to, from) {
- for (var key in from) {
- if (from.hasOwnProperty(key)) {
- to[key] = from[key];
- }
- }
-}
+ outerloop:
+ while (idx < len) {
+ queueName = queueNames[idx];
+ queue = this._queues && this._queues[queueName];
+ delete this._queues[queueName];
-mixinProperties(Binding, {
+ if (queue) {
+ // the sync phase is to allow property changes to propagate. don't
+ // invoke observers until that is finished.
+ if (queueName === 'sync') {
+ log = Ember.LOG_BINDINGS;
+ if (log) { Ember.Logger.log('Begin: Flush Sync Queue'); }
- /**
- See {{#crossLink "Ember.Binding/from"}}{{/crossLink}}
+ Ember.beginPropertyChanges();
- @method from
- @static
- */
- from: function() {
- var C = this, binding = new C();
- return binding.from.apply(binding, arguments);
- },
+ Ember.tryFinally(tryable, Ember.endPropertyChanges);
- /**
- See {{#crossLink "Ember.Binding/to"}}{{/crossLink}}
+ if (log) { Ember.Logger.log('End: Flush Sync Queue'); }
+ } else {
+ forEach.call(queue, iter);
+ }
+ }
- @method to
- @static
- */
- to: function() {
- var C = this, binding = new C();
- return binding.to.apply(binding, arguments);
- },
+ // Loop through prior queues
+ for (var i = 0; i <= idx; i++) {
+ if (this._queues && this._queues[queueNames[i]]) {
+ // Start over at the first queue with contents
+ idx = i;
+ continue outerloop;
+ }
+ }
- /**
- 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 (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.
+ idx++;
+ }
+ }
- See {{#crossLink "Binding/oneWay"}}{{/crossLink}}
+ timerMark = null;
- @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.
- */
- oneWay: function(from, flag) {
- var C = this, binding = new C(null, from);
- return binding.oneWay(flag);
+ return this;
}
-});
+};
-/**
- 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.
+Ember.RunLoop = RunLoop;
- ## Automatic Creation of Bindings with `/^*Binding/`-named Properties
- You do not usually create Binding objects directly but instead describe
- bindings in your class or object definition using automatic binding detection.
+// ..........................................................
+// Ember.run - this is ideally the only public API the dev sees
+//
- Properties ending in a `Binding` suffix will be converted to Ember.Binding instances.
- The value of this property should be a string representing a path to another object or
- a custom binding instanced created using Binding helpers (see "Customizing Your Bindings"):
+/**
+ Runs the passed target and method inside of a RunLoop, ensuring any
+ deferred actions including bindings and views updates are flushed at the
+ end.
- valueBinding: "MyApp.someController.title"
+ Normally you should not need to invoke this method yourself. However if
+ you are implementing raw event handlers when interfacing with other
+ libraries or plugins, you should probably wrap all of your code inside this
+ call.
- This will create a binding from `MyApp.someController.title` to the `value`
- property of your object instance automatically. Now the two values will be
- kept in sync.
+ ```javascript
+ Ember.run(function(){
+ // code to be execute within a RunLoop
+ });
+ ```
- ## One Way Bindings
+ @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.
+ @return {Object} return value from invoking the passed function.
+*/
+Ember.run = function(target, method) {
+ var loop,
+ args = arguments;
+ run.begin();
- One especially useful binding customization you can use is the `oneWay()`
- helper. This helper tells Ember that you are only interested in
- receiving changes on the object you are binding from. For example, if you
- are binding to a preference and you want to be notified if the preference
- has changed, but your object will not be changing the preference itself, you
- could do:
+ function tryable() {
+ if (target || method) {
+ return invoke(target, method, args, 2);
+ }
+ }
- bigTitlesBinding: Ember.Binding.oneWay("MyApp.preferencesController.bigTitles")
+ return Ember.tryFinally(tryable, run.end);
+};
- This way if the value of MyApp.preferencesController.bigTitles changes the
- "bigTitles" property of your object will change also. However, if you
- change the value of your "bigTitles" property, it will not update the
- preferencesController.
+var run = Ember.run;
- One way bindings are almost twice as fast to setup and twice as fast to
- execute because the binding only has to worry about changes to one side.
- You should consider using one way bindings anytime you have an object that
- may be created frequently and you do not intend to change a property; only
- to monitor it for changes. (such as in the example above).
+/**
+ Begins a new RunLoop. Any deferred actions invoked after the begin will
+ be buffered until you invoke a matching call to `Ember.run.end()`. This is
+ an lower-level way to use a RunLoop instead of using `Ember.run()`.
- ## Adding Bindings Manually
+ ```javascript
+ Ember.run.begin();
+ // code to be execute within a RunLoop
+ Ember.run.end();
+ ```
- All of the examples above show you how to configure a custom binding, but
- the result of these customizations will be a binding template, not a fully
- active Binding instance. The binding will actually become active only when you
- instantiate the object the binding belongs to. It is useful however, to
- understand what actually happens when the binding is activated.
+ @method begin
+ @return {void}
+*/
+Ember.run.begin = function() {
+ run.currentRunLoop = new RunLoop(run.currentRunLoop);
+};
- For a binding to function it must have at least a "from" property and a "to"
- property. The from property path points to the object/key that you want to
- bind from while the to path points to the object/key you want to bind to.
+/**
+ Ends a RunLoop. This must be called sometime after you call
+ `Ember.run.begin()` to flush any deferred actions. This is a lower-level way
+ to use a RunLoop instead of using `Ember.run()`.
- When you define a custom binding, you are usually describing the property
- you want to bind from (such as "MyApp.someController.value" in the examples
- above). When your object is created, it will automatically assign the value
- you want to bind "to" based on the name of your binding key. In the
- examples above, during init, Ember objects will effectively call
- something like this on your binding:
+ ```javascript
+ Ember.run.begin();
+ // code to be execute within a RunLoop
+ Ember.run.end();
+ ```
- binding = Ember.Binding.from(this.valueBinding).to("value");
+ @method end
+ @return {void}
+*/
+Ember.run.end = function() {
+ Ember.assert('must have a current run loop', run.currentRunLoop);
- This creates a new binding instance based on the template you provide, and
- sets the to path to the "value" property of the new object. Now that the
- binding is fully configured with a "from" and a "to", it simply needs to be
- connected to become active. This is done through the connect() method:
+ function tryable() { run.currentRunLoop.end(); }
+ function finalizer() { run.currentRunLoop = run.currentRunLoop.prev(); }
- binding.connect(this);
+ Ember.tryFinally(tryable, finalizer);
+};
- Note that when you connect a binding you pass the object you want it to be
- connected to. This object will be used as the root for both the from and
- to side of the binding when inspecting relative paths. This allows the
- binding to be automatically inherited by subclassed objects as well.
+/**
+ Array of named queues. This array determines the order in which queues
+ are flushed at the end of the RunLoop. You can define your own queues by
+ simply adding the queue name to this array. Normally you should not need
+ to inspect or modify this property.
- Now that the binding is connected, it will observe both the from and to side
- and relay changes.
+ @property queues
+ @type Array
+ @default ['sync', 'actions', 'destroy', 'timers']
+*/
+Ember.run.queues = ['sync', 'actions', 'destroy', 'timers'];
- If you ever needed to do so (you almost never will, but it is useful to
- understand this anyway), you could manually create an active binding by
- using the Ember.bind() helper method. (This is the same method used by
- to setup your bindings on objects):
+/**
+ Adds the passed target/method and any optional arguments to the named
+ queue to be executed at the end of the RunLoop. If you have not already
+ started a RunLoop when calling this method one will be started for you
+ automatically.
- Ember.bind(MyApp.anotherObject, "value", "MyApp.someController.value");
+ At the end of a RunLoop, any methods scheduled in this way will be invoked.
+ Methods will be invoked in an order matching the named queues defined in
+ the `run.queues` property.
- Both of these code fragments have the same effect as doing the most friendly
- form of binding creation like so:
+ ```javascript
+ Ember.run.schedule('timers', this, function(){
+ // this will be executed at the end of the RunLoop, when timers are run
+ console.log("scheduled on timers queue");
+ });
- MyApp.anotherObject = Ember.Object.create({
- valueBinding: "MyApp.someController.value",
+ Ember.run.schedule('sync', this, function(){
+ // this will be executed at the end of the RunLoop, when bindings are synced
+ console.log("scheduled on sync queue");
+ });
- // OTHER CODE FOR THIS OBJECT...
+ // Note the functions will be run in order based on the run queues order. Output would be:
+ // scheduled on sync queue
+ // scheduled on timers queue
+ ```
- });
+ @method schedule
+ @param {String} queue The name of the queue to schedule against.
+ Default queues are 'sync' and 'actions'
+ @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 {Object} [arguments*] Optional arguments to be passed to the queued method.
+ @return {void}
+*/
+Ember.run.schedule = function(queue, target, method) {
+ var loop = run.autorun();
+ loop.schedule.apply(loop, arguments);
+};
- Ember's built in binding creation method makes it easy to automatically
- create bindings for you. You should always use the highest-level APIs
- available, even if you understand how it works underneath.
+var scheduledAutorun;
+function autorun() {
+ scheduledAutorun = null;
+ if (run.currentRunLoop) { run.end(); }
+}
- @class Binding
- @namespace Ember
- @since Ember 0.9
-*/
-Ember.Binding = Binding;
+// Used by global test teardown
+Ember.run.hasScheduledTimers = function() {
+ return !!(scheduledAutorun || scheduledLater || scheduledNext);
+};
+// Used by global test teardown
+Ember.run.cancelTimers = function () {
+ if (scheduledAutorun) {
+ clearTimeout(scheduledAutorun);
+ scheduledAutorun = null;
+ }
+ if (scheduledLater) {
+ clearTimeout(scheduledLater);
+ scheduledLater = null;
+ }
+ if (scheduledNext) {
+ clearTimeout(scheduledNext);
+ scheduledNext = null;
+ }
+ timers = {};
+};
/**
- 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.
+ Begins a new RunLoop if necessary and schedules a timer to flush the
+ RunLoop at a later time. This method is used by parts of Ember to
+ ensure the RunLoop always finishes. You normally do not need to call this
+ method directly. Instead use `Ember.run()`
- @method bind
- @for Ember
- @param {Object} obj The root object of the transform.
+ @method autorun
+ @example
+ Ember.run.autorun();
+ @return {Ember.RunLoop} the new current RunLoop
+*/
+Ember.run.autorun = function() {
+ if (!run.currentRunLoop) {
+ Ember.assert("You have turned on testing mode, which disabled the run-loop's autorun. You will need to wrap any code with asynchronous side-effects in an Ember.run", !Ember.testing);
- @param {String} to The path to the 'to' side of the binding.
- Must be relative to obj.
+ run.begin();
- @param {String} from The path to the 'from' side of the binding.
- Must be relative to obj or a global path.
+ if (!scheduledAutorun) {
+ scheduledAutorun = setTimeout(autorun, 1);
+ }
+ }
- @return {Ember.Binding} binding instance
-*/
-Ember.bind = function(obj, to, from) {
- return new Ember.Binding(to, from).connect(obj);
+ return run.currentRunLoop;
};
/**
- @method oneWay
- @for Ember
- @param {Object} obj The root object of the transform.
+ Immediately flushes any events scheduled in the 'sync' queue. Bindings
+ use this queue so this method is a useful way to immediately force all
+ bindings in the application to sync.
- @param {String} to The path to the 'to' side of the binding.
- Must be relative to obj.
+ You should call this method anytime you need any changed state to propagate
+ throughout the app immediately without repainting the UI.
- @param {String} from The path to the 'from' side of the binding.
- Must be relative to obj or a global path.
+ ```javascript
+ Ember.run.sync();
+ ```
- @return {Ember.Binding} binding instance
+ @method sync
+ @return {void}
*/
-Ember.oneWay = function(obj, to, from) {
- return new Ember.Binding(to, from).oneWay().connect(obj);
+Ember.run.sync = function() {
+ run.autorun();
+ run.currentRunLoop.flush('sync');
};
-})();
-
-
-
-(function() {
-/**
-@module ember-metal
-*/
+// ..........................................................
+// TIMERS
+//
-var Mixin, REQUIRED, Alias,
- classToString, superClassString,
- a_map = Ember.ArrayPolyfills.map,
- a_indexOf = Ember.ArrayPolyfills.indexOf,
- a_forEach = Ember.ArrayPolyfills.forEach,
- a_slice = [].slice,
- EMPTY_META = {}, // dummy for non-writable meta
- META_SKIP = { __emberproto__: true, __ember_count__: true },
- o_create = Ember.create,
- defineProperty = Ember.defineProperty,
- guidFor = Ember.guidFor;
+var timers = {}; // active timers...
-function mixinsMeta(obj) {
- var m = Ember.meta(obj, true), ret = m.mixins;
- if (!ret) {
- ret = m.mixins = { __emberproto__: obj };
- } else if (ret.__emberproto__ !== obj) {
- ret = m.mixins = o_create(ret);
- ret.__emberproto__ = obj;
+var scheduledLater;
+function invokeLaterTimers() {
+ scheduledLater = null;
+ var now = (+ new Date()), earliest = -1;
+ for (var key in timers) {
+ if (!timers.hasOwnProperty(key)) { continue; }
+ var timer = timers[key];
+ if (timer && timer.expires) {
+ if (now >= timer.expires) {
+ delete timers[key];
+ invoke(timer.target, timer.method, timer.args, 2);
+ } else {
+ if (earliest<0 || (timer.expires < earliest)) earliest=timer.expires;
+ }
+ }
}
- return ret;
-}
-
-function initMixin(mixin, args) {
- if (args && args.length > 0) {
- mixin.mixins = a_map.call(args, function(x) {
- if (x instanceof Mixin) { return x; }
- // Note: Manually setup a primitive mixin here. This is the only
- // way to actually get a primitive mixin. This way normal creation
- // of mixins will give you combined mixins...
- var mixin = new Mixin();
- mixin.properties = x;
- return mixin;
- });
- }
- return mixin;
+ // schedule next timeout to fire...
+ if (earliest > 0) { scheduledLater = setTimeout(invokeLaterTimers, earliest-(+ new Date())); }
}
-function isMethod(obj) {
- return 'function' === typeof obj &&
- obj.isMethod !== false &&
- obj !== Boolean && obj !== Object && obj !== Number && obj !== Array && obj !== Date && obj !== String;
-}
+/**
+ Invokes the passed target/method and optional arguments after a specified
+ period if time. The last parameter of this method must always be a number
+ of milliseconds.
-function mergeMixins(mixins, m, descs, values, base) {
- var len = mixins.length, idx, mixin, guid, props, value, key, ovalue, concats;
+ You should use this method whenever you need to run some action after a
+ period of time instead of using `setTimeout()`. This method will ensure that
+ items that expire during the same script execution cycle all execute
+ together, which is often more efficient than using a real setTimeout.
- function removeKeys(keyName) {
- delete descs[keyName];
- delete values[keyName];
- }
+ ```javascript
+ Ember.run.later(myContext, function(){
+ // code here will execute within a RunLoop in about 500ms with this == myContext
+ }, 500);
+ ```
- for(idx=0; idx < len; idx++) {
- mixin = mixins[idx];
- Ember.assert('Expected hash or Mixin instance, got ' + Object.prototype.toString.call(mixin), typeof mixin === 'object' && mixin !== null && Object.prototype.toString.call(mixin) !== '[object Array]');
+ @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
+ target at the time the method is invoked.
+ @param {Object} [args*] Optional arguments to pass to the timeout.
+ @param {Number} wait
+ Number of milliseconds to wait.
+ @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;
- if (mixin instanceof Mixin) {
- guid = guidFor(mixin);
- if (m[guid]) { continue; }
- m[guid] = mixin;
- props = mixin.properties;
- } else {
- props = mixin; // apply anonymous mixin properties
- }
+ // setTimeout compatibility...
+ if (arguments.length===2 && 'function' === typeof target) {
+ wait = method;
+ method = target;
+ target = undefined;
+ args = [target, method];
+ } else {
+ args = slice.call(arguments);
+ wait = args.pop();
+ }
- if (props) {
- // reset before adding each new mixin to pickup concats from previous
- concats = values.concatenatedProperties || base.concatenatedProperties;
- if (props.concatenatedProperties) {
- concats = concats ? concats.concat(props.concatenatedProperties) : props.concatenatedProperties;
- }
+ expires = (+ new Date()) + wait;
+ timer = { target: target, method: method, expires: expires, args: args };
+ guid = Ember.guidFor(timer);
+ timers[guid] = timer;
+ run.once(timers, invokeLaterTimers);
+ return guid;
+};
- for (key in props) {
- if (!props.hasOwnProperty(key)) { continue; }
- value = props[key];
- if (value instanceof Ember.Descriptor) {
- if (value === REQUIRED && descs[key]) { continue; }
+function invokeOnceTimer(guid, onceTimers) {
+ if (onceTimers[this.tguid]) { delete onceTimers[this.tguid][this.mguid]; }
+ if (timers[guid]) { invoke(this.target, this.method, this.args); }
+ delete timers[guid];
+}
- descs[key] = value;
- values[key] = undefined;
- } else {
- // impl super if needed...
- if (isMethod(value)) {
- ovalue = descs[key] === undefined && values[key];
- if (!ovalue) { ovalue = base[key]; }
- if ('function' !== typeof ovalue) { ovalue = null; }
- if (ovalue) {
- var o = value.__ember_observes__, ob = value.__ember_observesBefore__;
- value = Ember.wrap(value, ovalue);
- value.__ember_observes__ = o;
- value.__ember_observesBefore__ = ob;
- }
- } else if ((concats && a_indexOf.call(concats, key) >= 0) || key === 'concatenatedProperties') {
- var baseValue = values[key] || base[key];
- value = baseValue ? baseValue.concat(value) : Ember.makeArray(value);
- }
+function scheduleOnce(queue, target, method, args) {
+ var tguid = Ember.guidFor(target),
+ mguid = Ember.guidFor(method),
+ onceTimers = run.autorun().onceTimers,
+ guid = onceTimers[tguid] && onceTimers[tguid][mguid],
+ timer;
- descs[key] = undefined;
- values[key] = value;
- }
- }
+ if (guid && timers[guid]) {
+ timers[guid].args = args; // replace args
+ } else {
+ timer = {
+ target: target,
+ method: method,
+ args: args,
+ tguid: tguid,
+ mguid: mguid
+ };
- // manually copy toString() because some JS engines do not enumerate it
- if (props.hasOwnProperty('toString')) {
- base.toString = props.toString;
- }
+ guid = Ember.guidFor(timer);
+ timers[guid] = timer;
+ if (!onceTimers[tguid]) { onceTimers[tguid] = {}; }
+ onceTimers[tguid][mguid] = guid; // so it isn't scheduled more than once
- } else if (mixin.mixins) {
- mergeMixins(mixin.mixins, m, descs, values, base);
- if (mixin._without) { a_forEach.call(mixin._without, removeKeys); }
- }
+ run.schedule(queue, timer, invokeOnceTimer, guid, onceTimers);
}
-}
-function writableReq(obj) {
- var m = Ember.meta(obj), req = m.required;
- if (!req || req.__emberproto__ !== obj) {
- req = m.required = req ? o_create(req) : { __ember_count__: 0 };
- req.__emberproto__ = obj;
- }
- return req;
+ return guid;
}
-var IS_BINDING = Ember.IS_BINDING = /^.+Binding$/;
+/**
+ Schedules an item to run one time during the current RunLoop. Calling
+ this method with the same target/method combination will have no effect.
-function detectBinding(obj, key, value, m) {
- if (IS_BINDING.test(key)) {
- var bindings = m.bindings;
- if (!bindings) {
- bindings = m.bindings = { __emberproto__: obj };
- } else if (bindings.__emberproto__ !== obj) {
- bindings = m.bindings = o_create(m.bindings);
- bindings.__emberproto__ = obj;
- }
- bindings[key] = value;
- }
-}
+ Note that although you can pass optional arguments these will not be
+ considered when looking for duplicates. New arguments will replace previous
+ calls.
-function connectBindings(obj, m) {
- // TODO Mixin.apply(instance) should disconnect binding if exists
- var bindings = m.bindings, key, binding, to;
- if (bindings) {
- for (key in bindings) {
- binding = key !== '__emberproto__' && bindings[key];
- if (binding) {
- to = key.slice(0, -7); // strip Binding off end
- if (binding instanceof Ember.Binding) {
- binding = binding.copy(); // copy prototypes' instance
- binding.to(to);
- } else { // binding is string path
- binding = new Ember.Binding(to, binding);
- }
- binding.connect(obj);
- obj[key] = binding;
- }
+ ```javascript
+ Ember.run(function(){
+ var doFoo = function() { foo(); }
+ Ember.run.once(myContext, doFoo);
+ Ember.run.once(myContext, doFoo);
+ // doFoo will only be executed once at the end of the RunLoop
+ });
+ ```
+
+ @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
+ target at the time the method is invoked.
+ @param {Object} [args*] Optional arguments to pass to the timeout.
+ @return {Object} timer
+*/
+Ember.run.once = function(target, method) {
+ return scheduleOnce('actions', target, method, slice.call(arguments, 2));
+};
+
+Ember.run.scheduleOnce = function(queue, target, method, args) {
+ return scheduleOnce(queue, target, method, slice.call(arguments, 3));
+};
+
+var scheduledNext;
+function invokeNextTimers() {
+ scheduledNext = null;
+ for(var key in timers) {
+ if (!timers.hasOwnProperty(key)) { continue; }
+ var timer = timers[key];
+ if (timer.next) {
+ delete timers[key];
+ invoke(timer.target, timer.method, timer.args, 2);
}
- // mark as applied
- m.bindings = { __emberproto__: obj };
}
}
-function finishPartial(obj, m) {
- connectBindings(obj, m || Ember.meta(obj));
- return obj;
-}
-
-function applyMixin(obj, mixins, partial) {
- var descs = {}, values = {}, m = Ember.meta(obj), req = m.required,
- key, value, desc, prevValue, paths, len, idx;
-
- // Go through all mixins and hashes passed in, and:
- //
- // * Handle concatenated properties
- // * Set up _super wrapping if necessary
- // * Set up computed property descriptors
- // * Copying `toString` in broken browsers
- mergeMixins(mixins, mixinsMeta(obj), descs, values, obj);
+/**
+ Schedules an item to run after control has been returned to the system.
+ This is often equivalent to calling `setTimeout(function() {}, 1)`.
- for(key in values) {
- if (key === 'contructor') { continue; }
- if (!values.hasOwnProperty(key)) { continue; }
+ ```javascript
+ Ember.run.next(myContext, function(){
+ // code to be executed in the next RunLoop, which will be scheduled after the current one
+ });
+ ```
- desc = descs[key];
- value = values[key];
+ @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
+ target at the time the method is invoked.
+ @param {Object} [args*] Optional arguments to pass to the timeout.
+ @return {Object} timer
+*/
+Ember.run.next = function(target, method) {
+ var guid,
+ timer = {
+ target: target,
+ method: method,
+ args: slice.call(arguments),
+ next: true
+ };
- if (desc === REQUIRED) {
- if (!(key in obj)) {
- Ember.assert('Required property not defined: '+key, !!partial);
+ guid = Ember.guidFor(timer);
+ timers[guid] = timer;
- // for partial applies add to hash of required keys
- req = writableReq(obj);
- req.__ember_count__++;
- req[key] = true;
- }
- } else {
- while (desc && desc instanceof Alias) {
- var altKey = desc.methodName;
- if (descs[altKey] || values[altKey]) {
- value = values[altKey];
- desc = descs[altKey];
- } else if (m.descs[altKey]) {
- desc = m.descs[altKey];
- value = undefined;
- } else {
- desc = undefined;
- value = obj[altKey];
- }
- }
+ if (!scheduledNext) { scheduledNext = setTimeout(invokeNextTimers, 1); }
+ return guid;
+};
- if (desc === undefined && value === undefined) { continue; }
+/**
+ Cancels a scheduled item. Must be a value returned by `Ember.run.later()`,
+ `Ember.run.once()`, or `Ember.run.next()`.
- prevValue = obj[key];
+ ```javascript
+ var runNext = Ember.run.next(myContext, function(){
+ // will not be executed
+ });
+ Ember.run.cancel(runNext);
- if ('function' === typeof prevValue) {
- if ((paths = prevValue.__ember_observesBefore__)) {
- len = paths.length;
- for (idx=0; idx < len; idx++) {
- Ember.removeBeforeObserver(obj, paths[idx], null, key);
- }
- } else if ((paths = prevValue.__ember_observes__)) {
- len = paths.length;
- for (idx=0; idx < len; idx++) {
- Ember.removeObserver(obj, paths[idx], null, key);
- }
- }
- }
+ var runLater = Ember.run.later(myContext, function(){
+ // will not be executed
+ }, 500);
+ Ember.run.cancel(runLater);
- detectBinding(obj, key, value, m);
+ var runOnce = Ember.run.once(myContext, function(){
+ // will not be executed
+ });
+ Ember.run.cancel(runOnce);
+ ```
- defineProperty(obj, key, desc, value, m);
+ @method cancel
+ @param {Object} timer Timer object to cancel
+ @return {void}
+*/
+Ember.run.cancel = function(timer) {
+ delete timers[timer];
+};
- if ('function' === typeof value) {
- if (paths = value.__ember_observesBefore__) {
- len = paths.length;
- for (idx=0; idx < len; idx++) {
- Ember.addBeforeObserver(obj, paths[idx], null, key);
- }
- } else if (paths = value.__ember_observes__) {
- len = paths.length;
- for (idx=0; idx < len; idx++) {
- Ember.addObserver(obj, paths[idx], null, key);
- }
- }
- }
+})();
- if (req && req[key]) {
- req = writableReq(obj);
- req.__ember_count__--;
- req[key] = false;
- }
- }
- }
- if (!partial) { // don't apply to prototype
- finishPartial(obj, m);
- }
- // Make sure no required attrs remain
- if (!partial && req && req.__ember_count__>0) {
- var keys = [];
- for (key in req) {
- if (META_SKIP[key]) { continue; }
- keys.push(key);
- }
- // TODO: Remove surrounding if clause from production build
- Ember.assert('Required properties not defined: '+keys.join(','));
- }
- return obj;
-}
+(function() {
+// Ember.Logger
+// get, set, trySet
+// guidFor, isArray, meta
+// addObserver, removeObserver
+// Ember.run.schedule
+/**
+@module ember-metal
+*/
+
+// ..........................................................
+// CONSTANTS
+//
/**
- @method mixin
+ 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
- @param obj
- @param mixins*
- @return obj
+ @type Boolean
+ @default false
*/
-Ember.mixin = function(obj) {
- var args = a_slice.call(arguments, 1);
- applyMixin(obj, args, false);
- return obj;
-};
+Ember.LOG_BINDINGS = false || !!Ember.ENV.LOG_BINDINGS;
-/**
- The `Ember.Mixin` class allows you to create mixins, whose properties can be
- added to other classes. For instance,
+var get = Ember.get,
+ set = Ember.set,
+ guidFor = Ember.guidFor,
+ isGlobalPath = Ember.isGlobalPath;
- App.Editable = Ember.Mixin.create({
- edit: function() {
- console.log('starting to edit');
- this.set('isEditing', true);
- },
- isEditing: false
- });
- // Mix mixins into classes by passing them as the first arguments to
- // .extend or .create.
- App.CommentView = Ember.View.extend(App.Editable, {
- template: Ember.Handlebars.compile('{{#if isEditing}}...{{else}}...{{/if}}')
- });
+function getWithGlobals(obj, path) {
+ return get(isGlobalPath(path) ? Ember.lookup : obj, path);
+}
- commentView = App.CommentView.create();
- commentView.edit(); // => outputs 'starting to edit'
+// ..........................................................
+// BINDING
+//
- Note that Mixins are created with `Ember.Mixin.create`, not
- `Ember.Mixin.extend`.
+var Binding = function(toPath, fromPath) {
+ this._direction = 'fwd';
+ this._from = fromPath;
+ this._to = toPath;
+ this._directionMap = Ember.Map.create();
+};
- @class Mixin
- @namespace Ember
+/**
+@class Binding
+@namespace Ember
*/
-Ember.Mixin = function() { return initMixin(this, arguments); };
-Mixin = Ember.Mixin;
+Binding.prototype = {
+ /**
+ This copies the Binding so it can be connected to another object.
-Mixin._apply = applyMixin;
+ @method copy
+ @return {Ember.Binding}
+ */
+ copy: function () {
+ var copy = new Binding(this._to, this._from);
+ if (this._oneWay) { copy._oneWay = true; }
+ return copy;
+ },
-Mixin.applyPartial = function(obj) {
- var args = a_slice.call(arguments, 1);
- return applyMixin(obj, args, true);
-};
+ // ..........................................................
+ // CONFIG
+ //
-Mixin.finishPartial = finishPartial;
+ /**
+ This will set `from` property path to the specified value. It will not
+ attempt to resolve this property path to an actual object until you
+ connect the binding.
-/**
- @method create
- @static
- @param arguments*
-*/
-Mixin.create = function() {
- classToString.processed = false;
- var M = this;
- return initMixin(new M(), arguments);
-};
+ The binding will search for the property path starting at the root object
+ you pass when you `connect()` the binding. It follows the same rules as
+ `get()` - see that method for more information.
-var MixinPrototype = Mixin.prototype;
+ @method from
+ @param {String} propertyPath the property path to connect to
+ @return {Ember.Binding} `this`
+ */
+ from: function(path) {
+ this._from = path;
+ return this;
+ },
-/**
- @method reopen
- @param arguments*
-*/
-MixinPrototype.reopen = function() {
- var mixin, tmp;
+ /**
+ This will set the `to` property path to the specified value. It will not
+ attempt to resolve this property path to an actual object until you
+ connect the binding.
- if (this.properties) {
- mixin = Mixin.create();
- mixin.properties = this.properties;
- delete this.properties;
- this.mixins = [mixin];
- } else if (!this.mixins) {
- this.mixins = [];
- }
+ The binding will search for the property path starting at the root object
+ you pass when you `connect()` the binding. It follows the same rules as
+ `get()` - see that method for more information.
- var len = arguments.length, mixins = this.mixins, idx;
+ @method to
+ @param {String|Tuple} propertyPath A property path or tuple
+ @return {Ember.Binding} `this`
+ */
+ to: function(path) {
+ this._to = path;
+ return this;
+ },
- for(idx=0; idx < len; idx++) {
- mixin = arguments[idx];
- Ember.assert('Expected hash or Mixin instance, got ' + Object.prototype.toString.call(mixin), typeof mixin === 'object' && mixin !== null && Object.prototype.toString.call(mixin) !== '[object Array]');
+ /**
+ Configures the binding as one way. A one-way binding will relay changes
+ on the `from` side to 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.
- if (mixin instanceof Mixin) {
- mixins.push(mixin);
- } else {
- tmp = Mixin.create();
- tmp.properties = mixin;
- mixins.push(tmp);
- }
- }
+ @method oneWay
+ @return {Ember.Binding} `this`
+ */
+ oneWay: function() {
+ this._oneWay = true;
+ return this;
+ },
- return this;
-};
+ toString: function() {
+ var oneWay = this._oneWay ? '[oneWay]' : '';
+ return "Ember.Binding<" + guidFor(this) + ">(" + this._from + " -> " + this._to + ")" + oneWay;
+ },
-/**
- @method apply
- @param obj
- @return applied object
-*/
-MixinPrototype.apply = function(obj) {
- return applyMixin(obj, [this], false);
-};
+ // ..........................................................
+ // CONNECT AND SYNC
+ //
-MixinPrototype.applyPartial = function(obj) {
- return applyMixin(obj, [this], true);
-};
+ /**
+ Attempts to connect this binding instance so that it can receive and relay
+ changes. This method will raise an exception if you have not set the
+ from/to properties yet.
-function _detect(curMixin, targetMixin, seen) {
- var guid = guidFor(curMixin);
+ @method connect
+ @param {Object} obj The root object for this binding.
+ @return {Ember.Binding} `this`
+ */
+ connect: function(obj) {
+ Ember.assert('Must pass a valid object to Ember.Binding.connect()', !!obj);
- if (seen[guid]) { return false; }
- seen[guid] = true;
+ var fromPath = this._from, toPath = this._to;
+ Ember.trySet(obj, toPath, getWithGlobals(obj, fromPath));
- if (curMixin === targetMixin) { return true; }
- var mixins = curMixin.mixins, loc = mixins ? mixins.length : 0;
- while (--loc >= 0) {
- if (_detect(mixins[loc], targetMixin, seen)) { return true; }
- }
- return false;
-}
+ // add an observer on the object to be notified when the binding should be updated
+ Ember.addObserver(obj, fromPath, this, this.fromDidChange);
-/**
- @method detect
- @param obj
- @return {Boolean}
-*/
-MixinPrototype.detect = function(obj) {
- if (!obj) { return false; }
- if (obj instanceof Mixin) { return _detect(obj, this, {}); }
- var mixins = Ember.meta(obj, false).mixins;
- if (mixins) {
- return !!mixins[guidFor(this)];
- }
- return false;
-};
+ // if the binding is a two-way binding, also set up an observer on the target
+ if (!this._oneWay) { Ember.addObserver(obj, toPath, this, this.toDidChange); }
-MixinPrototype.without = function() {
- var ret = new Mixin(this);
- ret._without = a_slice.call(arguments);
- return ret;
-};
+ this._readyToSync = true;
-function _keys(ret, mixin, seen) {
- if (seen[guidFor(mixin)]) { return; }
- seen[guidFor(mixin)] = true;
+ return this;
+ },
- if (mixin.properties) {
- var props = mixin.properties;
- for (var key in props) {
- if (props.hasOwnProperty(key)) { ret[key] = true; }
- }
- } else if (mixin.mixins) {
- a_forEach.call(mixin.mixins, function(x) { _keys(ret, x, seen); });
- }
-}
+ /**
+ Disconnects the binding instance. Changes will no longer be relayed. You
+ will not usually need to call this method.
-MixinPrototype.keys = function() {
- var keys = {}, seen = {}, ret = [];
- _keys(keys, this, seen);
- for(var key in keys) {
- if (keys.hasOwnProperty(key)) { ret.push(key); }
- }
- return ret;
-};
+ @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);
-/* make Mixins have nice displayNames */
+ var twoWay = !this._oneWay;
-var NAME_KEY = Ember.GUID_KEY+'_name';
-var get = Ember.get;
+ // remove an observer on the object so we're no longer notified of
+ // changes that should update bindings.
+ Ember.removeObserver(obj, this._from, this, this.fromDidChange);
-function processNames(paths, root, seen) {
- var idx = paths.length;
- for(var key in root) {
- if (!root.hasOwnProperty || !root.hasOwnProperty(key)) { continue; }
- var obj = root[key];
- paths[idx] = key;
+ // if the binding is two-way, remove the observer from the target as well
+ if (twoWay) { Ember.removeObserver(obj, this._to, this, this.toDidChange); }
- if (obj && obj.toString === classToString) {
- obj[NAME_KEY] = paths.join('.');
- } else if (obj && get(obj, 'isNamespace')) {
- if (seen[guidFor(obj)]) { continue; }
- seen[guidFor(obj)] = true;
- processNames(paths, obj, seen);
- }
- }
- paths.length = idx; // cut out last item
-}
+ this._readyToSync = false; // disable scheduled syncs...
+ return this;
+ },
-function findNamespaces() {
- var Namespace = Ember.Namespace, obj, isNamespace;
+ // ..........................................................
+ // PRIVATE
+ //
- if (Namespace.PROCESSED) { return; }
+ /* called when the from side changes */
+ fromDidChange: function(target) {
+ this._scheduleSync(target, 'fwd');
+ },
- for (var prop in window) {
- // get(window.globalStorage, 'isNamespace') would try to read the storage for domain isNamespace and cause exception in Firefox.
- // globalStorage is a storage obsoleted by the WhatWG storage specification. See https://developer.mozilla.org/en/DOM/Storage#globalStorage
- if (prop === "globalStorage" && window.StorageList && window.globalStorage instanceof window.StorageList) { continue; }
- // Unfortunately, some versions of IE don't support window.hasOwnProperty
- if (window.hasOwnProperty && !window.hasOwnProperty(prop)) { continue; }
+ /* called when the to side changes */
+ toDidChange: function(target) {
+ this._scheduleSync(target, 'back');
+ },
- // At times we are not allowed to access certain properties for security reasons.
- // There are also times where even if we can access them, we are not allowed to access their properties.
- try {
- obj = window[prop];
- isNamespace = obj && get(obj, 'isNamespace');
- } catch (e) {
- continue;
+ _scheduleSync: function(obj, dir) {
+ var directionMap = this._directionMap;
+ var existingDir = directionMap.get(obj);
+
+ // if we haven't scheduled the binding yet, schedule it
+ if (!existingDir) {
+ Ember.run.schedule('sync', this, this._sync, obj);
+ directionMap.set(obj, dir);
}
- if (isNamespace) {
- Ember.deprecate("Namespaces should not begin with lowercase.", /^[A-Z]/.test(prop));
- obj[NAME_KEY] = prop;
+ // If both a 'back' and 'fwd' sync have been scheduled on the same object,
+ // default to a 'fwd' sync so that it remains deterministic.
+ if (existingDir === 'back' && dir === 'fwd') {
+ directionMap.set(obj, 'fwd');
}
- }
-}
+ },
-/**
- @private
- @method identifyNamespaces
- @for Ember
-*/
-Ember.identifyNamespaces = findNamespaces;
+ _sync: function(obj) {
+ var log = Ember.LOG_BINDINGS;
-superClassString = function(mixin) {
- var superclass = mixin.superclass;
- if (superclass) {
- if (superclass[NAME_KEY]) { return superclass[NAME_KEY]; }
- else { return superClassString(superclass); }
- } else {
- return;
- }
-};
+ // don't synchronize destroyed objects or disconnected bindings
+ if (obj.isDestroyed || !this._readyToSync) { return; }
-classToString = function() {
- var Namespace = Ember.Namespace, namespace;
+ // get the direction of the binding for the object we are
+ // synchronizing from
+ var directionMap = this._directionMap;
+ var direction = directionMap.get(obj);
- // TODO: Namespace should really be in Metal
- if (Namespace) {
- if (!this[NAME_KEY] && !classToString.processed) {
- if (!Namespace.PROCESSED) {
- findNamespaces();
- Namespace.PROCESSED = true;
- }
+ var fromPath = this._from, toPath = this._to;
- classToString.processed = true;
+ directionMap.remove(obj);
- var namespaces = Namespace.NAMESPACES;
- for (var i=0, l=namespaces.length; i<l; i++) {
- namespace = namespaces[i];
- processNames([namespace.toString()], namespace, {});
+ // if we're synchronizing from the remote object...
+ if (direction === 'fwd') {
+ var fromValue = getWithGlobals(obj, this._from);
+ if (log) {
+ Ember.Logger.log(' ', this.toString(), '->', fromValue, obj);
+ }
+ if (this._oneWay) {
+ Ember.trySet(obj, toPath, fromValue);
+ } else {
+ Ember._suspendObserver(obj, toPath, this, this.toDidChange, function () {
+ Ember.trySet(obj, toPath, fromValue);
+ });
+ }
+ // if we're synchronizing *to* the remote object
+ } else if (direction === 'back') {
+ var toValue = get(obj, this._to);
+ if (log) {
+ Ember.Logger.log(' ', this.toString(), '<-', toValue, obj);
}
+ Ember._suspendObserver(obj, fromPath, this, this.fromDidChange, function () {
+ Ember.trySet(Ember.isGlobalPath(fromPath) ? Ember.lookup : obj, fromPath, toValue);
+ });
}
}
- if (this[NAME_KEY]) {
- return this[NAME_KEY];
- } else {
- var str = superClassString(this);
- if (str) {
- return "(subclass of " + str + ")";
- } else {
- return "(unknown mixin)";
+};
+
+function mixinProperties(to, from) {
+ for (var key in from) {
+ if (from.hasOwnProperty(key)) {
+ to[key] = from[key];
}
}
-};
+}
-MixinPrototype.toString = classToString;
+mixinProperties(Binding, {
-// returns the mixins currently applied to the specified object
-// TODO: Make Ember.mixin
-Mixin.mixins = function(obj) {
- var ret = [], mixins = Ember.meta(obj, false).mixins, key, mixin;
- if (mixins) {
- for(key in mixins) {
- if (META_SKIP[key]) { continue; }
- mixin = mixins[key];
+ /**
+ See {{#crossLink "Ember.Binding/from"}}{{/crossLink}}
- // skip primitive mixins since these are always anonymous
- if (!mixin.properties) { ret.push(mixins[key]); }
- }
- }
- return ret;
-};
+ @method from
+ @static
+ */
+ from: function() {
+ var C = this, binding = new C();
+ return binding.from.apply(binding, arguments);
+ },
-REQUIRED = new Ember.Descriptor();
-REQUIRED.toString = function() { return '(Required Property)'; };
+ /**
+ See {{#crossLink "Ember.Binding/to"}}{{/crossLink}}
-/**
- Denotes a required property for a mixin
+ @method to
+ @static
+ */
+ to: function() {
+ var C = this, binding = new C();
+ return binding.to.apply(binding, arguments);
+ },
- @method required
- @for Ember
-*/
-Ember.required = function() {
- return REQUIRED;
-};
+ /**
+ 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 (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.
-Alias = function(methodName) {
- this.methodName = methodName;
-};
-Alias.prototype = new Ember.Descriptor();
+ 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.
+ */
+ oneWay: function(from, flag) {
+ var C = this, binding = new C(null, from);
+ return binding.oneWay(flag);
+ }
+
+});
/**
- Makes a property or method available via an additional name.
+ 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.
- App.PaintSample = Ember.Object.extend({
- color: 'red',
- colour: Ember.alias('color'),
- name: function(){
- return "Zed";
- },
- moniker: Ember.alias("name")
- });
- var paintSample = App.PaintSample.create()
- paintSample.get('colour'); //=> 'red'
- paintSample.moniker(); //=> 'Zed'
+ ## Automatic Creation of Bindings with `/^*Binding/`-named Properties
- @method alias
- @for Ember
- @param {String} methodName name of the method or property to alias
- @return {Ember.Descriptor}
-*/
-Ember.alias = function(methodName) {
- return new Alias(methodName);
-};
+ You do not usually create Binding objects directly but instead describe
+ bindings in your class or object definition using automatic binding
+ detection.
-// ..........................................................
-// OBSERVER HELPER
-//
+ Properties ending in a `Binding` suffix will be converted to `Ember.Binding`
+ instances. The value of this property should be a string representing a path
+ to another object or a custom binding instanced created using Binding helpers
+ (see "Customizing Your Bindings"):
-/**
- @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;
- return func;
-};
+ ```
+ valueBinding: "MyApp.someController.title"
+ ```
-// 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];
- Ember.assert("Immediate observers must observe internal properties only, not properties on other objects.", typeof arg !== "string" || arg.indexOf('.') === -1);
- }
+ This will create a binding from `MyApp.someController.title` to the `value`
+ property of your object instance automatically. Now the two values will be
+ kept in sync.
- return Ember.observer.apply(this, arguments);
-};
+ ## One Way Bindings
-/**
- @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;
- return func;
-};
+ One especially useful binding customization you can use is the `oneWay()`
+ helper. This helper tells Ember that you are only interested in
+ receiving changes on the object you are binding from. For example, if you
+ are binding to a preference and you want to be notified if the preference
+ has changed, but your object will not be changing the preference itself, you
+ could do:
-})();
+ ```
+ bigTitlesBinding: Ember.Binding.oneWay("MyApp.preferencesController.bigTitles")
+ ```
+ This way if the value of `MyApp.preferencesController.bigTitles` changes the
+ `bigTitles` property of your object will change also. However, if you
+ change the value of your `bigTitles` property, it will not update the
+ `preferencesController`.
+ One way bindings are almost twice as fast to setup and twice as fast to
+ execute because the binding only has to worry about changes to one side.
-(function() {
-/**
-Ember Metal
+ You should consider using one way bindings anytime you have an object that
+ may be created frequently and you do not intend to change a property; only
+ to monitor it for changes. (such as in the example above).
-@module ember
-@submodule ember-metal
-*/
+ ## Adding Bindings Manually
-})();
+ All of the examples above show you how to configure a custom binding, but the
+ result of these customizations will be a binding template, not a fully active
+ Binding instance. The binding will actually become active only when you
+ instantiate the object the binding belongs to. It is useful however, to
+ understand what actually happens when the binding is activated.
-(function() {
-/*globals ENV */
-/**
-@module ember
-@submodule ember-runtime
-*/
+ For a binding to function it must have at least a `from` property and a `to`
+ property. The `from` property path points to the object/key that you want to
+ bind from while the `to` path points to the object/key you want to bind to.
-var indexOf = Ember.EnumerableUtils.indexOf;
+ When you define a custom binding, you are usually describing the property
+ you want to bind from (such as `MyApp.someController.value` in the examples
+ above). When your object is created, it will automatically assign the value
+ you want to bind `to` based on the name of your binding key. In the
+ examples above, during init, Ember objects will effectively call
+ something like this on your binding:
-// ........................................
-// TYPING & ARRAY MESSAGING
-//
+ ```javascript
+ binding = Ember.Binding.from(this.valueBinding).to("value");
+ ```
-var TYPE_MAP = {};
-var t = "Boolean Number String Function Array Date RegExp Object".split(" ");
-Ember.ArrayPolyfills.forEach.call(t, function(name) {
- TYPE_MAP[ "[object " + name + "]" ] = name.toLowerCase();
-});
+ This creates a new binding instance based on the template you provide, and
+ sets the to path to the `value` property of the new object. Now that the
+ binding is fully configured with a `from` and a `to`, it simply needs to be
+ connected to become active. This is done through the `connect()` method:
-var toString = Object.prototype.toString;
+ ```javascript
+ binding.connect(this);
+ ```
-/**
- Returns a consistent type for the passed item.
+ Note that when you connect a binding you pass the object you want it to be
+ connected to. This object will be used as the root for both the from and
+ to side of the binding when inspecting relative paths. This allows the
+ binding to be automatically inherited by subclassed objects as well.
- 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:
+ Now that the binding is connected, it will observe both the from and to side
+ and relay changes.
- | Return Value | Meaning |
- |---------------|------------------------------------------------------|
- | 'string' | String primitive |
- | 'number' | Number primitive |
- | 'boolean' | Boolean primitive |
- | 'null' | Null value |
- | 'undefined' | Undefined value |
- | 'function' | A function |
- | 'array' | An instance of Array |
- | 'class' | A Ember class (created using Ember.Object.extend()) |
- | 'instance' | A Ember object instance |
- | 'error' | An instance of the Error object |
- | 'object' | A JavaScript object not inheriting from Ember.Object |
+ If you ever needed to do so (you almost never will, but it is useful to
+ understand this anyway), you could manually create an active binding by
+ using the `Ember.bind()` helper method. (This is the same method used by
+ to setup your bindings on objects):
- Examples:
+ ```javascript
+ Ember.bind(MyApp.anotherObject, "value", "MyApp.someController.value");
+ ```
- Ember.typeOf(); => 'undefined'
- Ember.typeOf(null); => 'null'
- Ember.typeOf(undefined); => 'undefined'
- Ember.typeOf('michael'); => 'string'
- Ember.typeOf(101); => 'number'
- Ember.typeOf(true); => 'boolean'
- Ember.typeOf(Ember.makeArray); => 'function'
- Ember.typeOf([1,2,90]); => 'array'
- Ember.typeOf(Ember.Object.extend()); => 'class'
- Ember.typeOf(Ember.Object.create()); => 'instance'
- Ember.typeOf(new Error('teamocil')); => 'error'
-
- // "normal" JavaScript object
- Ember.typeOf({a: 'b'}); => 'object'
+ Both of these code fragments have the same effect as doing the most friendly
+ form of binding creation like so:
- @method typeOf
- @for Ember
- @param item {Object} the item to check
- @return {String} the type
-*/
-Ember.typeOf = function(item) {
- var ret;
+ ```javascript
+ MyApp.anotherObject = Ember.Object.create({
+ valueBinding: "MyApp.someController.value",
- ret = (item === null || item === undefined) ? String(item) : TYPE_MAP[toString.call(item)] || 'object';
+ // OTHER CODE FOR THIS OBJECT...
+ });
+ ```
- if (ret === 'function') {
- if (Ember.Object && Ember.Object.detect(item)) ret = 'class';
- } else if (ret === 'object') {
- if (item instanceof Error) ret = 'error';
- else if (Ember.Object && item instanceof Ember.Object) ret = 'instance';
- else ret = 'object';
- }
+ Ember's built in binding creation method makes it easy to automatically
+ create bindings for you. You should always use the highest-level APIs
+ available, even if you understand how it works underneath.
- return ret;
-};
+ @class Binding
+ @namespace Ember
+ @since Ember 0.9
+*/
+Ember.Binding = Binding;
-/**
- Returns true if the passed value is null or undefined. This avoids errors
- from JSLint complaining about use of ==, which can be technically
- confusing.
- Ember.none(); => true
- Ember.none(null); => true
- Ember.none(undefined); => true
- Ember.none(''); => false
- Ember.none([]); => false
- Ember.none(function(){}); => false
+/**
+ 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.
- @method none
+ @method bind
@for Ember
- @param {Object} obj Value to test
- @return {Boolean}
+ @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.none = function(obj) {
- return obj === null || obj === undefined;
+Ember.bind = function(obj, to, from) {
+ return new Ember.Binding(to, from).connect(obj);
};
/**
- Verifies that a value is null or an empty string | array | function.
-
- Constrains the rules on `Ember.none` by returning false for empty
- string and empty arrays.
-
- Ember.empty(); => true
- Ember.empty(null); => true
- Ember.empty(undefined); => true
- Ember.empty(''); => true
- Ember.empty([]); => true
- Ember.empty('tobias fünke'); => false
- Ember.empty([0,1,2]); => false
-
- @method empty
+ @method oneWay
@for Ember
- @param {Object} obj Value to test
- @return {Boolean}
+ @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.empty = function(obj) {
- return obj === null || obj === undefined || (obj.length === 0 && typeof obj !== 'function') || (typeof obj === 'object' && Ember.get(obj, 'length') === 0);
+Ember.oneWay = function(obj, to, from) {
+ return new Ember.Binding(to, from).oneWay().connect(obj);
};
+})();
+
+
+
+(function() {
/**
- This will compare two javascript values of possibly different types.
- It will tell you which one is greater than the other by returning:
+@module ember-metal
+*/
- - -1 if the first is smaller than the second,
- - 0 if both are equal,
- - 1 if the first is greater than the second.
+var Mixin, REQUIRED, Alias,
+ a_map = Ember.ArrayPolyfills.map,
+ a_indexOf = Ember.ArrayPolyfills.indexOf,
+ a_forEach = Ember.ArrayPolyfills.forEach,
+ a_slice = [].slice,
+ EMPTY_META = {}, // dummy for non-writable meta
+ o_create = Ember.create,
+ defineProperty = Ember.defineProperty,
+ guidFor = Ember.guidFor;
- The order is calculated based on Ember.ORDER_DEFINITION, if types are different.
- In case they have the same type an appropriate comparison for this type is made.
+function mixinsMeta(obj) {
+ var m = Ember.meta(obj, true), ret = m.mixins;
+ if (!ret) {
+ ret = m.mixins = {};
+ } else if (!m.hasOwnProperty('mixins')) {
+ ret = m.mixins = o_create(ret);
+ }
+ return ret;
+}
- Ember.compare('hello', 'hello'); => 0
- Ember.compare('abc', 'dfg'); => -1
- Ember.compare(2, 1); => 1
+function initMixin(mixin, args) {
+ if (args && args.length > 0) {
+ mixin.mixins = a_map.call(args, function(x) {
+ if (x instanceof Mixin) { return x; }
- @method compare
- @for Ember
- @param {Object} v First value to compare
- @param {Object} w Second value to compare
- @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; }
+ // Note: Manually setup a primitive mixin here. This is the only
+ // way to actually get a primitive mixin. This way normal creation
+ // of mixins will give you combined mixins...
+ var mixin = new Mixin();
+ mixin.properties = x;
+ return mixin;
+ });
+ }
+ return mixin;
+}
- var type1 = Ember.typeOf(v);
- var type2 = Ember.typeOf(w);
+function isMethod(obj) {
+ return 'function' === typeof obj &&
+ obj.isMethod !== false &&
+ obj !== Boolean && obj !== Object && obj !== Number && obj !== Array && obj !== Date && obj !== String;
+}
- var Comparable = Ember.Comparable;
- if (Comparable) {
- if (type1==='instance' && Comparable.detect(v.constructor)) {
- return v.constructor.compare(v, w);
- }
+var CONTINUE = {};
- if (type2 === 'instance' && Comparable.detect(w.constructor)) {
- return 1-w.constructor.compare(w, v);
- }
+function mixinProperties(mixinsMeta, mixin) {
+ var guid;
+
+ if (mixin instanceof Mixin) {
+ guid = guidFor(mixin);
+ if (mixinsMeta[guid]) { return CONTINUE; }
+ mixinsMeta[guid] = mixin;
+ return mixin.properties;
+ } else {
+ return mixin; // apply anonymous mixin properties
}
+}
- // If we haven't yet generated a reverse-mapping of Ember.ORDER_DEFINITION,
- // do so now.
- var mapping = Ember.ORDER_DEFINITION_MAPPING;
- if (!mapping) {
- var order = Ember.ORDER_DEFINITION;
- mapping = Ember.ORDER_DEFINITION_MAPPING = {};
- var idx, len;
- for (idx = 0, len = order.length; idx < len; ++idx) {
- mapping[order[idx]] = idx;
- }
+function concatenatedProperties(props, values, base) {
+ var concats;
- // We no longer need Ember.ORDER_DEFINITION.
- delete Ember.ORDER_DEFINITION;
+ // reset before adding each new mixin to pickup concats from previous
+ concats = values.concatenatedProperties || base.concatenatedProperties;
+ if (props.concatenatedProperties) {
+ concats = concats ? concats.concat(props.concatenatedProperties) : props.concatenatedProperties;
}
- var type1Index = mapping[type1];
- var type2Index = mapping[type2];
+ return concats;
+}
- if (type1Index < type2Index) { return -1; }
- if (type1Index > type2Index) { return 1; }
+function giveDescriptorSuper(meta, key, property, values, descs) {
+ var superProperty;
- // types are equal - so we have to check values now
- switch (type1) {
- case 'boolean':
- case 'number':
- if (v < w) { return -1; }
- if (v > w) { return 1; }
- return 0;
+ // Computed properties override methods, and do not call super to them
+ if (values[key] === undefined) {
+ // Find the original descriptor in a parent mixin
+ superProperty = descs[key];
+ }
- case 'string':
- var comp = v.localeCompare(w);
- if (comp < 0) { return -1; }
- if (comp > 0) { return 1; }
- return 0;
+ // If we didn't find the original descriptor in a parent mixin, find
+ // it on the original object.
+ superProperty = superProperty || meta.descs[key];
- case 'array':
- var vLen = v.length;
- var wLen = w.length;
- var l = Math.min(vLen, wLen);
- var r = 0;
- var i = 0;
- while (r === 0 && i < l) {
- r = compare(v[i],w[i]);
- i++;
- }
- if (r !== 0) { return r; }
+ if (!superProperty || !(superProperty instanceof Ember.ComputedProperty)) {
+ return property;
+ }
- // all elements are equal now
- // shorter array should be ordered first
- if (vLen < wLen) { return -1; }
- if (vLen > wLen) { return 1; }
- // arrays are equal now
- return 0;
+ // Since multiple mixins may inherit from the same parent, we need
+ // to clone the computed property so that other mixins do not receive
+ // the wrapped version.
+ property = o_create(property);
+ property.func = Ember.wrap(property.func, superProperty.func);
- case 'instance':
- if (Ember.Comparable && Ember.Comparable.detect(v)) {
- return v.compare(v, w);
- }
- return 0;
+ return property;
+}
- case 'date':
- var vNum = v.getTime();
- var wNum = w.getTime();
- if (vNum < wNum) { return -1; }
- if (vNum > wNum) { return 1; }
- return 0;
+function giveMethodSuper(obj, key, method, values, descs) {
+ var superMethod;
- default:
- return 0;
+ // Methods overwrite computed properties, and do not call super to them.
+ if (descs[key] === undefined) {
+ // Find the original method in a parent mixin
+ superMethod = values[key];
}
-};
-function _copy(obj, deep, seen, copies) {
- var ret, loc, key;
+ // If we didn't find the original value in a parent mixin, find it in
+ // the original object
+ superMethod = superMethod || obj[key];
- // primitive data types are immutable, just return them.
- if ('object' !== typeof obj || obj===null) return obj;
+ // Only wrap the new method if the original method was a function
+ if ('function' !== typeof superMethod) {
+ return method;
+ }
- // avoid cyclical loops
- if (deep && (loc=indexOf(seen, obj))>=0) return copies[loc];
+ return Ember.wrap(method, superMethod);
+}
- Ember.assert('Cannot clone an Ember.Object that does not implement Ember.Copyable', !(obj instanceof Ember.Object) || (Ember.Copyable && Ember.Copyable.detect(obj)));
+function applyConcatenatedProperties(obj, key, value, values) {
+ var baseValue = values[key] || obj[key];
- // IMPORTANT: this specific test will detect a native array only. Any other
- // object will need to implement Copyable.
- if (Ember.typeOf(obj) === 'array') {
- ret = obj.slice();
- if (deep) {
- loc = ret.length;
- while(--loc>=0) ret[loc] = _copy(ret[loc], deep, seen, copies);
+ if (baseValue) {
+ if ('function' === typeof baseValue.concat) {
+ return baseValue.concat(value);
+ } else {
+ return Ember.makeArray(baseValue).concat(value);
}
- } else if (Ember.Copyable && Ember.Copyable.detect(obj)) {
- ret = obj.copy(deep, seen, copies);
} else {
- ret = {};
- for(key in obj) {
- if (!obj.hasOwnProperty(key)) continue;
- ret[key] = deep ? _copy(obj[key], deep, seen, copies) : obj[key];
+ return Ember.makeArray(value);
+ }
+}
+
+function addNormalizedProperty(base, key, value, meta, descs, values, concats) {
+ if (value instanceof Ember.Descriptor) {
+ if (value === REQUIRED && descs[key]) { return CONTINUE; }
+
+ // Wrap descriptor function to implement
+ // _super() if needed
+ if (value.func) {
+ value = giveDescriptorSuper(meta, key, value, values, descs);
+ }
+
+ descs[key] = value;
+ values[key] = undefined;
+ } else {
+ // impl super if needed...
+ if (isMethod(value)) {
+ value = giveMethodSuper(base, key, value, values, descs);
+ } else if ((concats && a_indexOf.call(concats, key) >= 0) || key === 'concatenatedProperties') {
+ value = applyConcatenatedProperties(base, key, value, values);
}
+
+ descs[key] = undefined;
+ values[key] = value;
}
+}
- if (deep) {
- seen.push(obj);
- copies.push(ret);
+function mergeMixins(mixins, m, descs, values, base) {
+ var mixin, props, key, concats, meta;
+
+ function removeKeys(keyName) {
+ delete descs[keyName];
+ delete values[keyName];
}
- return ret;
-}
+ for(var i=0, l=mixins.length; i<l; i++) {
+ mixin = mixins[i];
+ Ember.assert('Expected hash or Mixin instance, got ' + Object.prototype.toString.call(mixin), typeof mixin === 'object' && mixin !== null && Object.prototype.toString.call(mixin) !== '[object Array]');
-/**
- Creates a clone of the passed object. This function can take just about
- any type of object and create a clone of it, including primitive values
- (which are not actually cloned because they are immutable).
+ props = mixinProperties(m, mixin);
+ if (props === CONTINUE) { continue; }
- If the passed object implements the clone() method, then this function
- will simply call that method and return the result.
+ if (props) {
+ meta = Ember.meta(base);
+ concats = concatenatedProperties(props, values, base);
- @method copy
- @for Ember
- @param {Object} object The object to clone
- @param {Boolean} deep If true, a deep copy of the object is made
- @return {Object} The cloned object
-*/
-Ember.copy = function(obj, deep) {
- // fast paths
- if ('object' !== typeof obj || obj===null) return obj; // can't copy primitives
- if (Ember.Copyable && Ember.Copyable.detect(obj)) return obj.copy(deep);
- return _copy(obj, deep, deep ? [] : null, deep ? [] : null);
-};
+ for (key in props) {
+ if (!props.hasOwnProperty(key)) { continue; }
+ addNormalizedProperty(base, key, props[key], meta, descs, values, concats);
+ }
-/**
- Convenience method to inspect an object. This method will attempt to
- convert the object into a useful string description.
+ // manually copy toString() because some JS engines do not enumerate it
+ if (props.hasOwnProperty('toString')) { base.toString = props.toString; }
+ } else if (mixin.mixins) {
+ mergeMixins(mixin.mixins, m, descs, values, base);
+ if (mixin._without) { a_forEach.call(mixin._without, removeKeys); }
+ }
+ }
+}
- @method inspect
- @for Ember
- @param {Object} obj The object you want to inspect.
- @return {String} A description of the object
-*/
-Ember.inspect = function(obj) {
- var v, ret = [];
- for(var key in obj) {
- if (obj.hasOwnProperty(key)) {
- v = obj[key];
- if (v === 'toString') { continue; } // ignore useless items
- if (Ember.typeOf(v) === 'function') { v = "function() { ... }"; }
- ret.push(key + ": " + v);
+function writableReq(obj) {
+ var m = Ember.meta(obj), req = m.required;
+ if (!req || !m.hasOwnProperty('required')) {
+ req = m.required = req ? o_create(req) : {};
+ }
+ return req;
+}
+
+var IS_BINDING = Ember.IS_BINDING = /^.+Binding$/;
+
+function detectBinding(obj, key, value, m) {
+ if (IS_BINDING.test(key)) {
+ var bindings = m.bindings;
+ if (!bindings) {
+ bindings = m.bindings = {};
+ } else if (!m.hasOwnProperty('bindings')) {
+ bindings = m.bindings = o_create(m.bindings);
}
+ bindings[key] = value;
}
- return "{" + ret.join(" , ") + "}";
-};
+}
-/**
- Compares two objects, returning true if they are logically equal. This is
- a deeper comparison than a simple triple equal. For sets it will compare the
- internal objects. For any other object that implements `isEqual()` it will
- respect that method.
+function connectBindings(obj, m) {
+ // TODO Mixin.apply(instance) should disconnect binding if exists
+ var bindings = m.bindings, key, binding, to;
+ if (bindings) {
+ for (key in bindings) {
+ binding = bindings[key];
+ if (binding) {
+ to = key.slice(0, -7); // strip Binding off end
+ if (binding instanceof Ember.Binding) {
+ binding = binding.copy(); // copy prototypes' instance
+ binding.to(to);
+ } else { // binding is string path
+ binding = new Ember.Binding(to, binding);
+ }
+ binding.connect(obj);
+ obj[key] = binding;
+ }
+ }
+ // mark as applied
+ m.bindings = {};
+ }
+}
- Ember.isEqual('hello', 'hello'); => true
- Ember.isEqual(1, 2); => false
- Ember.isEqual([4,2], [4,2]); => false
+function finishPartial(obj, m) {
+ connectBindings(obj, m || Ember.meta(obj));
+ return obj;
+}
- @method isEqual
- @for Ember
- @param {Object} a first object to compare
- @param {Object} b second object to compare
- @return {Boolean}
-*/
-Ember.isEqual = function(a, b) {
- if (a && 'function'===typeof a.isEqual) return a.isEqual(b);
- return a === b;
-};
+function followAlias(obj, desc, m, descs, values) {
+ var altKey = desc.methodName, value;
+ if (descs[altKey] || values[altKey]) {
+ value = values[altKey];
+ desc = descs[altKey];
+ } else if (m.descs[altKey]) {
+ desc = m.descs[altKey];
+ value = undefined;
+ } else {
+ desc = undefined;
+ value = obj[altKey];
+ }
-// Used by Ember.compare
-Ember.ORDER_DEFINITION = Ember.ENV.ORDER_DEFINITION || [
- 'undefined',
- 'null',
- 'boolean',
- 'number',
- 'string',
- 'array',
- 'object',
- 'instance',
- 'function',
- 'class',
- 'date'
-];
+ return { desc: desc, value: value };
+}
-/**
- Returns all of the keys defined on an object or hash. This is useful
- when inspecting objects for debugging. On browsers that support it, this
- uses the native Object.keys implementation.
+function updateObservers(obj, key, observer, observerKey, method) {
+ if ('function' !== typeof observer) { return; }
- @method keys
- @for Ember
- @param {Object} obj
- @return {Array} Array containing keys of obj
-*/
-Ember.keys = Object.keys;
+ var paths = observer[observerKey];
-if (!Ember.keys) {
- Ember.keys = function(obj) {
- var ret = [];
- for(var key in obj) {
- if (obj.hasOwnProperty(key)) { ret.push(key); }
+ if (paths) {
+ for (var i=0, l=paths.length; i<l; i++) {
+ Ember[method](obj, paths[i], null, key);
}
- return ret;
- };
+ }
}
-// ..........................................................
-// ERROR
-//
+function replaceObservers(obj, key, observer) {
+ var prevObserver = obj[key];
-var errorProps = ['description', 'fileName', 'lineNumber', 'message', 'name', 'number', 'stack'];
+ updateObservers(obj, key, prevObserver, '__ember_observesBefore__', 'removeBeforeObserver');
+ updateObservers(obj, key, prevObserver, '__ember_observes__', 'removeObserver');
-/**
- A subclass of the JavaScript Error object for use in Ember.
+ updateObservers(obj, key, observer, '__ember_observesBefore__', 'addBeforeObserver');
+ updateObservers(obj, key, observer, '__ember_observes__', 'addObserver');
+}
- @class Error
- @namespace Ember
- @extends Error
- @constructor
-*/
-Ember.Error = function() {
- var tmp = Error.prototype.constructor.apply(this, arguments);
+function applyMixin(obj, mixins, partial) {
+ var descs = {}, values = {}, m = Ember.meta(obj),
+ key, value, desc;
+
+ // Go through all mixins and hashes passed in, and:
+ //
+ // * Handle concatenated properties
+ // * Set up _super wrapping if necessary
+ // * Set up computed property descriptors
+ // * Copying `toString` in broken browsers
+ mergeMixins(mixins, mixinsMeta(obj), descs, values, obj);
+
+ for(key in values) {
+ if (key === 'contructor' || !values.hasOwnProperty(key)) { continue; }
+
+ desc = descs[key];
+ value = values[key];
+
+ if (desc === REQUIRED) { continue; }
+
+ while (desc && desc instanceof Alias) {
+ var followed = followAlias(obj, desc, m, descs, values);
+ desc = followed.desc;
+ value = followed.value;
+ }
+
+ if (desc === undefined && value === undefined) { continue; }
+
+ replaceObservers(obj, key, value);
+ detectBinding(obj, key, value, m);
+ defineProperty(obj, key, desc, value, m);
+ }
+
+ if (!partial) { // don't apply to prototype
+ finishPartial(obj, m);
+ }
+
+ 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);
+ return obj;
+};
+
+/**
+ The `Ember.Mixin` class allows you to create mixins, whose properties can be
+ added to other classes. For instance,
+
+ ```javascript
+ App.Editable = Ember.Mixin.create({
+ edit: function() {
+ console.log('starting to edit');
+ this.set('isEditing', true);
+ },
+ isEditing: false
+ });
+
+ // Mix mixins into classes by passing them as the first arguments to
+ // .extend or .create.
+ App.CommentView = Ember.View.extend(App.Editable, {
+ template: Ember.Handlebars.compile('{{#if isEditing}}...{{else}}...{{/if}}')
+ });
+
+ commentView = App.CommentView.create();
+ commentView.edit(); // outputs 'starting to edit'
+ ```
+
+ Note that Mixins are created with `Ember.Mixin.create`, not
+ `Ember.Mixin.extend`.
+
+ @class Mixin
+ @namespace Ember
+*/
+Ember.Mixin = function() { return initMixin(this, arguments); };
+
+Mixin = Ember.Mixin;
+
+Mixin._apply = applyMixin;
+
+Mixin.applyPartial = function(obj) {
+ var args = a_slice.call(arguments, 1);
+ return applyMixin(obj, args, true);
+};
+
+Mixin.finishPartial = finishPartial;
+
+Ember.anyUnprocessedMixins = false;
+
+/**
+ @method create
+ @static
+ @param arguments*
+*/
+Mixin.create = function() {
+ Ember.anyUnprocessedMixins = true;
+ var M = this;
+ return initMixin(new M(), arguments);
+};
+
+var MixinPrototype = Mixin.prototype;
+
+/**
+ @method reopen
+ @param arguments*
+*/
+MixinPrototype.reopen = function() {
+ var mixin, tmp;
+
+ if (this.properties) {
+ mixin = Mixin.create();
+ mixin.properties = this.properties;
+ delete this.properties;
+ this.mixins = [mixin];
+ } else if (!this.mixins) {
+ this.mixins = [];
+ }
+
+ var len = arguments.length, mixins = this.mixins, idx;
+
+ for(idx=0; idx < len; idx++) {
+ mixin = arguments[idx];
+ Ember.assert('Expected hash or Mixin instance, got ' + Object.prototype.toString.call(mixin), typeof mixin === 'object' && mixin !== null && Object.prototype.toString.call(mixin) !== '[object Array]');
+
+ if (mixin instanceof Mixin) {
+ mixins.push(mixin);
+ } else {
+ tmp = Mixin.create();
+ tmp.properties = mixin;
+ mixins.push(tmp);
+ }
+ }
+
+ return this;
+};
+
+/**
+ @method apply
+ @param obj
+ @return applied object
+*/
+MixinPrototype.apply = function(obj) {
+ return applyMixin(obj, [this], false);
+};
+
+MixinPrototype.applyPartial = function(obj) {
+ return applyMixin(obj, [this], true);
+};
+
+function _detect(curMixin, targetMixin, seen) {
+ var guid = guidFor(curMixin);
+
+ if (seen[guid]) { return false; }
+ seen[guid] = true;
+
+ if (curMixin === targetMixin) { return true; }
+ var mixins = curMixin.mixins, loc = mixins ? mixins.length : 0;
+ while (--loc >= 0) {
+ if (_detect(mixins[loc], targetMixin, seen)) { return true; }
+ }
+ return false;
+}
+
+/**
+ @method detect
+ @param obj
+ @return {Boolean}
+*/
+MixinPrototype.detect = function(obj) {
+ if (!obj) { return false; }
+ if (obj instanceof Mixin) { return _detect(obj, this, {}); }
+ var mixins = Ember.meta(obj, false).mixins;
+ if (mixins) {
+ return !!mixins[guidFor(this)];
+ }
+ return false;
+};
+
+MixinPrototype.without = function() {
+ var ret = new Mixin(this);
+ ret._without = a_slice.call(arguments);
+ return ret;
+};
+
+function _keys(ret, mixin, seen) {
+ if (seen[guidFor(mixin)]) { return; }
+ seen[guidFor(mixin)] = true;
+
+ if (mixin.properties) {
+ var props = mixin.properties;
+ for (var key in props) {
+ if (props.hasOwnProperty(key)) { ret[key] = true; }
+ }
+ } else if (mixin.mixins) {
+ a_forEach.call(mixin.mixins, function(x) { _keys(ret, x, seen); });
+ }
+}
+
+MixinPrototype.keys = function() {
+ var keys = {}, seen = {}, ret = [];
+ _keys(keys, this, seen);
+ for(var key in keys) {
+ if (keys.hasOwnProperty(key)) { ret.push(key); }
+ }
+ return ret;
+};
+
+// returns the mixins currently applied to the specified object
+// TODO: Make Ember.mixin
+Mixin.mixins = function(obj) {
+ var mixins = Ember.meta(obj, false).mixins, ret = [];
+
+ if (!mixins) { return ret; }
+
+ for (var key in mixins) {
+ var mixin = mixins[key];
+
+ // skip primitive mixins since these are always anonymous
+ if (!mixin.properties) { ret.push(mixin); }
+ }
+
+ return ret;
+};
+
+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;
+};
+
+Alias = function(methodName) {
+ this.methodName = methodName;
+};
+Alias.prototype = new Ember.Descriptor();
+
+/**
+ Makes a property or method available via an additional name.
+
+ ```javascript
+ App.PaintSample = Ember.Object.extend({
+ color: 'red',
+ colour: Ember.alias('color'),
+ name: function(){
+ return "Zed";
+ },
+ moniker: Ember.alias("name")
+ });
+
+ var paintSample = App.PaintSample.create()
+ paintSample.get('colour'); // 'red'
+ paintSample.moniker(); // 'Zed'
+ ```
+
+ @method alias
+ @for Ember
+ @param {String} methodName name of the method or property to alias
+ @return {Ember.Descriptor}
+ @deprecated Use `Ember.aliasMethod` or `Ember.computed.alias` instead
+*/
+Ember.alias = function(methodName) {
+ return new Alias(methodName);
+};
+
+Ember.deprecateFunc("Ember.alias is deprecated. Please use Ember.aliasMethod or Ember.computed.alias instead.", Ember.alias);
+
+/**
+ Makes a method available via an additional name.
+
+ ```javascript
+ App.Person = Ember.Object.extend({
+ name: function(){
+ return 'Tomhuda Katzdale';
+ },
+ moniker: Ember.aliasMethod('name')
+ });
+
+ var goodGuy = App.Person.create()
+ ```
+
+ @method aliasMethod
+ @for Ember
+ @param {String} methodName name of the method to alias
+ @return {Ember.Descriptor}
+*/
+Ember.aliasMethod = function(methodName) {
+ return new Alias(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;
+ return 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];
+ Ember.assert("Immediate observers must observe internal properties only, not properties on other objects.", typeof arg !== "string" || arg.indexOf('.') === -1);
+ }
+
+ 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;
+ return func;
+};
+
+})();
+
+
+
+(function() {
+/**
+Ember Metal
+
+@module ember
+@submodule ember-metal
+*/
+
+})();
+
+(function() {
+define("rsvp",
+ [],
+ function() {
+ "use strict";
+ var browserGlobal = (typeof window !== 'undefined') ? window : {};
+
+ var MutationObserver = browserGlobal.MutationObserver || browserGlobal.WebKitMutationObserver;
+ var RSVP, async;
+
+ if (typeof process !== 'undefined' &&
+ {}.toString.call(process) === '[object process]') {
+ async = function(callback, binding) {
+ process.nextTick(function() {
+ callback.call(binding);
+ });
+ };
+ } else if (MutationObserver) {
+ var queue = [];
+
+ var observer = new MutationObserver(function() {
+ var toProcess = queue.slice();
+ queue = [];
+
+ toProcess.forEach(function(tuple) {
+ var callback = tuple[0], binding = tuple[1];
+ callback.call(binding);
+ });
+ });
+
+ var element = document.createElement('div');
+ observer.observe(element, { attributes: true });
+
+ // Chrome Memory Leak: https://bugs.webkit.org/show_bug.cgi?id=93661
+ window.addEventListener('unload', function(){
+ observer.disconnect();
+ observer = null;
+ });
+
+ async = function(callback, binding) {
+ queue.push([callback, binding]);
+ element.setAttribute('drainQueue', 'drainQueue');
+ };
+ } else {
+ async = function(callback, binding) {
+ setTimeout(function() {
+ callback.call(binding);
+ }, 1);
+ };
+ }
+
+ var Event = function(type, options) {
+ this.type = type;
+
+ for (var option in options) {
+ if (!options.hasOwnProperty(option)) { continue; }
+
+ this[option] = options[option];
+ }
+ };
+
+ var indexOf = function(callbacks, callback) {
+ for (var i=0, l=callbacks.length; i<l; i++) {
+ if (callbacks[i][0] === callback) { return i; }
+ }
+
+ return -1;
+ };
+
+ var callbacksFor = function(object) {
+ var callbacks = object._promiseCallbacks;
+
+ if (!callbacks) {
+ callbacks = object._promiseCallbacks = {};
+ }
+
+ return callbacks;
+ };
+
+ var EventTarget = {
+ mixin: function(object) {
+ object.on = this.on;
+ object.off = this.off;
+ object.trigger = this.trigger;
+ return object;
+ },
+
+ on: function(eventNames, callback, binding) {
+ var allCallbacks = callbacksFor(this), callbacks, eventName;
+ eventNames = eventNames.split(/\s+/);
+ binding = binding || this;
+
+ while (eventName = eventNames.shift()) {
+ callbacks = allCallbacks[eventName];
+
+ if (!callbacks) {
+ callbacks = allCallbacks[eventName] = [];
+ }
+
+ if (indexOf(callbacks, callback) === -1) {
+ callbacks.push([callback, binding]);
+ }
+ }
+ },
+
+ off: function(eventNames, callback) {
+ var allCallbacks = callbacksFor(this), callbacks, eventName, index;
+ eventNames = eventNames.split(/\s+/);
+
+ while (eventName = eventNames.shift()) {
+ if (!callback) {
+ allCallbacks[eventName] = [];
+ continue;
+ }
+
+ callbacks = allCallbacks[eventName];
+
+ index = indexOf(callbacks, callback);
+
+ if (index !== -1) { callbacks.splice(index, 1); }
+ }
+ },
+
+ trigger: function(eventName, options) {
+ var allCallbacks = callbacksFor(this),
+ callbacks, callbackTuple, callback, binding, event;
+
+ if (callbacks = allCallbacks[eventName]) {
+ for (var i=0, l=callbacks.length; i<l; i++) {
+ callbackTuple = callbacks[i];
+ callback = callbackTuple[0];
+ binding = callbackTuple[1];
+
+ if (typeof options !== 'object') {
+ options = { detail: options };
+ }
+
+ event = new Event(eventName, options);
+ callback.call(binding, event);
+ }
+ }
+ }
+ };
+
+ var Promise = function() {
+ this.on('promise:resolved', function(event) {
+ this.trigger('success', { detail: event.detail });
+ }, this);
+
+ this.on('promise:failed', function(event) {
+ this.trigger('error', { detail: event.detail });
+ }, this);
+ };
+
+ var noop = function() {};
+
+ var invokeCallback = function(type, promise, callback, event) {
+ var hasCallback = typeof callback === 'function',
+ value, error, succeeded, failed;
+
+ if (hasCallback) {
+ try {
+ value = callback(event.detail);
+ succeeded = true;
+ } catch(e) {
+ failed = true;
+ error = e;
+ }
+ } else {
+ value = event.detail;
+ succeeded = true;
+ }
+
+ if (value && typeof value.then === 'function') {
+ value.then(function(value) {
+ promise.resolve(value);
+ }, function(error) {
+ promise.reject(error);
+ });
+ } else if (hasCallback && succeeded) {
+ promise.resolve(value);
+ } else if (failed) {
+ promise.reject(error);
+ } else {
+ promise[type](value);
+ }
+ };
+
+ Promise.prototype = {
+ then: function(done, fail) {
+ var thenPromise = new Promise();
+
+ if (this.isResolved) {
+ RSVP.async(function() {
+ invokeCallback('resolve', thenPromise, done, { detail: this.resolvedValue });
+ }, this);
+ }
+
+ if (this.isRejected) {
+ RSVP.async(function() {
+ invokeCallback('reject', thenPromise, fail, { detail: this.rejectedValue });
+ }, this);
+ }
+
+ this.on('promise:resolved', function(event) {
+ invokeCallback('resolve', thenPromise, done, event);
+ });
+
+ this.on('promise:failed', function(event) {
+ invokeCallback('reject', thenPromise, fail, event);
+ });
+
+ return thenPromise;
+ },
+
+ resolve: function(value) {
+ resolve(this, value);
+
+ this.resolve = noop;
+ this.reject = noop;
+ },
+
+ reject: function(value) {
+ reject(this, value);
+
+ this.resolve = noop;
+ this.reject = noop;
+ }
+ };
+
+ function resolve(promise, value) {
+ RSVP.async(function() {
+ promise.trigger('promise:resolved', { detail: value });
+ promise.isResolved = true;
+ promise.resolvedValue = value;
+ });
+ }
+
+ function reject(promise, value) {
+ RSVP.async(function() {
+ promise.trigger('promise:failed', { detail: value });
+ promise.isRejected = true;
+ promise.rejectedValue = value;
+ });
+ }
+
+ EventTarget.mixin(Promise.prototype);
+
+ RSVP = { async: async, Promise: Promise, Event: Event, EventTarget: EventTarget };
+ return RSVP;
+ });
+
+})();
+
+(function() {
+define("container",
+ [],
+ function() {
+
+ var objectCreate = Object.create || function(parent) {
+ function F() {}
+ F.prototype = parent;
+ return new F();
+ };
+
+ function InheritingDict(parent) {
+ this.parent = parent;
+ this.dict = {};
+ }
+
+ InheritingDict.prototype = {
+ get: function(key) {
+ var dict = this.dict;
+
+ if (dict.hasOwnProperty(key)) {
+ return dict[key];
+ }
+
+ if (this.parent) {
+ return this.parent.get(key);
+ }
+ },
+
+ set: function(key, value) {
+ this.dict[key] = value;
+ },
+
+ has: function(key) {
+ var dict = this.dict;
+
+ if (dict.hasOwnProperty(key)) {
+ return true;
+ }
+
+ if (this.parent) {
+ return this.parent.has(key);
+ }
+
+ return false;
+ },
+
+ eachLocal: function(callback, binding) {
+ var dict = this.dict;
+
+ for (var prop in dict) {
+ if (dict.hasOwnProperty(prop)) {
+ callback.call(binding, prop, dict[prop]);
+ }
+ }
+ }
+ };
+
+ function Container(parent) {
+ this.parent = parent;
+ this.children = [];
+
+ this.resolver = parent && parent.resolver || function() {};
+ this.registry = new InheritingDict(parent && parent.registry);
+ this.cache = new InheritingDict(parent && parent.cache);
+ this.typeInjections = {};
+ this.injections = {};
+ this.options = {};
+ this.typeOptions = {};
+ }
+
+ Container.prototype = {
+ child: function() {
+ var container = new Container(this);
+ this.children.push(container);
+ return container;
+ },
+
+ set: function(object, key, value) {
+ object[key] = value;
+ },
+
+ register: function(type, name, factory, options) {
+ this.registry.set(type + ":" + name, factory);
+ this.options[type + ":" + name] = options || {};
+ },
+
+ resolve: function(fullName) {
+ return this.resolver(fullName) || this.registry.get(fullName);
+ },
+
+ lookup: function(fullName) {
+ if (this.cache.has(fullName)) {
+ return this.cache.get(fullName);
+ }
+
+ var value = instantiate(this, fullName);
+
+ if (!value) { return; }
+
+ if (isSingleton(this, fullName)) {
+ this.cache.set(fullName, value);
+ }
+
+ return value;
+ },
+
+ has: function(fullName) {
+ if (this.cache.has(fullName)) {
+ return true;
+ }
+
+ return !!factoryFor(this, fullName);
+ },
+
+ optionsForType: function(type, options) {
+ if (this.parent) { illegalChildOperation('optionsForType'); }
+
+ this.typeOptions[type] = options;
+ },
+
+ typeInjection: function(type, property, fullName) {
+ if (this.parent) { illegalChildOperation('typeInjection'); }
+
+ var injections = this.typeInjections[type] = this.typeInjections[type] || [];
+ injections.push({ property: property, fullName: fullName });
+ },
+
+ injection: function(factoryName, property, injectionName) {
+ if (this.parent) { illegalChildOperation('injection'); }
+
+ var injections = this.injections[factoryName] = this.injections[factoryName] || [];
+ injections.push({ property: property, fullName: injectionName });
+ },
+
+ destroy: function() {
+ this.isDestroyed = true;
+
+ for (var i=0, l=this.children.length; i<l; i++) {
+ this.children[i].destroy();
+ }
+
+ this.children = [];
+
+ eachDestroyable(this, function(item) {
+ item.isDestroying = true;
+ });
+
+ eachDestroyable(this, function(item) {
+ item.destroy();
+ });
+
+ delete this.parent;
+ this.isDestroyed = true;
+ },
+
+ reset: function() {
+ for (var i=0, l=this.children.length; i<l; i++) {
+ resetCache(this.children[i]);
+ }
+ resetCache(this);
+ }
+ };
+
+ function illegalChildOperation(operation) {
+ throw new Error(operation + " is not currently supported on child containers");
+ }
+
+ function isSingleton(container, fullName) {
+ var singleton = option(container, fullName, 'singleton');
+
+ return singleton !== false;
+ }
+
+ function buildInjections(container, injections) {
+ var hash = {};
+
+ if (!injections) { return hash; }
+
+ var injection, lookup;
+
+ for (var i=0, l=injections.length; i<l; i++) {
+ injection = injections[i];
+ lookup = container.lookup(injection.fullName);
+ hash[injection.property] = lookup;
+ }
+
+ return hash;
+ }
+
+ function option(container, fullName, optionName) {
+ var options = container.options[fullName];
+
+ if (options && options[optionName] !== undefined) {
+ return options[optionName];
+ }
+
+ var type = fullName.split(":")[0];
+ options = container.typeOptions[type];
+
+ if (options) {
+ return options[optionName];
+ }
+ }
+
+ function factoryFor(container, fullName) {
+ return container.resolve(fullName);
+ }
+
+ function instantiate(container, fullName) {
+ var factory = factoryFor(container, fullName);
+
+ var splitName = fullName.split(":"),
+ type = splitName[0], name = splitName[1],
+ value;
+
+ if (option(container, fullName, 'instantiate') === false) {
+ return factory;
+ }
+
+ if (factory) {
+ var injections = [];
+ injections = injections.concat(container.typeInjections[type] || []);
+ injections = injections.concat(container.injections[fullName] || []);
+
+ var hash = buildInjections(container, injections);
+ hash.container = container;
+
+ value = factory.create(hash);
+
+ return value;
+ }
+ }
+
+ function eachDestroyable(container, callback) {
+ container.cache.eachLocal(function(key, value) {
+ if (option(container, key, 'instantiate') === false) { return; }
+ callback(value);
+ });
+ }
+
+ function resetCache(container) {
+ container.cache.eachLocal(function(key, value) {
+ if (option(container, key, 'instantiate') === false) { return; }
+ value.destroy();
+ });
+ container.cache.dict = {};
+ }
+
+ return Container;
+});
+
+})();
+
+(function() {
+/*globals ENV */
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+var indexOf = Ember.EnumerableUtils.indexOf;
+
+// ........................................
+// TYPING & ARRAY MESSAGING
+//
+
+var TYPE_MAP = {};
+var t = "Boolean Number String Function Array Date RegExp Object".split(" ");
+Ember.ArrayPolyfills.forEach.call(t, function(name) {
+ TYPE_MAP[ "[object " + name + "]" ] = name.toLowerCase();
+});
+
+var toString = Object.prototype.toString;
+
+/**
+ Returns a consistent type for the passed 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:
+
+ | Return Value | Meaning |
+ |---------------|------------------------------------------------------|
+ | 'string' | String primitive |
+ | 'number' | Number primitive |
+ | 'boolean' | Boolean primitive |
+ | 'null' | Null value |
+ | 'undefined' | Undefined value |
+ | 'function' | A function |
+ | 'array' | An instance of Array |
+ | 'class' | A Ember class (created using Ember.Object.extend()) |
+ | 'instance' | A Ember object instance |
+ | 'error' | An instance of the Error object |
+ | 'object' | A JavaScript object not inheriting from Ember.Object |
+
+ Examples:
+
+ ```javascript
+ Ember.typeOf(); // 'undefined'
+ Ember.typeOf(null); // 'null'
+ Ember.typeOf(undefined); // 'undefined'
+ Ember.typeOf('michael'); // 'string'
+ Ember.typeOf(101); // 'number'
+ Ember.typeOf(true); // 'boolean'
+ Ember.typeOf(Ember.makeArray); // 'function'
+ Ember.typeOf([1,2,90]); // 'array'
+ Ember.typeOf(Ember.Object.extend()); // 'class'
+ Ember.typeOf(Ember.Object.create()); // 'instance'
+ Ember.typeOf(new Error('teamocil')); // 'error'
+
+ // "normal" JavaScript object
+ Ember.typeOf({a: 'b'}); // 'object'
+ ```
+
+ @method typeOf
+ @for Ember
+ @param item {Object} the item to check
+ @return {String} the type
+*/
+Ember.typeOf = function(item) {
+ var ret;
+
+ ret = (item === null || item === undefined) ? String(item) : TYPE_MAP[toString.call(item)] || 'object';
+
+ if (ret === 'function') {
+ if (Ember.Object && Ember.Object.detect(item)) ret = 'class';
+ } else if (ret === 'object') {
+ if (item instanceof Error) ret = 'error';
+ else if (Ember.Object && item instanceof Ember.Object) ret = 'instance';
+ else ret = 'object';
+ }
+
+ return ret;
+};
+
+/**
+ Returns true if the passed value is null or undefined. This avoids errors
+ from JSLint complaining about use of ==, which can be technically
+ confusing.
+
+ ```javascript
+ Ember.isNone(); // true
+ Ember.isNone(null); // true
+ Ember.isNone(undefined); // true
+ Ember.isNone(''); // false
+ Ember.isNone([]); // false
+ Ember.isNone(function(){}); // false
+ ```
+
+ @method isNone
+ @for Ember
+ @param {Object} obj Value to test
+ @return {Boolean}
+*/
+Ember.isNone = function(obj) {
+ return obj === null || obj === undefined;
+};
+Ember.none = Ember.deprecateFunc("Ember.none is deprecated. Please use Ember.isNone instead.", Ember.isNone);
+
+/**
+ Verifies that a value is `null` or an empty string, empty array,
+ or empty function.
+
+ Constrains the rules on `Ember.isNone` by returning false for empty
+ string and empty arrays.
+
+ ```javascript
+ Ember.isEmpty(); // true
+ Ember.isEmpty(null); // true
+ Ember.isEmpty(undefined); // true
+ Ember.isEmpty(''); // true
+ Ember.isEmpty([]); // true
+ Ember.isEmpty('Adam Hawkins'); // false
+ Ember.isEmpty([0,1,2]); // false
+ ```
+
+ @method isEmpty
+ @for Ember
+ @param {Object} obj Value to test
+ @return {Boolean}
+*/
+Ember.isEmpty = function(obj) {
+ return obj === null || obj === undefined || (obj.length === 0 && typeof obj !== 'function') || (typeof obj === 'object' && Ember.get(obj, 'length') === 0);
+};
+Ember.empty = Ember.deprecateFunc("Ember.empty is deprecated. Please use Ember.isEmpty instead.", Ember.isEmpty) ;
+
+/**
+ This will compare two javascript values of possibly different types.
+ It will tell you which one is greater than the other by returning:
+
+ - -1 if the first is smaller than the second,
+ - 0 if both are equal,
+ - 1 if the first is greater than the second.
+
+ The order is calculated based on `Ember.ORDER_DEFINITION`, if types are different.
+ In case they have the same type an appropriate comparison for this type is made.
+
+ ```javascript
+ Ember.compare('hello', 'hello'); // 0
+ Ember.compare('abc', 'dfg'); // -1
+ Ember.compare(2, 1); // 1
+ ```javascript
+
+ @method compare
+ @for Ember
+ @param {Object} v First value to compare
+ @param {Object} w Second value to compare
+ @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; }
+
+ var type1 = Ember.typeOf(v);
+ var type2 = Ember.typeOf(w);
+
+ var Comparable = Ember.Comparable;
+ if (Comparable) {
+ if (type1==='instance' && Comparable.detect(v.constructor)) {
+ return v.constructor.compare(v, w);
+ }
+
+ if (type2 === 'instance' && Comparable.detect(w.constructor)) {
+ return 1-w.constructor.compare(w, v);
+ }
+ }
+
+ // If we haven't yet generated a reverse-mapping of Ember.ORDER_DEFINITION,
+ // do so now.
+ var mapping = Ember.ORDER_DEFINITION_MAPPING;
+ if (!mapping) {
+ var order = Ember.ORDER_DEFINITION;
+ mapping = Ember.ORDER_DEFINITION_MAPPING = {};
+ var idx, len;
+ for (idx = 0, len = order.length; idx < len; ++idx) {
+ mapping[order[idx]] = idx;
+ }
+
+ // We no longer need Ember.ORDER_DEFINITION.
+ delete Ember.ORDER_DEFINITION;
+ }
+
+ var type1Index = mapping[type1];
+ var type2Index = mapping[type2];
+
+ if (type1Index < type2Index) { return -1; }
+ if (type1Index > type2Index) { return 1; }
+
+ // types are equal - so we have to check values now
+ switch (type1) {
+ case 'boolean':
+ case 'number':
+ if (v < w) { return -1; }
+ if (v > w) { return 1; }
+ return 0;
+
+ case 'string':
+ var comp = v.localeCompare(w);
+ if (comp < 0) { return -1; }
+ if (comp > 0) { return 1; }
+ return 0;
+
+ case 'array':
+ var vLen = v.length;
+ var wLen = w.length;
+ var l = Math.min(vLen, wLen);
+ var r = 0;
+ var i = 0;
+ while (r === 0 && i < l) {
+ r = compare(v[i],w[i]);
+ i++;
+ }
+ if (r !== 0) { return r; }
+
+ // all elements are equal now
+ // shorter array should be ordered first
+ if (vLen < wLen) { return -1; }
+ if (vLen > wLen) { return 1; }
+ // arrays are equal now
+ return 0;
+
+ case 'instance':
+ if (Ember.Comparable && Ember.Comparable.detect(v)) {
+ return v.compare(v, w);
+ }
+ return 0;
+
+ case 'date':
+ var vNum = v.getTime();
+ var wNum = w.getTime();
+ if (vNum < wNum) { return -1; }
+ if (vNum > wNum) { return 1; }
+ return 0;
+
+ default:
+ return 0;
+ }
+};
+
+function _copy(obj, deep, seen, copies) {
+ var ret, loc, key;
+
+ // primitive data types are immutable, just return them.
+ if ('object' !== typeof obj || obj===null) return obj;
+
+ // avoid cyclical loops
+ if (deep && (loc=indexOf(seen, obj))>=0) return copies[loc];
+
+ Ember.assert('Cannot clone an Ember.Object that does not implement Ember.Copyable', !(obj instanceof Ember.Object) || (Ember.Copyable && Ember.Copyable.detect(obj)));
+
+ // IMPORTANT: this specific test will detect a native array only. Any other
+ // object will need to implement Copyable.
+ if (Ember.typeOf(obj) === 'array') {
+ ret = obj.slice();
+ if (deep) {
+ loc = ret.length;
+ while(--loc>=0) ret[loc] = _copy(ret[loc], deep, seen, copies);
+ }
+ } else if (Ember.Copyable && Ember.Copyable.detect(obj)) {
+ ret = obj.copy(deep, seen, copies);
+ } else {
+ ret = {};
+ for(key in obj) {
+ if (!obj.hasOwnProperty(key)) continue;
+
+ // Prevents browsers that don't respect non-enumerability from
+ // copying internal Ember properties
+ if (key.substring(0,2) === '__') continue;
+
+ ret[key] = deep ? _copy(obj[key], deep, seen, copies) : obj[key];
+ }
+ }
+
+ if (deep) {
+ seen.push(obj);
+ copies.push(ret);
+ }
+
+ return ret;
+}
+
+/**
+ Creates a clone of the passed object. This function can take just about
+ any type of object and create a clone of it, including primitive values
+ (which are not actually cloned because they are immutable).
+
+ 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
+ @return {Object} The cloned object
+*/
+Ember.copy = function(obj, deep) {
+ // fast paths
+ if ('object' !== typeof obj || obj===null) return obj; // can't copy primitives
+ if (Ember.Copyable && Ember.Copyable.detect(obj)) return obj.copy(deep);
+ return _copy(obj, deep, deep ? [] : null, deep ? [] : null);
+};
+
+/**
+ Convenience method to inspect an object. This method will attempt to
+ convert the object into a useful string description.
+
+ It is a pretty simple implementation. If you want something more robust,
+ use something like JSDump: https://github.com/NV/jsDump
+
+ @method inspect
+ @for Ember
+ @param {Object} obj The object you want to inspect.
+ @return {String} A description of the object
+*/
+Ember.inspect = function(obj) {
+ if (typeof obj !== 'object' || obj === null) {
+ return obj + '';
+ }
+
+ var v, ret = [];
+ for(var key in obj) {
+ if (obj.hasOwnProperty(key)) {
+ v = obj[key];
+ if (v === 'toString') { continue; } // ignore useless items
+ if (Ember.typeOf(v) === 'function') { v = "function() { ... }"; }
+ ret.push(key + ": " + v);
+ }
+ }
+ return "{" + ret.join(", ") + "}";
+};
+
+/**
+ Compares two objects, returning true if they are logically equal. This is
+ a deeper comparison than a simple triple equal. For sets it will compare the
+ internal objects. For any other object that implements `isEqual()` it will
+ respect that method.
+
+ ```javascript
+ Ember.isEqual('hello', 'hello'); // true
+ Ember.isEqual(1, 2); // false
+ Ember.isEqual([4,2], [4,2]); // false
+ ```
+
+ @method isEqual
+ @for Ember
+ @param {Object} a first object to compare
+ @param {Object} b second object to compare
+ @return {Boolean}
+*/
+Ember.isEqual = function(a, b) {
+ if (a && 'function'===typeof a.isEqual) return a.isEqual(b);
+ return a === b;
+};
+
+// Used by Ember.compare
+Ember.ORDER_DEFINITION = Ember.ENV.ORDER_DEFINITION || [
+ 'undefined',
+ 'null',
+ 'boolean',
+ 'number',
+ 'string',
+ 'array',
+ 'object',
+ 'instance',
+ 'function',
+ 'class',
+ 'date'
+];
+
+/**
+ Returns all of the keys defined on an object or hash. This is useful
+ when inspecting objects for debugging. On browsers that support it, this
+ uses the native `Object.keys` implementation.
+
+ @method keys
+ @for Ember
+ @param {Object} obj
+ @return {Array} Array containing keys of obj
+*/
+Ember.keys = Object.keys;
+
+if (!Ember.keys) {
+ Ember.keys = function(obj) {
+ var ret = [];
+ for(var key in obj) {
+ if (obj.hasOwnProperty(key)) { ret.push(key); }
+ }
+ return ret;
+ };
+}
+
+// ..........................................................
+// ERROR
+//
+
+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);
+
+ // 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]];
+ }
+};
+
+Ember.Error.prototype = Ember.create(Error.prototype);
+
+})();
+
+
+
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+var STRING_DASHERIZE_REGEXP = (/[ _]/g);
+var STRING_DASHERIZE_CACHE = {};
+var STRING_DECAMELIZE_REGEXP = (/([a-z])([A-Z])/g);
+var STRING_CAMELIZE_REGEXP = (/(\-|_|\.|\s)+(.)?/g);
+var STRING_UNDERSCORE_REGEXP_1 = (/([a-z\d])([A-Z]+)/g);
+var STRING_UNDERSCORE_REGEXP_2 = (/\-|\s+/g);
+
+/**
+ Defines the hash of localized strings for the current language. Used by
+ the `Ember.String.loc()` helper. To localize, add string values to this
+ hash.
+
+ @property STRINGS
+ @for Ember
+ @type Hash
+*/
+Ember.STRINGS = {};
+
+/**
+ Defines string helper methods including string formatting and localization.
+ Unless `Ember.EXTEND_PROTOTYPES.String` is `false` these methods will also be
+ added to the `String.prototype` as well.
+
+ @class String
+ @namespace Ember
+ @static
+*/
+Ember.String = {
+
+ /**
+ Apply formatting options to the string. This will look for occurrences
+ of "%@" in your string and substitute them with the arguments you pass into
+ this method. If you want to control the specific order of replacement,
+ you can add a number after the key as well to indicate which argument
+ you want to insert.
+
+ Ordered insertions are most useful when building loc strings where values
+ you need to insert may appear in different orders.
+
+ ```javascript
+ "Hello %@ %@".fmt('John', 'Doe'); // "Hello John Doe"
+ "Hello %@2, %@1".fmt('John', 'Doe'); // "Hello Doe, John"
+ ```
+
+ @method fmt
+ @param {Object...} [args]
+ @return {String} formatted string
+ */
+ fmt: function(str, formats) {
+ // first, replace any ORDERED replacements.
+ var idx = 0; // the current index for non-numerical replacements
+ return str.replace(/%@([0-9]+)?/g, function(s, argIndex) {
+ argIndex = (argIndex) ? parseInt(argIndex,0) - 1 : idx++ ;
+ s = formats[argIndex];
+ return ((s === null) ? '(null)' : (s === undefined) ? '' : s).toString();
+ }) ;
+ },
+
+ /**
+ Formats the passed string, but first looks up the string in the localized
+ strings hash. This is a convenient way to localize text. See
+ `Ember.String.fmt()` for more information on formatting.
+
+ Note that it is traditional but not required to prefix localized string
+ keys with an underscore or other character so you can easily identify
+ localized strings.
+
+ ```javascript
+ Ember.STRINGS = {
+ '_Hello World': 'Bonjour le monde',
+ '_Hello %@ %@': 'Bonjour %@ %@'
+ };
+
+ Ember.String.loc("_Hello World"); // 'Bonjour le monde';
+ Ember.String.loc("_Hello %@ %@", ["John", "Smith"]); // "Bonjour John Smith";
+ ```
+
+ @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;
+ return Ember.String.fmt(str, formats) ;
+ },
+
+ /**
+ Splits a string into separate units separated by spaces, eliminating any
+ empty strings in the process. This is a convenience method for split that
+ is mostly useful when applied to the `String.prototype`.
+
+ ```javascript
+ Ember.String.w("alpha beta gamma").forEach(function(key) {
+ console.log(key);
+ });
+
+ // > alpha
+ // > beta
+ // > gamma
+ ```
+
+ @method w
+ @param {String} str The string to split
+ @return {String} split string
+ */
+ w: function(str) { return str.split(/\s+/); },
+
+ /**
+ Converts a camelized string into all lower case separated by underscores.
+
+ ```javascript
+ 'innerHTML'.decamelize(); // 'inner_html'
+ 'action_name'.decamelize(); // 'action_name'
+ 'css-class-name'.decamelize(); // 'css-class-name'
+ 'my favorite items'.decamelize(); // 'my favorite items'
+ ```
+
+ @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();
+ },
+
+ /**
+ Replaces underscores or spaces with dashes.
+
+ ```javascript
+ 'innerHTML'.dasherize(); // 'inner-html'
+ 'action_name'.dasherize(); // 'action-name'
+ 'css-class-name'.dasherize(); // 'css-class-name'
+ 'my favorite items'.dasherize(); // 'my-favorite-items'
+ ```
+
+ @method dasherize
+ @param {String} str The string to dasherize.
+ @return {String} the dasherized string.
+ */
+ dasherize: function(str) {
+ var cache = STRING_DASHERIZE_CACHE,
+ ret = cache[str];
+
+ if (ret) {
+ return ret;
+ } else {
+ ret = Ember.String.decamelize(str).replace(STRING_DASHERIZE_REGEXP,'-');
+ cache[str] = ret;
+ }
+
+ return ret;
+ },
+
+ /**
+ Returns the lowerCaseCamel form of a string.
+
+ ```javascript
+ 'innerHTML'.camelize(); // 'innerHTML'
+ 'action_name'.camelize(); // 'actionName'
+ 'css-class-name'.camelize(); // 'cssClassName'
+ 'my favorite items'.camelize(); // 'myFavoriteItems'
+ ```
+
+ @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) {
+ return chr ? chr.toUpperCase() : '';
+ });
+ },
+
+ /**
+ Returns the UpperCamelCase form of a string.
+
+ ```javascript
+ 'innerHTML'.classify(); // 'InnerHTML'
+ 'action_name'.classify(); // 'ActionName'
+ 'css-class-name'.classify(); // 'CssClassName'
+ 'my favorite items'.classify(); // 'MyFavoriteItems'
+ ```
+
+ @method classify
+ @param {String} str the string to classify
+ @return {String} the classified string
+ */
+ classify: function(str) {
+ var parts = str.split("."),
+ out = [];
+
+ for (var i=0, l=parts.length; i<l; i++) {
+ var camelized = Ember.String.camelize(parts[i]);
+ out.push(camelized.charAt(0).toUpperCase() + camelized.substr(1));
+ }
+
+ return out.join(".");
+ },
+
+ /**
+ More general than decamelize. Returns the lower\_case\_and\_underscored
+ form of a string.
+
+ ```javascript
+ 'innerHTML'.underscore(); // 'inner_html'
+ 'action_name'.underscore(); // 'action_name'
+ 'css-class-name'.underscore(); // 'css_class_name'
+ 'my favorite items'.underscore(); // 'my_favorite_items'
+ ```
+
+ @method 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').
+ replace(STRING_UNDERSCORE_REGEXP_2, '_').toLowerCase();
+ },
+
+ /**
+ Returns the Capitalized form of a string
+
+ 'innerHTML'.capitalize() => 'InnerHTML'
+ 'action_name'.capitalize() => 'Action_name'
+ 'css-class-name'.capitalize() => 'Css-class-name'
+ 'my favorite items'.capitalize() => 'My favorite items'
+
+ @method capitalize
+ @param {String} str
+ @return {String}
+ */
+ capitalize: function(str) {
+ return str.charAt(0).toUpperCase() + str.substr(1);
+ }
+
+};
+
+})();
+
+
+
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+
+
+var fmt = Ember.String.fmt,
+ w = Ember.String.w,
+ loc = Ember.String.loc,
+ camelize = Ember.String.camelize,
+ decamelize = Ember.String.decamelize,
+ dasherize = Ember.String.dasherize,
+ underscore = Ember.String.underscore,
+ capitalize = Ember.String.capitalize,
+ classify = Ember.String.classify;
+
+if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.String) {
+
+ /**
+ See {{#crossLink "Ember.String/fmt"}}{{/crossLink}}
+
+ @method fmt
+ @for String
+ */
+ String.prototype.fmt = function() {
+ return fmt(this, arguments);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/w"}}{{/crossLink}}
+
+ @method w
+ @for String
+ */
+ String.prototype.w = function() {
+ return w(this);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/loc"}}{{/crossLink}}
+
+ @method loc
+ @for String
+ */
+ String.prototype.loc = function() {
+ return loc(this, arguments);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/camelize"}}{{/crossLink}}
+
+ @method camelize
+ @for String
+ */
+ String.prototype.camelize = function() {
+ return camelize(this);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/decamelize"}}{{/crossLink}}
+
+ @method decamelize
+ @for String
+ */
+ String.prototype.decamelize = function() {
+ return decamelize(this);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/dasherize"}}{{/crossLink}}
+
+ @method dasherize
+ @for String
+ */
+ String.prototype.dasherize = function() {
+ return dasherize(this);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/underscore"}}{{/crossLink}}
+
+ @method underscore
+ @for String
+ */
+ String.prototype.underscore = function() {
+ return underscore(this);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/classify"}}{{/crossLink}}
+
+ @method classify
+ @for String
+ */
+ String.prototype.classify = function() {
+ return classify(this);
+ };
+
+ /**
+ See {{#crossLink "Ember.String/capitalize"}}{{/crossLink}}
+
+ @method capitalize
+ @for String
+ */
+ String.prototype.capitalize = function() {
+ return capitalize(this);
+ };
+
+}
+
+
+})();
+
+
+
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+var a_slice = Array.prototype.slice;
+
+if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.Function) {
+
+ /**
+ The `property` extension of Javascript's Function prototype is available
+ when `Ember.EXTEND_PROTOTYPES` or `Ember.EXTEND_PROTOTYPES.Function` is
+ `true`, which is the default.
+
+ Computed properties allow you to treat a function like a property:
+
+ ```javascript
+ MyApp.president = Ember.Object.create({
+ firstName: "Barack",
+ lastName: "Obama",
+
+ fullName: function() {
+ return this.get('firstName') + ' ' + this.get('lastName');
+
+ // Call this flag to mark the function as a property
+ }.property()
+ });
+
+ MyApp.president.get('fullName'); // "Barack Obama"
+ ```
+
+ Treating a function like a property is useful because they can work with
+ bindings, just like any other property.
+
+ Many computed properties have dependencies on other properties. For
+ example, in the above example, the `fullName` property depends on
+ `firstName` and `lastName` to determine its value. You can tell Ember
+ about these dependencies like this:
+
+ ```javascript
+ MyApp.president = Ember.Object.create({
+ firstName: "Barack",
+ lastName: "Obama",
+
+ fullName: function() {
+ return this.get('firstName') + ' ' + this.get('lastName');
+
+ // Tell Ember.js that this computed property depends on firstName
+ // and lastName
+ }.property('firstName', 'lastName')
+ });
+ ```
+
+ Make sure you list these dependencies so Ember knows when to update
+ bindings that connect to a computed property. Changing a dependency
+ will not immediately trigger an update of the computed property, but
+ will instead clear the cache so that it is updated when the next `get`
+ is called on the property.
+
+ See {{#crossLink "Ember.ComputedProperty"}}{{/crossLink}},
+ {{#crossLink "Ember/computed"}}{{/crossLink}}
+
+ @method property
+ @for Function
+ */
+ Function.prototype.property = function() {
+ var ret = Ember.computed(this);
+ return ret.property.apply(ret, arguments);
+ };
+
+ /**
+ The `observes` extension of Javascript's Function prototype is available
+ when `Ember.EXTEND_PROTOTYPES` or `Ember.EXTEND_PROTOTYPES.Function` 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.
+ For example:
+
+ ```javascript
+ Ember.Object.create({
+ valueObserver: function() {
+ // Executes whenever the "value" property changes
+ }.observes('value')
+ });
+ ```
+
+ See {{#crossLink "Ember.Observable/observes"}}{{/crossLink}}
+
+ @method observes
+ @for Function
+ */
+ Function.prototype.observes = function() {
+ this.__ember_observes__ = a_slice.call(arguments);
+ return this;
+ };
+
+ /**
+ The `observesBefore` extension of Javascript's Function prototype is
+ available when `Ember.EXTEND_PROTOTYPES` or
+ `Ember.EXTEND_PROTOTYPES.Function` 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
+ declarations in classes that you write. For example:
+
+ ```javascript
+ Ember.Object.create({
+ valueObserver: function() {
+ // Executes whenever the "value" property is about to change
+ }.observesBefore('value')
+ });
+ ```
+
+ See {{#crossLink "Ember.Observable/observesBefore"}}{{/crossLink}}
+
+ @method observesBefore
+ @for Function
+ */
+ Function.prototype.observesBefore = function() {
+ this.__ember_observesBefore__ = a_slice.call(arguments);
+ return this;
+ };
+
+}
+
+
+})();
+
+
+
+(function() {
+
+})();
+
+
+
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+// ..........................................................
+// HELPERS
+//
+
+var get = Ember.get, set = Ember.set;
+var a_slice = Array.prototype.slice;
+var a_indexOf = Ember.EnumerableUtils.indexOf;
+
+var contexts = [];
+
+function popCtx() {
+ return contexts.length===0 ? {} : contexts.pop();
+}
+
+function pushCtx(ctx) {
+ contexts.push(ctx);
+ return null;
+}
+
+function iter(key, value) {
+ var valueProvided = arguments.length === 2;
+
+ function i(item) {
+ var cur = get(item, key);
+ return valueProvided ? value===cur : !!cur;
+ }
+ return i ;
+}
+
+/**
+ 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
+ cannot be emulated in older versions of JavaScript).
+
+ This mixin is applied automatically to the Array class on page load, so you
+ can use any of these methods on simple arrays. If Array already implements
+ one of these methods, the mixin will not override them.
+
+ ## Writing Your Own Enumerable
+
+ To make your own custom class enumerable, you need two items:
+
+ 1. You must have a length property. This property should change whenever
+ the number of items in your enumerable object changes. If you using this
+ with an `Ember.Object` subclass, you should be sure to change the length
+ property using `set().`
+
+ 2. If you must implement `nextObject().` See documentation.
+
+ Once you have these two methods implement, apply the `Ember.Enumerable` mixin
+ to your class and you will be able to enumerate the contents of your object
+ like any other collection.
+
+ ## Using Ember Enumeration with Other Libraries
+
+ Many other libraries provide some kind of iterator or enumeration like
+ facility. This is often where the most common API conflicts occur.
+ Ember's API is designed to be as friendly as possible with other
+ 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 */ {
+
+ // compatibility
+ isEnumerable: true,
+
+ /**
+ Implement this method to make your class enumerable.
+
+ This method will be call repeatedly during enumeration. The index value
+ will always begin with 0 and increment monotonically. You don't have to
+ rely on the index value to determine what object to return, but you should
+ always check the value and start from the beginning when you see the
+ requested index is 0.
+
+ The `previousObject` is the object that was returned from the last call
+ to `nextObject` for the current iteration. This is a useful way to
+ manage iteration if you are tracing a linked list, for example.
+
+ Finally the context parameter will always contain a hash you can use as
+ a "scratchpad" to maintain any other state you need in order to iterate
+ properly. The context object is reused and is not reset between
+ iterations so make sure you setup the context with a fresh state whenever
+ the index parameter is 0.
+
+ Generally iterators will continue to call `nextObject` until the index
+ reaches the your current length-1. If you run out of data before this
+ time for some reason, you should simply return undefined.
+
+ 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.
+ @return {Object} the next object in the iteration or undefined
+ */
+ nextObject: Ember.required(Function),
+
+ /**
+ Helper method returns the first object from a collection. This is usually
+ used by bindings and other parts of the framework to extract a single
+ object if the enumerable contains only one item.
+
+ If you override this method, you should implement it so that it will
+ always return the same value each time it is called. If your enumerable
+ contains only one object, this method should always return that object.
+ If your enumerable is empty, this method should return `undefined`.
+
+ ```javascript
+ var arr = ["a", "b", "c"];
+ arr.firstObject(); // "a"
+
+ var arr = [];
+ arr.firstObject(); // undefined
+ ```
+
+ @property firstObject
+ @return {Object} the object or undefined
+ */
+ firstObject: Ember.computed(function() {
+ if (get(this, 'length')===0) return undefined ;
+
+ // handle generic enumerables
+ var context = popCtx(), ret;
+ ret = this.nextObject(0, null, context);
+ pushCtx(context);
+ return ret ;
+ }).property('[]'),
+
+ /**
+ Helper method returns the last object from a collection. If your enumerable
+ contains only one object, this method should always return that object.
+ If your enumerable is empty, this method should return `undefined`.
+
+ ```javascript
+ var arr = ["a", "b", "c"];
+ arr.lastObject(); // "c"
+
+ var arr = [];
+ arr.lastObject(); // undefined
+ ```
+
+ @property lastObject
+ @return {Object} the last object or undefined
+ */
+ lastObject: Ember.computed(function() {
+ var len = get(this, 'length');
+ if (len===0) return undefined ;
+ var context = popCtx(), idx=0, cur, last = null;
+ do {
+ last = cur;
+ cur = this.nextObject(idx++, last, context);
+ } while (cur !== undefined);
+ pushCtx(context);
+ return last;
+ }).property('[]'),
+
+ /**
+ Returns `true` if the passed object can be found in the receiver. The
+ default version will iterate through the enumerable until the object
+ is found. You may want to override this with a more efficient version.
+
+ ```javascript
+ var arr = ["a", "b", "c"];
+ arr.contains("a"); // true
+ arr.contains("z"); // false
+ ```
+
+ @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;
+ },
+
+ /**
+ Iterates through the enumerable, calling the passed function on each
+ item. This method corresponds to the `forEach()` method defined in
+ JavaScript 1.6.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(item, index, enumerable);
+ ```
+
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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
+ @return {Object} receiver
+ */
+ forEach: function(callback, target) {
+ if (typeof callback !== "function") throw new TypeError() ;
+ var len = get(this, 'length'), last = null, context = popCtx();
+
+ if (target === undefined) target = null;
+
+ for(var idx=0;idx<len;idx++) {
+ var next = this.nextObject(idx, last, context) ;
+ callback.call(target, next, idx, this);
+ last = next ;
+ }
+ last = null ;
+ context = pushCtx(context);
+ return this ;
+ },
+
+ /**
+ Alias for `mapProperty`
+
+ @method getEach
+ @param {String} key name of the property
+ @return {Array} The mapped array.
+ */
+ getEach: function(key) {
+ return this.mapProperty(key);
+ },
+
+ /**
+ Sets the value on the named property for each member. This is more
+ efficient than using other methods defined on this helper. If the object
+ 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
+ @return {Object} receiver
+ */
+ setEach: function(key, value) {
+ return this.forEach(function(item) {
+ set(item, key, value);
+ });
+ },
+
+ /**
+ Maps all of the items in the enumeration to another value, returning
+ a new array. This method corresponds to `map()` defined in JavaScript 1.6.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(item, index, enumerable);
+ ```
+
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ It should return the mapped value.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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
+ @return {Array} The mapped array.
+ */
+ map: function(callback, target) {
+ var ret = [];
+ this.forEach(function(x, idx, i) {
+ ret[idx] = callback.call(target, x, idx,i);
+ });
+ return ret ;
+ },
+
+ /**
+ 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
+ @return {Array} The mapped array.
+ */
+ mapProperty: function(key) {
+ return this.map(function(next) {
+ return get(next, key);
+ });
+ },
+
+ /**
+ Returns an array with all of the items in the enumeration that the passed
+ function returns true for. This method corresponds to `filter()` defined in
+ JavaScript 1.6.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(item, index, enumerable);
+ ```
+
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ It should return the `true` to include the item in the results, `false`
+ otherwise.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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
+ @return {Array} A filtered array.
+ */
+ filter: function(callback, target) {
+ var ret = [];
+ this.forEach(function(x, idx, i) {
+ if (callback.call(target, x, idx, i)) ret.push(x);
+ });
+ return ret ;
+ },
+
+ /**
+ Returns an array with all of the items in the enumeration where the passed
+ function returns false for. This method is the inverse of filter().
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ function(item, index, enumerable);
+
+ - *item* is the current item in the iteration.
+ - *index* is the current index in the iteration
+ - *enumerable* is the enumerable object itself.
+
+ It should return the a falsey value to include the item in the results.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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 reject
+ @param {Function} callback The callback to execute
+ @param {Object} [target] The target object to use
+ @return {Array} A rejected array.
+ */
+ reject: function(callback, target) {
+ return this.filter(function() {
+ return !(callback.apply(target, arguments));
+ });
+ },
+
+ /**
+ Returns an array with just the items with the matched property. You
+ 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.
+ @return {Array} filtered array
+ */
+ filterProperty: function(key, value) {
+ return this.filter(iter.apply(this, arguments));
+ },
+
+ /**
+ Returns an array with the items that do not have truthy values for
+ key. You can pass an optional second argument with the target value. Otherwise
+ this will match any property that evaluates to false.
+
+ @method rejectProperty
+ @param {String} key the property to test
+ @param {String} [value] optional value to test against.
+ @return {Array} rejected array
+ */
+ rejectProperty: function(key, value) {
+ var exactValue = function(item) { return get(item, key) === value; },
+ hasValue = function(item) { return !!get(item, key); },
+ use = (arguments.length === 2 ? exactValue : hasValue);
+
+ return this.reject(use);
+ },
+
+ /**
+ Returns the first item in the array for which the callback returns true.
+ This method works similar to the `filter()` method defined in JavaScript 1.6
+ except that it will stop working on the array once a match is found.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(item, index, enumerable);
+ ```
+
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ It should return the `true` to include the item in the results, `false`
+ otherwise.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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
+ @return {Object} Found item or `null`.
+ */
+ find: function(callback, target) {
+ var len = get(this, 'length') ;
+ if (target === undefined) target = null;
+
+ var last = null, next, found = false, ret ;
+ var context = popCtx();
+ for(var idx=0;idx<len && !found;idx++) {
+ next = this.nextObject(idx, last, context) ;
+ if (found = callback.call(target, next, idx, this)) ret = next ;
+ last = next ;
+ }
+ next = last = null ;
+ context = pushCtx(context);
+ return ret ;
+ },
+
+ /**
+ Returns the first item with a property matching the passed value. You
+ can pass an optional second argument with the target value. Otherwise
+ this will match any property that evaluates to `true`.
+
+ 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.
+ @return {Object} found item or `null`
+ */
+ findProperty: function(key, value) {
+ return this.find(iter.apply(this, arguments));
+ },
+
+ /**
+ Returns `true` if the passed function returns true for every item in the
+ enumeration. This corresponds with the `every()` method in JavaScript 1.6.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(item, index, enumerable);
+ ```
+
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ It should return the `true` or `false`.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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.
+
+ Example Usage:
+
+ ```javascript
+ if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
+ ```
+
+ @method every
+ @param {Function} callback The callback to execute
+ @param {Object} [target] The target object to use
+ @return {Boolean}
+ */
+ every: function(callback, target) {
+ return !this.find(function(x, idx, i) {
+ return !callback.call(target, x, idx, i);
+ });
+ },
+
+ /**
+ 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.
+ @return {Boolean}
+ */
+ everyProperty: function(key, value) {
+ return this.every(iter.apply(this, arguments));
+ },
+
+
+ /**
+ Returns `true` if the passed function returns true for any item in the
+ enumeration. This corresponds with the `every()` method in JavaScript 1.6.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(item, index, enumerable);
+ ```
+
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ It should return the `true` to include the item in the results, `false`
+ otherwise.
+
+ Note that in addition to a callback, you can also pass an optional target
+ 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.
+
+ Usage Example:
+
+ ```javascript
+ if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
+ ```
+
+ @method some
+ @param {Function} callback The callback to execute
+ @param {Object} [target] The target object to use
+ @return {Array} A filtered array.
+ */
+ some: function(callback, target) {
+ return !!this.find(function(x, idx, i) {
+ return !!callback.call(target, x, idx, i);
+ });
+ },
+
+ /**
+ 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.
+ @return {Boolean} `true`
+ */
+ someProperty: function(key, value) {
+ return this.some(iter.apply(this, arguments));
+ },
+
+ /**
+ This will combine the values of the enumerator into a single value. It
+ is a useful way to collect a summary value from an enumeration. This
+ corresponds to the `reduce()` method defined in JavaScript 1.8.
+
+ The callback method you provide should have the following signature (all
+ parameters are optional):
+
+ ```javascript
+ function(previousValue, item, index, enumerable);
+ ```
+
+ - `previousValue` is the value returned by the last call to the iterator.
+ - `item` is the current item in the iteration.
+ - `index` is the current index in the iteration.
+ - `enumerable` is the enumerable object itself.
+
+ Return the new cumulative value.
+
+ In addition to the callback you can also pass an `initialValue`. An error
+ will be raised if you do not pass an initial value and the enumerator is
+ empty.
+
+ Note that unlike the other methods, this method does not allow you to
+ 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.
+ @return {Object} The reduced value.
+ */
+ reduce: function(callback, initialValue, reducerProperty) {
+ if (typeof callback !== "function") { throw new TypeError(); }
+
+ var ret = initialValue;
+
+ this.forEach(function(item, i) {
+ ret = callback.call(null, ret, item, i, this, reducerProperty);
+ }, this);
+
+ return ret;
+ },
+
+ /**
+ Invokes the named method on every object in the receiver that
+ 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.
+ @return {Array} return values from calling invoke.
+ */
+ invoke: function(methodName) {
+ var args, ret = [];
+ if (arguments.length>1) args = a_slice.call(arguments, 1);
+
+ this.forEach(function(x, idx) {
+ var method = x && x[methodName];
+ if ('function' === typeof method) {
+ ret[idx] = args ? method.apply(x, args) : method.call(x);
+ }
+ }, this);
+
+ return ret;
+ },
+
+ /**
+ Simply converts the enumerable into a genuine array. The order is not
+ guaranteed. Corresponds to the method implemented by Prototype.
+
+ @method toArray
+ @return {Array} the enumerable as an array.
+ */
+ toArray: function() {
+ var ret = [];
+ this.forEach(function(o, idx) { ret[idx] = o; });
+ return ret ;
+ },
+
+ /**
+ Returns a copy of the array with all null elements removed.
+
+ ```javascript
+ var arr = ["a", null, "c", null];
+ arr.compact(); // ["a", "c"]
+ ```
+
+ @method compact
+ @return {Array} the array without null elements.
+ */
+ compact: function() { return this.without(null); },
+
+ /**
+ Returns a new enumerable that excludes the passed value. The default
+ implementation returns an array regardless of the receiver type unless
+ the receiver does not contain the value.
+
+ ```javascript
+ var arr = ["a", "b", "a", "c"];
+ arr.without("a"); // ["b", "c"]
+ ```
+
+ @method without
+ @param {Object} value
+ @return {Ember.Enumerable}
+ */
+ without: function(value) {
+ if (!this.contains(value)) return this; // nothing to do
+ var ret = [] ;
+ this.forEach(function(k) {
+ if (k !== value) ret[ret.length] = k;
+ }) ;
+ return ret ;
+ },
+
+ /**
+ Returns a new enumerable that contains only unique values. The default
+ implementation returns an array regardless of the receiver type.
+
+ ```javascript
+ var arr = ["a", "a", "b", "b"];
+ arr.uniq(); // ["a", "b"]
+ ```
+
+ @method uniq
+ @return {Ember.Enumerable}
+ */
+ uniq: function() {
+ var ret = [];
+ this.forEach(function(k){
+ if (a_indexOf(ret, k)<0) ret.push(k);
+ });
+ return ret;
+ },
+
+ /**
+ This property will trigger anytime the enumerable's content changes.
+ You can observe this property to be notified of changes to the enumerables
+ content.
+
+ For plain enumerables, this property is read only. `Ember.Array` overrides
+ this method.
+
+ @property []
+ @type Ember.Array
+ */
+ '[]': Ember.computed(function(key, value) {
+ return this;
+ }),
+
+ // ..........................................................
+ // ENUMERABLE OBSERVERS
+ //
+
+ /**
+ 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',
+ didChange = (opts && opts.didChange) || 'enumerableDidChange';
+
+ var hasObservers = get(this, 'hasEnumerableObservers');
+ if (!hasObservers) Ember.propertyWillChange(this, 'hasEnumerableObservers');
+ Ember.addListener(this, '@enumerable:before', target, willChange);
+ Ember.addListener(this, '@enumerable:change', target, didChange);
+ if (!hasObservers) Ember.propertyDidChange(this, 'hasEnumerableObservers');
+ return this;
+ },
+
+ /**
+ Removes a registered enumerable observer.
+
+ @method removeEnumerableObserver
+ @param target {Object}
+ @param [opts] {Hash}
+ */
+ removeEnumerableObserver: function(target, opts) {
+ var willChange = (opts && opts.willChange) || 'enumerableWillChange',
+ didChange = (opts && opts.didChange) || 'enumerableDidChange';
+
+ var hasObservers = get(this, 'hasEnumerableObservers');
+ if (hasObservers) Ember.propertyWillChange(this, 'hasEnumerableObservers');
+ Ember.removeListener(this, '@enumerable:before', target, willChange);
+ Ember.removeListener(this, '@enumerable:change', target, didChange);
+ if (hasObservers) Ember.propertyDidChange(this, 'hasEnumerableObservers');
+ return this;
+ },
+
+ /**
+ Becomes true whenever the array currently has observers watching changes
+ on the array.
+
+ @property hasEnumerableObservers
+ @type Boolean
+ */
+ hasEnumerableObservers: Ember.computed(function() {
+ return Ember.hasListeners(this, '@enumerable:change') || Ember.hasListeners(this, '@enumerable:before');
+ }),
+
+
+ /**
+ Invoke this method just before the contents of your enumerable will
+ change. You can either omit the parameters completely or pass the objects
+ to be removed or added if available or just a count.
+
+ @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) {
+
+ var removeCnt, addCnt, hasDelta;
+
+ if ('number' === typeof removing) removeCnt = removing;
+ else if (removing) removeCnt = get(removing, 'length');
+ else removeCnt = removing = -1;
+
+ if ('number' === typeof adding) addCnt = adding;
+ else if (adding) addCnt = get(adding,'length');
+ else addCnt = adding = -1;
+
+ hasDelta = addCnt<0 || removeCnt<0 || addCnt-removeCnt!==0;
+
+ if (removing === -1) removing = null;
+ if (adding === -1) adding = null;
+
+ Ember.propertyWillChange(this, '[]');
+ if (hasDelta) Ember.propertyWillChange(this, 'length');
+ Ember.sendEvent(this, '@enumerable:before', [this, removing, adding]);
+
+ return this;
+ },
+
+ /**
+ Invoke this method when the contents of your enumerable has changed.
+ This will notify any observers watching for content changes. If your are
+ implementing an ordered enumerable (such as an array), also pass the
+ start and end values where the content changed so that it can be used to
+ notify range observers.
+
+ @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;
+
+ if ('number' === typeof removing) removeCnt = removing;
+ else if (removing) removeCnt = get(removing, 'length');
+ else removeCnt = removing = -1;
+
+ if ('number' === typeof adding) addCnt = adding;
+ else if (adding) addCnt = get(adding, 'length');
+ else addCnt = adding = -1;
+
+ hasDelta = addCnt<0 || removeCnt<0 || addCnt-removeCnt!==0;
+
+ if (removing === -1) removing = null;
+ if (adding === -1) adding = null;
+
+ Ember.sendEvent(this, '@enumerable:change', [this, removing, adding]);
+ if (hasDelta) Ember.propertyDidChange(this, 'length');
+ Ember.propertyDidChange(this, '[]');
+
+ return this ;
+ }
+
+}) ;
+
+})();
+
+
+
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+// ..........................................................
+// HELPERS
+//
+
+var get = Ember.get, set = Ember.set, meta = Ember.meta, map = Ember.EnumerableUtils.map, cacheFor = Ember.cacheFor;
+
+function none(obj) { return obj===null || obj===undefined; }
+
+// ..........................................................
+// ARRAY
+//
+/**
+ 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.
+
+ Unlike `Ember.Enumerable,` this mixin defines methods specifically for
+ collections that provide index-ordered access to their contents. When you
+ are designing code that needs to accept any kind of Array-like object, you
+ should use these methods instead of Array primitives because these will
+ properly notify observers of changes to the array.
+
+ Although these methods are efficient, they do add a layer of indirection to
+ your application so it is a good idea to use them only when you need the
+ flexibility of using both true JavaScript arrays and "virtual" arrays such
+ as controllers and collections.
+
+ You can use the methods defined in this module to access and modify array
+ contents in a KVO-friendly way. You can also be notified whenever the
+ membership if an array changes by changing the syntax of the property to
+ `.observes('*myProperty.[]')`.
+
+ To support `Ember.Array` in your own class, you must override two
+ primitives to use it: `replace()` and `objectAt()`.
+
+ Note that the Ember.Array mixin also incorporates the `Ember.Enumerable`
+ mixin. All `Ember.Array`-like objects are also 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 */ {
+
+ // compatibility
+ isSCArray: true,
+
+ /**
+ Your array must support the `length` property. Your replace methods should
+ set this property whenever it changes.
+
+ @property {Number} length
+ */
+ length: Ember.required(),
+
+ /**
+ Returns the object at the given `index`. If the given `index` is negative
+ or is greater or equal than the array length, returns `undefined`.
+
+ This is one of the primitives you must implement to support `Ember.Array`.
+ If your object supports retrieving the value of an array item using `get()`
+ (i.e. `myArray.get(0)`), then you do not need to implement this method
+ yourself.
+
+ ```javascript
+ var arr = ['a', 'b', 'c', 'd'];
+ arr.objectAt(0); // "a"
+ arr.objectAt(3); // "d"
+ arr.objectAt(-1); // undefined
+ arr.objectAt(4); // undefined
+ arr.objectAt(5); // undefined
+ ```
+
+ @method objectAt
+ @param {Number} idx The index of the item to return.
+ */
+ objectAt: function(idx) {
+ if ((idx < 0) || (idx>=get(this, 'length'))) return undefined ;
+ return get(this, idx);
+ },
+
+ /**
+ This returns the objects at the specified indexes, using `objectAt`.
+
+ ```javascript
+ var arr = ['a', 'b', 'c', 'd'];
+ 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.
+ */
+ objectsAt: function(indexes) {
+ var self = this;
+ return map(indexes, function(idx){ return self.objectAt(idx); });
+ },
+
+ // overrides Ember.Enumerable version
+ nextObject: function(idx) {
+ return this.objectAt(idx);
+ },
+
+ /**
+ 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) ;
+ return this ;
+ }),
+
+ firstObject: Ember.computed(function() {
+ return this.objectAt(0);
+ }),
+
+ lastObject: Ember.computed(function() {
+ return this.objectAt(get(this, 'length')-1);
+ }),
+
+ // optimized version from Enumerable
+ contains: function(obj){
+ return this.indexOf(obj) >= 0;
+ },
+
+ // Add any extra methods to Ember.Array that are native to the built-in Array.
+ /**
+ Returns a new array that is a slice of the receiver. This implementation
+ uses the observable array methods to retrieve the objects for the new
+ slice.
+
+ ```javascript
+ var arr = ['red', 'green', 'blue'];
+ arr.slice(0); // ['red', 'green', 'blue']
+ 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.
+ @return {Array} New array with specified slice
+ */
+ slice: function(beginIndex, endIndex) {
+ var ret = [];
+ var length = get(this, 'length') ;
+ if (none(beginIndex)) beginIndex = 0 ;
+ if (none(endIndex) || (endIndex > length)) endIndex = length ;
+ while(beginIndex < endIndex) {
+ ret[ret.length] = this.objectAt(beginIndex++) ;
+ }
+ return ret ;
+ },
+
+ /**
+ Returns the index of the given object's first occurrence.
+ If no `startAt` argument is given, the starting location to
+ search is 0. If it's negative, will count backward from
+ the end of the array. Returns -1 if no match is found.
+
+ ```javascript
+ var arr = ["a", "b", "c", "d", "a"];
+ arr.indexOf("a"); // 0
+ arr.indexOf("z"); // -1
+ arr.indexOf("a", 2); // 4
+ arr.indexOf("a", -1); // 4
+ arr.indexOf("b", 3); // -1
+ arr.indexOf("a", 100); // -1
+ ```javascript
+
+ @method indexOf
+ @param {Object} object the item to search for
+ @param {Number} startAt optional starting location to search, default 0
+ @return {Number} index or -1 if not found
+ */
+ indexOf: function(object, startAt) {
+ var idx, len = get(this, 'length');
+
+ if (startAt === undefined) startAt = 0;
+ if (startAt < 0) startAt += len;
+
+ for(idx=startAt;idx<len;idx++) {
+ if (this.objectAt(idx, true) === object) return idx ;
+ }
+ return -1;
+ },
+
+ /**
+ Returns the index of the given object's last occurrence.
+ If no `startAt` argument is given, the search starts from
+ the last position. If it's negative, will count backward
+ from the end of the array. Returns -1 if no match is found.
+
+ ```javascript
+ var arr = ["a", "b", "c", "d", "a"];
+ arr.lastIndexOf("a"); // 4
+ arr.lastIndexOf("z"); // -1
+ arr.lastIndexOf("a", 2); // 0
+ arr.lastIndexOf("a", -1); // 4
+ 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
+ @return {Number} index or -1 if not found
+ */
+ lastIndexOf: function(object, startAt) {
+ var idx, len = get(this, 'length');
+
+ if (startAt === undefined || startAt >= len) startAt = len-1;
+ if (startAt < 0) startAt += len;
+
+ for(idx=startAt;idx>=0;idx--) {
+ if (this.objectAt(idx) === object) return idx ;
+ }
+ return -1;
+ },
+
+ // ..........................................................
+ // ARRAY OBSERVERS
+ //
+
+ /**
+ Adds an array observer to the receiving array. The array observer object
+ normally must implement two methods:
+
+ * `arrayWillChange(start, removeCount, addCount)` - This method will be
+ called just before the array is modified.
+ * `arrayDidChange(start, removeCount, addCount)` - This method will be
+ called just after the array is modified.
+
+ Both callbacks will be passed the starting index of the change as well a
+ a count of the items to be removed and added. You can use these callbacks
+ to optionally inspect the array during the change, clear caches, or do
+ any other bookkeeping necessary.
+
+ In addition to passing a target, you can also include an options hash
+ which you can use to override the method names that will be invoked on the
+ target.
+
+ @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',
+ didChange = (opts && opts.didChange) || 'arrayDidChange';
+
+ var hasObservers = get(this, 'hasArrayObservers');
+ if (!hasObservers) Ember.propertyWillChange(this, 'hasArrayObservers');
+ Ember.addListener(this, '@array:before', target, willChange);
+ Ember.addListener(this, '@array:change', target, didChange);
+ if (!hasObservers) Ember.propertyDidChange(this, 'hasArrayObservers');
+ return this;
+ },
+
+ /**
+ Removes an array observer from the object if the observer is current
+ registered. Calling this method multiple times with the same object will
+ have no effect.
+
+ @method removeArrayObserver
+ @param {Object} target The object observing the array.
+ @return {Ember.Array} receiver
+ */
+ removeArrayObserver: function(target, opts) {
+ var willChange = (opts && opts.willChange) || 'arrayWillChange',
+ didChange = (opts && opts.didChange) || 'arrayDidChange';
+
+ var hasObservers = get(this, 'hasArrayObservers');
+ if (hasObservers) Ember.propertyWillChange(this, 'hasArrayObservers');
+ Ember.removeListener(this, '@array:before', target, willChange);
+ Ember.removeListener(this, '@array:change', target, didChange);
+ if (hasObservers) Ember.propertyDidChange(this, 'hasArrayObservers');
+ return this;
+ },
+
+ /**
+ Becomes true whenever the array currently has observers watching changes
+ on the array.
+
+ @property Boolean
+ */
+ hasArrayObservers: Ember.computed(function() {
+ return Ember.hasListeners(this, '@array:change') || Ember.hasListeners(this, '@array:before');
+ }),
+
+ /**
+ If you are implementing an object that supports `Ember.Array`, call this
+ method just before the array content changes to notify any observers and
+ invalidate any related properties. Pass the starting index of the change
+ as well as a delta of the amounts to change.
+
+ @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) {
+
+ // if no args are passed assume everything changes
+ if (startIdx===undefined) {
+ startIdx = 0;
+ removeAmt = addAmt = -1;
+ } else {
+ if (removeAmt === undefined) removeAmt=-1;
+ if (addAmt === undefined) addAmt=-1;
+ }
+
+ // Make sure the @each proxy is set up if anyone is observing @each
+ if (Ember.isWatching(this, '@each')) { get(this, '@each'); }
+
+ Ember.sendEvent(this, '@array:before', [this, startIdx, removeAmt, addAmt]);
+
+ var removing, lim;
+ if (startIdx>=0 && removeAmt>=0 && get(this, 'hasEnumerableObservers')) {
+ removing = [];
+ lim = startIdx+removeAmt;
+ for(var idx=startIdx;idx<lim;idx++) removing.push(this.objectAt(idx));
+ } else {
+ removing = removeAmt;
+ }
+
+ this.enumerableContentWillChange(removing, addAmt);
+
+ return this;
+ },
+
+ arrayContentDidChange: function(startIdx, removeAmt, addAmt) {
+
+ // if no args are passed assume everything changes
+ if (startIdx===undefined) {
+ startIdx = 0;
+ removeAmt = addAmt = -1;
+ } else {
+ if (removeAmt === undefined) removeAmt=-1;
+ if (addAmt === undefined) addAmt=-1;
+ }
+
+ var adding, lim;
+ if (startIdx>=0 && addAmt>=0 && get(this, 'hasEnumerableObservers')) {
+ adding = [];
+ lim = startIdx+addAmt;
+ for(var idx=startIdx;idx<lim;idx++) adding.push(this.objectAt(idx));
+ } else {
+ adding = addAmt;
+ }
+
+ this.enumerableContentDidChange(removeAmt, adding);
+ Ember.sendEvent(this, '@array:change', [this, startIdx, removeAmt, addAmt]);
+
+ var length = get(this, 'length'),
+ cachedFirst = cacheFor(this, 'firstObject'),
+ cachedLast = cacheFor(this, 'lastObject');
+ if (this.objectAt(0) !== cachedFirst) {
+ Ember.propertyWillChange(this, 'firstObject');
+ Ember.propertyDidChange(this, 'firstObject');
+ }
+ if (this.objectAt(length-1) !== cachedLast) {
+ Ember.propertyWillChange(this, 'lastObject');
+ Ember.propertyDidChange(this, 'lastObject');
+ }
+
+ return this;
+ },
- // 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]];
- }
-};
+ // ..........................................................
+ // ENUMERATED PROPERTIES
+ //
-Ember.Error.prototype = Ember.create(Error.prototype);
+ /**
+ Returns a special object that can be used to observe individual properties
+ 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);
+ return this.__each;
+ })
+
+}) ;
})();
@submodule ember-runtime
*/
-var STRING_DASHERIZE_REGEXP = (/[ _]/g);
-var STRING_DASHERIZE_CACHE = {};
-var STRING_DECAMELIZE_REGEXP = (/([a-z])([A-Z])/g);
-var STRING_CAMELIZE_REGEXP = (/(\-|_|\s)+(.)?/g);
-var STRING_UNDERSCORE_REGEXP_1 = (/([a-z\d])([A-Z]+)/g);
-var STRING_UNDERSCORE_REGEXP_2 = (/\-|\s+/g);
/**
- Defines the hash of localized strings for the current language. Used by
- the `Ember.String.loc()` helper. To localize, add string values to this
- hash.
-
- @property STRINGS
- @for Ember
- @type Hash
-*/
-Ember.STRINGS = {};
+ Implements some standard methods for comparing objects. Add this mixin to
+ any class you create that can compare its instances.
-/**
- Defines string helper methods including string formatting and localization.
- Unless Ember.EXTEND_PROTOTYPES = false these methods will also be added to the
- String.prototype as well.
+ You should implement the `compare()` method.
- @class String
+ @class Comparable
@namespace Ember
- @static
+ @extends Ember.Mixin
+ @since Ember 0.9
*/
-Ember.String = {
+Ember.Comparable = Ember.Mixin.create( /** @scope Ember.Comparable.prototype */{
/**
- Apply formatting options to the string. This will look for occurrences
- of %@ in your string and substitute them with the arguments you pass into
- this method. If you want to control the specific order of replacement,
- you can add a number after the key as well to indicate which argument
- you want to insert.
-
- Ordered insertions are most useful when building loc strings where values
- you need to insert may appear in different orders.
-
- "Hello %@ %@".fmt('John', 'Doe') => "Hello John Doe"
- "Hello %@2, %@1".fmt('John', 'Doe') => "Hello Doe, John"
+ walk like a duck. Indicates that the object can be compared.
- @method fmt
- @param {Object...} [args]
- @return {String} formatted string
+ @property isComparable
+ @type Boolean
+ @default true
*/
- fmt: function(str, formats) {
- // first, replace any ORDERED replacements.
- var idx = 0; // the current index for non-numerical replacements
- return str.replace(/%@([0-9]+)?/g, function(s, argIndex) {
- argIndex = (argIndex) ? parseInt(argIndex,0) - 1 : idx++ ;
- s = formats[argIndex];
- return ((s === null) ? '(null)' : (s === undefined) ? '' : s).toString();
- }) ;
- },
+ isComparable: true,
/**
- Formats the passed string, but first looks up the string in the localized
- strings hash. This is a convenient way to localize text. See
- `Ember.String.fmt()` for more information on formatting.
-
- Note that it is traditional but not required to prefix localized string
- keys with an underscore or other character so you can easily identify
- localized strings.
-
- Ember.STRINGS = {
- '_Hello World': 'Bonjour le monde',
- '_Hello %@ %@': 'Bonjour %@ %@'
- };
+ Override to return the result of the comparison of the two parameters. The
+ compare method should return:
- Ember.String.loc("_Hello World");
- => 'Bonjour le monde';
+ - `-1` if `a < b`
+ - `0` if `a == b`
+ - `1` if `a > b`
- Ember.String.loc("_Hello %@ %@", ["John", "Smith"]);
- => "Bonjour John Smith";
+ Default implementation raises an exception.
- @method loc
- @param {String} str The string to format
- @param {Array} formats Optional array of parameters to interpolate into string.
- @return {String} formatted string
+ @method compare
+ @param a {Object} the first object to compare
+ @param b {Object} the second object to compare
+ @return {Integer} the result of the comparison
*/
- loc: function(str, formats) {
- str = Ember.STRINGS[str] || str;
- return Ember.String.fmt(str, formats) ;
- },
+ compare: Ember.required(Function)
- /**
- Splits a string into separate units separated by spaces, eliminating any
- empty strings in the process. This is a convenience method for split that
- is mostly useful when applied to the String.prototype.
+});
- Ember.String.w("alpha beta gamma").forEach(function(key) {
- console.log(key);
- });
- > alpha
- > beta
- > gamma
- @method w
- @param {String} str The string to split
- @return {String} split string
- */
- w: function(str) { return str.split(/\s+/); },
+})();
- /**
- Converts a camelized string into all lower case separated by underscores.
-
- 'innerHTML'.decamelize() => 'inner_html'
- 'action_name'.decamelize() => 'action_name'
- 'css-class-name'.decamelize() => 'css-class-name'
- 'my favorite items'.decamelize() => 'my favorite items'
- @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();
- },
- /**
- Replaces underscores or spaces with dashes.
-
- 'innerHTML'.dasherize() => 'inner-html'
- 'action_name'.dasherize() => 'action-name'
- 'css-class-name'.dasherize() => 'css-class-name'
- 'my favorite items'.dasherize() => 'my-favorite-items'
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- @method dasherize
- @param {String} str The string to dasherize.
- @return {String} the dasherized string.
- */
- dasherize: function(str) {
- var cache = STRING_DASHERIZE_CACHE,
- ret = cache[str];
- if (ret) {
- return ret;
- } else {
- ret = Ember.String.decamelize(str).replace(STRING_DASHERIZE_REGEXP,'-');
- cache[str] = ret;
- }
- return ret;
- },
+var get = Ember.get, set = Ember.set;
- /**
- Returns the lowerCaseCamel form of a string.
+/**
+ 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.
- 'innerHTML'.camelize() => 'innerHTML'
- 'action_name'.camelize() => 'actionName'
- 'css-class-name'.camelize() => 'cssClassName'
- 'my favorite items'.camelize() => 'myFavoriteItems'
+ You should generally implement the `copy()` method to return a copy of the
+ receiver.
- @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) {
- return chr ? chr.toUpperCase() : '';
- });
- },
+ Note that `frozenCopy()` will only work if you also implement
+ `Ember.Freezable`.
- /**
- Returns the UpperCamelCase form of a string.
+ @class Copyable
+ @namespace Ember
+ @extends Ember.Mixin
+ @since Ember 0.9
+*/
+Ember.Copyable = Ember.Mixin.create(
+/** @scope Ember.Copyable.prototype */ {
- 'innerHTML'.classify() => 'InnerHTML'
- 'action_name'.classify() => 'ActionName'
- 'css-class-name'.classify() => 'CssClassName'
- 'my favorite items'.classify() => 'MyFavoriteItems'
+ /**
+ Override to return a copy of the receiver. Default implementation raises
+ an exception.
- @method classify
- @param {String} str the string to classify
- @return {String} the classified string
+ @method copy
+ @param deep {Boolean} if `true`, a deep copy of the object should be made
+ @return {Object} copy of receiver
*/
- classify: function(str) {
- var camelized = Ember.String.camelize(str);
- return camelized.charAt(0).toUpperCase() + camelized.substr(1);
- },
+ copy: Ember.required(Function),
/**
- More general than decamelize. Returns the lower_case_and_underscored
- form of a string.
+ If the object implements `Ember.Freezable`, then this will return a new
+ copy if the object is not frozen and the receiver if the object is frozen.
- 'innerHTML'.underscore() => 'inner_html'
- 'action_name'.underscore() => 'action_name'
- 'css-class-name'.underscore() => 'css_class_name'
- 'my favorite items'.underscore() => 'my_favorite_items'
+ Raises an exception if you try to call this method on a object that does
+ not support freezing.
- @property underscore
- @param {String} str The string to underscore.
- @return {String} the underscored string.
+ You should use this method whenever you want a copy of a freezable object
+ since a freezable object can simply return itself without actually
+ consuming more memory.
+
+ @method frozenCopy
+ @return {Object} copy of receiver or receiver
*/
- underscore: function(str) {
- return str.replace(STRING_UNDERSCORE_REGEXP_1, '$1_$2').
- replace(STRING_UNDERSCORE_REGEXP_2, '_').toLowerCase();
+ frozenCopy: function() {
+ if (Ember.Freezable && Ember.Freezable.detect(this)) {
+ return get(this, 'isFrozen') ? this : this.copy().freeze();
+ } else {
+ throw new Error(Ember.String.fmt("%@ does not support freezing", [this]));
+ }
}
-};
+});
})();
*/
+var get = Ember.get, set = Ember.set;
-var fmt = Ember.String.fmt,
- w = Ember.String.w,
- loc = Ember.String.loc,
- camelize = Ember.String.camelize,
- decamelize = Ember.String.decamelize,
- dasherize = Ember.String.dasherize,
- underscore = Ember.String.underscore;
-
-if (Ember.EXTEND_PROTOTYPES) {
-
- /**
- See {{#crossLink "Ember.String/fmt"}}{{/crossLink}}
+/**
+ 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.
- @method fmt
- @for String
- */
- String.prototype.fmt = function() {
- return fmt(this, arguments);
- };
+ ## Enforcement
- /**
- See {{#crossLink "Ember.String/w"}}{{/crossLink}}
+ To fully support freezing in your subclass, you must include this mixin and
+ override any method that might alter any property on the object to instead
+ raise an exception. You can check the state of an object by checking the
+ `isFrozen` property.
- @method w
- @for String
- */
- String.prototype.w = function() {
- return w(this);
- };
+ Although future versions of JavaScript may support language-level freezing
+ object objects, that is not the case today. Even if an object is freezable,
+ it is still technically possible to modify the object, even though it could
+ break other parts of your application that do not expect a frozen object to
+ change. It is, therefore, very important that you always respect the
+ `isFrozen` property on all freezable objects.
- /**
- See {{#crossLink "Ember.String/loc"}}{{/crossLink}}
+ ## Example Usage
- @method loc
- @for String
- */
- String.prototype.loc = function() {
- return loc(this, arguments);
- };
+ The example below shows a simple object that implement the `Ember.Freezable`
+ protocol.
- /**
- See {{#crossLink "Ember.String/camelize"}}{{/crossLink}}
+ ```javascript
+ Contact = Ember.Object.extend(Ember.Freezable, {
+ firstName: null,
+ lastName: null,
- @method camelize
- @for String
- */
- String.prototype.camelize = function() {
- return camelize(this);
- };
+ // swaps the names
+ swapNames: function() {
+ if (this.get('isFrozen')) throw Ember.FROZEN_ERROR;
+ var tmp = this.get('firstName');
+ this.set('firstName', this.get('lastName'));
+ this.set('lastName', tmp);
+ return this;
+ }
- /**
- See {{#crossLink "Ember.String/decamelize"}}{{/crossLink}}
+ });
- @method decamelize
- @for String
- */
- String.prototype.decamelize = function() {
- return decamelize(this);
- };
+ c = Context.create({ firstName: "John", lastName: "Doe" });
+ c.swapNames(); // returns c
+ c.freeze();
+ c.swapNames(); // EXCEPTION
+ ```
+
+ ## Copying
+
+ Usually the `Ember.Freezable` protocol is implemented in cooperation with the
+ `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
+*/
+Ember.Freezable = Ember.Mixin.create(
+/** @scope Ember.Freezable.prototype */ {
/**
- See {{#crossLink "Ember.String/dasherize"}}{{/crossLink}}
+ Set to `true` when the object is frozen. Use this property to detect
+ whether your object is frozen or not.
- @method dasherize
- @for String
+ @property isFrozen
+ @type Boolean
*/
- String.prototype.dasherize = function() {
- return dasherize(this);
- };
+ isFrozen: false,
/**
- See {{#crossLink "Ember.String/underscore"}}{{/crossLink}}
+ Freezes the object. Once this method has been called the object should
+ no longer allow any properties to be edited.
- @method underscore
- @for String
+ @method freeze
+ @return {Object} receiver
*/
- String.prototype.underscore = function() {
- return underscore(this);
- };
+ freeze: function() {
+ if (get(this, 'isFrozen')) return this;
+ set(this, 'isFrozen', true);
+ return this;
+ }
-}
+});
+Ember.FROZEN_ERROR = "Frozen object cannot be modified.";
})();
@submodule ember-runtime
*/
-var a_slice = Array.prototype.slice;
+var forEach = Ember.EnumerableUtils.forEach;
-if (Ember.EXTEND_PROTOTYPES) {
+/**
+ 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.
- /**
- The `property` extension of Javascript's Function prototype is available
- when Ember.EXTEND_PROTOTYPES is true, which is the default.
+ Note that an Enumerable can change even if it does not implement this mixin.
+ For example, a MappedEnumerable cannot be directly modified but if its
+ underlying enumerable changes, it will change also.
- Computed properties allow you to treat a function like a property:
+ ## Adding Objects
- MyApp.president = Ember.Object.create({
- firstName: "Barack",
- lastName: "Obama",
+ To add an object to an enumerable, use the `addObject()` method. This
+ method will only add the object to the enumerable if the object is not
+ already present and the object if of a type supported by the enumerable.
- fullName: function() {
- return this.get('firstName') + ' ' + this.get('lastName');
+ ```javascript
+ set.addObject(contact);
+ ```
- // Call this flag to mark the function as a property
- }.property()
- });
+ ## Removing Objects
- MyApp.president.get('fullName'); => "Barack Obama"
+ To remove an object form an enumerable, use the `removeObject()` method. This
+ will only remove the object if it is already in the enumerable, otherwise
+ this method has no effect.
- Treating a function like a property is useful because they can work with
- bindings, just like any other property.
+ ```javascript
+ set.removeObject(contact);
+ ```
- Many computed properties have dependencies on other properties. For
- example, in the above example, the `fullName` property depends on
- `firstName` and `lastName` to determine its value. You can tell Ember.js
- about these dependencies like this:
+ ## Implementing In Your Own Code
- MyApp.president = Ember.Object.create({
- firstName: "Barack",
- lastName: "Obama",
+ If you are implementing an object and want to support this API, just include
+ this mixin in your class and implement the required methods. In your unit
+ tests, be sure to apply the Ember.MutableEnumerableTests to your object.
- fullName: function() {
- return this.get('firstName') + ' ' + this.get('lastName');
+ @class MutableEnumerable
+ @namespace Ember
+ @extends Ember.Mixin
+ @uses Ember.Enumerable
+*/
+Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable,
+ /** @scope Ember.MutableEnumerable.prototype */ {
- // Tell Ember.js that this computed property depends on firstName
- // and lastName
- }.property('firstName', 'lastName')
- });
+ /**
+ __Required.__ You must implement this method to apply this mixin.
- Make sure you list these dependencies so Ember.js knows when to update
- bindings that connect to a computed property. Changing a dependency
- will not immediately trigger an update of the computed property, but
- will instead clear the cache so that it is updated when the next `get`
- is called on the property.
+ Attempts to add the passed object to the receiver if the object is not
+ already present in the collection. If the object is present, this method
+ has no effect.
- See {{#crossLink "Ember.ComputedProperty"}}{{/crossLink}},
- {{#crossLink "Ember/computed"}}{{/crossLink}}
+ If the passed object is of a type not supported by the receiver
+ then this method should raise an exception.
- @method property
- @for Function
+ @method addObject
+ @param {Object} object The object to add to the enumerable.
+ @return {Object} the passed object
*/
- Function.prototype.property = function() {
- var ret = Ember.computed(this);
- return ret.property.apply(ret, arguments);
- };
+ addObject: Ember.required(Function),
/**
- The `observes` extension of Javascript's Function prototype is available
- 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.
- For example:
-
- Ember.Object.create({
- valueObserver: function() {
- // Executes whenever the "value" property changes
- }.observes('value')
- });
-
- See {{#crossLink "Ember.Observable/observes"}}{{/crossLink}}
+ Adds each object in the passed enumerable to the receiver.
- @method observes
- @for Function
+ @method addObjects
+ @param {Ember.Enumerable} objects the objects to add.
+ @return {Object} receiver
*/
- Function.prototype.observes = function() {
- this.__ember_observes__ = a_slice.call(arguments);
+ addObjects: function(objects) {
+ Ember.beginPropertyChanges(this);
+ forEach(objects, function(obj) { this.addObject(obj); }, this);
+ Ember.endPropertyChanges(this);
return this;
- };
+ },
/**
- The `observesBefore` extension of Javascript's Function prototype is
- 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
- declarations in classes that you write. For example:
+ __Required.__ You must implement this method to apply this mixin.
- Ember.Object.create({
- valueObserver: function() {
- // Executes whenever the "value" property is about to change
- }.observesBefore('value')
- });
+ Attempts to remove the passed object from the receiver collection if the
+ object is in present in the collection. If the object is not present,
+ this method has no effect.
- See {{#crossLink "Ember.Observable/observesBefore"}}{{/crossLink}}
+ If the passed object is of a type not supported by the receiver
+ then this method should raise an exception.
- @method observesBefore
- @for Function
+ @method removeObject
+ @param {Object} object The object to remove from the enumerable.
+ @return {Object} the passed object
*/
- Function.prototype.observesBefore = function() {
- this.__ember_observesBefore__ = a_slice.call(arguments);
- return this;
- };
-
-}
-
+ removeObject: Ember.required(Function),
-})();
+ /**
+ Removes each objects in the passed enumerable from the receiver.
+ @method removeObjects
+ @param {Ember.Enumerable} objects the objects to remove
+ @return {Object} receiver
+ */
+ removeObjects: function(objects) {
+ Ember.beginPropertyChanges(this);
+ forEach(objects, function(obj) { this.removeObject(obj); }, this);
+ Ember.endPropertyChanges(this);
+ return this;
+ }
-(function() {
+});
})();
@module ember
@submodule ember-runtime
*/
-
// ..........................................................
-// HELPERS
+// CONSTANTS
//
-var get = Ember.get, set = Ember.set;
-var a_slice = Array.prototype.slice;
-var a_indexOf = Ember.EnumerableUtils.indexOf;
-
-var contexts = [];
-
-function popCtx() {
- return contexts.length===0 ? {} : contexts.pop();
-}
-
-function pushCtx(ctx) {
- contexts.push(ctx);
- return null;
-}
+var OUT_OF_RANGE_EXCEPTION = "Index out of range" ;
+var EMPTY = [];
-function iter(key, value) {
- var valueProvided = arguments.length === 2;
+// ..........................................................
+// HELPERS
+//
- function i(item) {
- var cur = get(item, key);
- return valueProvided ? value===cur : !!cur;
- }
- return i ;
-}
+var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach;
/**
- 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
- cannot be emulated in older versions of JavaScript).
+ 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.
- This mixin is applied automatically to the Array class on page load, so you
- can use any of these methods on simple arrays. If Array already implements
- one of these methods, the mixin will not override them.
+ Note that an Array can change even if it does not implement this mixin.
+ For example, one might implement a SparseArray that cannot be directly
+ modified, but if its underlying enumerable changes, it will change also.
- h3. Writing Your Own Enumerable
+ @class MutableArray
+ @namespace Ember
+ @extends Ember.Mixin
+ @uses Ember.Array
+ @uses Ember.MutableEnumerable
+*/
+Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable,
+ /** @scope Ember.MutableArray.prototype */ {
- To make your own custom class enumerable, you need two items:
+ /**
+ __Required.__ You must implement this method to apply this mixin.
- 1. You must have a length property. This property should change whenever
- the number of items in your enumerable object changes. If you using this
- with an Ember.Object subclass, you should be sure to change the length
- property using set().
+ This is one of the primitives you must implement to support `Ember.Array`.
+ You should replace amt objects started at idx with the objects in the
+ passed array. You should also call `this.enumerableContentDidChange()`
- 2. If you must implement nextObject(). See documentation.
+ @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(),
- Once you have these two methods implement, apply the Ember.Enumerable mixin
- to your class and you will be able to enumerate the contents of your object
- like any other collection.
+ /**
+ Remove all elements from self. This is useful if you
+ want to reuse an existing array without having to recreate it.
- h3. Using Ember Enumeration with Other Libraries
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ color.length(); // 3
+ colors.clear(); // []
+ colors.length(); // 0
+ ```
- Many other libraries provide some kind of iterator or enumeration like
- facility. This is often where the most common API conflicts occur.
- Ember's API is designed to be as friendly as possible with other
- libraries by implementing only methods that mostly correspond to the
- JavaScript 1.8 API.
+ @method clear
+ @return {Ember.Array} An empty Array.
+ */
+ clear: function () {
+ var len = get(this, 'length');
+ if (len === 0) return this;
+ this.replace(0, len, EMPTY);
+ return this;
+ },
- @class Enumerable
- @namespace Ember
- @extends Ember.Mixin
- @since Ember 0.9
-*/
-Ember.Enumerable = Ember.Mixin.create(
- /** @scope Ember.Enumerable.prototype */ {
+ /**
+ This will use the primitive `replace()` method to insert an object at the
+ specified index.
- // compatibility
- isEnumerable: true,
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ colors.insertAt(2, "yellow"); // ["red", "green", "yellow", "blue"]
+ colors.insertAt(5, "orange"); // Error: Index out of range
+ ```javascript
+
+ @method insertAt
+ @param {Number} idx index of insert the object at.
+ @param {Object} object object to insert
+ */
+ insertAt: function(idx, object) {
+ if (idx > get(this, 'length')) throw new Error(OUT_OF_RANGE_EXCEPTION) ;
+ this.replace(idx, 0, [object]) ;
+ return this ;
+ },
/**
- Implement this method to make your class enumerable.
+ Remove an object at the specified index using the `replace()` primitive
+ method. You can pass either a single index, or a start and a length.
- This method will be call repeatedly during enumeration. The index value
- will always begin with 0 and increment monotonically. You don't have to
- rely on the index value to determine what object to return, but you should
- always check the value and start from the beginning when you see the
- requested index is 0.
+ If you pass a start and length that is beyond the
+ length this method will throw an `Ember.OUT_OF_RANGE_EXCEPTION`
- The previousObject is the object that was returned from the last call
- to nextObject for the current iteration. This is a useful way to
- manage iteration if you are tracing a linked list, for example.
+ ```javascript
+ var colors = ["red", "green", "blue", "yellow", "orange"];
+ colors.removeAt(0); // ["green", "blue", "yellow", "orange"]
+ colors.removeAt(2, 2); // ["green", "blue"]
+ colors.removeAt(4, 2); // Error: Index out of range
+ ```
- Finally the context parameter will always contain a hash you can use as
- a "scratchpad" to maintain any other state you need in order to iterate
- properly. The context object is reused and is not reset between
- iterations so make sure you setup the context with a fresh state whenever
- the index parameter is 0.
+ @method removeAt
+ @param {Number} start index, start of range
+ @param {Number} len length of passing range
+ @return {Object} receiver
+ */
+ removeAt: function(start, len) {
+ if ('number' === typeof start) {
- Generally iterators will continue to call nextObject until the index
- reaches the your current length-1. If you run out of data before this
- time for some reason, you should simply return undefined.
+ if ((start < 0) || (start >= get(this, 'length'))) {
+ throw new Error(OUT_OF_RANGE_EXCEPTION);
+ }
- The default implementation of this method simply looks up the index.
- This works great on any Array-like objects.
+ // fast case
+ if (len === undefined) len = 1;
+ this.replace(start, len, EMPTY);
+ }
- @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.
- @return {Object} the next object in the iteration or undefined
+ return this ;
+ },
+
+ /**
+ Push the object onto the end of the array. Works just like `push()` but it
+ is KVO-compliant.
+
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ 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
*/
- nextObject: Ember.required(Function),
+ pushObject: function(obj) {
+ this.insertAt(get(this, 'length'), obj) ;
+ return obj ;
+ },
/**
- Helper method returns the first object from a collection. This is usually
- used by bindings and other parts of the framework to extract a single
- object if the enumerable contains only one item.
+ Add the objects in the passed numerable to the end of the array. Defers
+ notifying observers of the change until all objects are added.
- If you override this method, you should implement it so that it will
- always return the same value each time it is called. If your enumerable
- contains only one object, this method should always return that object.
- If your enumerable is empty, this method should return undefined.
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ colors.pushObjects("black"); // ["red", "green", "blue", "black"]
+ colors.pushObjects(["yellow", "orange"]); // ["red", "green", "blue", "black", "yellow", "orange"]
+ ```
- var arr = ["a", "b", "c"];
- arr.firstObject(); => "a"
+ @method pushObjects
+ @param {Ember.Enumerable} objects the objects to add
+ @return {Ember.Array} receiver
+ */
+ pushObjects: function(objects) {
+ this.replace(get(this, 'length'), 0, objects);
+ return this;
+ },
- var arr = [];
- arr.firstObject(); => undefined
+ /**
+ Pop object from array or nil if none are left. Works just like `pop()` but
+ it is KVO-compliant.
- @property firstObject
- @return {Object} the object or undefined
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ colors.popObject(); // "blue"
+ console.log(colors); // ["red", "green"]
+ ```
+
+ @method popObject
+ @return object
*/
- firstObject: Ember.computed(function() {
- if (get(this, 'length')===0) return undefined ;
+ popObject: function() {
+ var len = get(this, 'length') ;
+ if (len === 0) return null ;
- // handle generic enumerables
- var context = popCtx(), ret;
- ret = this.nextObject(0, null, context);
- pushCtx(context);
+ var ret = this.objectAt(len-1) ;
+ this.removeAt(len-1, 1) ;
return ret ;
- }).property('[]').cacheable(),
+ },
/**
- Helper method returns the last object from a collection. If your enumerable
- contains only one object, this method should always return that object.
- If your enumerable is empty, this method should return undefined.
+ Shift an object from start of array or nil if none are left. Works just
+ like `shift()` but it is KVO-compliant.
- var arr = ["a", "b", "c"];
- arr.lastObject(); => "c"
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ colors.shiftObject(); // "red"
+ console.log(colors); // ["green", "blue"]
+ ```
- var arr = [];
- arr.lastObject(); => undefined
+ @method shiftObject
+ @return object
+ */
+ shiftObject: function() {
+ if (get(this, 'length') === 0) return null ;
+ var ret = this.objectAt(0) ;
+ this.removeAt(0) ;
+ return ret ;
+ },
- @property lastObject
- @return {Object} the last object or undefined
+ /**
+ Unshift an object to start of array. Works just like `unshift()` but it is
+ KVO-compliant.
+
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ 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
*/
- lastObject: Ember.computed(function() {
- var len = get(this, 'length');
- if (len===0) return undefined ;
- var context = popCtx(), idx=0, cur, last = null;
- do {
- last = cur;
- cur = this.nextObject(idx++, last, context);
- } while (cur !== undefined);
- pushCtx(context);
- return last;
- }).property('[]').cacheable(),
+ unshiftObject: function(obj) {
+ this.insertAt(0, obj) ;
+ return obj ;
+ },
/**
- Returns true if the passed object can be found in the receiver. The
- default version will iterate through the enumerable until the object
- is found. You may want to override this with a more efficient version.
+ Adds the named objects to the beginning of the array. Defers notifying
+ observers until all objects have been added.
- var arr = ["a", "b", "c"];
- arr.contains("a"); => true
- arr.contains("z"); => false
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ colors.unshiftObjects(["black", "white"]); // ["black", "white", "red", "green", "blue"]
+ colors.unshiftObjects("yellow"); // Type Error: 'undefined' is not a function
+ ```
- @method contains
- @param {Object} obj The object to search for.
- @return {Boolean} true if object is found in enumerable.
+ @method unshiftObjects
+ @param {Ember.Enumerable} objects the objects to add
+ @return {Ember.Array} receiver
*/
- contains: function(obj) {
- return this.find(function(item) { return item===obj; }) !== undefined;
+ unshiftObjects: function(objects) {
+ this.replace(0, 0, objects);
+ return this;
},
/**
- Iterates through the enumerable, calling the passed function on each
- item. This method corresponds to the forEach() method defined in
- JavaScript 1.6.
+ Reverse objects in the array. Works just like `reverse()` but it is
+ KVO-compliant.
- The callback method you provide should have the following signature (all
- parameters are optional):
+ @method reverseObjects
+ @return {Ember.Array} receiver
+ */
+ reverseObjects: function() {
+ var len = get(this, 'length');
+ if (len === 0) return this;
+ var objects = this.toArray().reverse();
+ this.replace(0, len, objects);
+ return this;
+ },
- function(item, index, enumerable);
+ /**
+ Replace all the the receiver's content with content of the argument.
+ If argument is an empty array receiver will be cleared.
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ ```javascript
+ var colors = ["red", "green", "blue"];
+ colors.setObjects(["black", "white"]); // ["black", "white"]
+ colors.setObjects([]); // []
+ ```
- Note that in addition to a callback, you can also pass an optional target
- 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 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();
- @method forEach
- @param {Function} callback The callback to execute
- @param {Object} [target] The target object to use
- @return {Object} receiver
- */
- forEach: function(callback, target) {
- if (typeof callback !== "function") throw new TypeError() ;
- var len = get(this, 'length'), last = null, context = popCtx();
+ var len = get(this, 'length');
+ this.replace(0, len, objects);
+ return this;
+ },
- if (target === undefined) target = null;
+ // ..........................................................
+ // IMPLEMENT Ember.MutableEnumerable
+ //
- for(var idx=0;idx<len;idx++) {
- var next = this.nextObject(idx, last, context) ;
- callback.call(target, next, idx, this);
- last = next ;
+ removeObject: function(obj) {
+ var loc = get(this, 'length') || 0;
+ while(--loc >= 0) {
+ var curObject = this.objectAt(loc) ;
+ if (curObject === obj) this.removeAt(loc) ;
}
- last = null ;
- context = pushCtx(context);
return this ;
},
- /**
- Alias for mapProperty
+ addObject: function(obj) {
+ if (!this.contains(obj)) this.pushObject(obj);
+ return this ;
+ }
- @method getEach
- @param {String} key name of the property
- @return {Array} The mapped array.
- */
- getEach: function(key) {
- return this.mapProperty(key);
- },
+});
- /**
- Sets the value on the named property for each member. This is more
- efficient than using other methods defined on this helper. If the object
- 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
- @return {Object} receiver
- */
- setEach: function(key, value) {
- return this.forEach(function(item) {
- set(item, key, value);
- });
- },
+})();
- /**
- Maps all of the items in the enumeration to another value, returning
- a new array. This method corresponds to map() defined in JavaScript 1.6.
- The callback method you provide should have the following signature (all
- parameters are optional):
- function(item, index, enumerable);
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
+
+var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty;
+
+/**
+ ## 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.
+
+ 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`
+ call to the end of your method declarations in classes that you write.
+ For example:
+
+ ```javascript
+ Ember.Object.create({
+ valueObserver: function() {
+ // 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
+ these two methods to add and remove observers yourself if you need to
+ do so at runtime.
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ To add an observer for a property, call:
- It should return the mapped value.
+ ```javascript
+ object.addObserver('propertyKey', targetObject, targetAction)
+ ```
- Note that in addition to a callback, you can also pass an optional target
- 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.
+ This will call the `targetAction` method on the `targetObject` to be called
+ whenever the value of the `propertyKey` changes.
- @method map
- @param {Function} callback The callback to execute
- @param {Object} [target] The target object to use
- @return {Array} The mapped array.
- */
- map: function(callback, target) {
- var ret = [];
- this.forEach(function(x, idx, i) {
- ret[idx] = callback.call(target, x, idx,i);
- });
- return ret ;
- },
+ 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.
- /**
- Similar to map, this specialized function returns the value of the named
- property on all items in the enumeration.
+ @class Observable
+ @namespace Ember
+ @extends Ember.Mixin
+*/
+Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ {
- @method mapProperty
- @param {String} key name of the property
- @return {Array} The mapped array.
- */
- mapProperty: function(key) {
- return this.map(function(next) {
- return get(next, key);
- });
- },
+ // compatibility
+ isObserverable: true,
/**
- Returns an array with all of the items in the enumeration that the passed
- function returns true for. This method corresponds to filter() defined in
- JavaScript 1.6.
+ Retrieves the value of a property from the object.
- The callback method you provide should have the following signature (all
- parameters are optional):
+ This method is usually similar to using `object[keyName]` or `object.keyName`,
+ however it supports both computed properties and the unknownProperty
+ handler.
- function(item, index, enumerable);
+ 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.
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ ### Computed Properties
- It should return the true to include the item in the results, false otherwise.
+ Computed properties are methods defined with the `property` modifier
+ declared at the end, such as:
- Note that in addition to a callback, you can also pass an optional target
- 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.
+ ```javascript
+ fullName: function() {
+ return this.getEach('firstName', 'lastName').compact().join(' ');
+ }.property('firstName', 'lastName')
+ ```
- @method filter
- @param {Function} callback The callback to execute
- @param {Object} [target] The target object to use
- @return {Array} A filtered array.
- */
- filter: function(callback, target) {
- var ret = [];
- this.forEach(function(x, idx, i) {
- if (callback.call(target, x, idx, i)) ret.push(x);
- });
- return ret ;
- },
+ When you call `get` on a computed property, the function will be
+ called and the return value will be returned instead of the function
+ itself.
- /**
- Returns an array with just the items with the matched property. You
- can pass an optional second argument with the target value. Otherwise
- this will match any property that evaluates to true.
+ ### Unknown Properties
- @method filterProperty
- @param {String} key the property to test
- @param {String} [value] optional value to test against.
- @return {Array} filtered array
+ Likewise, if you try to call `get` on a property whose value is
+ `undefined`, the `unknownProperty()` method will be called on the object.
+ If this method returns any value other than `undefined`, it will be returned
+ instead. This allows you to implement "virtual" properties that are
+ not defined upfront.
+
+ @method get
+ @param {String} key The property to retrieve
+ @return {Object} The property value or undefined.
*/
- filterProperty: function(key, value) {
- return this.filter(iter.apply(this, arguments));
+ get: function(keyName) {
+ return get(this, keyName);
},
/**
- Returns the first item in the array for which the callback returns true.
- This method works similar to the filter() method defined in JavaScript 1.6
- except that it will stop working on the array once a match is found.
-
- The callback method you provide should have the following signature (all
- parameters are optional):
-
- function(item, index, enumerable);
+ To get multiple properties at once, call `getProperties`
+ with a list of strings or an array:
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ ```javascript
+ record.getProperties('firstName', 'lastName', 'zipCode'); // { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
+ ```
- It should return the true to include the item in the results, false otherwise.
+ is equivalent to:
- Note that in addition to a callback, you can also pass an optional target
- 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.
+ ```javascript
+ record.getProperties(['firstName', 'lastName', 'zipCode']); // { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
+ ```
- @method find
- @param {Function} callback The callback to execute
- @param {Object} [target] The target object to use
- @return {Object} Found item or null.
+ @method getProperties
+ @param {String...|Array} list of keys to get
+ @return {Hash}
*/
- find: function(callback, target) {
- var len = get(this, 'length') ;
- if (target === undefined) target = null;
-
- var last = null, next, found = false, ret ;
- var context = popCtx();
- for(var idx=0;idx<len && !found;idx++) {
- next = this.nextObject(idx, last, context) ;
- if (found = callback.call(target, next, idx, this)) ret = next ;
- last = next ;
+ getProperties: function() {
+ var ret = {};
+ var propertyNames = arguments;
+ if (arguments.length === 1 && Ember.typeOf(arguments[0]) === 'array') {
+ propertyNames = arguments[0];
}
- next = last = null ;
- context = pushCtx(context);
- return ret ;
+ for(var i = 0; i < propertyNames.length; i++) {
+ ret[propertyNames[i]] = get(this, propertyNames[i]);
+ }
+ return ret;
},
/**
- Returns the first item with a property matching the passed value. You
- can pass an optional second argument with the target value. Otherwise
- this will match any property that evaluates to true.
+ Sets the provided key or path to the value.
- This method works much like the more generic find() method.
+ This method is generally very similar to calling `object[key] = value` or
+ `object.key = value`, except that it provides support for computed
+ properties, the `unknownProperty()` method and property observers.
- @method findProperty
- @param {String} key the property to test
- @param {String} [value] optional value to test against.
- @return {Object} found item or null
- */
- findProperty: function(key, value) {
- return this.find(iter.apply(this, arguments));
- },
+ ### Computed Properties
- /**
- Returns true if the passed function returns true for every item in the
- enumeration. This corresponds with the every() method in JavaScript 1.6.
+ If you try to set a value on a key that has a computed property handler
+ defined (see the `get()` method for an example), then `set()` will call
+ that method, passing both the value and key instead of simply changing
+ the value itself. This is useful for those times when you need to
+ implement a property that is composed of one or more member
+ properties.
- The callback method you provide should have the following signature (all
- parameters are optional):
+ ### Unknown Properties
- function(item, index, enumerable);
+ If you try to set a value on a key that is undefined in the target
+ object, then the `unknownProperty()` handler will be called instead. This
+ gives you an opportunity to implement complex "virtual" properties that
+ are not predefined on the object. If `unknownProperty()` returns
+ undefined, then `set()` will simply set the value on the object.
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ ### Property Observers
- It should return the true or false.
+ In addition to changing the property, `set()` will also register a property
+ change with the object. Unless you have placed this call inside of a
+ `beginPropertyChanges()` and `endPropertyChanges(),` any "local" observers
+ (i.e. observer methods declared on the same object), will be called
+ immediately. Any "remote" observers (i.e. observer methods declared on
+ another object) will be placed in a queue and called at a later time in a
+ coalesced manner.
- Note that in addition to a callback, you can also pass an optional target
- 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.
+ ### Chaining
- Example Usage:
+ In addition to property changes, `set()` returns the value of the object
+ itself so you can do chaining like this:
- if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
+ ```javascript
+ record.set('firstName', 'Charles').set('lastName', 'Jolley');
+ ```
- @method every
- @param {Function} callback The callback to execute
- @param {Object} [target] The target object to use
- @return {Boolean}
+ @method set
+ @param {String} key The property to set
+ @param {Object} value The value to set or `null`.
+ @return {Ember.Observable}
*/
- every: function(callback, target) {
- return !this.find(function(x, idx, i) {
- return !callback.call(target, x, idx, i);
- });
+ set: function(keyName, value) {
+ set(this, keyName, value);
+ return this;
},
/**
- 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.
+ To set multiple properties at once, call `setProperties`
+ with a Hash:
- @method everyProperty
- @param {String} key the property to test
- @param {String} [value] optional value to test against.
- @return {Array} filtered array
+ ```javascript
+ record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });
+ ```
+
+ @method setProperties
+ @param {Hash} hash the hash of keys and values to set
+ @return {Ember.Observable}
*/
- everyProperty: function(key, value) {
- return this.every(iter.apply(this, arguments));
+ setProperties: function(hash) {
+ return Ember.setProperties(this, hash);
},
-
/**
- Returns true if the passed function returns true for any item in the
- enumeration. This corresponds with the every() method in JavaScript 1.6.
+ Begins a grouping of property changes.
- The callback method you provide should have the following signature (all
- parameters are optional):
+ You can use this method to group property changes so that notifications
+ will not be sent until the changes are finished. If you plan to make a
+ large number of changes to an object at one time, you should call this
+ method at the beginning of the changes to begin deferring change
+ notifications. When you are done making changes, call
+ `endPropertyChanges()` to deliver the deferred change notifications and end
+ deferring.
- function(item, index, enumerable);
+ @method beginPropertyChanges
+ @return {Ember.Observable}
+ */
+ beginPropertyChanges: function() {
+ Ember.beginPropertyChanges();
+ return this;
+ },
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ /**
+ Ends a grouping of property changes.
+
+ You can use this method to group property changes so that notifications
+ will not be sent until the changes are finished. If you plan to make a
+ large number of changes to an object at one time, you should call
+ `beginPropertyChanges()` at the beginning of the changes to defer change
+ notifications. When you are done making changes, call this method to
+ deliver the deferred change notifications and end deferring.
- It should return the true to include the item in the results, false otherwise.
+ @method endPropertyChanges
+ @return {Ember.Observable}
+ */
+ endPropertyChanges: function() {
+ Ember.endPropertyChanges();
+ return this;
+ },
- Note that in addition to a callback, you can also pass an optional target
- 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.
+ /**
+ Notify the observer system that a property is about to change.
- Usage Example:
+ Sometimes you need to change a value directly or indirectly without
+ actually calling `get()` or `set()` on it. In this case, you can use this
+ method and `propertyDidChange()` instead. Calling these two methods
+ together will notify all observers that the property has potentially
+ changed value.
- if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
+ Note that you must always call `propertyWillChange` and `propertyDidChange`
+ as 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 some
- @param {Function} callback The callback to execute
- @param {Object} [target] The target object to use
- @return {Array} A filtered array.
+ @method propertyWillChange
+ @param {String} key The property key that is about to change.
+ @return {Ember.Observable}
*/
- some: function(callback, target) {
- return !!this.find(function(x, idx, i) {
- return !!callback.call(target, x, idx, i);
- });
+ propertyWillChange: function(keyName){
+ Ember.propertyWillChange(this, keyName);
+ return this;
},
/**
- 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.
+ Notify the observer system that a property has just changed.
- @method someProperty
- @param {String} key the property to test
- @param {String} [value] optional value to test against.
- @return {Boolean} true
+ Sometimes you need to change a value directly or indirectly without
+ actually calling `get()` or `set()` on it. In this case, you can use this
+ method and `propertyWillChange()` instead. Calling these two methods
+ together will notify all observers that the property has potentially
+ changed value.
+
+ Note that you must always call `propertyWillChange` and `propertyDidChange`
+ as 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.
+ @return {Ember.Observable}
*/
- someProperty: function(key, value) {
- return this.some(iter.apply(this, arguments));
+ propertyDidChange: function(keyName) {
+ Ember.propertyDidChange(this, keyName);
+ return this;
},
/**
- This will combine the values of the enumerator into a single value. It
- is a useful way to collect a summary value from an enumeration. This
- corresponds to the reduce() method defined in JavaScript 1.8.
+ Convenience method to call `propertyWillChange` and `propertyDidChange` in
+ succession.
- The callback method you provide should have the following signature (all
- parameters are optional):
+ @method notifyPropertyChange
+ @param {String} keyName The property key to be notified about.
+ @return {Ember.Observable}
+ */
+ notifyPropertyChange: function(keyName) {
+ this.propertyWillChange(keyName);
+ this.propertyDidChange(keyName);
+ return this;
+ },
- function(previousValue, item, index, enumerable);
+ addBeforeObserver: function(key, target, method) {
+ Ember.addBeforeObserver(this, key, target, method);
+ },
- - *previousValue* is the value returned by the last call to the iterator.
- - *item* is the current item in the iteration.
- - *index* is the current index in the iteration
- - *enumerable* is the enumerable object itself.
+ /**
+ Adds an observer on a property.
- Return the new cumulative value.
+ This is the core method used to register an observer for a property.
- In addition to the callback you can also pass an initialValue. An error
- will be raised if you do not pass an initial value and the enumerator is
- empty.
+ Once you call this method, anytime the key's value is set, your observer
+ will be notified. Note that the observers are triggered anytime the
+ value is set, regardless of whether it has actually changed. Your
+ observer should be prepared to handle that.
- Note that unlike the other methods, this method does not allow you to
- pass a target object to set as this for the callback. It's part of the
- spec. Sorry.
+ You can also pass an optional context parameter to this method. The
+ context will be passed to your observer method whenever it is triggered.
+ Note that if you add the same target/method pair on a key multiple times
+ with different context parameters, your observer will only be called once
+ with the last context you passed.
- @method reduce
- @param {Function} callback The callback to execute
- @param {Object} initialValue Initial value for the reduce
- @param {String} reducerProperty internal use only.
- @return {Object} The reduced value.
- */
- reduce: function(callback, initialValue, reducerProperty) {
- if (typeof callback !== "function") { throw new TypeError(); }
+ ### Observer Methods
- var ret = initialValue;
+ Observer methods you pass should generally have the following signature if
+ you do not pass a `context` parameter:
- this.forEach(function(item, i) {
- ret = callback.call(null, ret, item, i, this, reducerProperty);
- }, this);
+ ```javascript
+ fooDidChange: function(sender, key, value, rev) { };
+ ```
- return ret;
- },
+ The sender is the object that changed. The key is the property that
+ changes. The value property is currently reserved and unused. The rev
+ is the last property revision of the object when it changed, which you can
+ use to detect if the key value has really changed or not.
- /**
- Invokes the named method on every object in the receiver that
- implements it. This method corresponds to the implementation in
- Prototype 1.6.
+ If you pass a `context` parameter, the context will be passed before the
+ revision like so:
- @method invoke
- @param {String} methodName the name of the method
- @param {Object...} args optional arguments to pass as well.
- @return {Array} return values from calling invoke.
- */
- invoke: function(methodName) {
- var args, ret = [];
- if (arguments.length>1) args = a_slice.call(arguments, 1);
+ ```javascript
+ fooDidChange: function(sender, key, value, context, rev) { };
+ ```
- this.forEach(function(x, idx) {
- var method = x && x[methodName];
- if ('function' === typeof method) {
- ret[idx] = args ? method.apply(x, args) : method.call(x);
- }
- }, this);
+ Usually you will not need the value, context or revision parameters at
+ the end. In this case, it is common to write observer methods that take
+ 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.
- return ret;
+ @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.
+ @return {Ember.Object} self
+ */
+ addObserver: function(key, target, method) {
+ Ember.addObserver(this, key, target, method);
},
/**
- Simply converts the enumerable into a genuine array. The order is not
- guaranteed. Corresponds to the method implemented by Prototype.
+ Remove an observer you have previously registered on this object. Pass
+ the same key, target, and method you passed to `addObserver()` and your
+ target will no longer receive notifications.
- @method toArray
- @return {Array} the enumerable as an array.
+ @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.
+ @return {Ember.Observable} receiver
*/
- toArray: function() {
- var ret = [];
- this.forEach(function(o, idx) { ret[idx] = o; });
- return ret ;
+ removeObserver: function(key, target, method) {
+ Ember.removeObserver(this, key, target, method);
},
/**
- Returns a copy of the array with all null elements removed.
-
- var arr = ["a", null, "c", null];
- arr.compact(); => ["a", "c"]
+ Returns `true` if the object currently has observers registered for a
+ particular key. You can use this method to potentially defer performing
+ an expensive action until someone begins observing a particular property
+ on the object.
- @method compact
- @return {Array} the array without null elements.
+ @method hasObserverFor
+ @param {String} key Key to check
+ @return {Boolean}
*/
- compact: function() { return this.without(null); },
+ hasObserverFor: function(key) {
+ return Ember.hasListeners(this, key+':change');
+ },
/**
- Returns a new enumerable that excludes the passed value. The default
- implementation returns an array regardless of the receiver type unless
- the receiver does not contain the value.
-
- var arr = ["a", "b", "a", "c"];
- arr.without("a"); => ["b", "c"]
-
- @method without
- @param {Object} value
- @return {Ember.Enumerable}
+ @deprecated
+ @method getPath
+ @param {String} path The property path to retrieve
+ @return {Object} The property value or undefined.
*/
- without: function(value) {
- if (!this.contains(value)) return this; // nothing to do
- var ret = [] ;
- this.forEach(function(k) {
- if (k !== value) ret[ret.length] = k;
- }) ;
- return ret ;
+ getPath: function(path) {
+ Ember.deprecate("getPath is deprecated since get now supports paths");
+ return this.get(path);
},
/**
- Returns a new enumerable that contains only unique values. The default
- implementation returns an array regardless of the receiver type.
-
- var arr = ["a", "a", "b", "b"];
- arr.uniq(); => ["a", "b"]
-
- @method uniq
- @return {Ember.Enumerable}
+ @deprecated
+ @method setPath
+ @param {String} path The path to the property that will be set
+ @param {Object} value The value to set or `null`.
+ @return {Ember.Observable}
*/
- uniq: function() {
- var ret = [];
- this.forEach(function(k){
- if (a_indexOf(ret, k)<0) ret.push(k);
- });
- return ret;
+ setPath: function(path, value) {
+ Ember.deprecate("setPath is deprecated since set now supports paths");
+ return this.set(path, value);
},
/**
- This property will trigger anytime the enumerable's content changes.
- You can observe this property to be notified of changes to the enumerables
- content.
+ Retrieves the value of a property, or a default value in the case that the
+ property returns `undefined`.
- For plain enumerables, this property is read only. Ember.Array overrides
- this method.
+ ```javascript
+ person.getWithDefault('lastName', 'Doe');
+ ```
- @property []
- @type Ember.Array
+ @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
+ @return {Object} The property value or the defaultValue.
*/
- '[]': Ember.computed(function(key, value) {
- return this;
- }).property().cacheable(),
-
- // ..........................................................
- // ENUMERABLE OBSERVERS
- //
+ getWithDefault: function(keyName, defaultValue) {
+ return Ember.getWithDefault(this, keyName, defaultValue);
+ },
/**
- Registers an enumerable observer. Must implement Ember.EnumerableObserver
- mixin.
+ Set the value of a property to the current value plus some amount.
- @method addEnumerableObserver
- @param target {Object}
- @param opts {Hash}
- */
- addEnumerableObserver: function(target, opts) {
- var willChange = (opts && opts.willChange) || 'enumerableWillChange',
- didChange = (opts && opts.didChange) || 'enumerableDidChange';
+ ```javascript
+ person.incrementProperty('age');
+ team.incrementProperty('score', 2);
+ ```
- var hasObservers = get(this, 'hasEnumerableObservers');
- if (!hasObservers) Ember.propertyWillChange(this, 'hasEnumerableObservers');
- Ember.addListener(this, '@enumerable:before', target, willChange);
- Ember.addListener(this, '@enumerable:change', target, didChange);
- if (!hasObservers) Ember.propertyDidChange(this, 'hasEnumerableObservers');
- return this;
+ @method incrementProperty
+ @param {String} keyName The name of the property to increment
+ @param {Object} increment The amount to increment by. Defaults to 1
+ @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);
},
/**
- Removes a registered enumerable observer.
+ Set the value of a property to the current value minus some amount.
- @method removeEnumerableObserver
- @param target {Object}
- @param [opts] {Hash}
- */
- removeEnumerableObserver: function(target, opts) {
- var willChange = (opts && opts.willChange) || 'enumerableWillChange',
- didChange = (opts && opts.didChange) || 'enumerableDidChange';
+ ```javascript
+ player.decrementProperty('lives');
+ orc.decrementProperty('health', 5);
+ ```
- var hasObservers = get(this, 'hasEnumerableObservers');
- if (hasObservers) Ember.propertyWillChange(this, 'hasEnumerableObservers');
- Ember.removeListener(this, '@enumerable:before', target, willChange);
- Ember.removeListener(this, '@enumerable:change', target, didChange);
- if (hasObservers) Ember.propertyDidChange(this, 'hasEnumerableObservers');
- return this;
+ @method decrementProperty
+ @param {String} keyName The name of the property to decrement
+ @param {Object} increment The amount to decrement by. Defaults to 1
+ @return {Object} The new property value
+ */
+ decrementProperty: function(keyName, increment) {
+ if (!increment) { increment = 1; }
+ set(this, keyName, (get(this, keyName) || 0)-increment);
+ return get(this, keyName);
},
/**
- Becomes true whenever the array currently has observers watching changes
- on the array.
+ Set the value of a boolean property to the opposite of it's
+ current value.
- @property hasEnumerableObservers
- @type Boolean
- */
- hasEnumerableObservers: Ember.computed(function() {
- return Ember.hasListeners(this, '@enumerable:change') || Ember.hasListeners(this, '@enumerable:before');
- }).property().cacheable(),
+ ```javascript
+ starship.toggleProperty('warpDriveEnaged');
+ ```
+ @method toggleProperty
+ @param {String} keyName The name of the property to toggle
+ @return {Object} The new property value
+ */
+ toggleProperty: function(keyName) {
+ set(this, keyName, !get(this, keyName));
+ return get(this, keyName);
+ },
/**
- Invoke this method just before the contents of your enumerable will
- change. You can either omit the parameters completely or pass the objects
- to be removed or added if available or just a count.
+ Returns the cached value of a computed property, if it exists.
+ This allows you to inspect the value of a computed property
+ without accidentally invoking it if it is intended to be
+ generated lazily.
- @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
+ @method cacheFor
+ @param {String} keyName
+ @return {Object} The cached value of the computed property, if any
*/
- enumerableContentWillChange: function(removing, adding) {
-
- var removeCnt, addCnt, hasDelta;
+ cacheFor: function(keyName) {
+ return Ember.cacheFor(this, keyName);
+ },
- if ('number' === typeof removing) removeCnt = removing;
- else if (removing) removeCnt = get(removing, 'length');
- else removeCnt = removing = -1;
+ // intended for debugging purposes
+ observersForKey: function(keyName) {
+ return Ember.observersFor(this, keyName);
+ }
+});
- if ('number' === typeof adding) addCnt = adding;
- else if (adding) addCnt = get(adding,'length');
- else addCnt = adding = -1;
- hasDelta = addCnt<0 || removeCnt<0 || addCnt-removeCnt!==0;
+})();
- if (removing === -1) removing = null;
- if (adding === -1) adding = null;
- Ember.propertyWillChange(this, '[]');
- if (hasDelta) Ember.propertyWillChange(this, 'length');
- Ember.sendEvent(this, '@enumerable:before', [this, removing, adding]);
- return this;
- },
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- /**
- Invoke this method when the contents of your enumerable has changed.
- This will notify any observers watching for content changes. If your are
- implementing an ordered enumerable (such as an array), also pass the
- start and end values where the content changed so that it can be used to
- notify range observers.
+var get = Ember.get, set = Ember.set;
- @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;
+/**
+@class TargetActionSupport
+@namespace Ember
+@extends Ember.Mixin
+*/
+Ember.TargetActionSupport = Ember.Mixin.create({
+ target: null,
+ action: null,
- if ('number' === typeof removing) removeCnt = removing;
- else if (removing) removeCnt = get(removing, 'length');
- else removeCnt = removing = -1;
+ targetObject: Ember.computed(function() {
+ var target = get(this, 'target');
- if ('number' === typeof adding) addCnt = adding;
- else if (adding) addCnt = get(adding, 'length');
- else addCnt = adding = -1;
+ if (Ember.typeOf(target) === "string") {
+ var value = get(this, target);
+ if (value === undefined) { value = get(Ember.lookup, target); }
+ return value;
+ } else {
+ return target;
+ }
+ }).property('target'),
- hasDelta = addCnt<0 || removeCnt<0 || addCnt-removeCnt!==0;
+ triggerAction: function() {
+ var action = get(this, 'action'),
+ target = get(this, 'targetObject');
- if (removing === -1) removing = null;
- if (adding === -1) adding = null;
+ if (target && action) {
+ var ret;
- Ember.sendEvent(this, '@enumerable:change', [this, removing, adding]);
- if (hasDelta) Ember.propertyDidChange(this, 'length');
- Ember.propertyDidChange(this, '[]');
+ if (typeof target.send === 'function') {
+ ret = target.send(action, this);
+ } else {
+ if (typeof action === 'string') {
+ action = target[action];
+ }
+ ret = action.call(target, this);
+ }
+ if (ret !== false) ret = true;
- return this ;
+ return ret;
+ } else {
+ return false;
+ }
}
-
-}) ;
-
-
-
+});
})();
@submodule ember-runtime
*/
-// ..........................................................
-// HELPERS
-//
-
-var get = Ember.get, set = Ember.set, meta = Ember.meta, map = Ember.EnumerableUtils.map, cacheFor = Ember.cacheFor;
-
-function none(obj) { return obj===null || obj===undefined; }
-
-// ..........................................................
-// ARRAY
-//
/**
- 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.
+ This mixin allows for Ember objects to subscribe to and emit events.
- Unlike Ember.Enumerable, this mixin defines methods specifically for
- collections that provide index-ordered access to their contents. When you
- are designing code that needs to accept any kind of Array-like object, you
- should use these methods instead of Array primitives because these will
- properly notify observers of changes to the array.
+ ```javascript
+ App.Person = Ember.Object.extend(Ember.Evented, {
+ greet: function() {
+ // ...
+ this.trigger('greet');
+ }
+ });
- Although these methods are efficient, they do add a layer of indirection to
- your application so it is a good idea to use them only when you need the
- flexibility of using both true JavaScript arrays and "virtual" arrays such
- as controllers and collections.
+ var person = App.Person.create();
- You can use the methods defined in this module to access and modify array
- contents in a KVO-friendly way. You can also be notified whenever the
- membership if an array changes by changing the syntax of the property to
- .observes('*myProperty.[]') .
+ person.on('greet', function() {
+ console.log('Our person has greeted');
+ });
- To support Ember.Array in your own class, you must override two
- primitives to use it: replace() and objectAt().
+ person.greet();
- Note that the Ember.Array mixin also incorporates the Ember.Enumerable mixin. All
- Ember.Array-like objects are also enumerable.
+ // outputs: 'Our person has greeted'
+ ```
- @class Array
+ @class Evented
@namespace Ember
@extends Ember.Mixin
- @uses Ember.Enumerable
- @since Ember 0.9.0
-*/
-Ember.Array = Ember.Mixin.create(Ember.Enumerable, /** @scope Ember.Array.prototype */ {
-
- // compatibility
- isSCArray: true,
+ */
+Ember.Evented = Ember.Mixin.create({
/**
- Your array must support the length property. Your replace methods should
- set this property whenever it changes.
+ Subscribes to a named event with given function.
- @property {Number} length
+ ```javascript
+ person.on('didLoad', function() {
+ // fired once the person has loaded
+ });
+ ```
+
+ An optional target can be passed in as the 2nd argument that will
+ be set as the "this" for the callback. This is a good way to give your
+ function access to the object triggering the event. When the target
+ parameter is used the callback becomes the third argument.
+
+ @method on
+ @param {String} name The name of the event
+ @param {Object} [target] The "this" binding for the callback
+ @param {Function} method The callback to execute
*/
- length: Ember.required(),
+ on: function(name, target, method) {
+ Ember.addListener(this, name, target, method);
+ },
/**
- Returns the object at the given index. If the given index is negative or
- is greater or equal than the array length, returns `undefined`.
-
- This is one of the primitives you must implement to support `Ember.Array`.
- If your object supports retrieving the value of an array item using `get()`
- (i.e. `myArray.get(0)`), then you do not need to implement this method
- yourself.
+ Subscribes a function to a named event and then cancels the subscription
+ after the first time the event is triggered. It is good to use ``one`` when
+ you only care about the first time an event has taken place.
- var arr = ['a', 'b', 'c', 'd'];
- arr.objectAt(0); => "a"
- arr.objectAt(3); => "d"
- arr.objectAt(-1); => undefined
- arr.objectAt(4); => undefined
- arr.objectAt(5); => undefined
+ This function takes an optional 2nd argument that will become the "this"
+ value for the callback. If this argument is passed then the 3rd argument
+ becomes the function.
- @method objectAt
- @param {Number} idx
- The index of the item to return.
+ @method one
+ @param {String} name The name of the event
+ @param {Object} [target] The "this" binding for the callback
+ @param {Function} method The callback to execute
*/
- objectAt: function(idx) {
- if ((idx < 0) || (idx>=get(this, 'length'))) return undefined ;
- return get(this, idx);
+ one: function(name, target, method) {
+ if (!method) {
+ method = target;
+ target = null;
+ }
+
+ Ember.addListener(this, name, target, method, true);
},
/**
- This returns the objects at the specified indexes, using `objectAt`.
+ Triggers a named event for the object. Any additional arguments
+ will be passed as parameters to the functions that are subscribed to the
+ event.
- var arr = ['a', 'b', 'c', 'd'];
- arr.objectsAt([0, 1, 2]) => ["a", "b", "c"]
- arr.objectsAt([2, 3, 4]) => ["c", "d", undefined]
+ ```javascript
+ person.on('didEat', food) {
+ console.log('person ate some ' + food);
+ });
- @method objectsAt
- @param {Array} indexes
- An array of indexes of items to return.
- */
- objectsAt: function(indexes) {
- var self = this;
- return map(indexes, function(idx){ return self.objectAt(idx); });
+ person.trigger('didEat', 'broccoli');
+
+ // outputs: person ate some broccoli
+ ```
+ @method trigger
+ @param {String} name The name of the event
+ @param {Object...} args Optional arguments to pass on
+ */
+ trigger: function(name) {
+ var args = [], i, l;
+ for (i = 1, l = arguments.length; i < l; i++) {
+ args.push(arguments[i]);
+ }
+ Ember.sendEvent(this, name, args);
},
- // overrides Ember.Enumerable version
- nextObject: function(idx) {
- return this.objectAt(idx);
+ fire: function(name) {
+ Ember.deprecate("Ember.Evented#fire() has been deprecated in favor of trigger() for compatibility with jQuery. It will be removed in 1.0. Please update your code to call trigger() instead.");
+ this.trigger.apply(this, arguments);
},
/**
- 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.
+ Cancels subscription for give name, target, and method.
- @property []
+ @method off
+ @param {String} name The name of the event
+ @param {Object} target The target of the subscription
+ @param {Function} method The function of the subscription
*/
- '[]': Ember.computed(function(key, value) {
- if (value !== undefined) this.replace(0, get(this, 'length'), value) ;
- return this ;
- }).property().cacheable(),
+ off: function(name, target, method) {
+ Ember.removeListener(this, name, target, method);
+ },
+
+ /**
+ Checks to see if object has any subscriptions for named event.
+
+ @method has
+ @param {String} name The name of the event
+ @return {Boolean} does the object have a subscription for event
+ */
+ has: function(name) {
+ return Ember.hasListeners(this, name);
+ }
+});
+
+})();
+
+
+
+(function() {
+var RSVP = requireModule("rsvp");
+
+RSVP.async = function(callback, binding) {
+ Ember.run.schedule('actions', binding, callback);
+};
+
+/**
+@module ember
+@submodule ember-runtime
+*/
- firstObject: Ember.computed(function() {
- return this.objectAt(0);
- }).property().cacheable(),
+var get = Ember.get,
+ slice = Array.prototype.slice;
- lastObject: Ember.computed(function() {
- return this.objectAt(get(this, 'length')-1);
- }).property().cacheable(),
+/**
+ @class Deferred
+ @namespace Ember
+ @extends Ember.Mixin
+ */
+Ember.DeferredMixin = Ember.Mixin.create({
+ /**
+ Add handlers to be called when the Deferred object is resolved or rejected.
- // optimized version from Enumerable
- contains: function(obj){
- return this.indexOf(obj) >= 0;
+ @method then
+ @param {Function} doneCallback a callback function to be called when done
+ @param {Function} failCallback a callback function to be called when failed
+ */
+ then: function(doneCallback, failCallback) {
+ var promise = get(this, 'promise');
+ return promise.then.apply(promise, arguments);
},
- // Add any extra methods to Ember.Array that are native to the built-in Array.
/**
- Returns a new array that is a slice of the receiver. This implementation
- uses the observable array methods to retrieve the objects for the new
- slice.
-
- var arr = ['red', 'green', 'blue'];
- arr.slice(0); => ['red', 'green', 'blue']
- arr.slice(0, 2); => ['red', 'green']
- arr.slice(1, 100); => ['green', 'blue']
+ Resolve a Deferred object and call any `doneCallbacks` with the given args.
- @method slice
- @param beginIndex {Integer} (Optional) index to begin slicing from.
- @param endIndex {Integer} (Optional) index to end the slice at.
- @return {Array} New array with specified slice
+ @method resolve
*/
- slice: function(beginIndex, endIndex) {
- var ret = [];
- var length = get(this, 'length') ;
- if (none(beginIndex)) beginIndex = 0 ;
- if (none(endIndex) || (endIndex > length)) endIndex = length ;
- while(beginIndex < endIndex) {
- ret[ret.length] = this.objectAt(beginIndex++) ;
- }
- return ret ;
+ resolve: function(value) {
+ get(this, 'promise').resolve(value);
},
/**
- Returns the index of the given object's first occurrence.
- If no startAt argument is given, the starting location to
- search is 0. If it's negative, will count backward from
- the end of the array. Returns -1 if no match is found.
+ Reject a Deferred object and call any `failCallbacks` with the given args.
- var arr = ["a", "b", "c", "d", "a"];
- arr.indexOf("a"); => 0
- arr.indexOf("z"); => -1
- arr.indexOf("a", 2); => 4
- arr.indexOf("a", -1); => 4
- 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
- @return {Number} index or -1 if not found
+ @method reject
*/
- indexOf: function(object, startAt) {
- var idx, len = get(this, 'length');
+ reject: function(value) {
+ get(this, 'promise').reject(value);
+ },
- if (startAt === undefined) startAt = 0;
- if (startAt < 0) startAt += len;
+ promise: Ember.computed(function() {
+ return new RSVP.Promise();
+ })
+});
- for(idx=startAt;idx<len;idx++) {
- if (this.objectAt(idx, true) === object) return idx ;
- }
- return -1;
- },
- /**
- Returns the index of the given object's last occurrence.
- If no startAt argument is given, the search starts from
- the last position. If it's negative, will count backward
- from the end of the array. Returns -1 if no match is found.
+})();
- var arr = ["a", "b", "c", "d", "a"];
- arr.lastIndexOf("a"); => 4
- arr.lastIndexOf("z"); => -1
- arr.lastIndexOf("a", 2); => 0
- arr.lastIndexOf("a", -1); => 4
- 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
- @return {Number} index or -1 if not found
- */
- lastIndexOf: function(object, startAt) {
- var idx, len = get(this, 'length');
- if (startAt === undefined || startAt >= len) startAt = len-1;
- if (startAt < 0) startAt += len;
+(function() {
- for(idx=startAt;idx>=0;idx--) {
- if (this.objectAt(idx) === object) return idx ;
- }
- return -1;
- },
+})();
- // ..........................................................
- // ARRAY OBSERVERS
- //
- /**
- Adds an array observer to the receiving array. The array observer object
- normally must implement two methods:
- * `arrayWillChange(start, removeCount, addCount)` - This method will be
- called just before the array is modified.
- * `arrayDidChange(start, removeCount, addCount)` - This method will be
- called just after the array is modified.
+(function() {
+Ember.Container = requireModule('container');
+Ember.Container.set = Ember.set;
- Both callbacks will be passed the starting index of the change as well a
- a count of the items to be removed and added. You can use these callbacks
- to optionally inspect the array during the change, clear caches, or do
- any other bookkeeping necessary.
+})();
- In addition to passing a target, you can also include an options hash
- which you can use to override the method names that will be invoked on the
- target.
- @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',
- didChange = (opts && opts.didChange) || 'arrayDidChange';
- var hasObservers = get(this, 'hasArrayObservers');
- if (!hasObservers) Ember.propertyWillChange(this, 'hasArrayObservers');
- Ember.addListener(this, '@array:before', target, willChange);
- Ember.addListener(this, '@array:change', target, didChange);
- if (!hasObservers) Ember.propertyDidChange(this, 'hasArrayObservers');
- return this;
- },
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- /**
- Removes an array observer from the object if the observer is current
- registered. Calling this method multiple times with the same object will
- have no effect.
- @method removeArrayObserver
- @param {Object} target The object observing the array.
- @return {Ember.Array} receiver
- */
- removeArrayObserver: function(target, opts) {
- var willChange = (opts && opts.willChange) || 'arrayWillChange',
- didChange = (opts && opts.didChange) || 'arrayDidChange';
+// NOTE: this object should never be included directly. Instead use Ember.
+// Ember.Object. We only define this separately so that Ember.Set can depend on it
- var hasObservers = get(this, 'hasArrayObservers');
- if (hasObservers) Ember.propertyWillChange(this, 'hasArrayObservers');
- Ember.removeListener(this, '@array:before', target, willChange);
- Ember.removeListener(this, '@array:change', target, didChange);
- if (hasObservers) Ember.propertyDidChange(this, 'hasArrayObservers');
- return this;
- },
- /**
- Becomes true whenever the array currently has observers watching changes
- on the array.
+var set = Ember.set, get = Ember.get,
+ o_create = Ember.create,
+ o_defineProperty = Ember.platform.defineProperty,
+ a_slice = Array.prototype.slice,
+ GUID_KEY = Ember.GUID_KEY,
+ guidFor = Ember.guidFor,
+ generateGuid = Ember.generateGuid,
+ meta = Ember.meta,
+ rewatch = Ember.rewatch,
+ finishChains = Ember.finishChains,
+ destroy = Ember.destroy,
+ schedule = Ember.run.schedule,
+ Mixin = Ember.Mixin,
+ applyMixin = Mixin._apply,
+ finishPartial = Mixin.finishPartial,
+ reopen = Mixin.prototype.reopen,
+ MANDATORY_SETTER = Ember.ENV.MANDATORY_SETTER,
+ indexOf = Ember.EnumerableUtils.indexOf;
- @property Boolean
- */
- hasArrayObservers: Ember.computed(function() {
- return Ember.hasListeners(this, '@array:change') || Ember.hasListeners(this, '@array:before');
- }).property().cacheable(),
+var undefinedDescriptor = {
+ configurable: true,
+ writable: true,
+ enumerable: false,
+ value: undefined
+};
- /**
- If you are implementing an object that supports Ember.Array, call this
- method just before the array content changes to notify any observers and
- invalidate any related properties. Pass the starting index of the change
- as well as a delta of the amounts to change.
+function makeCtor() {
- @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) {
+ // Note: avoid accessing any properties on the object since it makes the
+ // method a lot faster. This is glue code so we want it to be as fast as
+ // possible.
- // if no args are passed assume everything changes
- if (startIdx===undefined) {
- startIdx = 0;
- removeAmt = addAmt = -1;
- } else {
- if (removeAmt === undefined) removeAmt=-1;
- if (addAmt === undefined) addAmt=-1;
+ var wasApplied = false, initMixins, initProperties;
+
+ var Class = function() {
+ if (!wasApplied) {
+ Class.proto(); // prepare prototype...
+ }
+ o_defineProperty(this, GUID_KEY, undefinedDescriptor);
+ o_defineProperty(this, '_super', undefinedDescriptor);
+ var m = meta(this);
+ m.proto = this;
+ if (initMixins) {
+ // capture locally so we can clear the closed over variable
+ var mixins = initMixins;
+ initMixins = null;
+ this.reopen.apply(this, mixins);
}
+ if (initProperties) {
+ // capture locally so we can clear the closed over variable
+ var props = initProperties;
+ initProperties = null;
- // Make sure the @each proxy is set up if anyone is observing @each
- if (Ember.isWatching(this, '@each')) { get(this, '@each'); }
+ var concatenatedProperties = this.concatenatedProperties;
- Ember.sendEvent(this, '@array:before', [this, startIdx, removeAmt, addAmt]);
+ for (var i = 0, l = props.length; i < l; i++) {
+ var properties = props[i];
+ for (var keyName in properties) {
+ if (!properties.hasOwnProperty(keyName)) { continue; }
- var removing, lim;
- if (startIdx>=0 && removeAmt>=0 && get(this, 'hasEnumerableObservers')) {
- removing = [];
- lim = startIdx+removeAmt;
- for(var idx=startIdx;idx<lim;idx++) removing.push(this.objectAt(idx));
- } else {
- removing = removeAmt;
- }
+ var value = properties[keyName],
+ IS_BINDING = Ember.IS_BINDING;
- this.enumerableContentWillChange(removing, addAmt);
+ if (IS_BINDING.test(keyName)) {
+ var bindings = m.bindings;
+ if (!bindings) {
+ bindings = m.bindings = {};
+ } else if (!m.hasOwnProperty('bindings')) {
+ bindings = m.bindings = o_create(m.bindings);
+ }
+ bindings[keyName] = value;
+ }
- return this;
- },
+ var desc = m.descs[keyName];
- arrayContentDidChange: function(startIdx, removeAmt, addAmt) {
+ Ember.assert("Ember.Object.create no longer supports defining computed properties.", !(value instanceof Ember.ComputedProperty));
+ Ember.assert("Ember.Object.create no longer supports defining methods that call _super.", !(typeof value === 'function' && value.toString().indexOf('._super') !== -1));
- // if no args are passed assume everything changes
- if (startIdx===undefined) {
- startIdx = 0;
- removeAmt = addAmt = -1;
- } else {
- if (removeAmt === undefined) removeAmt=-1;
- if (addAmt === undefined) addAmt=-1;
+ if (concatenatedProperties && indexOf(concatenatedProperties, keyName) >= 0) {
+ var baseValue = this[keyName];
+
+ if (baseValue) {
+ if ('function' === typeof baseValue.concat) {
+ value = baseValue.concat(value);
+ } else {
+ value = Ember.makeArray(baseValue).concat(value);
+ }
+ } else {
+ value = Ember.makeArray(value);
+ }
+ }
+
+ if (desc) {
+ desc.set(this, keyName, value);
+ } else {
+ if (typeof this.setUnknownProperty === 'function' && !(keyName in this)) {
+ this.setUnknownProperty(keyName, value);
+ } else if (MANDATORY_SETTER) {
+ Ember.defineProperty(this, keyName, null, value); // setup mandatory setter
+ } else {
+ this[keyName] = value;
+ }
+ }
+ }
+ }
+ }
+ finishPartial(this, m);
+ delete m.proto;
+ finishChains(this);
+ this.init.apply(this, arguments);
+ };
+
+ Class.toString = Mixin.prototype.toString;
+ Class.willReopen = function() {
+ if (wasApplied) {
+ Class.PrototypeMixin = Mixin.create(Class.PrototypeMixin);
}
- var adding, lim;
- if (startIdx>=0 && addAmt>=0 && get(this, 'hasEnumerableObservers')) {
- adding = [];
- lim = startIdx+addAmt;
- for(var idx=startIdx;idx<lim;idx++) adding.push(this.objectAt(idx));
- } else {
- adding = addAmt;
+ wasApplied = false;
+ };
+ Class._initMixins = function(args) { initMixins = args; };
+ Class._initProperties = function(args) { initProperties = args; };
+
+ Class.proto = function() {
+ var superclass = Class.superclass;
+ if (superclass) { superclass.proto(); }
+
+ if (!wasApplied) {
+ wasApplied = true;
+ Class.PrototypeMixin.applyPartial(Class.prototype);
+ rewatch(Class.prototype);
}
- this.enumerableContentDidChange(removeAmt, adding);
- Ember.sendEvent(this, '@array:change', [this, startIdx, removeAmt, addAmt]);
+ return this.prototype;
+ };
+
+ return Class;
+
+}
+
+var CoreObject = makeCtor();
- var length = get(this, 'length'),
- cachedFirst = cacheFor(this, 'firstObject'),
- cachedLast = cacheFor(this, 'lastObject');
- if (this.objectAt(0) !== cachedFirst) {
- Ember.propertyWillChange(this, 'firstObject');
- Ember.propertyDidChange(this, 'firstObject');
- }
- if (this.objectAt(length-1) !== cachedLast) {
- Ember.propertyWillChange(this, 'lastObject');
- Ember.propertyDidChange(this, 'lastObject');
- }
+CoreObject.PrototypeMixin = Mixin.create({
+ reopen: function() {
+ applyMixin(this, arguments, true);
return this;
},
- // ..........................................................
- // ENUMERATED PROPERTIES
- //
+ isInstance: true,
+
+ init: function() {},
/**
- Returns a special object that can be used to observe individual properties
- 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.
+ Defines the properties that will be concatenated from the superclass
+ (instead of overridden).
- @property @each
- */
- '@each': Ember.computed(function() {
- if (!this.__each) this.__each = new Ember.EachProxy(this);
- return this.__each;
- }).property().cacheable()
+ By default, when you extend an Ember class a property defined in
+ the subclass overrides a property with the same name that is defined
+ in the superclass. However, there are some cases where it is preferable
+ to build up a property's value by combining the superclass' property
+ value with the subclass' value. An example of this in use within Ember
+ is the `classNames` property of `Ember.View`.
-}) ;
+ Here is some sample code showing the difference between a concatenated
+ property and a normal one:
-})();
+ ```javascript
+ App.BarView = Ember.View.extend({
+ someNonConcatenatedProperty: ['bar'],
+ classNames: ['bar']
+ });
+ App.FooBarView = App.BarView.extend({
+ someNonConcatenatedProperty: ['foo'],
+ classNames: ['foo'],
+ });
+ var fooBarView = App.FooBarView.create();
+ fooBarView.get('someNonConcatenatedProperty'); // ['foo']
+ fooBarView.get('classNames'); // ['ember-view', 'bar', 'foo']
+ ```
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ This behavior extends to object creation as well. Continuing the
+ above example:
+ ```javascript
+ var view = App.FooBarView.create({
+ someNonConcatenatedProperty: ['baz'],
+ classNames: ['baz']
+ })
+ view.get('someNonConcatenatedProperty'); // ['baz']
+ view.get('classNames'); // ['ember-view', 'bar', 'foo', 'baz']
+ ```
+ Adding a single property that is not an array will just add it in the array:
+
+ ```javascript
+ var view = App.FooBarView.create({
+ classNames: 'baz'
+ })
+ view.get('classNames'); // ['ember-view', 'bar', 'foo', 'baz']
+ ```
+
+ Using the `concatenatedProperties` property, we can tell to Ember that mix
+ the content of the properties.
-/**
- Implements some standard methods for comparing objects. Add this mixin to
- any class you create that can compare its instances.
+ In `Ember.View` the `classNameBindings` and `attributeBindings` properties
+ are also concatenated, in addition to `classNames`.
- You should implement the compare() method.
+ This feature is available for you to use throughout the Ember object model,
+ although typical app developers are likely to use it infrequently.
- @class Comparable
- @namespace Ember
- @extends Ember.Mixin
- @since Ember 0.9
-*/
-Ember.Comparable = Ember.Mixin.create( /** @scope Ember.Comparable.prototype */{
+ @property concatenatedProperties
+ @type Array
+ @default null
+ */
+ concatenatedProperties: null,
/**
- walk like a duck. Indicates that the object can be compared.
+ @property isDestroyed
+ @default false
+ */
+ isDestroyed: false,
- @property isComparable
- @type Boolean
- @default true
+ /**
+ @property isDestroying
+ @default false
*/
- isComparable: true,
+ isDestroying: false,
/**
- Override to return the result of the comparison of the two parameters. The
- compare method should return:
+ Destroys an object by setting the `isDestroyed` flag and removing its
+ metadata, which effectively destroys observers and bindings.
- - `-1` if `a < b`
- - `0` if `a == b`
- - `1` if `a > b`
+ If you try to set a property on a destroyed object, an exception will be
+ raised.
- Default implementation raises an exception.
+ Note that destruction is scheduled for the end of the run loop and does not
+ happen immediately.
- @method compare
- @param a {Object} the first object to compare
- @param b {Object} the second object to compare
- @return {Integer} the result of the comparison
+ @method destroy
+ @return {Ember.Object} receiver
*/
- compare: Ember.required(Function)
+ destroy: function() {
+ if (this.isDestroying) { return; }
-});
+ this.isDestroying = true;
+ if (this.willDestroy) { this.willDestroy(); }
-})();
+ schedule('destroy', this, this._scheduledDestroy);
+ return this;
+ },
+ /**
+ @private
+ Invoked by the run loop to actually destroy the object. This is
+ scheduled for execution by the `destroy` method.
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ @method _scheduledDestroy
+ */
+ _scheduledDestroy: function() {
+ destroy(this);
+ set(this, 'isDestroyed', true);
+ if (this.didDestroy) { this.didDestroy(); }
+ },
+ bind: function(to, from) {
+ if (!(from instanceof Ember.Binding)) { from = Ember.Binding.from(from); }
+ from.to(to).connect(this);
+ return from;
+ },
-var get = Ember.get, set = Ember.set;
+ /**
+ Returns a string representation which attempts to provide more information
+ than Javascript's `toString` typically does, in a generic way for all Ember
+ objects.
-/**
- 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.
+ App.Person = Em.Object.extend()
+ person = App.Person.create()
+ person.toString() //=> "<App.Person:ember1024>"
- You should generally implement the copy() method to return a copy of the
- receiver.
+ If the object's class is not defined on an Ember namespace, it will
+ indicate it is a subclass of the registered superclass:
- Note that frozenCopy() will only work if you also implement Ember.Freezable.
+ Student = App.Person.extend()
+ student = Student.create()
+ student.toString() //=> "<(subclass of App.Person):ember1025>"
- @class Copyable
- @namespace Ember
- @extends Ember.Mixin
- @since Ember 0.9
-*/
-Ember.Copyable = Ember.Mixin.create(
-/** @scope Ember.Copyable.prototype */ {
+ If the method `toStringExtension` is defined, its return value will be
+ included in the output.
- /**
- Override to return a copy of the receiver. Default implementation raises
- an exception.
+ App.Teacher = App.Person.extend({
+ toStringExtension: function(){
+ return this.get('fullName');
+ }
+ });
+ teacher = App.Teacher.create()
+ teacher.toString(); // #=> "<App.Teacher:ember1026:Tom Dale>"
- @method copy
- @param deep {Boolean} if true, a deep copy of the object should be made
- @return {Object} copy of receiver
+ @method toString
+ @return {String} string representation
*/
- copy: Ember.required(Function),
+ toString: function toString() {
+ var hasToStringExtension = typeof this.toStringExtension === 'function',
+ extension = hasToStringExtension ? ":" + this.toStringExtension() : '';
+ var ret = '<'+this.constructor.toString()+':'+guidFor(this)+extension+'>';
+ this.toString = makeToString(ret);
+ return ret;
+ }
+});
- /**
- If the object implements Ember.Freezable, then this will return a new copy
- if the object is not frozen and the receiver if the object is frozen.
+function makeToString(ret) {
+ return function() { return ret; };
+}
- Raises an exception if you try to call this method on a object that does
- not support freezing.
+if (Ember.config.overridePrototypeMixin) {
+ Ember.config.overridePrototypeMixin(CoreObject.PrototypeMixin);
+}
- You should use this method whenever you want a copy of a freezable object
- since a freezable object can simply return itself without actually
- consuming more memory.
+CoreObject.__super__ = null;
- @method frozenCopy
- @return {Object} copy of receiver or receiver
- */
- frozenCopy: function() {
- if (Ember.Freezable && Ember.Freezable.detect(this)) {
- return get(this, 'isFrozen') ? this : this.copy().freeze();
- } else {
- throw new Error(Ember.String.fmt("%@ does not support freezing", [this]));
- }
- }
-});
+var ClassMixin = Mixin.create({
+ ClassMixin: Ember.required(),
+ PrototypeMixin: Ember.required(),
+ isClass: true,
-})();
+ isMethod: false,
+ extend: function() {
+ var Class = makeCtor(), proto;
+ Class.ClassMixin = Mixin.create(this.ClassMixin);
+ Class.PrototypeMixin = Mixin.create(this.PrototypeMixin);
+ Class.ClassMixin.ownerConstructor = Class;
+ Class.PrototypeMixin.ownerConstructor = Class;
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ reopen.apply(Class.PrototypeMixin, arguments);
+ Class.superclass = this;
+ Class.__super__ = this.prototype;
-var get = Ember.get, set = Ember.set;
+ proto = Class.prototype = o_create(this.prototype);
+ proto.constructor = Class;
+ generateGuid(proto, 'ember');
+ meta(proto).proto = proto; // this will disable observers on prototype
-/**
- 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.
+ Class.ClassMixin.apply(Class);
+ return Class;
+ },
- ## Enforcement
+ createWithMixins: function() {
+ var C = this;
+ if (arguments.length>0) { this._initMixins(arguments); }
+ return new C();
+ },
- To fully support freezing in your subclass, you must include this mixin and
- override any method that might alter any property on the object to instead
- raise an exception. You can check the state of an object by checking the
- isFrozen property.
+ create: function() {
+ var C = this;
+ if (arguments.length>0) { this._initProperties(arguments); }
+ return new C();
+ },
- Although future versions of JavaScript may support language-level freezing
- object objects, that is not the case today. Even if an object is freezable,
- it is still technically possible to modify the object, even though it could
- break other parts of your application that do not expect a frozen object to
- change. It is, therefore, very important that you always respect the
- isFrozen property on all freezable objects.
+ reopen: function() {
+ this.willReopen();
+ reopen.apply(this.PrototypeMixin, arguments);
+ return this;
+ },
- ## Example Usage
+ reopenClass: function() {
+ reopen.apply(this.ClassMixin, arguments);
+ applyMixin(this, arguments, false);
+ return this;
+ },
- The example below shows a simple object that implement the Ember.Freezable
- protocol.
+ detect: function(obj) {
+ if ('function' !== typeof obj) { return false; }
+ while(obj) {
+ if (obj===this) { return true; }
+ obj = obj.superclass;
+ }
+ return false;
+ },
- Contact = Ember.Object.extend(Ember.Freezable, {
+ detectInstance: function(obj) {
+ return obj instanceof this;
+ },
- firstName: null,
+ /**
+ In some cases, you may want to annotate computed properties with additional
+ metadata about how they function or what values they operate on. For
+ example, computed property functions may close over variables that are then
+ no longer available for introspection.
- lastName: null,
+ You can pass a hash of these values to a computed property like this:
- // swaps the names
- swapNames: function() {
- if (this.get('isFrozen')) throw Ember.FROZEN_ERROR;
- var tmp = this.get('firstName');
- this.set('firstName', this.get('lastName'));
- this.set('lastName', tmp);
- return this;
- }
+ ```javascript
+ person: function() {
+ var personId = this.get('personId');
+ return App.Person.create({ id: personId });
+ }.property().meta({ type: App.Person })
+ ```
- });
+ Once you've done this, you can retrieve the values saved to the computed
+ property from your class like this:
- c = Context.create({ firstName: "John", lastName: "Doe" });
- c.swapNames(); => returns c
- c.freeze();
- c.swapNames(); => EXCEPTION
+ ```javascript
+ MyClass.metaForProperty('person');
+ ```
- ## Copying
+ This will return the original hash that was passed to `meta()`.
- Usually the Ember.Freezable protocol is implemented in cooperation with the
- Ember.Copyable protocol, which defines a frozenCopy() method that will return
- a frozen object, if the object implements this method as well.
+ @method metaForProperty
+ @param key {String} property name
+ */
+ metaForProperty: function(key) {
+ var desc = meta(this.proto(), false).descs[key];
- @class Freezable
- @namespace Ember
- @extends Ember.Mixin
- @since Ember 0.9
-*/
-Ember.Freezable = Ember.Mixin.create(
-/** @scope Ember.Freezable.prototype */ {
+ Ember.assert("metaForProperty() could not find a computed property with key '"+key+"'.", !!desc && desc instanceof Ember.ComputedProperty);
+ return desc._meta || {};
+ },
/**
- Set to true when the object is frozen. Use this property to detect whether
- your object is frozen or not.
+ Iterate over each computed property for the class, passing its name
+ and any associated metadata (see `metaForProperty`) to the callback.
- @property isFrozen
- @type Boolean
+ @method eachComputedProperty
+ @param {Function} callback
+ @param {Object} binding
*/
- isFrozen: false,
+ eachComputedProperty: function(callback, binding) {
+ var proto = this.proto(),
+ descs = meta(proto).descs,
+ empty = {},
+ property;
- /**
- Freezes the object. Once this method has been called the object should
- no longer allow any properties to be edited.
+ for (var name in descs) {
+ property = descs[name];
- @method freeze
- @return {Object} receiver
- */
- freeze: function() {
- if (get(this, 'isFrozen')) return this;
- set(this, 'isFrozen', true);
- return this;
+ if (property instanceof Ember.ComputedProperty) {
+ callback.call(binding || this, name, property._meta || empty);
+ }
+ }
}
});
-Ember.FROZEN_ERROR = "Frozen object cannot be modified.";
+if (Ember.config.overrideClassMixin) {
+ Ember.config.overrideClassMixin(ClassMixin);
+}
+
+CoreObject.ClassMixin = ClassMixin;
+ClassMixin.apply(CoreObject);
+
+/**
+ @class CoreObject
+ @namespace Ember
+*/
+Ember.CoreObject = CoreObject;
})();
@submodule ember-runtime
*/
-var forEach = Ember.EnumerableUtils.forEach;
+var get = Ember.get, set = Ember.set, guidFor = Ember.guidFor, none = Ember.isNone;
/**
- 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.
+ An unordered collection of objects.
- Note that an Enumerable can change even if it does not implement this mixin.
- For example, a MappedEnumerable cannot be directly modified but if its
- underlying enumerable changes, it will change also.
+ A Set works a bit like an array except that its items are not ordered. You
+ can create a set to efficiently test for membership for an object. You can
+ also iterate through a set just like an array, even accessing objects by
+ index, however there is no guarantee as to their order.
- ## Adding Objects
+ All Sets are observable via the Enumerable Observer API - which works
+ on any enumerable object including both Sets and Arrays.
- To add an object to an enumerable, use the addObject() method. This
- method will only add the object to the enumerable if the object is not
- already present and the object if of a type supported by the enumerable.
+ ## Creating a Set
- set.addObject(contact);
+ You can create a set like you would most objects using
+ `new Ember.Set()`. Most new sets you create will be empty, but you can
+ also initialize the set with some content by passing an array or other
+ enumerable of objects to the constructor.
- ## Removing Objects
+ Finally, you can pass in an existing set and the set will be copied. You
+ can also create a copy of a set by calling `Ember.Set#copy()`.
- To remove an object form an enumerable, use the removeObject() method. This
- will only remove the object if it is already in the enumerable, otherwise
- this method has no effect.
+ ```javascript
+ // creates a new empty set
+ var foundNames = new Ember.Set();
- set.removeObject(contact);
+ // creates a set with four names in it.
+ var names = new Ember.Set(["Charles", "Tom", "Juan", "Alex"]); // :P
- ## Implementing In Your Own Code
+ // creates a copy of the names set.
+ var namesCopy = new Ember.Set(names);
- If you are implementing an object and want to support this API, just include
- this mixin in your class and implement the required methods. In your unit
- tests, be sure to apply the Ember.MutableEnumerableTests to your object.
+ // same as above.
+ var anotherNamesCopy = names.copy();
+ ```
- @class MutableEnumerable
- @namespace Ember
- @extends Ember.Mixin
- @uses Ember.Enumerable
-*/
-Ember.MutableEnumerable = Ember.Mixin.create(Ember.Enumerable,
- /** @scope Ember.MutableEnumerable.prototype */ {
+ ## Adding/Removing Objects
- /**
- __Required.__ You must implement this method to apply this mixin.
+ You generally add or remove objects from a set using `add()` or
+ `remove()`. You can add any type of object including primitives such as
+ numbers, strings, and booleans.
- Attempts to add the passed object to the receiver if the object is not
- already present in the collection. If the object is present, this method
- has no effect.
+ Unlike arrays, objects can only exist one time in a set. If you call `add()`
+ on a set with the same object multiple times, the object will only be added
+ once. Likewise, calling `remove()` with the same object multiple times will
+ remove the object the first time and have no effect on future calls until
+ you add the object to the set again.
- If the passed object is of a type not supported by the receiver
- then this method should raise an exception.
+ NOTE: You cannot add/remove `null` or `undefined` to a set. Any attempt to do
+ so will be ignored.
- @method addObject
- @param {Object} object The object to add to the enumerable.
- @return {Object} the passed object
- */
- addObject: Ember.required(Function),
+ In addition to add/remove you can also call `push()`/`pop()`. Push behaves
+ just like `add()` but `pop()`, unlike `remove()` will pick an arbitrary
+ object, remove it and return it. This is a good way to use a set as a job
+ queue when you don't care which order the jobs are executed in.
+
+ ## Testing for an Object
+
+ To test for an object's presence in a set you simply call
+ `Ember.Set#contains()`.
+
+ ## Observing changes
+
+ When using `Ember.Set`, you can observe the `"[]"` property to be
+ alerted whenever the content changes. You can also add an enumerable
+ observer to the set to be notified of specific objects that are added and
+ removed from the set. See `Ember.Enumerable` for more information on
+ enumerables.
+
+ This is often unhelpful. If you are filtering sets of objects, for instance,
+ it is very inefficient to re-filter all of the items each time the set
+ changes. It would be better if you could just adjust the filtered set based
+ on what was changed on the original set. The same issue applies to merging
+ sets, as well.
+
+ ## Other Methods
+
+ `Ember.Set` primary implements other mixin APIs. For a complete reference
+ on the methods you will use with `Ember.Set`, please consult these mixins.
+ The most useful ones will be `Ember.Enumerable` and
+ `Ember.MutableEnumerable` which implement most of the common iterator
+ methods you are used to on Array.
+
+ Note that you can also use the `Ember.Copyable` and `Ember.Freezable`
+ APIs on `Ember.Set` as well. Once a set is frozen it can no longer be
+ modified. The benefit of this is that when you call `frozenCopy()` on it,
+ Ember will avoid making copies of the set. This allows you to write
+ code that can know with certainty when the underlying set data will or
+ will not be modified.
+
+ @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,
+ /** @scope Ember.Set.prototype */ {
+
+ // ..........................................................
+ // IMPLEMENT ENUMERABLE APIS
+ //
/**
- Adds each object in the passed enumerable to the receiver.
+ This property will change as the number of objects in the set changes.
- @method addObjects
- @param {Ember.Enumerable} objects the objects to add.
- @return {Object} receiver
+ @property length
+ @type number
+ @default 0
*/
- addObjects: function(objects) {
- Ember.beginPropertyChanges(this);
- forEach(objects, function(obj) { this.addObject(obj); }, this);
- Ember.endPropertyChanges(this);
- return this;
- },
+ length: 0,
/**
- __Required.__ You must implement this method to apply this mixin.
-
- Attempts to remove the passed object from the receiver collection if the
- object is in present in the collection. If the object is not present,
- this method has no effect.
+ Clears the set. This is useful if you want to reuse an existing set
+ without having to recreate it.
- If the passed object is of a type not supported by the receiver
- then this method should raise an exception.
+ ```javascript
+ var colors = new Ember.Set(["red", "green", "blue"]);
+ colors.length; // 3
+ colors.clear();
+ colors.length; // 0
+ ```
- @method removeObject
- @param {Object} object The object to remove from the enumerable.
- @return {Object} the passed object
+ @method clear
+ @return {Ember.Set} An empty Set
*/
- removeObject: Ember.required(Function),
+ clear: function() {
+ if (this.isFrozen) { throw new Error(Ember.FROZEN_ERROR); }
+ var len = get(this, 'length');
+ if (len === 0) { return this; }
- /**
- Removes each objects in the passed enumerable from the receiver.
+ var guid;
- @method removeObjects
- @param {Ember.Enumerable} objects the objects to remove
- @return {Object} receiver
- */
- removeObjects: function(objects) {
- Ember.beginPropertyChanges(this);
- forEach(objects, function(obj) { this.removeObject(obj); }, this);
- Ember.endPropertyChanges(this);
- return this;
- }
+ this.enumerableContentWillChange(len, 0);
+ Ember.propertyWillChange(this, 'firstObject');
+ Ember.propertyWillChange(this, 'lastObject');
-});
+ for (var i=0; i < len; i++){
+ guid = guidFor(this[i]);
+ delete this[guid];
+ delete this[i];
+ }
-})();
+ set(this, 'length', 0);
+ Ember.propertyDidChange(this, 'firstObject');
+ Ember.propertyDidChange(this, 'lastObject');
+ this.enumerableContentDidChange(len, 0);
+ return this;
+ },
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
-// ..........................................................
-// CONSTANTS
-//
+ /**
+ Returns true if the passed object is also an enumerable that contains the
+ same objects as the receiver.
-var OUT_OF_RANGE_EXCEPTION = "Index out of range" ;
-var EMPTY = [];
+ ```javascript
+ var colors = ["red", "green", "blue"],
+ same_colors = new Ember.Set(colors);
-// ..........................................................
-// HELPERS
-//
+ same_colors.isEqual(colors); // true
+ same_colors.isEqual(["purple", "brown"]); // false
+ ```
-var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach;
+ @method isEqual
+ @param {Ember.Set} obj the other object.
+ @return {Boolean}
+ */
+ isEqual: function(obj) {
+ // fail fast
+ if (!Ember.Enumerable.detect(obj)) return false;
-/**
- 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.
+ var loc = get(this, 'length');
+ if (get(obj, 'length') !== loc) return false;
- Note that an Array can change even if it does not implement this mixin.
- For example, one might implement a SparseArray that cannot be directly
- modified, but if its underlying enumerable changes, it will change also.
+ while(--loc >= 0) {
+ if (!obj.contains(this[loc])) return false;
+ }
- @class MutableArray
- @namespace Ember
- @extends Ember.Mixin
- @uses Ember.Array
- @uses Ember.MutableEnumerable
-*/
-Ember.MutableArray = Ember.Mixin.create(Ember.Array, Ember.MutableEnumerable,
- /** @scope Ember.MutableArray.prototype */ {
+ return true;
+ },
/**
- __Required.__ You must implement this method to apply this mixin.
+ Adds an object to the set. Only non-`null` objects can be added to a set
+ and those can only be added once. If the object is already in the set or
+ the passed value is null this method will have no effect.
+
+ This is an alias for `Ember.MutableEnumerable.addObject()`.
- This is one of the primitives you must implement to support Ember.Array. You
- should replace amt objects started at idx with the objects in the passed
- array. You should also call this.enumerableContentDidChange() ;
+ ```javascript
+ var colors = new Ember.Set();
+ colors.add("blue"); // ["blue"]
+ colors.add("blue"); // ["blue"]
+ colors.add("red"); // ["blue", "red"]
+ colors.add(null); // ["blue", "red"]
+ colors.add(undefined); // ["blue", "red"]
+ ```
- @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*
+ @method add
+ @param {Object} obj The object to add.
+ @return {Ember.Set} The set itself.
*/
- replace: Ember.required(),
+ add: Ember.aliasMethod('addObject'),
/**
- Remove all elements from self. This is useful if you
- want to reuse an existing array without having to recreate it.
+ Removes the object from the set if it is found. If you pass a `null` value
+ or an object that is already not in the set, this method will have no
+ effect. This is an alias for `Ember.MutableEnumerable.removeObject()`.
- var colors = ["red", "green", "blue"];
- color.length(); => 3
- colors.clear(); => []
- colors.length(); => 0
+ ```javascript
+ var colors = new Ember.Set(["red", "green", "blue"]);
+ colors.remove("red"); // ["blue", "green"]
+ colors.remove("purple"); // ["blue", "green"]
+ colors.remove(null); // ["blue", "green"]
+ ```
- @method clear
- @return {Ember.Array} An empty Array.
+ @method remove
+ @param {Object} obj The object to remove
+ @return {Ember.Set} The set itself.
*/
- clear: function () {
- var len = get(this, 'length');
- if (len === 0) return this;
- this.replace(0, len, EMPTY);
- return this;
- },
+ remove: Ember.aliasMethod('removeObject'),
/**
- This will use the primitive replace() method to insert an object at the
- specified index.
+ Removes the last element from the set and returns it, or `null` if it's empty.
- var colors = ["red", "green", "blue"];
- colors.insertAt(2, "yellow"); => ["red", "green", "yellow", "blue"]
- colors.insertAt(5, "orange"); => Error: Index out of range
+ ```javascript
+ var colors = new Ember.Set(["green", "blue"]);
+ colors.pop(); // "blue"
+ colors.pop(); // "green"
+ colors.pop(); // null
+ ```
- @method insertAt
- @param {Number} idx index of insert the object at.
- @param {Object} object object to insert
+ @method pop
+ @return {Object} The removed object from the set or null.
*/
- insertAt: function(idx, object) {
- if (idx > get(this, 'length')) throw new Error(OUT_OF_RANGE_EXCEPTION) ;
- this.replace(idx, 0, [object]) ;
- return this ;
+ pop: function() {
+ if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR);
+ var obj = this.length > 0 ? this[this.length-1] : null;
+ this.remove(obj);
+ return obj;
},
/**
- Remove an object at the specified index using the replace() primitive
- method. You can pass either a single index, or a start and a length.
+ Inserts the given object on to the end of the set. It returns
+ the set itself.
- If you pass a start and length that is beyond the
- length this method will throw an Ember.OUT_OF_RANGE_EXCEPTION
+ This is an alias for `Ember.MutableEnumerable.addObject()`.
- var colors = ["red", "green", "blue", "yellow", "orange"];
- colors.removeAt(0); => ["green", "blue", "yellow", "orange"]
- colors.removeAt(2, 2); => ["green", "blue"]
- colors.removeAt(4, 2); => Error: Index out of range
+ ```javascript
+ var colors = new Ember.Set();
+ colors.push("red"); // ["red"]
+ colors.push("green"); // ["red", "green"]
+ colors.push("blue"); // ["red", "green", "blue"]
+ ```
- @method removeAt
- @param {Number} start index, start of range
- @param {Number} len length of passing range
- @return {Object} receiver
+ @method push
+ @return {Ember.Set} The set itself.
*/
- removeAt: function(start, len) {
- if ('number' === typeof start) {
+ push: Ember.aliasMethod('addObject'),
- if ((start < 0) || (start >= get(this, 'length'))) {
- throw new Error(OUT_OF_RANGE_EXCEPTION);
- }
+ /**
+ Removes the last element from the set and returns it, or `null` if it's empty.
- // fast case
- if (len === undefined) len = 1;
- this.replace(start, len, EMPTY);
- }
+ This is an alias for `Ember.Set.pop()`.
- return this ;
- },
+ ```javascript
+ var colors = new Ember.Set(["green", "blue"]);
+ colors.shift(); // "blue"
+ colors.shift(); // "green"
+ colors.shift(); // null
+ ```
+
+ @method shift
+ @return {Object} The removed object from the set or null.
+ */
+ shift: Ember.aliasMethod('pop'),
/**
- Push the object onto the end of the array. Works just like push() but it
- is KVO-compliant.
+ Inserts the given object on to the end of the set. It returns
+ the set itself.
- var colors = ["red", "green", "blue"];
- colors.pushObject("black"); => ["red", "green", "blue", "black"]
- colors.pushObject(["yellow", "orange"]); => ["red", "green", "blue", "black", ["yellow", "orange"]]
+ This is an alias of `Ember.Set.push()`
- @method pushObject
- @param {anything} obj object to push
+ ```javascript
+ var colors = new Ember.Set();
+ colors.unshift("red"); // ["red"]
+ colors.unshift("green"); // ["red", "green"]
+ colors.unshift("blue"); // ["red", "green", "blue"]
+ ```
+
+ @method unshift
+ @return {Ember.Set} The set itself.
*/
- pushObject: function(obj) {
- this.insertAt(get(this, 'length'), obj) ;
- return obj ;
- },
+ unshift: Ember.aliasMethod('push'),
/**
- Add the objects in the passed numerable to the end of the array. Defers
- notifying observers of the change until all objects are added.
+ Adds each object in the passed enumerable to the set.
- var colors = ["red", "green", "blue"];
- colors.pushObjects("black"); => ["red", "green", "blue", "black"]
- colors.pushObjects(["yellow", "orange"]); => ["red", "green", "blue", "black", "yellow", "orange"]
+ This is an alias of `Ember.MutableEnumerable.addObjects()`
- @method pushObjects
- @param {Ember.Enumerable} objects the objects to add
- @return {Ember.Array} receiver
+ ```javascript
+ var colors = new Ember.Set();
+ colors.addEach(["red", "green", "blue"]); // ["red", "green", "blue"]
+ ```
+
+ @method addEach
+ @param {Ember.Enumerable} objects the objects to add.
+ @return {Ember.Set} The set itself.
*/
- pushObjects: function(objects) {
- this.replace(get(this, 'length'), 0, objects);
- return this;
- },
+ addEach: Ember.aliasMethod('addObjects'),
/**
- Pop object from array or nil if none are left. Works just like pop() but
- it is KVO-compliant.
+ Removes each object in the passed enumerable to the set.
- var colors = ["red", "green", "blue"];
- colors.popObject(); => "blue"
- console.log(colors); => ["red", "green"]
+ This is an alias of `Ember.MutableEnumerable.removeObjects()`
- @method popObject
- @return object
+ ```javascript
+ var colors = new Ember.Set(["red", "green", "blue"]);
+ colors.removeEach(["red", "blue"]); // ["green"]
+ ```
+
+ @method removeEach
+ @param {Ember.Enumerable} objects the objects to remove.
+ @return {Ember.Set} The set itself.
*/
- popObject: function() {
- var len = get(this, 'length') ;
- if (len === 0) return null ;
+ removeEach: Ember.aliasMethod('removeObjects'),
- var ret = this.objectAt(len-1) ;
- this.removeAt(len-1, 1) ;
- return ret ;
+ // ..........................................................
+ // PRIVATE ENUMERABLE SUPPORT
+ //
+
+ init: function(items) {
+ this._super();
+ if (items) this.addObjects(items);
},
- /**
- Shift an object from start of array or nil if none are left. Works just
- like shift() but it is KVO-compliant.
+ // implement Ember.Enumerable
+ nextObject: function(idx) {
+ return this[idx];
+ },
+
+ // more optimized version
+ firstObject: Ember.computed(function() {
+ return this.length > 0 ? this[0] : undefined;
+ }),
- var colors = ["red", "green", "blue"];
- colors.shiftObject(); => "red"
- console.log(colors); => ["green", "blue"]
+ // more optimized version
+ lastObject: Ember.computed(function() {
+ return this.length > 0 ? this[this.length-1] : undefined;
+ }),
- @method shiftObject
- @return object
- */
- shiftObject: function() {
- if (get(this, 'length') === 0) return null ;
- var ret = this.objectAt(0) ;
- this.removeAt(0) ;
- return ret ;
- },
+ // implements Ember.MutableEnumerable
+ addObject: function(obj) {
+ if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR);
+ if (none(obj)) return this; // nothing to do
- /**
- Unshift an object to start of array. Works just like unshift() but it is
- KVO-compliant.
+ var guid = guidFor(obj),
+ idx = this[guid],
+ len = get(this, 'length'),
+ added ;
- var colors = ["red", "green", "blue"];
- colors.unshiftObject("yellow"); => ["yellow", "red", "green", "blue"]
- colors.unshiftObject(["black", "white"]); => [["black", "white"], "yellow", "red", "green", "blue"]
+ if (idx>=0 && idx<len && (this[idx] === obj)) return this; // added
- @method unshiftObject
- @param {anything} obj object to unshift
- */
- unshiftObject: function(obj) {
- this.insertAt(0, obj) ;
- return obj ;
- },
+ added = [obj];
- /**
- Adds the named objects to the beginning of the array. Defers notifying
- observers until all objects have been added.
+ this.enumerableContentWillChange(null, added);
+ Ember.propertyWillChange(this, 'lastObject');
- var colors = ["red", "green", "blue"];
- colors.unshiftObjects(["black", "white"]); => ["black", "white", "red", "green", "blue"]
- colors.unshiftObjects("yellow"); => Type Error: 'undefined' is not a function
+ len = get(this, 'length');
+ this[guid] = len;
+ this[len] = obj;
+ set(this, 'length', len+1);
+
+ Ember.propertyDidChange(this, 'lastObject');
+ this.enumerableContentDidChange(null, added);
- @method unshiftObjects
- @param {Ember.Enumerable} objects the objects to add
- @return {Ember.Array} receiver
- */
- unshiftObjects: function(objects) {
- this.replace(0, 0, objects);
return this;
},
- /**
- Reverse objects in the array. Works just like reverse() but it is
- KVO-compliant.
+ // implements Ember.MutableEnumerable
+ removeObject: function(obj) {
+ if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR);
+ if (none(obj)) return this; // nothing to do
- @method reverseObjects
- @return {Ember.Array} receiver
- */
- reverseObjects: function() {
- var len = get(this, 'length');
- if (len === 0) return this;
- var objects = this.toArray().reverse();
- this.replace(0, len, objects);
- return this;
- },
+ var guid = guidFor(obj),
+ idx = this[guid],
+ len = get(this, 'length'),
+ isFirst = idx === 0,
+ isLast = idx === len-1,
+ last, removed;
- /**
- 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([]); => []
+ if (idx>=0 && idx<len && (this[idx] === obj)) {
+ removed = [obj];
- @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();
+ this.enumerableContentWillChange(removed, null);
+ if (isFirst) { Ember.propertyWillChange(this, 'firstObject'); }
+ if (isLast) { Ember.propertyWillChange(this, 'lastObject'); }
+
+ // swap items - basically move the item to the end so it can be removed
+ if (idx < len-1) {
+ last = this[len-1];
+ this[idx] = last;
+ this[guidFor(last)] = idx;
+ }
+
+ delete this[guid];
+ delete this[len-1];
+ set(this, 'length', len-1);
+
+ if (isFirst) { Ember.propertyDidChange(this, 'firstObject'); }
+ if (isLast) { Ember.propertyDidChange(this, 'lastObject'); }
+ this.enumerableContentDidChange(removed, null);
+ }
- var len = get(this, 'length');
- this.replace(0, len, objects);
return this;
},
- // ..........................................................
- // IMPLEMENT Ember.MutableEnumerable
- //
+ // optimized version
+ contains: function(obj) {
+ return this[guidFor(obj)]>=0;
+ },
- removeObject: function(obj) {
- var loc = get(this, 'length') || 0;
- while(--loc >= 0) {
- var curObject = this.objectAt(loc) ;
- if (curObject === obj) this.removeAt(loc) ;
+ copy: function() {
+ var C = this.constructor, ret = new C(), loc = get(this, 'length');
+ set(ret, 'length', loc);
+ while(--loc>=0) {
+ ret[loc] = this[loc];
+ ret[guidFor(this[loc])] = loc;
}
- return this ;
+ return ret;
},
- addObject: function(obj) {
- if (!this.contains(obj)) this.pushObject(obj);
- return this ;
+ toString: function() {
+ var len = this.length, idx, array = [];
+ for(idx = 0; idx < len; idx++) {
+ array[idx] = this[idx];
+ }
+ return "Ember.Set<%@>".fmt(array.join(','));
}
});
-
})();
@submodule ember-runtime
*/
-var get = Ember.get, set = Ember.set, defineProperty = Ember.defineProperty;
-
/**
- ## 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.
-
- 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.
+ `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.
- More documentation about `get` and `set` are below.
+ @class Object
+ @namespace Ember
+ @extends Ember.CoreObject
+ @uses Ember.Observable
+*/
+Ember.Object = Ember.CoreObject.extend(Ember.Observable);
- ## Observing Property Changes
+})();
- You typically observe property changes simply by adding the `observes`
- call to the end of your method declarations in classes that you write.
- For example:
- Ember.Object.create({
- valueObserver: function() {
- // 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
- these two methods to add and remove observers yourself if you need to
- do so at runtime.
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- To add an observer for a property, call:
+var get = Ember.get, indexOf = Ember.ArrayPolyfills.indexOf;
- object.addObserver('propertyKey', targetObject, targetAction)
+/**
+ 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.
- This will call the `targetAction` method on the `targetObject` to be called
- whenever the value of the `propertyKey` changes.
+ # Example Usage
- 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.
+ ```javascript
+ MyFramework = Ember.Namespace.create({
+ VERSION: '1.0.0'
+ });
+ ```
- @class Observable
+ @class Namespace
@namespace Ember
- @extends Ember.Mixin
+ @extends Ember.Object
*/
-Ember.Observable = Ember.Mixin.create(/** @scope Ember.Observable.prototype */ {
-
- // compatibility
- isObserverable: true,
-
- /**
- Retrieves the value of a property from the object.
-
- This method is usually similar to using object[keyName] or object.keyName,
- however it supports both computed properties and the unknownProperty
- handler.
+var Namespace = Ember.Namespace = Ember.Object.extend({
+ isNamespace: true,
- 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.
+ init: function() {
+ Ember.Namespace.NAMESPACES.push(this);
+ Ember.Namespace.PROCESSED = false;
+ },
- ### Computed Properties
+ toString: function() {
+ var name = get(this, 'name');
+ if (name) { return name; }
- Computed properties are methods defined with the `property` modifier
- declared at the end, such as:
+ findNamespaces();
+ return this[Ember.GUID_KEY+'_name'];
+ },
- fullName: function() {
- return this.getEach('firstName', 'lastName').compact().join(' ');
- }.property('firstName', 'lastName')
+ nameClasses: function() {
+ processNamespace([this.toString()], this, {});
+ },
- When you call `get` on a computed property, the function will be
- called and the return value will be returned instead of the function
- itself.
+ destroy: function() {
+ var namespaces = Ember.Namespace.NAMESPACES;
+ Ember.lookup[this.toString()] = undefined;
+ namespaces.splice(indexOf.call(namespaces, this), 1);
+ this._super();
+ }
+});
- ### Unknown Properties
+Namespace.reopenClass({
+ NAMESPACES: [Ember],
+ PROCESSED: false,
+ processAll: processAllNamespaces
+});
- Likewise, if you try to call `get` on a property whose value is
- undefined, the unknownProperty() method will be called on the object.
- If this method returns any value other than undefined, it will be returned
- instead. This allows you to implement "virtual" properties that are
- not defined upfront.
+var hasOwnProp = ({}).hasOwnProperty,
+ guidFor = Ember.guidFor;
- @method get
- @param {String} key The property to retrieve
- @return {Object} The property value or undefined.
- */
- get: function(keyName) {
- return get(this, keyName);
- },
+function processNamespace(paths, root, seen) {
+ var idx = paths.length;
- /**
- To get multiple properties at once, call getProperties
- with a list of strings or an array:
+ // Loop over all of the keys in the namespace, looking for classes
+ for(var key in root) {
+ if (!hasOwnProp.call(root, key)) { continue; }
+ var obj = root[key];
- record.getProperties('firstName', 'lastName', 'zipCode'); // => { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
+ // If we are processing the `Ember` namespace, for example, the
+ // `paths` will start with `["Ember"]`. Every iteration through
+ // the loop will update the **second** element of this list with
+ // the key, so processing `Ember.View` will make the Array
+ // `['Ember', 'View']`.
+ paths[idx] = key;
- is equivalent to:
+ // If we have found an unprocessed class
+ if (obj && obj.toString === classToString) {
+ // Replace the class' `toString` with the dot-separated path
+ // and set its `NAME_KEY`
+ obj.toString = makeToString(paths.join('.'));
+ obj[NAME_KEY] = paths.join('.');
- record.getProperties(['firstName', 'lastName', 'zipCode']); // => { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
+ // Support nested namespaces
+ } else if (obj && obj.isNamespace) {
+ // Skip aliased namespaces
+ if (seen[guidFor(obj)]) { continue; }
+ seen[guidFor(obj)] = true;
- @method getProperties
- @param {String...|Array} list of keys to get
- @return {Hash}
- */
- getProperties: function() {
- var ret = {};
- var propertyNames = arguments;
- if (arguments.length === 1 && Ember.typeOf(arguments[0]) === 'array') {
- propertyNames = arguments[0];
+ // Process the child namespace
+ processNamespace(paths, obj, seen);
}
- for(var i = 0; i < propertyNames.length; i++) {
- ret[propertyNames[i]] = get(this, propertyNames[i]);
- }
- return ret;
- },
-
- /**
- Sets the provided key or path to the value.
+ }
- This method is generally very similar to calling object[key] = value or
- object.key = value, except that it provides support for computed
- properties, the unknownProperty() method and property observers.
+ paths.length = idx; // cut out last item
+}
- ### Computed Properties
+function findNamespaces() {
+ var Namespace = Ember.Namespace, lookup = Ember.lookup, obj, isNamespace;
- If you try to set a value on a key that has a computed property handler
- defined (see the get() method for an example), then set() will call
- that method, passing both the value and key instead of simply changing
- the value itself. This is useful for those times when you need to
- implement a property that is composed of one or more member
- properties.
+ if (Namespace.PROCESSED) { return; }
- ### Unknown Properties
+ for (var prop in lookup) {
+ // These don't raise exceptions but can cause warnings
+ if (prop === "parent" || prop === "top" || prop === "frameElement") { continue; }
- If you try to set a value on a key that is undefined in the target
- object, then the unknownProperty() handler will be called instead. This
- gives you an opportunity to implement complex "virtual" properties that
- are not predefined on the object. If unknownProperty() returns
- undefined, then set() will simply set the value on the object.
+ // get(window.globalStorage, 'isNamespace') would try to read the storage for domain isNamespace and cause exception in Firefox.
+ // globalStorage is a storage obsoleted by the WhatWG storage specification. See https://developer.mozilla.org/en/DOM/Storage#globalStorage
+ if (prop === "globalStorage" && lookup.StorageList && lookup.globalStorage instanceof lookup.StorageList) { continue; }
+ // Unfortunately, some versions of IE don't support window.hasOwnProperty
+ if (lookup.hasOwnProperty && !lookup.hasOwnProperty(prop)) { continue; }
- ### Property Observers
+ // At times we are not allowed to access certain properties for security reasons.
+ // There are also times where even if we can access them, we are not allowed to access their properties.
+ try {
+ obj = Ember.lookup[prop];
+ isNamespace = obj && obj.isNamespace;
+ } catch (e) {
+ continue;
+ }
- In addition to changing the property, set() will also register a
- property change with the object. Unless you have placed this call
- inside of a beginPropertyChanges() and endPropertyChanges(), any "local"
- observers (i.e. observer methods declared on the same object), will be
- called immediately. Any "remote" observers (i.e. observer methods
- declared on another object) will be placed in a queue and called at a
- later time in a coalesced manner.
+ if (isNamespace) {
+ Ember.deprecate("Namespaces should not begin with lowercase.", /^[A-Z]/.test(prop));
+ obj[NAME_KEY] = prop;
+ }
+ }
+}
- ### Chaining
+var NAME_KEY = Ember.NAME_KEY = Ember.GUID_KEY + '_name';
- In addition to property changes, set() returns the value of the object
- itself so you can do chaining like this:
+function superClassString(mixin) {
+ var superclass = mixin.superclass;
+ if (superclass) {
+ if (superclass[NAME_KEY]) { return superclass[NAME_KEY]; }
+ else { return superClassString(superclass); }
+ } else {
+ return;
+ }
+}
- record.set('firstName', 'Charles').set('lastName', 'Jolley');
+function classToString() {
+ if (!Ember.BOOTED && !this[NAME_KEY]) {
+ processAllNamespaces();
+ }
- @method set
- @param {String} key The property to set
- @param {Object} value The value to set or null.
- @return {Ember.Observable}
- */
- set: function(keyName, value) {
- set(this, keyName, value);
- return this;
- },
+ var ret;
- /**
- To set multiple properties at once, call setProperties
- with a Hash:
+ if (this[NAME_KEY]) {
+ ret = this[NAME_KEY];
+ } else {
+ var str = superClassString(this);
+ if (str) {
+ ret = "(subclass of " + str + ")";
+ } else {
+ ret = "(unknown mixin)";
+ }
+ this.toString = makeToString(ret);
+ }
- record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });
+ return ret;
+}
- @method setProperties
- @param {Hash} hash the hash of keys and values to set
- @return {Ember.Observable}
- */
- setProperties: function(hash) {
- return Ember.setProperties(this, hash);
- },
+function processAllNamespaces() {
+ if (!Namespace.PROCESSED) {
+ findNamespaces();
+ Namespace.PROCESSED = true;
+ }
- /**
- Begins a grouping of property changes.
+ if (Ember.anyUnprocessedMixins) {
+ var namespaces = Namespace.NAMESPACES, namespace;
+ for (var i=0, l=namespaces.length; i<l; i++) {
+ namespace = namespaces[i];
+ processNamespace([namespace.toString()], namespace, {});
+ }
- You can use this method to group property changes so that notifications
- will not be sent until the changes are finished. If you plan to make a
- large number of changes to an object at one time, you should call this
- method at the beginning of the changes to begin deferring change
- notifications. When you are done making changes, call endPropertyChanges()
- to deliver the deferred change notifications and end deferring.
+ Ember.anyUnprocessedMixins = false;
+ }
+}
- @method beginPropertyChanges
- @return {Ember.Observable}
- */
- beginPropertyChanges: function() {
- Ember.beginPropertyChanges();
- return this;
- },
+function makeToString(ret) {
+ return function() { return ret; };
+}
- /**
- Ends a grouping of property changes.
+Ember.Mixin.prototype.toString = classToString;
- You can use this method to group property changes so that notifications
- will not be sent until the changes are finished. If you plan to make a
- large number of changes to an object at one time, you should call
- beginPropertyChanges() at the beginning of the changes to defer change
- notifications. When you are done making changes, call this method to
- deliver the deferred change notifications and end deferring.
+})();
- @method endPropertyChanges
- @return {Ember.Observable}
- */
- endPropertyChanges: function() {
- Ember.endPropertyChanges();
- return this;
- },
- /**
- Notify the observer system that a property is about to change.
- Sometimes you need to change a value directly or indirectly without
- actually calling get() or set() on it. In this case, you can use this
- method and propertyDidChange() instead. Calling these two methods
- together will notify all observers that the property has potentially
- changed value.
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- Note that you must always call propertyWillChange and propertyDidChange as
- 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.
+/**
+ 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.
- @method propertyWillChange
- @param {String} key The property key that is about to change.
- @return {Ember.Observable}
- */
- propertyWillChange: function(keyName){
- Ember.propertyWillChange(this, keyName);
- return this;
- },
+ Currently `Ember.Application` is very similar to `Ember.Namespace.` However,
+ this class may be augmented by additional frameworks so it is important to
+ use this instance when building new applications.
- /**
- Notify the observer system that a property has just changed.
+ # Example Usage
- Sometimes you need to change a value directly or indirectly without
- actually calling get() or set() on it. In this case, you can use this
- method and propertyWillChange() instead. Calling these two methods
- together will notify all observers that the property has potentially
- changed value.
+ ```javascript
+ MyApp = Ember.Application.create({
+ VERSION: '1.0.0',
+ store: Ember.Store.create().from(Ember.fixtures)
+ });
- Note that you must always call propertyWillChange and propertyDidChange as
- 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.
+ MyApp.ready = function() {
+ //..init code goes here...
+ }
+ ```
- @method propertyDidChange
- @param {String} keyName The property key that has just changed.
- @return {Ember.Observable}
- */
- propertyDidChange: function(keyName) {
- Ember.propertyDidChange(this, keyName);
- return this;
- },
+ @class Application
+ @namespace Ember
+ @extends Ember.Namespace
+*/
+Ember.Application = Ember.Namespace.extend();
- /**
- Convenience method to call `propertyWillChange` and `propertyDidChange` in
- succession.
- @method notifyPropertyChange
- @param {String} keyName The property key to be notified about.
- @return {Ember.Observable}
- */
- notifyPropertyChange: function(keyName) {
- this.propertyWillChange(keyName);
- this.propertyDidChange(keyName);
- return this;
- },
+})();
- addBeforeObserver: function(key, target, method) {
- Ember.addBeforeObserver(this, key, target, method);
- },
- /**
- Adds an observer on a property.
- This is the core method used to register an observer for a property.
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- Once you call this method, anytime the key's value is set, your observer
- will be notified. Note that the observers are triggered anytime the
- value is set, regardless of whether it has actually changed. Your
- observer should be prepared to handle that.
- You can also pass an optional context parameter to this method. The
- context will be passed to your observer method whenever it is triggered.
- Note that if you add the same target/method pair on a key multiple times
- with different context parameters, your observer will only be called once
- with the last context you passed.
+var get = Ember.get, set = Ember.set;
- ### Observer Methods
+/**
+ 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
+ out the underlying array is useful.
- Observer methods you pass should generally have the following signature if
- you do not pass a "context" parameter:
+ A simple example of usage:
- fooDidChange: function(sender, key, value, rev);
+ ```javascript
+ var pets = ['dog', 'cat', 'fish'];
+ var ap = Ember.ArrayProxy.create({ content: Ember.A(pets) });
- The sender is the object that changed. The key is the property that
- changes. The value property is currently reserved and unused. The rev
- is the last property revision of the object when it changed, which you can
- use to detect if the key value has really changed or not.
+ ap.get('firstObject'); // 'dog'
+ ap.set('content', ['amoeba', 'paramecium']);
+ ap.get('firstObject'); // 'amoeba'
+ ```
- If you pass a "context" parameter, the context will be passed before the
- revision like so:
+ This class can also be useful as a layer to transform the contents of
+ an array, as they are accessed. This can be done by overriding
+ `objectAtContent`:
- fooDidChange: function(sender, key, value, context, rev);
+ ```javascript
+ var pets = ['dog', 'cat', 'fish'];
+ var ap = Ember.ArrayProxy.create({
+ content: Ember.A(pets),
+ objectAtContent: function(idx) {
+ return this.get('content').objectAt(idx).toUpperCase();
+ }
+ });
- Usually you will not need the value, context or revision parameters at
- the end. In this case, it is common to write observer methods that take
- 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.
+ ap.get('firstObject'); // . 'DOG'
+ ```
- @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.
- @return {Ember.Object} self
- */
- addObserver: function(key, target, method) {
- Ember.addObserver(this, key, target, method);
- },
+ @class ArrayProxy
+ @namespace Ember
+ @extends Ember.Object
+ @uses Ember.MutableArray
+*/
+Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray,
+/** @scope Ember.ArrayProxy.prototype */ {
/**
- Remove an observer you have previously registered on this object. Pass
- the same key, target, and method you passed to addObserver() and your
- target will no longer receive notifications.
+ The content array. Must be an object that implements `Ember.Array` and/or
+ `Ember.MutableArray.`
- @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.
- @return {Ember.Observable} receiver
+ @property content
+ @type Ember.Array
*/
- removeObserver: function(key, target, method) {
- Ember.removeObserver(this, key, target, method);
- },
+ content: null,
/**
- Returns true if the object currently has observers registered for a
- particular key. You can use this method to potentially defer performing
- an expensive action until someone begins observing a particular property
- on the object.
+ 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.
- @method hasObserverFor
- @param {String} key Key to check
- @return {Boolean}
+ @property arrangedContent
*/
- hasObserverFor: function(key) {
- return Ember.hasListeners(this, key+':change');
- },
+ arrangedContent: Ember.computed('content', function() {
+ return get(this, 'content');
+ }),
/**
- 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.
+ Should actually retrieve the object at the specified index from the
+ content. You can override this method in subclasses to transform the
+ content item to something new.
- @method unknownProperty
- @param {String} key The name of the unknown property that was requested.
- @return {Object} The property value or undefined. Default is undefined.
+ This method will only be called if content is non-`null`.
+
+ @method objectAtContent
+ @param {Number} idx The index to retrieve.
+ @return {Object} the value or undefined if none found
*/
- unknownProperty: function(key) {
- return undefined;
+ objectAtContent: function(idx) {
+ return get(this, 'arrangedContent').objectAt(idx);
},
/**
- 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.
+ Should actually replace the specified objects on the content array.
+ You can override this method in subclasses to transform the content item
+ into something new.
- @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.
- */
- setUnknownProperty: function(key, value) {
- defineProperty(this, key);
- set(this, key, value);
- },
+ This method will only be called if content is non-`null`.
- /**
- @deprecated
- @method getPath
- @param {String} path The property path to retrieve
- @return {Object} The property value or undefined.
+ @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}
*/
- getPath: function(path) {
- Ember.deprecate("getPath is deprecated since get now supports paths");
- return this.get(path);
+ replaceContent: function(idx, amt, objects) {
+ get(this, 'content').replace(idx, amt, objects);
},
/**
- @deprecated
- @method setPath
- @param {String} path The path to the property that will be set
- @param {Object} value The value to set or null.
- @return {Ember.Observable}
+ @private
+
+ Invoked when the content property is about to change. Notifies observers that the
+ entire array content will change.
+
+ @method _contentWillChange
*/
- setPath: function(path, value) {
- Ember.deprecate("setPath is deprecated since set now supports paths");
- return this.set(path, value);
+ _contentWillChange: Ember.beforeObserver(function() {
+ this._teardownContent();
+ }, 'content'),
+
+ _teardownContent: function() {
+ var content = get(this, 'content');
+
+ if (content) {
+ content.removeArrayObserver(this, {
+ willChange: 'contentArrayWillChange',
+ didChange: 'contentArrayDidChange'
+ });
+ }
},
+ contentArrayWillChange: Ember.K,
+ contentArrayDidChange: Ember.K,
+
/**
- Retrieves the value of a property, or a default value in the case that the property
- returns undefined.
+ @private
- person.getWithDefault('lastName', 'Doe');
+ Invoked when the content property changes. Notifies observers that the
+ entire array content has changed.
- @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
- @return {Object} The property value or the defaultValue.
+ @method _contentDidChange
*/
- getWithDefault: function(keyName, defaultValue) {
- return Ember.getWithDefault(this, keyName, defaultValue);
+ _contentDidChange: Ember.observer(function() {
+ var content = get(this, 'content');
+
+ Ember.assert("Can't set ArrayProxy's content to itself", content !== this);
+
+ this._setupContent();
+ }, 'content'),
+
+ _setupContent: function() {
+ var content = get(this, 'content');
+
+ if (content) {
+ content.addArrayObserver(this, {
+ willChange: 'contentArrayWillChange',
+ didChange: 'contentArrayDidChange'
+ });
+ }
},
- /**
- Set the value of a property to the current value plus some amount.
+ _arrangedContentWillChange: Ember.beforeObserver(function() {
+ var arrangedContent = get(this, 'arrangedContent'),
+ len = arrangedContent ? get(arrangedContent, 'length') : 0;
+
+ this.arrangedContentArrayWillChange(this, 0, len, undefined);
+ this.arrangedContentWillChange(this);
+
+ this._teardownArrangedContent(arrangedContent);
+ }, 'arrangedContent'),
+
+ _arrangedContentDidChange: Ember.observer(function() {
+ var arrangedContent = get(this, 'arrangedContent'),
+ len = arrangedContent ? get(arrangedContent, 'length') : 0;
+
+ Ember.assert("Can't set ArrayProxy's content to itself", arrangedContent !== this);
+
+ this._setupArrangedContent();
+
+ this.arrangedContentDidChange(this);
+ this.arrangedContentArrayDidChange(this, 0, undefined, len);
+ }, 'arrangedContent'),
+
+ _setupArrangedContent: function() {
+ var arrangedContent = get(this, 'arrangedContent');
+
+ if (arrangedContent) {
+ arrangedContent.addArrayObserver(this, {
+ willChange: 'arrangedContentArrayWillChange',
+ didChange: 'arrangedContentArrayDidChange'
+ });
+ }
+ },
- person.incrementProperty('age');
- team.incrementProperty('score', 2);
+ _teardownArrangedContent: function() {
+ var arrangedContent = get(this, 'arrangedContent');
- @method incrementProperty
- @param {String} keyName The name of the property to increment
- @param {Object} increment The amount to increment by. Defaults to 1
- @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);
+ if (arrangedContent) {
+ arrangedContent.removeArrayObserver(this, {
+ willChange: 'arrangedContentArrayWillChange',
+ didChange: 'arrangedContentArrayDidChange'
+ });
+ }
},
- /**
- Set the value of a property to the current value minus some amount.
-
- player.decrementProperty('lives');
- orc.decrementProperty('health', 5);
+ arrangedContentWillChange: Ember.K,
+ arrangedContentDidChange: Ember.K,
- @method decrementProperty
- @param {String} keyName The name of the property to decrement
- @param {Object} increment The amount to decrement by. Defaults to 1
- @return {Object} The new property value
- */
- decrementProperty: function(keyName, increment) {
- if (!increment) { increment = 1; }
- set(this, keyName, (get(this, keyName) || 0)-increment);
- return get(this, keyName);
+ objectAt: function(idx) {
+ return get(this, 'content') && this.objectAtContent(idx);
},
- /**
- Set the value of a boolean property to the opposite of it's
- current value.
+ length: Ember.computed(function() {
+ var arrangedContent = get(this, 'arrangedContent');
+ return arrangedContent ? get(arrangedContent, 'length') : 0;
+ // No dependencies since Enumerable notifies length of change
+ }),
- starship.toggleProperty('warpDriveEnaged');
+ replace: function(idx, amt, objects) {
+ Ember.assert('The content property of '+ this.constructor + ' should be set before modifying it', this.get('content'));
+ if (get(this, 'content')) this.replaceContent(idx, amt, objects);
+ return this;
+ },
- @method toggleProperty
- @param {String} keyName The name of the property to toggle
- @return {Object} The new property value
- */
- toggleProperty: function(keyName) {
- set(this, keyName, !get(this, keyName));
- return get(this, keyName);
+ arrangedContentArrayWillChange: function(item, idx, removedCnt, addedCnt) {
+ this.arrayContentWillChange(idx, removedCnt, addedCnt);
},
- /**
- Returns the cached value of a computed property, if it exists.
- This allows you to inspect the value of a computed property
- without accidentally invoking it if it is intended to be
- generated lazily.
+ arrangedContentArrayDidChange: function(item, idx, removedCnt, addedCnt) {
+ this.arrayContentDidChange(idx, removedCnt, addedCnt);
+ },
- @method cacheFor
- @param {String} keyName
- @return {Object} The cached value of the computed property, if any
- */
- cacheFor: function(keyName) {
- return Ember.cacheFor(this, keyName);
+ init: function() {
+ this._super();
+ this._setupContent();
+ this._setupArrangedContent();
},
- // intended for debugging purposes
- observersForKey: function(keyName) {
- return Ember.observersFor(this, keyName);
+ willDestroy: function() {
+ this._teardownArrangedContent();
+ this._teardownContent();
}
});
@submodule ember-runtime
*/
-var get = Ember.get, set = Ember.set;
+var get = Ember.get,
+ set = Ember.set,
+ fmt = Ember.String.fmt,
+ addBeforeObserver = Ember.addBeforeObserver,
+ addObserver = Ember.addObserver,
+ removeBeforeObserver = Ember.removeBeforeObserver,
+ removeObserver = Ember.removeObserver,
+ propertyWillChange = Ember.propertyWillChange,
+ propertyDidChange = Ember.propertyDidChange;
-/**
-@class TargetActionSupport
-@namespace Ember
-@extends Ember.Mixin
-*/
-Ember.TargetActionSupport = Ember.Mixin.create({
- target: null,
- action: null,
+function contentPropertyWillChange(content, contentKey) {
+ var key = contentKey.slice(8); // remove "content."
+ if (key in this) { return; } // if shadowed in proxy
+ propertyWillChange(this, key);
+}
- targetObject: Ember.computed(function() {
- var target = get(this, 'target');
+function contentPropertyDidChange(content, contentKey) {
+ var key = contentKey.slice(8); // remove "content."
+ if (key in this) { return; } // if shadowed in proxy
+ propertyDidChange(this, key);
+}
- if (Ember.typeOf(target) === "string") {
- var value = get(this, target);
- if (value === undefined) { value = get(window, target); }
- return value;
- } else {
- return target;
- }
- }).property('target').cacheable(),
+/**
+ `Ember.ObjectProxy` forwards all properties not defined by the proxy itself
+ to a proxied `content` object.
- triggerAction: function() {
- var action = get(this, 'action'),
- target = get(this, 'targetObject');
+ ```javascript
+ object = Ember.Object.create({
+ name: 'Foo'
+ });
- if (target && action) {
- var ret;
+ proxy = Ember.ObjectProxy.create({
+ content: object
+ });
- if (typeof target.send === 'function') {
- ret = target.send(action, this);
- } else {
- if (typeof action === 'string') {
- action = target[action];
- }
- ret = action.call(target, this);
- }
- if (ret !== false) ret = true;
+ // Access and change existing properties
+ proxy.get('name') // 'Foo'
+ proxy.set('name', 'Bar');
+ object.get('name') // 'Bar'
- return ret;
- } else {
- return false;
- }
- }
-});
+ // Create new 'description' property on `object`
+ proxy.set('description', 'Foo is a whizboo baz');
+ object.get('description') // 'Foo is a whizboo baz'
+ ```
-})();
+ While `content` is unset, setting a property to be delegated will throw an
+ Error.
+ ```javascript
+ proxy = Ember.ObjectProxy.create({
+ content: null,
+ flag: null
+ });
+ proxy.set('flag', true);
+ proxy.get('flag'); // true
+ proxy.get('foo'); // undefined
+ proxy.set('foo', 'data'); // throws Error
+ ```
+ Delegated properties can be bound to and will change when content is updated.
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ Computed properties on the proxy itself can depend on delegated properties.
-/**
- @class Evented
- @namespace Ember
- @extends Ember.Mixin
- */
-Ember.Evented = Ember.Mixin.create({
- on: function(name, target, method) {
- Ember.addListener(this, name, target, method);
- },
+ ```javascript
+ ProxyWithComputedProperty = Ember.ObjectProxy.extend({
+ fullName: function () {
+ var firstName = this.get('firstName'),
+ lastName = this.get('lastName');
+ if (firstName && lastName) {
+ return firstName + ' ' + lastName;
+ }
+ return firstName || lastName;
+ }.property('firstName', 'lastName')
+ });
- one: function(name, target, method) {
- if (!method) {
- method = target;
- target = null;
- }
+ proxy = ProxyWithComputedProperty.create();
- var self = this;
- var wrapped = function() {
- Ember.removeListener(self, name, target, wrapped);
+ proxy.get('fullName'); // undefined
+ proxy.set('content', {
+ firstName: 'Tom', lastName: 'Dale'
+ }); // triggers property change for fullName on proxy
- if ('string' === typeof method) { method = this[method]; }
+ proxy.get('fullName'); // 'Tom Dale'
+ ```
- // Internally, a `null` target means that the target is
- // the first parameter to addListener. That means that
- // the `this` passed into this function is the target
- // determined by the event system.
- method.apply(this, arguments);
- };
+ @class ObjectProxy
+ @namespace Ember
+ @extends Ember.Object
+*/
+Ember.ObjectProxy = Ember.Object.extend(
+/** @scope Ember.ObjectProxy.prototype */ {
+ /**
+ The object whose properties will be forwarded.
- this.on(name, target, wrapped);
- },
+ @property content
+ @type Ember.Object
+ @default null
+ */
+ content: null,
+ _contentDidChange: Ember.observer(function() {
+ Ember.assert("Can't set ObjectProxy's content to itself", this.get('content') !== this);
+ }, 'content'),
- trigger: function(name) {
- var args = [], i, l;
- for (i = 1, l = arguments.length; i < l; i++) {
- args.push(arguments[i]);
- }
- Ember.sendEvent(this, name, args);
+ willWatchProperty: function (key) {
+ var contentKey = 'content.' + key;
+ addBeforeObserver(this, contentKey, null, contentPropertyWillChange);
+ addObserver(this, contentKey, null, contentPropertyDidChange);
},
- fire: function(name) {
- Ember.deprecate("Ember.Evented#fire() has been deprecated in favor of trigger() for compatibility with jQuery. It will be removed in 1.0. Please update your code to call trigger() instead.");
- this.trigger.apply(this, arguments);
+ didUnwatchProperty: function (key) {
+ var contentKey = 'content.' + key;
+ removeBeforeObserver(this, contentKey, null, contentPropertyWillChange);
+ removeObserver(this, contentKey, null, contentPropertyDidChange);
},
- off: function(name, target, method) {
- Ember.removeListener(this, name, target, method);
+ unknownProperty: function (key) {
+ var content = get(this, 'content');
+ if (content) {
+ return get(content, key);
+ }
},
- has: function(name) {
- return Ember.hasListeners(this, name);
+ 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);
+ return set(content, key, value);
}
});
-(function() {
-
-})();
-
-
-
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
-
-
-// NOTE: this object should never be included directly. Instead use Ember.
-// Ember.Object. We only define this separately so that Ember.Set can depend on it
-
-
-var set = Ember.set, get = Ember.get,
- o_create = Ember.create,
- o_defineProperty = Ember.platform.defineProperty,
- a_slice = Array.prototype.slice,
- GUID_KEY = Ember.GUID_KEY,
- guidFor = Ember.guidFor,
- generateGuid = Ember.generateGuid,
- meta = Ember.meta,
- rewatch = Ember.rewatch,
- finishChains = Ember.finishChains,
- destroy = Ember.destroy,
- schedule = Ember.run.schedule,
- Mixin = Ember.Mixin,
- applyMixin = Mixin._apply,
- finishPartial = Mixin.finishPartial,
- reopen = Mixin.prototype.reopen,
- classToString = Mixin.prototype.toString;
-
-var undefinedDescriptor = {
- configurable: true,
- writable: true,
- enumerable: false,
- value: undefined
-};
-
-function makeCtor() {
-
- // Note: avoid accessing any properties on the object since it makes the
- // method a lot faster. This is glue code so we want it to be as fast as
- // possible.
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- var wasApplied = false, initMixins;
- var Class = function() {
- if (!wasApplied) {
- Class.proto(); // prepare prototype...
- }
- o_defineProperty(this, GUID_KEY, undefinedDescriptor);
- o_defineProperty(this, '_super', undefinedDescriptor);
- var m = meta(this);
- m.proto = this;
- if (initMixins) {
- this.reopen.apply(this, initMixins);
- initMixins = null;
- }
- finishPartial(this, m);
- delete m.proto;
- finishChains(this);
- this.init.apply(this, arguments);
- };
+var set = Ember.set, get = Ember.get, guidFor = Ember.guidFor;
+var forEach = Ember.EnumerableUtils.forEach;
- Class.toString = classToString;
- Class.willReopen = function() {
- if (wasApplied) {
- Class.PrototypeMixin = Mixin.create(Class.PrototypeMixin);
- }
+var EachArray = Ember.Object.extend(Ember.Array, {
- wasApplied = false;
- };
- Class._initMixins = function(args) { initMixins = args; };
+ init: function(content, keyName, owner) {
+ this._super();
+ this._keyName = keyName;
+ this._owner = owner;
+ this._content = content;
+ },
- Class.proto = function() {
- var superclass = Class.superclass;
- if (superclass) { superclass.proto(); }
+ objectAt: function(idx) {
+ var item = this._content.objectAt(idx);
+ return item && get(item, this._keyName);
+ },
- if (!wasApplied) {
- wasApplied = true;
- Class.PrototypeMixin.applyPartial(Class.prototype);
- rewatch(Class.prototype);
- }
+ length: Ember.computed(function() {
+ var content = this._content;
+ return content ? get(content, 'length') : 0;
+ })
- return this.prototype;
- };
+});
- return Class;
+var IS_OBSERVER = /^.+:(before|change)$/;
+
+function addObserverForContentKey(content, keyName, proxy, idx, loc) {
+ var objects = proxy._objects, guid;
+ if (!objects) objects = proxy._objects = {};
+
+ while(--loc>=idx) {
+ var item = content.objectAt(loc);
+ if (item) {
+ Ember.addBeforeObserver(item, keyName, proxy, 'contentKeyWillChange');
+ Ember.addObserver(item, keyName, proxy, 'contentKeyDidChange');
+ // keep track of the indicies each item was found at so we can map
+ // it back when the obj changes.
+ guid = guidFor(item);
+ if (!objects[guid]) objects[guid] = [];
+ objects[guid].push(loc);
+ }
+ }
}
-var CoreObject = makeCtor();
+function removeObserverForContentKey(content, keyName, proxy, idx, loc) {
+ var objects = proxy._objects;
+ if (!objects) objects = proxy._objects = {};
+ var indicies, guid;
-CoreObject.PrototypeMixin = Mixin.create({
+ while(--loc>=idx) {
+ var item = content.objectAt(loc);
+ if (item) {
+ Ember.removeBeforeObserver(item, keyName, proxy, 'contentKeyWillChange');
+ Ember.removeObserver(item, keyName, proxy, 'contentKeyDidChange');
- reopen: function() {
- applyMixin(this, arguments, true);
- return this;
- },
+ guid = guidFor(item);
+ indicies = objects[guid];
+ indicies[indicies.indexOf(loc)] = null;
+ }
+ }
+}
- isInstance: true,
+/**
+ 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.
- init: function() {},
+ @private
+ @class EachProxy
+ @namespace Ember
+ @extends Ember.Object
+*/
+Ember.EachProxy = Ember.Object.extend({
- /**
- @property isDestroyed
- @default false
- */
- isDestroyed: false,
+ init: function(content) {
+ this._super();
+ this._content = content;
+ content.addArrayObserver(this);
+
+ // in case someone is already observing some keys make sure they are
+ // added
+ forEach(Ember.watchedEvents(this), function(eventName) {
+ this.didAddListener(eventName);
+ }, this);
+ },
/**
- @property isDestroying
- @default false
+ 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}
*/
- isDestroying: false,
+ unknownProperty: function(keyName, value) {
+ var ret;
+ ret = new EachArray(this._content, keyName, this);
+ Ember.defineProperty(this, keyName, null, ret);
+ this.beginObservingContentKey(keyName);
+ return ret;
+ },
- /**
- Destroys an object by setting the isDestroyed flag and removing its
- metadata, which effectively destroys observers and bindings.
+ // ..........................................................
+ // ARRAY CHANGES
+ // Invokes whenever the content array itself changes.
- If you try to set a property on a destroyed object, an exception will be
- raised.
+ arrayWillChange: function(content, idx, removedCnt, addedCnt) {
+ var keys = this._keys, key, array, lim;
- Note that destruction is scheduled for the end of the run loop and does not
- happen immediately.
+ lim = removedCnt>0 ? idx+removedCnt : -1;
+ Ember.beginPropertyChanges(this);
- @method destroy
- @return {Ember.Object} receiver
- */
- destroy: function() {
- if (this.isDestroying) { return; }
+ for(key in keys) {
+ if (!keys.hasOwnProperty(key)) { continue; }
- this.isDestroying = true;
+ if (lim>0) removeObserverForContentKey(content, key, this, idx, lim);
- if (this.willDestroy) { this.willDestroy(); }
+ Ember.propertyWillChange(this, key);
+ }
- set(this, 'isDestroyed', true);
- schedule('destroy', this, this._scheduledDestroy);
- return this;
+ Ember.propertyWillChange(this._content, '@each');
+ Ember.endPropertyChanges(this);
},
- /**
- @private
+ arrayDidChange: function(content, idx, removedCnt, addedCnt) {
+ var keys = this._keys, key, array, lim;
- Invoked by the run loop to actually destroy the object. This is
- scheduled for execution by the `destroy` method.
+ lim = addedCnt>0 ? idx+addedCnt : -1;
+ Ember.beginPropertyChanges(this);
- @method _scheduledDestroy
- */
- _scheduledDestroy: function() {
- destroy(this);
- if (this.didDestroy) { this.didDestroy(); }
+ for(key in keys) {
+ if (!keys.hasOwnProperty(key)) { continue; }
+
+ if (lim>0) addObserverForContentKey(content, key, this, idx, lim);
+
+ Ember.propertyDidChange(this, key);
+ }
+
+ Ember.propertyDidChange(this._content, '@each');
+ Ember.endPropertyChanges(this);
},
- bind: function(to, from) {
- if (!(from instanceof Ember.Binding)) { from = Ember.Binding.from(from); }
- from.to(to).connect(this);
- return from;
+ // ..........................................................
+ // LISTEN FOR NEW OBSERVERS AND OTHER EVENT LISTENERS
+ // Start monitoring keys based on who is listening...
+
+ didAddListener: function(eventName) {
+ if (IS_OBSERVER.test(eventName)) {
+ this.beginObservingContentKey(eventName.slice(0, -7));
+ }
},
- toString: function() {
- return '<'+this.constructor.toString()+':'+guidFor(this)+'>';
- }
-});
+ didRemoveListener: function(eventName) {
+ if (IS_OBSERVER.test(eventName)) {
+ this.stopObservingContentKey(eventName.slice(0, -7));
+ }
+ },
-if (Ember.config.overridePrototypeMixin) {
- Ember.config.overridePrototypeMixin(CoreObject.PrototypeMixin);
-}
+ // ..........................................................
+ // CONTENT KEY OBSERVING
+ // Actual watch keys on the source content.
-CoreObject.__super__ = null;
+ beginObservingContentKey: function(keyName) {
+ var keys = this._keys;
+ if (!keys) keys = this._keys = {};
+ if (!keys[keyName]) {
+ keys[keyName] = 1;
+ var content = this._content,
+ len = get(content, 'length');
+ addObserverForContentKey(content, keyName, this, 0, len);
+ } else {
+ keys[keyName]++;
+ }
+ },
-var ClassMixin = Mixin.create({
+ stopObservingContentKey: function(keyName) {
+ var keys = this._keys;
+ if (keys && (keys[keyName]>0) && (--keys[keyName]<=0)) {
+ var content = this._content,
+ len = get(content, 'length');
+ removeObserverForContentKey(content, keyName, this, 0, len);
+ }
+ },
- ClassMixin: Ember.required(),
+ contentKeyWillChange: function(obj, keyName) {
+ Ember.propertyWillChange(this, keyName);
+ },
- PrototypeMixin: Ember.required(),
+ contentKeyDidChange: function(obj, keyName) {
+ Ember.propertyDidChange(this, keyName);
+ }
- isClass: true,
+});
- isMethod: false,
- extend: function() {
- var Class = makeCtor(), proto;
- Class.ClassMixin = Mixin.create(this.ClassMixin);
- Class.PrototypeMixin = Mixin.create(this.PrototypeMixin);
- Class.ClassMixin.ownerConstructor = Class;
- Class.PrototypeMixin.ownerConstructor = Class;
+})();
- reopen.apply(Class.PrototypeMixin, arguments);
- Class.superclass = this;
- Class.__super__ = this.prototype;
- proto = Class.prototype = o_create(this.prototype);
- proto.constructor = Class;
- generateGuid(proto, 'ember');
- meta(proto).proto = proto; // this will disable observers on prototype
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- Class.ClassMixin.apply(Class);
- return Class;
- },
- create: function() {
- var C = this;
- if (arguments.length>0) { this._initMixins(arguments); }
- return new C();
- },
+var get = Ember.get, set = Ember.set;
- reopen: function() {
- this.willReopen();
- reopen.apply(this.PrototypeMixin, arguments);
- return this;
- },
+// Add Ember.Array to Array.prototype. Remove methods with native
+// implementations and supply some more optimized versions of generic methods
+// because they are so common.
+var NativeArray = Ember.Mixin.create(Ember.MutableArray, Ember.Observable, Ember.Copyable, {
- reopenClass: function() {
- reopen.apply(this.ClassMixin, arguments);
- applyMixin(this, arguments, false);
- return this;
+ // because length is a built-in property we need to know to just get the
+ // original property.
+ get: function(key) {
+ if (key==='length') return this.length;
+ else if ('number' === typeof key) return this[key];
+ else return this._super(key);
},
- detect: function(obj) {
- if ('function' !== typeof obj) { return false; }
- while(obj) {
- if (obj===this) { return true; }
- obj = obj.superclass;
- }
- return false;
+ objectAt: function(idx) {
+ return this[idx];
},
- detectInstance: function(obj) {
- return obj instanceof this;
- },
+ // primitive for array support.
+ replace: function(idx, amt, objects) {
- /**
- In some cases, you may want to annotate computed properties with additional
- metadata about how they function or what values they operate on. For example,
- computed property functions may close over variables that are then no longer
- available for introspection.
+ if (this.isFrozen) throw Ember.FROZEN_ERROR ;
- You can pass a hash of these values to a computed property like this:
+ // if we replaced exactly the same number of items, then pass only the
+ // replaced range. Otherwise, pass the full remaining array length
+ // since everything has shifted
+ var len = objects ? get(objects, 'length') : 0;
+ this.arrayContentWillChange(idx, amt, len);
- person: function() {
- var personId = this.get('personId');
- return App.Person.create({ id: personId });
- }.property().meta({ type: App.Person })
+ if (!objects || objects.length === 0) {
+ this.splice(idx, amt) ;
+ } else {
+ var args = [idx, amt].concat(objects) ;
+ this.splice.apply(this,args) ;
+ }
- Once you've done this, you can retrieve the values saved to the computed
- property from your class like this:
+ this.arrayContentDidChange(idx, amt, len);
+ return this ;
+ },
- MyClass.metaForProperty('person');
+ // If you ask for an unknown property, then try to collect the value
+ // from member items.
+ unknownProperty: function(key, value) {
+ var ret;// = this.reducedProperty(key, value) ;
+ if ((value !== undefined) && ret === undefined) {
+ ret = this[key] = value;
+ }
+ return ret ;
+ },
- This will return the original hash that was passed to `meta()`.
+ // If browser did not implement indexOf natively, then override with
+ // specialized version
+ indexOf: function(object, startAt) {
+ var idx, len = this.length;
- @method metaForProperty
- @param key {String} property name
- */
- metaForProperty: function(key) {
- var desc = meta(this.proto(), false).descs[key];
+ if (startAt === undefined) startAt = 0;
+ else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
+ if (startAt < 0) startAt += len;
- Ember.assert("metaForProperty() could not find a computed property with key '"+key+"'.", !!desc && desc instanceof Ember.ComputedProperty);
- return desc._meta || {};
+ for(idx=startAt;idx<len;idx++) {
+ if (this[idx] === object) return idx ;
+ }
+ return -1;
},
- /**
- Iterate over each computed property for the class, passing its name
- and any associated metadata (see `metaForProperty`) to the callback.
+ lastIndexOf: function(object, startAt) {
+ var idx, len = this.length;
- @method eachComputedProperty
- @param {Function} callback
- @param {Object} binding
- */
- eachComputedProperty: function(callback, binding) {
- var proto = this.proto(),
- descs = meta(proto).descs,
- empty = {},
- property;
+ if (startAt === undefined) startAt = len-1;
+ else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
+ if (startAt < 0) startAt += len;
- for (var name in descs) {
- property = descs[name];
+ for(idx=startAt;idx>=0;idx--) {
+ if (this[idx] === object) return idx ;
+ }
+ return -1;
+ },
- if (property instanceof Ember.ComputedProperty) {
- callback.call(binding || this, name, property._meta || empty);
- }
+ copy: function(deep) {
+ if (deep) {
+ return this.map(function(item){ return Ember.copy(item, true); });
}
+
+ return this.slice();
}
+});
+// Remove any methods implemented natively so we don't override them
+var ignore = ['length'];
+Ember.EnumerableUtils.forEach(NativeArray.keys(), function(methodName) {
+ if (Array.prototype[methodName]) ignore.push(methodName);
});
-if (Ember.config.overrideClassMixin) {
- Ember.config.overrideClassMixin(ClassMixin);
+if (ignore.length>0) {
+ NativeArray = NativeArray.without.apply(NativeArray, ignore);
}
-CoreObject.ClassMixin = ClassMixin;
-ClassMixin.apply(CoreObject);
-
/**
- @class CoreObject
+ The NativeArray mixin contains the properties needed to to make the native
+ Array support Ember.MutableArray and all of its dependent APIs. Unless you
+ have `Ember.EXTEND_PROTOTYPES or `Ember.EXTEND_PROTOTYPES.Array` set to
+ false, this will be applied automatically. Otherwise you can apply the mixin
+ at anytime by calling `Ember.NativeArray.activate`.
+
+ @class NativeArray
@namespace Ember
+ @extends Ember.Mixin
+ @uses Ember.MutableArray
+ @uses Ember.MutableEnumerable
+ @uses Ember.Copyable
+ @uses Ember.Freezable
*/
-Ember.CoreObject = CoreObject;
+Ember.NativeArray = NativeArray;
+
+/**
+ Creates an `Ember.NativeArray` from an Array like object.
+ Does not modify the original object.
+
+ @method A
+ @for Ember
+ @return {Ember.NativeArray}
+*/
+Ember.A = function(arr){
+ if (arr === undefined) { arr = []; }
+ return Ember.Array.detect(arr) ? arr : Ember.NativeArray.apply(arr);
+};
+
+/**
+ Activates the mixin on the Array.prototype if not already applied. Calling
+ this method more than once is safe.
+
+ @method activate
+ @for Ember.NativeArray
+ @static
+ @return {void}
+*/
+Ember.NativeArray.activate = function() {
+ NativeArray.apply(Array.prototype);
+
+ Ember.A = function(arr) { return arr || []; };
+};
+
+if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.Array) {
+ Ember.NativeArray.activate();
+}
+
+
+})();
+(function() {
+var DeferredMixin = Ember.DeferredMixin, // mixins/deferred
+ EmberObject = Ember.Object, // system/object
+ get = Ember.get;
+
+var Deferred = Ember.Object.extend(DeferredMixin);
+
+Deferred.reopenClass({
+ promise: function(callback, binding) {
+ var deferred = Deferred.create();
+ callback.call(binding, deferred);
+ return get(deferred, 'promise');
+ }
+});
+
+Ember.Deferred = Deferred;
})();
@submodule ember-runtime
*/
-var get = Ember.get, set = Ember.set, guidFor = Ember.guidFor, none = Ember.none;
+var loadHooks = {};
+var loaded = {};
/**
- An unordered collection of objects.
-
- A Set works a bit like an array except that its items are not ordered.
- You can create a set to efficiently test for membership for an object. You
- can also iterate through a set just like an array, even accessing objects
- by index, however there is no guarantee as to their order.
-
- All Sets are observable via the Enumerable Observer API - which works
- on any enumerable object including both Sets and Arrays.
-
- ## Creating a Set
+@method onLoad
+@for Ember
+@param name {String} name of hook
+@param callback {Function} callback to be called
+*/
+Ember.onLoad = function(name, callback) {
+ var object;
- You can create a set like you would most objects using
- `new Ember.Set()`. Most new sets you create will be empty, but you can
- also initialize the set with some content by passing an array or other
- enumerable of objects to the constructor.
+ loadHooks[name] = loadHooks[name] || Ember.A();
+ loadHooks[name].pushObject(callback);
- Finally, you can pass in an existing set and the set will be copied. You
- can also create a copy of a set by calling `Ember.Set#copy()`.
+ if (object = loaded[name]) {
+ callback(object);
+ }
+};
- #js
- // creates a new empty set
- var foundNames = new Ember.Set();
+/**
+@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;
- // creates a set with four names in it.
- var names = new Ember.Set(["Charles", "Tom", "Juan", "Alex"]); // :P
+ loaded[name] = object;
- // creates a copy of the names set.
- var namesCopy = new Ember.Set(names);
+ if (hooks = loadHooks[name]) {
+ loadHooks[name].forEach(function(callback) {
+ callback(object);
+ });
+ }
+};
- // same as above.
- var anotherNamesCopy = names.copy();
+})();
- ## Adding/Removing Objects
- You generally add or remove objects from a set using `add()` or
- `remove()`. You can add any type of object including primitives such as
- numbers, strings, and booleans.
- Unlike arrays, objects can only exist one time in a set. If you call `add()`
- on a set with the same object multiple times, the object will only be added
- once. Likewise, calling `remove()` with the same object multiple times will
- remove the object the first time and have no effect on future calls until
- you add the object to the set again.
+(function() {
- NOTE: You cannot add/remove null or undefined to a set. Any attempt to do so
- will be ignored.
+})();
- In addition to add/remove you can also call `push()`/`pop()`. Push behaves
- just like `add()` but `pop()`, unlike `remove()` will pick an arbitrary
- object, remove it and return it. This is a good way to use a set as a job
- queue when you don't care which order the jobs are executed in.
- ## Testing for an Object
- To test for an object's presence in a set you simply call
- `Ember.Set#contains()`.
+(function() {
+var get = Ember.get;
- ## Observing changes
+/**
+@module ember
+@submodule ember-runtime
+*/
- When using `Ember.Set`, you can observe the `"[]"` property to be
- alerted whenever the content changes. You can also add an enumerable
- observer to the set to be notified of specific objects that are added and
- removed from the set. See `Ember.Enumerable` for more information on
- enumerables.
+/**
+ `Ember.ControllerMixin` provides a standard interface for all classes that
+ compose Ember's controller layer: `Ember.Controller`,
+ `Ember.ArrayController`, and `Ember.ObjectController`.
- This is often unhelpful. If you are filtering sets of objects, for instance,
- it is very inefficient to re-filter all of the items each time the set
- changes. It would be better if you could just adjust the filtered set based
- on what was changed on the original set. The same issue applies to merging
- sets, as well.
+ 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.
- ## Other Methods
+ ## Views
- `Ember.Set` primary implements other mixin APIs. For a complete reference
- on the methods you will use with `Ember.Set`, please consult these mixins.
- The most useful ones will be `Ember.Enumerable` and
- `Ember.MutableEnumerable` which implement most of the common iterator
- methods you are used to on Array.
+ 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`.
- Note that you can also use the `Ember.Copyable` and `Ember.Freezable`
- APIs on `Ember.Set` as well. Once a set is frozen it can no longer be
- modified. The benefit of this is that when you call frozenCopy() on it,
- Ember will avoid making copies of the set. This allows you to write
- code that can know with certainty when the underlying set data will or
- will not be modified.
+ Within the view's template, the `Ember.View` instance can be accessed
+ through the controller with `{{view}}`.
- @class Set
+ ## 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.CoreObject
- @uses Ember.MutableEnumerable
- @uses Ember.Copyable
- @uses Ember.Freezable
- @since Ember 0.9
+ @extends Ember.Mixin
*/
-Ember.Set = Ember.CoreObject.extend(Ember.MutableEnumerable, Ember.Copyable, Ember.Freezable,
- /** @scope Ember.Set.prototype */ {
+Ember.ControllerMixin = Ember.Mixin.create({
+ /**
+ The object to which events from the view should be sent.
- // ..........................................................
- // IMPLEMENT ENUMERABLE APIS
- //
+ For example, when a Handlebars template uses the `{{action}}` helper,
+ it will attempt to send the event to the view's controller's `target`.
- /**
- This property will change as the number of objects in the set changes.
+ By default, a controller's `target` is set to the router after it is
+ instantiated by `Ember.Application#initialize`.
- @property length
- @type number
- @default 0
+ @property target
+ @default null
*/
- length: 0,
+ target: null,
- /**
- Clears the set. This is useful if you want to reuse an existing set
- without having to recreate it.
+ container: null,
- var colors = new Ember.Set(["red", "green", "blue"]);
- colors.length; => 3
- colors.clear();
- colors.length; => 0
+ store: null,
- @method clear
- @return {Ember.Set} An empty Set
- */
- clear: function() {
- if (this.isFrozen) { throw new Error(Ember.FROZEN_ERROR); }
+ send: function(actionName) {
+ var args = [].slice.call(arguments, 1), target;
- var len = get(this, 'length');
- if (len === 0) { return this; }
+ if (this[actionName]) {
+ Ember.assert("The controller " + this + " does not have the action " + actionName, typeof this[actionName] === 'function');
+ this[actionName].apply(this, args);
+ } else if(target = get(this, 'target')) {
+ Ember.assert("The target for controller " + this + " (" + target + ") did not define a `send` method", typeof target.send === 'function');
+ target.send.apply(target, arguments);
+ }
+ }
+});
- var guid;
+/**
+ @class Controller
+ @namespace Ember
+ @extends Ember.Object
+ @uses Ember.ControllerMixin
+*/
+Ember.Controller = Ember.Object.extend(Ember.ControllerMixin);
- this.enumerableContentWillChange(len, 0);
- Ember.propertyWillChange(this, 'firstObject');
- Ember.propertyWillChange(this, 'lastObject');
+})();
- for (var i=0; i < len; i++){
- guid = guidFor(this[i]);
- delete this[guid];
- delete this[i];
- }
- set(this, 'length', 0);
- Ember.propertyDidChange(this, 'firstObject');
- Ember.propertyDidChange(this, 'lastObject');
- this.enumerableContentDidChange(len, 0);
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- return this;
- },
+var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach;
- /**
- Returns true if the passed object is also an enumerable that contains the
- same objects as the receiver.
+/**
+ `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:
- var colors = ["red", "green", "blue"],
- same_colors = new Ember.Set(colors);
- same_colors.isEqual(colors); => true
- same_colors.isEqual(["purple", "brown"]); => false
+ ```javascript
+ 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'},
+ ];
- @method isEqual
- @param {Ember.Set} obj the other object.
- @return {Boolean}
- */
- isEqual: function(obj) {
- // fail fast
- if (!Ember.Enumerable.detect(obj)) return false;
+ songsController = Ember.ArrayController.create({
+ content: songs,
+ sortProperties: ['trackNumber']
+ });
- var loc = get(this, 'length');
- if (get(obj, 'length') !== loc) return false;
+ songsController.get('firstObject'); // {trackNumber: 2, title: 'Back in the U.S.S.R.'}
- while(--loc >= 0) {
- if (!obj.contains(this[loc])) return false;
- }
+ songsController.addObject({trackNumber: 1, title: 'Dear Prudence'});
+ songsController.get('firstObject'); // {trackNumber: 1, title: 'Dear Prudence'}
+ ```
- return true;
+ @class SortableMixin
+ @namespace Ember
+ @extends Ember.Mixin
+ @uses Ember.MutableEnumerable
+*/
+Ember.SortableMixin = Ember.Mixin.create(Ember.MutableEnumerable, {
+ sortProperties: null,
+ sortAscending: true,
+
+ orderBy: function(item1, item2) {
+ var result = 0,
+ sortProperties = get(this, 'sortProperties'),
+ sortAscending = get(this, 'sortAscending');
+
+ Ember.assert("you need to define `sortProperties`", !!sortProperties);
+
+ forEach(sortProperties, function(propertyName) {
+ if (result === 0) {
+ result = Ember.compare(get(item1, propertyName), get(item2, propertyName));
+ if ((result !== 0) && !sortAscending) {
+ result = (-1) * result;
+ }
+ }
+ });
+
+ return result;
},
- /**
- Adds an object to the set. Only non-null objects can be added to a set
- and those can only be added once. If the object is already in the set or
- the passed value is null this method will have no effect.
+ destroy: function() {
+ var content = get(this, 'content'),
+ sortProperties = get(this, 'sortProperties');
- This is an alias for `Ember.MutableEnumerable.addObject()`.
+ if (content && sortProperties) {
+ forEach(content, function(item) {
+ forEach(sortProperties, function(sortProperty) {
+ Ember.removeObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
+ }, this);
+ }, this);
+ }
- var colors = new Ember.Set();
- colors.add("blue"); => ["blue"]
- colors.add("blue"); => ["blue"]
- colors.add("red"); => ["blue", "red"]
- colors.add(null); => ["blue", "red"]
- colors.add(undefined); => ["blue", "red"]
+ return this._super();
+ },
- @method add
- @param {Object} obj The object to add.
- @return {Ember.Set} The set itself.
- */
- add: Ember.alias('addObject'),
+ isSorted: Ember.computed('sortProperties', function() {
+ return !!get(this, 'sortProperties');
+ }),
- /**
- Removes the object from the set if it is found. If you pass a null value
- or an object that is already not in the set, this method will have no
- effect. This is an alias for `Ember.MutableEnumerable.removeObject()`.
+ arrangedContent: Ember.computed('content', 'sortProperties.@each', function(key, value) {
+ var content = get(this, 'content'),
+ isSorted = get(this, 'isSorted'),
+ sortProperties = get(this, 'sortProperties'),
+ self = this;
- var colors = new Ember.Set(["red", "green", "blue"]);
- colors.remove("red"); => ["blue", "green"]
- colors.remove("purple"); => ["blue", "green"]
- colors.remove(null); => ["blue", "green"]
+ if (content && isSorted) {
+ content = content.slice();
+ content.sort(function(item1, item2) {
+ return self.orderBy(item1, item2);
+ });
+ forEach(content, function(item) {
+ forEach(sortProperties, function(sortProperty) {
+ Ember.addObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
+ }, this);
+ }, this);
+ return Ember.A(content);
+ }
- @method remove
- @param {Object} obj The object to remove
- @return {Ember.Set} The set itself.
- */
- remove: Ember.alias('removeObject'),
+ return content;
+ }),
- /**
- Removes the last element from the set and returns it, or null if it's empty.
+ _contentWillChange: Ember.beforeObserver(function() {
+ var content = get(this, 'content'),
+ sortProperties = get(this, 'sortProperties');
- var colors = new Ember.Set(["green", "blue"]);
- colors.pop(); => "blue"
- colors.pop(); => "green"
- colors.pop(); => null
+ if (content && sortProperties) {
+ forEach(content, function(item) {
+ forEach(sortProperties, function(sortProperty) {
+ Ember.removeObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
+ }, this);
+ }, this);
+ }
- @method pop
- @return {Object} The removed object from the set or null.
- */
- pop: function() {
- if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR);
- var obj = this.length > 0 ? this[this.length-1] : null;
- this.remove(obj);
- return obj;
- },
+ this._super();
+ }, 'content'),
- /**
- Inserts the given object on to the end of the set. It returns
- the set itself.
+ sortAscendingWillChange: Ember.beforeObserver(function() {
+ this._lastSortAscending = get(this, 'sortAscending');
+ }, 'sortAscending'),
- This is an alias for `Ember.MutableEnumerable.addObject()`.
+ sortAscendingDidChange: Ember.observer(function() {
+ if (get(this, 'sortAscending') !== this._lastSortAscending) {
+ var arrangedContent = get(this, 'arrangedContent');
+ arrangedContent.reverseObjects();
+ }
+ }, 'sortAscending'),
- var colors = new Ember.Set();
- colors.push("red"); => ["red"]
- colors.push("green"); => ["red", "green"]
- colors.push("blue"); => ["red", "green", "blue"]
+ contentArrayWillChange: function(array, idx, removedCount, addedCount) {
+ var isSorted = get(this, 'isSorted');
- @method push
- @return {Ember.Set} The set itself.
- */
- push: Ember.alias('addObject'),
+ if (isSorted) {
+ var arrangedContent = get(this, 'arrangedContent');
+ var removedObjects = array.slice(idx, idx+removedCount);
+ var sortProperties = get(this, 'sortProperties');
- /**
- Removes the last element from the set and returns it, or null if it's empty.
+ forEach(removedObjects, function(item) {
+ arrangedContent.removeObject(item);
- This is an alias for `Ember.Set.pop()`.
+ forEach(sortProperties, function(sortProperty) {
+ Ember.removeObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
+ }, this);
+ }, this);
+ }
- var colors = new Ember.Set(["green", "blue"]);
- colors.shift(); => "blue"
- colors.shift(); => "green"
- colors.shift(); => null
+ return this._super(array, idx, removedCount, addedCount);
+ },
- @method shift
- @return {Object} The removed object from the set or null.
- */
- shift: Ember.alias('pop'),
+ contentArrayDidChange: function(array, idx, removedCount, addedCount) {
+ var isSorted = get(this, 'isSorted'),
+ sortProperties = get(this, 'sortProperties');
- /**
- Inserts the given object on to the end of the set. It returns
- the set itself.
+ if (isSorted) {
+ var addedObjects = array.slice(idx, idx+addedCount);
+ var arrangedContent = get(this, 'arrangedContent');
- This is an alias of `Ember.Set.push()`
+ forEach(addedObjects, function(item) {
+ this.insertItemSorted(item);
- var colors = new Ember.Set();
- colors.unshift("red"); => ["red"]
- colors.unshift("green"); => ["red", "green"]
- colors.unshift("blue"); => ["red", "green", "blue"]
+ forEach(sortProperties, function(sortProperty) {
+ Ember.addObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
+ }, this);
+ }, this);
+ }
- @method unshift
- @return {Ember.Set} The set itself.
- */
- unshift: Ember.alias('push'),
+ return this._super(array, idx, removedCount, addedCount);
+ },
- /**
- Adds each object in the passed enumerable to the set.
+ insertItemSorted: function(item) {
+ var arrangedContent = get(this, 'arrangedContent');
+ var length = get(arrangedContent, 'length');
- This is an alias of `Ember.MutableEnumerable.addObjects()`
+ var idx = this._binarySearch(item, 0, length);
+ arrangedContent.insertAt(idx, item);
+ },
- var colors = new Ember.Set();
- colors.addEach(["red", "green", "blue"]); => ["red", "green", "blue"]
+ contentItemSortPropertyDidChange: function(item) {
+ var arrangedContent = get(this, 'arrangedContent'),
+ oldIndex = arrangedContent.indexOf(item),
+ leftItem = arrangedContent.objectAt(oldIndex - 1),
+ rightItem = arrangedContent.objectAt(oldIndex + 1),
+ leftResult = leftItem && this.orderBy(item, leftItem),
+ rightResult = rightItem && this.orderBy(item, rightItem);
- @method addEach
- @param {Ember.Enumerable} objects the objects to add.
- @return {Ember.Set} The set itself.
- */
- addEach: Ember.alias('addObjects'),
+ if (leftResult < 0 || rightResult > 0) {
+ arrangedContent.removeObject(item);
+ this.insertItemSorted(item);
+ }
+ },
- /**
- Removes each object in the passed enumerable to the set.
+ _binarySearch: function(item, low, high) {
+ var mid, midItem, res, arrangedContent;
- This is an alias of `Ember.MutableEnumerable.removeObjects()`
+ if (low === high) {
+ return low;
+ }
- var colors = new Ember.Set(["red", "green", "blue"]);
- colors.removeEach(["red", "blue"]); => ["green"]
+ arrangedContent = get(this, 'arrangedContent');
- @method removeEach
- @param {Ember.Enumerable} objects the objects to remove.
- @return {Ember.Set} The set itself.
- */
- removeEach: Ember.alias('removeObjects'),
+ mid = low + Math.floor((high - low) / 2);
+ midItem = arrangedContent.objectAt(mid);
- // ..........................................................
- // PRIVATE ENUMERABLE SUPPORT
- //
+ res = this.orderBy(midItem, item);
- init: function(items) {
- this._super();
- if (items) this.addObjects(items);
- },
+ if (res < 0) {
+ return this._binarySearch(item, mid+1, high);
+ } else if (res > 0) {
+ return this._binarySearch(item, low, mid);
+ }
- // implement Ember.Enumerable
- nextObject: function(idx) {
- return this[idx];
- },
+ return mid;
+ }
+});
- // more optimized version
- firstObject: Ember.computed(function() {
- return this.length > 0 ? this[0] : undefined;
- }).property().cacheable(),
+})();
- // more optimized version
- lastObject: Ember.computed(function() {
- return this.length > 0 ? this[this.length-1] : undefined;
- }).property().cacheable(),
- // implements Ember.MutableEnumerable
- addObject: function(obj) {
- if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR);
- if (none(obj)) return this; // nothing to do
- var guid = guidFor(obj),
- idx = this[guid],
- len = get(this, 'length'),
- added ;
+(function() {
+/**
+@module ember
+@submodule ember-runtime
+*/
- if (idx>=0 && idx<len && (this[idx] === obj)) return this; // added
+var get = Ember.get, set = Ember.set, isGlobalPath = Ember.isGlobalPath,
+ forEach = Ember.EnumerableUtils.forEach, replace = Ember.EnumerableUtils.replace;
- added = [obj];
+/**
+ `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.
- this.enumerableContentWillChange(null, added);
- Ember.propertyWillChange(this, 'lastObject');
+ The advantage of using an `ArrayController` is that you only have to set up
+ your view bindings once; to change what's displayed, simply swap out the
+ `content` property on the controller.
- len = get(this, 'length');
- this[guid] = len;
- this[len] = obj;
- set(this, 'length', len+1);
+ 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:
- Ember.propertyDidChange(this, 'lastObject');
- this.enumerableContentDidChange(null, added);
+ ```javascript
+ MyApp.listController = Ember.ArrayController.create();
- return this;
- },
+ $.get('people.json', function(data) {
+ MyApp.listController.set('content', data);
+ });
+ ```
- // implements Ember.MutableEnumerable
- removeObject: function(obj) {
- if (get(this, 'isFrozen')) throw new Error(Ember.FROZEN_ERROR);
- if (none(obj)) return this; // nothing to do
+ Then, create a view that binds to your new controller:
- var guid = guidFor(obj),
- idx = this[guid],
- len = get(this, 'length'),
- isFirst = idx === 0,
- isLast = idx === len-1,
- last, removed;
+ ```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
+ capability comes from `Ember.ArrayProxy`, which this class inherits from.
- if (idx>=0 && idx<len && (this[idx] === obj)) {
- removed = [obj];
+ Sometimes you want to display computed properties within the body of an
+ `#each` helper that depend on the underlying items in `content`, but are not
+ present on those items. To do this, set `itemController` to the name of a
+ controller (probably an `ObjectController`) that will wrap each individual item.
- this.enumerableContentWillChange(removed, null);
- if (isFirst) { Ember.propertyWillChange(this, 'firstObject'); }
- if (isLast) { Ember.propertyWillChange(this, 'lastObject'); }
+ For example:
- // swap items - basically move the item to the end so it can be removed
- if (idx < len-1) {
- last = this[len-1];
- this[idx] = last;
- this[guidFor(last)] = idx;
- }
+ ```handlebars
+ {{#each post in controller}}
+ <li>{{title}} ({{titleLength}} characters)</li>
+ {{/each}}
+ ```
- delete this[guid];
- delete this[len-1];
- set(this, 'length', len-1);
+ ```javascript
+ App.PostsController = Ember.ArrayController.extend({
+ itemController: 'post'
+ });
- if (isFirst) { Ember.propertyDidChange(this, 'firstObject'); }
- if (isLast) { Ember.propertyDidChange(this, 'lastObject'); }
- this.enumerableContentDidChange(removed, null);
- }
+ App.PostController = Ember.ObjectController.extend({
+ // the `title` property will be proxied to the underlying post.
- return this;
- },
+ titleLength: function() {
+ return this.get('title').length;
+ }.property('title')
+ });
+ ```
- // optimized version
- contains: function(obj) {
- return this[guidFor(obj)]>=0;
- },
+ In some cases it is helpful to return a different `itemController` depending
+ on the particular item. Subclasses can do this by overriding
+ `lookupItemController`.
- copy: function() {
- var C = this.constructor, ret = new C(), loc = get(this, 'length');
- set(ret, 'length', loc);
- while(--loc>=0) {
- ret[loc] = this[loc];
- ret[guidFor(this[loc])] = loc;
- }
- return ret;
- },
+ For example:
- toString: function() {
- var len = this.length, idx, array = [];
- for(idx = 0; idx < len; idx++) {
- array[idx] = this[idx];
+ ```javascript
+ App.MyArrayController = Ember.ArrayController.extend({
+ lookupItemController: function( object ) {
+ if (object.get('isSpecial')) {
+ return "special"; // use App.SpecialController
+ } else {
+ return "regular"; // use App.RegularController
+ }
}
- return "Ember.Set<%@>".fmt(array.join(','));
- }
-
-});
+ });
+ ```
-})();
+ @class ArrayController
+ @namespace Ember
+ @extends Ember.ArrayProxy
+ @uses Ember.SortableMixin
+ @uses Ember.ControllerMixin
+*/
+Ember.ArrayController = Ember.ArrayProxy.extend(Ember.ControllerMixin,
+ Ember.SortableMixin, {
+ /**
+ The controller used to wrap items, if any.
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ @property itemController
+ @type String
+ @default null
+ */
+ itemController: null,
-/**
- `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.
+ /**
+ Return the name of the controller to wrap items, or `null` if items should
+ be returned directly. The default implementation simply returns the
+ `itemController` property, but subclasses can override this method to return
+ different controllers for different objects.
- @class Object
- @namespace Ember
- @extends Ember.CoreObject
- @uses Ember.Observable
-*/
-Ember.Object = Ember.CoreObject.extend(Ember.Observable);
+ For example:
-})();
+ ```javascript
+ App.MyArrayController = Ember.ArrayController.extend({
+ lookupItemController: function( object ) {
+ if (object.get('isSpecial')) {
+ return "special"; // use App.SpecialController
+ } else {
+ return "regular"; // use App.RegularController
+ }
+ }
+ });
+ ```
+ @method
+ @type String
+ @default null
+ */
+ lookupItemController: function(object) {
+ return get(this, 'itemController');
+ },
+ objectAtContent: function(idx) {
+ var length = get(this, 'length'),
+ object = get(this,'arrangedContent').objectAt(idx),
+ controllerClass = this.lookupItemController(object);
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ if (controllerClass && idx < length) {
+ return this.controllerAt(idx, object, controllerClass);
+ } else {
+ // When controllerClass is falsy we have not opted in to using item
+ // controllers, so return the object directly. However, when
+ // controllerClass is defined but the index is out of range, we want to
+ // return the "out of range" value, whatever that might be. Rather than
+ // make assumptions (e.g. guessing `null` or `undefined`) we defer this to
+ // `arrangedContent`.
+ return object;
+ }
+ },
-var indexOf = Ember.ArrayPolyfills.indexOf;
+ arrangedContentDidChange: function() {
+ this._super();
+ this._resetSubContainers();
+ },
-/**
- 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.
+ arrayContentDidChange: function(idx, removedCnt, addedCnt) {
+ var subContainers = get(this, 'subContainers'),
+ subContainersToRemove = subContainers.slice(idx, idx+removedCnt);
- # Example Usage
+ forEach(subContainersToRemove, function(subContainer) {
+ if (subContainer) { subContainer.destroy(); }
+ });
- MyFramework = Ember.Namespace.create({
- VERSION: '1.0.0'
- });
+ replace(subContainers, idx, removedCnt, new Array(addedCnt));
- @class Namespace
- @namespace Ember
- @extends Ember.Object
-*/
-Ember.Namespace = Ember.Object.extend({
- isNamespace: true,
+ // The shadow array of subcontainers must be updated before we trigger
+ // observers, otherwise observers will get the wrong subcontainer when
+ // calling `objectAt`
+ this._super(idx, removedCnt, addedCnt);
+ },
init: function() {
- Ember.Namespace.NAMESPACES.push(this);
- Ember.Namespace.PROCESSED = false;
+ this._super();
+ this._resetSubContainers();
},
- toString: function() {
- Ember.identifyNamespaces();
- return this[Ember.GUID_KEY+'_name'];
+ controllerAt: function(idx, object, controllerClass) {
+ var container = get(this, 'container'),
+ subContainers = get(this, 'subContainers'),
+ subContainer = subContainers[idx],
+ controller;
+
+ if (!subContainer) {
+ subContainer = subContainers[idx] = container.child();
+ }
+
+ controller = subContainer.lookup("controller:" + controllerClass);
+ if (!controller) {
+ throw new Error('Could not resolve itemController: "' + controllerClass + '"');
+ }
+
+ controller.set('target', this);
+ controller.set('content', object);
+
+ return controller;
},
- destroy: function() {
- var namespaces = Ember.Namespace.NAMESPACES;
- window[this.toString()] = undefined;
- namespaces.splice(indexOf.call(namespaces, this), 1);
- this._super();
+ subContainers: null,
+
+ _resetSubContainers: function() {
+ var subContainers = get(this, 'subContainers');
+
+ if (subContainers) {
+ forEach(subContainers, function(subContainer) {
+ if (subContainer) { subContainer.destroy(); }
+ });
+ }
+
+ this.set('subContainers', Ember.A());
}
});
-Ember.Namespace.NAMESPACES = [Ember];
-Ember.Namespace.PROCESSED = false;
-
})();
*/
/**
- 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.
+ `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.
- Currently Ember.Application is very similar to Ember.Namespace. However, this
- class may be augmented by additional frameworks so it is important to use
- this instance when building new applications.
+ `Ember.ObjectController` derives its functionality from its superclass
+ `Ember.ObjectProxy` and the `Ember.ControllerMixin` mixin.
- # Example Usage
+ @class ObjectController
+ @namespace Ember
+ @extends Ember.ObjectProxy
+ @uses Ember.ControllerMixin
+**/
+Ember.ObjectController = Ember.ObjectProxy.extend(Ember.ControllerMixin);
- MyApp = Ember.Application.create({
- VERSION: '1.0.0',
- store: Ember.Store.create().from(Ember.fixtures)
- });
+})();
- MyApp.ready = function() {
- //..init code goes here...
- }
- @class Application
- @namespace Ember
- @extends Ember.Namespace
-*/
-Ember.Application = Ember.Namespace.extend();
+(function() {
})();
(function() {
/**
+Ember Runtime
+
@module ember
@submodule ember-runtime
+@requires ember-metal
*/
+})();
-var get = Ember.get, set = Ember.set;
-
+(function() {
/**
- 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
- out the underlying array is useful.
-
- A simple example of usage:
-
- var pets = ['dog', 'cat', 'fish'];
- var ap = Ember.ArrayProxy.create({ content: Ember.A(pets) });
- ap.get('firstObject'); // => 'dog'
- ap.set('content', ['amoeba', 'paramecium']);
- ap.get('firstObject'); // => 'amoeba'
-
- This class can also be useful as a layer to transform the contents of
- an array, as they are accessed. This can be done by overriding
- `objectAtContent`:
+@module ember
+@submodule ember-views
+*/
- var pets = ['dog', 'cat', 'fish'];
- var ap = Ember.ArrayProxy.create({
- content: Ember.A(pets),
- objectAtContent: function(idx) {
- return this.get('content').objectAt(idx).toUpperCase();
- }
- });
- ap.get('firstObject'); // => 'DOG'
+var jQuery = Ember.imports.jQuery;
+Ember.assert("Ember Views require jQuery 1.7 (>= 1.7.2), 1.8 or 1.9", jQuery && (jQuery().jquery.match(/^1\.(7(?!$)(?!\.[01])|8|9)(\.\d+)?(pre|rc\d?)?/) || Ember.ENV.FORCE_JQUERY));
+/**
+ Alias for jQuery
- @class ArrayProxy
- @namespace Ember
- @extends Ember.Object
- @uses Ember.MutableArray
+ @method $
+ @for Ember
*/
-Ember.ArrayProxy = Ember.Object.extend(Ember.MutableArray,
-/** @scope Ember.ArrayProxy.prototype */ {
-
- /**
- The content array. Must be an object that implements Ember.Array and/or
- Ember.MutableArray.
+Ember.$ = jQuery;
- @property content
- @type Ember.Array
- */
- content: null,
-
- /**
- 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');
- }).cacheable(),
+})();
- /**
- Should actually retrieve the object at the specified index from the
- content. You can override this method in subclasses to transform the
- content item to something new.
- This method will only be called if content is non-null.
- @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);
- },
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- /**
- Should actually replace the specified objects on the content array.
- You can override this method in subclasses to transform the content item
- into something new.
+// 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');
- This method will only be called if content is non-null.
+// Copies the `dataTransfer` property from a browser event object onto the
+// jQuery event object for the specified events
+Ember.EnumerableUtils.forEach(dragEvents, function(eventName) {
+ Ember.$.event.fixHooks[eventName] = { props: ['dataTransfer'] };
+});
- @method replaceContent
- @param {Number} idx The starting index
- @param {Number} amt The number of items to remove from the content.
- @param {Array} objects Optional array of objects to insert or null if no objects.
- @return {void}
- */
- replaceContent: function(idx, amt, objects) {
- get(this, 'arrangedContent').replace(idx, amt, objects);
- },
+})();
- /**
- @private
- Invoked when the content property is about to change. Notifies observers that the
- entire array content will change.
- @method _contentWillChange
- */
- _contentWillChange: Ember.beforeObserver(function() {
- this._teardownContent();
- }, 'content'),
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- _teardownContent: function() {
- var content = get(this, 'content');
+/*** BEGIN METAMORPH HELPERS ***/
- if (content) {
- content.removeArrayObserver(this, {
- willChange: 'contentArrayWillChange',
- didChange: 'contentArrayDidChange'
- });
- }
- },
+// Internet Explorer prior to 9 does not allow setting innerHTML if the first element
+// is a "zero-scope" element. This problem can be worked around by making
+// the first node an invisible text node. We, like Modernizr, use ­
+var needsShy = (function(){
+ var testEl = document.createElement('div');
+ testEl.innerHTML = "<div></div>";
+ testEl.firstChild.innerHTML = "<script></script>";
+ return testEl.firstChild.innerHTML === '';
+})();
- contentArrayWillChange: Ember.K,
- contentArrayDidChange: Ember.K,
+// IE 8 (and likely earlier) likes to move whitespace preceeding
+// a script tag to appear after it. This means that we can
+// accidentally remove whitespace when updating a morph.
+var movesWhitespace = (function() {
+ var testEl = document.createElement('div');
+ testEl.innerHTML = "Test: <script type='text/x-placeholder'></script>Value";
+ return testEl.childNodes[0].nodeValue === 'Test:' &&
+ testEl.childNodes[2].nodeValue === ' Value';
+})();
- /**
- @private
+// Use this to find children by ID instead of using jQuery
+var findChildById = function(element, id) {
+ if (element.getAttribute('id') === id) { return element; }
- Invoked when the content property changes. Notifies observers that the
- entire array content has changed.
+ var len = element.childNodes.length, idx, node, found;
+ for (idx=0; idx<len; idx++) {
+ node = element.childNodes[idx];
+ found = node.nodeType === 1 && findChildById(node, id);
+ if (found) { return found; }
+ }
+};
- @method _contentDidChange
- */
- _contentDidChange: Ember.observer(function() {
- var content = get(this, 'content');
+var setInnerHTMLWithoutFix = function(element, html) {
+ if (needsShy) {
+ html = '­' + html;
+ }
- Ember.assert("Can't set ArrayProxy's content to itself", content !== this);
+ var matches = [];
+ if (movesWhitespace) {
+ // Right now we only check for script tags with ids with the
+ // goal of targeting morphs.
+ html = html.replace(/(\s+)(<script id='([^']+)')/g, function(match, spaces, tag, id) {
+ matches.push([id, spaces]);
+ return tag;
+ });
+ }
- this._setupContent();
- }, 'content'),
+ element.innerHTML = html;
- _setupContent: function() {
- var content = get(this, 'content');
+ // If we have to do any whitespace adjustments do them now
+ if (matches.length > 0) {
+ var len = matches.length, idx;
+ for (idx=0; idx<len; idx++) {
+ var script = findChildById(element, matches[idx][0]),
+ node = document.createTextNode(matches[idx][1]);
+ script.parentNode.insertBefore(node, script);
+ }
+ }
- if (content) {
- content.addArrayObserver(this, {
- willChange: 'contentArrayWillChange',
- didChange: 'contentArrayDidChange'
- });
+ if (needsShy) {
+ var shyElement = element.firstChild;
+ while (shyElement.nodeType === 1 && !shyElement.nodeName) {
+ shyElement = shyElement.firstChild;
}
- },
+ if (shyElement.nodeType === 3 && shyElement.nodeValue.charAt(0) === "\u00AD") {
+ shyElement.nodeValue = shyElement.nodeValue.slice(1);
+ }
+ }
+};
- _arrangedContentWillChange: Ember.beforeObserver(function() {
- var arrangedContent = get(this, 'arrangedContent'),
- len = arrangedContent ? get(arrangedContent, 'length') : 0;
+/*** END METAMORPH HELPERS */
- this.arrangedContentArrayWillChange(this, 0, len, undefined);
- this.arrangedContentWillChange(this);
- this._teardownArrangedContent(arrangedContent);
- }, 'arrangedContent'),
+var innerHTMLTags = {};
+var canSetInnerHTML = function(tagName) {
+ if (innerHTMLTags[tagName] !== undefined) {
+ return innerHTMLTags[tagName];
+ }
- _arrangedContentDidChange: Ember.observer(function() {
- var arrangedContent = get(this, 'arrangedContent'),
- len = arrangedContent ? get(arrangedContent, 'length') : 0;
+ var canSet = true;
- Ember.assert("Can't set ArrayProxy's content to itself", arrangedContent !== this);
+ // IE 8 and earlier don't allow us to do innerHTML on select
+ if (tagName.toLowerCase() === 'select') {
+ var el = document.createElement('select');
+ setInnerHTMLWithoutFix(el, '<option value="test">Test</option>');
+ canSet = el.options.length === 1;
+ }
- this._setupArrangedContent();
+ innerHTMLTags[tagName] = canSet;
- this.arrangedContentDidChange(this);
- this.arrangedContentArrayDidChange(this, 0, undefined, len);
- }, 'arrangedContent'),
+ return canSet;
+};
- _setupArrangedContent: function() {
- var arrangedContent = get(this, 'arrangedContent');
+var setInnerHTML = function(element, html) {
+ var tagName = element.tagName;
- if (arrangedContent) {
- arrangedContent.addArrayObserver(this, {
- willChange: 'arrangedContentArrayWillChange',
- didChange: 'arrangedContentArrayDidChange'
- });
- }
- },
+ if (canSetInnerHTML(tagName)) {
+ setInnerHTMLWithoutFix(element, html);
+ } else {
+ Ember.assert("Can't set innerHTML on "+element.tagName+" in this browser", element.outerHTML);
- _teardownArrangedContent: function() {
- var arrangedContent = get(this, 'arrangedContent');
+ var startTag = element.outerHTML.match(new RegExp("<"+tagName+"([^>]*)>", 'i'))[0],
+ endTag = '</'+tagName+'>';
- if (arrangedContent) {
- arrangedContent.removeArrayObserver(this, {
- willChange: 'arrangedContentArrayWillChange',
- didChange: 'arrangedContentArrayDidChange'
- });
+ var wrapper = document.createElement('div');
+ setInnerHTMLWithoutFix(wrapper, startTag + html + endTag);
+ element = wrapper.firstChild;
+ while (element.tagName !== tagName) {
+ element = element.nextSibling;
}
- },
-
- arrangedContentWillChange: Ember.K,
- arrangedContentDidChange: Ember.K,
-
- objectAt: function(idx) {
- return get(this, 'content') && this.objectAtContent(idx);
- },
-
- 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(),
-
- replace: function(idx, amt, objects) {
- if (get(this, 'content')) this.replaceContent(idx, amt, objects);
- return this;
- },
-
- arrangedContentArrayWillChange: function(item, idx, removedCnt, addedCnt) {
- this.arrayContentWillChange(idx, removedCnt, addedCnt);
- },
-
- arrangedContentArrayDidChange: function(item, idx, removedCnt, addedCnt) {
- this.arrayContentDidChange(idx, removedCnt, addedCnt);
- },
-
- init: function() {
- this._super();
- this._setupContent();
- this._setupArrangedContent();
- },
-
- willDestroy: function() {
- this._teardownArrangedContent();
- this._teardownContent();
}
-});
+ return element;
+};
+
+function isSimpleClick(event) {
+ var modifier = event.shiftKey || event.metaKey || event.altKey || event.ctrlKey,
+ secondaryClick = event.which > 1; // IE9 may return undefined
+
+ return !modifier && !secondaryClick;
+}
+
+Ember.ViewUtils = {
+ setInnerHTML: setInnerHTML,
+ isSimpleClick: isSimpleClick
+};
})();
(function() {
/**
@module ember
-@submodule ember-runtime
+@submodule ember-views
*/
-var get = Ember.get,
- set = Ember.set,
- fmt = Ember.String.fmt,
- addBeforeObserver = Ember.addBeforeObserver,
- addObserver = Ember.addObserver,
- removeBeforeObserver = Ember.removeBeforeObserver,
- removeObserver = Ember.removeObserver,
- propertyWillChange = Ember.propertyWillChange,
- propertyDidChange = Ember.propertyDidChange;
-
-function contentPropertyWillChange(content, contentKey) {
- var key = contentKey.slice(8); // remove "content."
- if (key in this) { return; } // if shadowed in proxy
- propertyWillChange(this, key);
-}
-
-function contentPropertyDidChange(content, contentKey) {
- var key = contentKey.slice(8); // remove "content."
- if (key in this) { return; } // if shadowed in proxy
- propertyDidChange(this, key);
-}
+var get = Ember.get, set = Ember.set;
+var indexOf = Ember.ArrayPolyfills.indexOf;
-/**
- `Ember.ObjectProxy` forwards all properties not defined by the proxy itself
- to a proxied `content` object.
- object = Ember.Object.create({
- name: 'Foo'
- });
- proxy = Ember.ObjectProxy.create({
- content: object
- });
- // Access and change existing properties
- proxy.get('name') // => 'Foo'
- proxy.set('name', 'Bar');
- object.get('name') // => 'Bar'
- // Create new 'description' property on `object`
- proxy.set('description', 'Foo is a whizboo baz');
- object.get('description') // => 'Foo is a whizboo baz'
- While `content` is unset, setting a property to be delegated will throw an Error.
+var ClassSet = function() {
+ this.seen = {};
+ this.list = [];
+};
- proxy = Ember.ObjectProxy.create({
- content: null,
- flag: null
- });
- proxy.set('flag', true);
- proxy.get('flag'); // => true
- proxy.get('foo'); // => undefined
- proxy.set('foo', 'data'); // throws Error
+ClassSet.prototype = {
+ add: function(string) {
+ if (string in this.seen) { return; }
+ this.seen[string] = true;
- Delegated properties can be bound to and will change when content is updated.
+ this.list.push(string);
+ },
- Computed properties on the proxy itself can depend on delegated properties.
+ toDOM: function() {
+ return this.list.join(" ");
+ }
+};
- ProxyWithComputedProperty = Ember.ObjectProxy.extend({
- fullName: function () {
- var firstName = this.get('firstName'),
- lastName = this.get('lastName');
- if (firstName && lastName) {
- return firstName + ' ' + lastName;
- }
- return firstName || lastName;
- }.property('firstName', 'lastName')
- });
- proxy = ProxyWithComputedProperty.create();
- proxy.get('fullName'); => undefined
- proxy.set('content', {
- firstName: 'Tom', lastName: 'Dale'
- }); // triggers property change for fullName on proxy
- proxy.get('fullName'); => 'Tom Dale'
+/**
+ `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.
- @class ObjectProxy
+ @class RenderBuffer
@namespace Ember
- @extends Ember.Object
+ @constructor
*/
-Ember.ObjectProxy = Ember.Object.extend(
-/** @scope Ember.ObjectProxy.prototype */ {
- /**
- The object whose properties will be forwarded.
-
- @property content
- @type Ember.Object
- @default null
- */
- content: null,
- _contentDidChange: Ember.observer(function() {
- Ember.assert("Can't set ObjectProxy's content to itself", this.get('content') !== this);
- }, 'content'),
-
- willWatchProperty: function (key) {
- var contentKey = 'content.' + key;
- addBeforeObserver(this, contentKey, null, contentPropertyWillChange);
- addObserver(this, contentKey, null, contentPropertyDidChange);
- },
-
- didUnwatchProperty: function (key) {
- var contentKey = 'content.' + key;
- removeBeforeObserver(this, contentKey, null, contentPropertyWillChange);
- removeObserver(this, contentKey, null, contentPropertyDidChange);
- },
+Ember.RenderBuffer = function(tagName) {
+ return new Ember._RenderBuffer(tagName);
+};
- unknownProperty: function (key) {
- var content = get(this, 'content');
- if (content) {
- return get(content, key);
- }
- },
+Ember._RenderBuffer = function(tagName) {
+ this.tagNames = [tagName || null];
+ this.buffer = [];
+};
- 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);
- return set(content, key, value);
- }
-});
+Ember._RenderBuffer.prototype =
+/** @scope Ember.RenderBuffer.prototype */ {
-})();
+ // The root view's element
+ _element: null,
+ /**
+ @private
+ An internal set used to de-dupe class names when `addClass()` is
+ used. After each call to `addClass()`, the `classes` property
+ will be updated.
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ @property elementClasses
+ @type Array
+ @default []
+ */
+ elementClasses: null,
+ /**
+ Array of class names which will be applied in the class attribute.
-var set = Ember.set, get = Ember.get, guidFor = Ember.guidFor;
-var forEach = Ember.EnumerableUtils.forEach;
+ You can use `setClasses()` to set this property directly. If you
+ use `addClass()`, it will be maintained for you.
-var EachArray = Ember.Object.extend(Ember.Array, {
+ @property classes
+ @type Array
+ @default []
+ */
+ classes: null,
- init: function(content, keyName, owner) {
- this._super();
- this._keyName = keyName;
- this._owner = owner;
- this._content = content;
- },
+ /**
+ The id in of the element, to be applied in the id attribute.
- objectAt: function(idx) {
- var item = this._content.objectAt(idx);
- return item && get(item, this._keyName);
- },
+ You should not set this property yourself, rather, you should use
+ the `id()` method of `Ember.RenderBuffer`.
- length: Ember.computed(function() {
- var content = this._content;
- return content ? get(content, 'length') : 0;
- }).property().cacheable()
+ @property elementId
+ @type String
+ @default null
+ */
+ elementId: null,
-});
+ /**
+ A hash keyed on the name of the attribute and whose value will be
+ applied to that attribute. For example, if you wanted to apply a
+ `data-view="Foo.bar"` property to an element, you would set the
+ elementAttributes hash to `{'data-view':'Foo.bar'}`.
-var IS_OBSERVER = /^.+:(before|change)$/;
+ You should not maintain this hash yourself, rather, you should use
+ the `attr()` method of `Ember.RenderBuffer`.
-function addObserverForContentKey(content, keyName, proxy, idx, loc) {
- var objects = proxy._objects, guid;
- if (!objects) objects = proxy._objects = {};
+ @property elementAttributes
+ @type Hash
+ @default {}
+ */
+ elementAttributes: null,
- while(--loc>=idx) {
- var item = content.objectAt(loc);
- if (item) {
- Ember.addBeforeObserver(item, keyName, proxy, 'contentKeyWillChange');
- Ember.addObserver(item, keyName, proxy, 'contentKeyDidChange');
+ /**
+ The tagname of the element an instance of `Ember.RenderBuffer` represents.
- // keep track of the indicies each item was found at so we can map
- // it back when the obj changes.
- guid = guidFor(item);
- if (!objects[guid]) objects[guid] = [];
- objects[guid].push(loc);
- }
- }
-}
+ Usually, this gets set as the first parameter to `Ember.RenderBuffer`. For
+ example, if you wanted to create a `p` tag, then you would call
-function removeObserverForContentKey(content, keyName, proxy, idx, loc) {
- var objects = proxy._objects;
- if (!objects) objects = proxy._objects = {};
- var indicies, guid;
+ ```javascript
+ Ember.RenderBuffer('p')
+ ```
- while(--loc>=idx) {
- var item = content.objectAt(loc);
- if (item) {
- Ember.removeBeforeObserver(item, keyName, proxy, 'contentKeyWillChange');
- Ember.removeObserver(item, keyName, proxy, 'contentKeyDidChange');
+ @property elementTag
+ @type String
+ @default null
+ */
+ elementTag: null,
- guid = guidFor(item);
- indicies = objects[guid];
- indicies[indicies.indexOf(loc)] = null;
- }
- }
-}
+ /**
+ A hash keyed on the name of the style attribute and whose value will
+ be applied to that attribute. For example, if you wanted to apply a
+ `background-color:black;` style to an element, you would set the
+ elementStyle hash to `{'background-color':'black'}`.
-/**
- 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.
+ You should not maintain this hash yourself, rather, you should use
+ the `style()` method of `Ember.RenderBuffer`.
- @private
- @class EachProxy
- @namespace Ember
- @extends Ember.Object
-*/
-Ember.EachProxy = Ember.Object.extend({
+ @property elementStyle
+ @type Hash
+ @default {}
+ */
+ elementStyle: null,
- init: function(content) {
- this._super();
- this._content = content;
- content.addArrayObserver(this);
+ /**
+ Nested `RenderBuffers` will set this to their parent `RenderBuffer`
+ instance.
- // in case someone is already observing some keys make sure they are
- // added
- forEach(Ember.watchedEvents(this), function(eventName) {
- this.didAddListener(eventName);
- }, this);
- },
+ @property parentBuffer
+ @type Ember._RenderBuffer
+ */
+ parentBuffer: null,
/**
- You can directly access mapped properties by simply requesting them.
- The unknownProperty handler will generate an EachArray of each item.
+ Adds a string of HTML to the `RenderBuffer`.
- @method unknownProperty
- @param keyName {String}
- @param value {anything}
+ @method push
+ @param {String} string HTML to push into the buffer
+ @chainable
*/
- unknownProperty: function(keyName, value) {
- var ret;
- ret = new EachArray(this._content, keyName, this);
- Ember.defineProperty(this, keyName, null, ret);
- this.beginObservingContentKey(keyName);
- return ret;
+ push: function(string) {
+ this.buffer.push(string);
+ return this;
},
- // ..........................................................
- // ARRAY CHANGES
- // Invokes whenever the content array itself changes.
-
- arrayWillChange: function(content, idx, removedCnt, addedCnt) {
- var keys = this._keys, key, array, lim;
-
- lim = removedCnt>0 ? idx+removedCnt : -1;
- Ember.beginPropertyChanges(this);
-
- for(key in keys) {
- if (!keys.hasOwnProperty(key)) { continue; }
+ /**
+ Adds a class to the buffer, which will be rendered to the class attribute.
- if (lim>0) removeObserverForContentKey(content, key, this, idx, lim);
+ @method addClass
+ @param {String} className Class name to add to the buffer
+ @chainable
+ */
+ addClass: function(className) {
+ // lazily create elementClasses
+ var elementClasses = this.elementClasses = (this.elementClasses || new ClassSet());
+ this.elementClasses.add(className);
+ this.classes = this.elementClasses.list;
- Ember.propertyWillChange(this, key);
- }
+ return this;
+ },
- Ember.propertyWillChange(this._content, '@each');
- Ember.endPropertyChanges(this);
+ setClasses: function(classNames) {
+ this.classes = classNames;
},
- arrayDidChange: function(content, idx, removedCnt, addedCnt) {
- var keys = this._keys, key, array, lim;
+ /**
+ Sets the elementID to be used for the element.
- lim = addedCnt>0 ? idx+addedCnt : -1;
- Ember.beginPropertyChanges(this);
+ @method id
+ @param {String} id
+ @chainable
+ */
+ id: function(id) {
+ this.elementId = id;
+ return this;
+ },
- for(key in keys) {
- if (!keys.hasOwnProperty(key)) { continue; }
+ // duck type attribute functionality like jQuery so a render buffer
+ // can be used like a jQuery object in attribute binding scenarios.
- if (lim>0) addObserverForContentKey(content, key, this, idx, lim);
+ /**
+ Adds an attribute which will be rendered to the element.
- Ember.propertyDidChange(this, key);
+ @method attr
+ @param {String} name The name of the attribute
+ @param {String} value The value to add to the attribute
+ @chainable
+ @return {Ember.RenderBuffer|String} this or the current attribute value
+ */
+ attr: function(name, value) {
+ var attributes = this.elementAttributes = (this.elementAttributes || {});
+
+ if (arguments.length === 1) {
+ return attributes[name];
+ } else {
+ attributes[name] = value;
}
- Ember.propertyDidChange(this._content, '@each');
- Ember.endPropertyChanges(this);
+ return this;
},
- // ..........................................................
- // LISTEN FOR NEW OBSERVERS AND OTHER EVENT LISTENERS
- // Start monitoring keys based on who is listening...
+ /**
+ Remove an attribute from the list of attributes to render.
- didAddListener: function(eventName) {
- if (IS_OBSERVER.test(eventName)) {
- this.beginObservingContentKey(eventName.slice(0, -7));
- }
- },
+ @method removeAttr
+ @param {String} name The name of the attribute
+ @chainable
+ */
+ removeAttr: function(name) {
+ var attributes = this.elementAttributes;
+ if (attributes) { delete attributes[name]; }
- didRemoveListener: function(eventName) {
- if (IS_OBSERVER.test(eventName)) {
- this.stopObservingContentKey(eventName.slice(0, -7));
- }
+ return this;
},
- // ..........................................................
- // CONTENT KEY OBSERVING
- // Actual watch keys on the source content.
+ /**
+ Adds a style to the style attribute which will be rendered to the element.
- beginObservingContentKey: function(keyName) {
- var keys = this._keys;
- if (!keys) keys = this._keys = {};
- if (!keys[keyName]) {
- keys[keyName] = 1;
- var content = this._content,
- len = get(content, 'length');
- addObserverForContentKey(content, keyName, this, 0, len);
- } else {
- keys[keyName]++;
- }
- },
+ @method style
+ @param {String} name Name of the style
+ @param {String} value
+ @chainable
+ */
+ style: function(name, value) {
+ var style = this.elementStyle = (this.elementStyle || {});
- stopObservingContentKey: function(keyName) {
- var keys = this._keys;
- if (keys && (keys[keyName]>0) && (--keys[keyName]<=0)) {
- var content = this._content,
- len = get(content, 'length');
- removeObserverForContentKey(content, keyName, this, 0, len);
- }
+ this.elementStyle[name] = value;
+ return this;
},
- contentKeyWillChange: function(obj, keyName) {
- Ember.propertyWillChange(this, keyName);
+ begin: function(tagName) {
+ this.tagNames.push(tagName || null);
+ return this;
},
- contentKeyDidChange: function(obj, keyName) {
- Ember.propertyDidChange(this, keyName);
- }
+ pushOpeningTag: function() {
+ var tagName = this.currentTagName();
+ if (!tagName) { return; }
-});
+ if (!this._element && this.buffer.length === 0) {
+ this._element = this.generateElement();
+ return;
+ }
+ var buffer = this.buffer,
+ id = this.elementId,
+ classes = this.classes,
+ attrs = this.elementAttributes,
+ style = this.elementStyle,
+ prop;
+ buffer.push('<' + tagName);
-})();
+ if (id) {
+ buffer.push(' id="' + this._escapeAttribute(id) + '"');
+ this.elementId = null;
+ }
+ if (classes) {
+ buffer.push(' class="' + this._escapeAttribute(classes.join(' ')) + '"');
+ this.classes = null;
+ }
+ if (style) {
+ buffer.push(' style="');
+ for (prop in style) {
+ if (style.hasOwnProperty(prop)) {
+ buffer.push(prop + ':' + this._escapeAttribute(style[prop]) + ';');
+ }
+ }
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ buffer.push('"');
+ this.elementStyle = null;
+ }
-var get = Ember.get, set = Ember.set;
+ if (attrs) {
+ for (prop in attrs) {
+ if (attrs.hasOwnProperty(prop)) {
+ buffer.push(' ' + prop + '="' + this._escapeAttribute(attrs[prop]) + '"');
+ }
+ }
-// Add Ember.Array to Array.prototype. Remove methods with native
-// implementations and supply some more optimized versions of generic methods
-// because they are so common.
-var NativeArray = Ember.Mixin.create(Ember.MutableArray, Ember.Observable, Ember.Copyable, {
+ this.elementAttributes = null;
+ }
- // because length is a built-in property we need to know to just get the
- // original property.
- get: function(key) {
- if (key==='length') return this.length;
- else if ('number' === typeof key) return this[key];
- else return this._super(key);
+ buffer.push('>');
},
- objectAt: function(idx) {
- return this[idx];
+ pushClosingTag: function() {
+ var tagName = this.tagNames.pop();
+ if (tagName) { this.buffer.push('</' + tagName + '>'); }
},
- // primitive for array support.
- replace: function(idx, amt, objects) {
-
- if (this.isFrozen) throw Ember.FROZEN_ERROR ;
+ currentTagName: function() {
+ return this.tagNames[this.tagNames.length-1];
+ },
- // if we replaced exactly the same number of items, then pass only the
- // replaced range. Otherwise, pass the full remaining array length
- // since everything has shifted
- var len = objects ? get(objects, 'length') : 0;
- this.arrayContentWillChange(idx, amt, len);
+ generateElement: function() {
+ var tagName = this.tagNames.pop(), // pop since we don't need to close
+ element = document.createElement(tagName),
+ $element = Ember.$(element),
+ id = this.elementId,
+ classes = this.classes,
+ attrs = this.elementAttributes,
+ style = this.elementStyle,
+ styleBuffer = '', prop;
- if (!objects || objects.length === 0) {
- this.splice(idx, amt) ;
- } else {
- var args = [idx, amt].concat(objects) ;
- this.splice.apply(this,args) ;
+ if (id) {
+ $element.attr('id', id);
+ this.elementId = null;
}
-
- this.arrayContentDidChange(idx, amt, len);
- return this ;
- },
-
- // If you ask for an unknown property, then try to collect the value
- // from member items.
- unknownProperty: function(key, value) {
- var ret;// = this.reducedProperty(key, value) ;
- if ((value !== undefined) && ret === undefined) {
- ret = this[key] = value;
+ if (classes) {
+ $element.attr('class', classes.join(' '));
+ this.classes = null;
}
- return ret ;
- },
- // If browser did not implement indexOf natively, then override with
- // specialized version
- indexOf: function(object, startAt) {
- var idx, len = this.length;
+ if (style) {
+ for (prop in style) {
+ if (style.hasOwnProperty(prop)) {
+ styleBuffer += (prop + ':' + style[prop] + ';');
+ }
+ }
- if (startAt === undefined) startAt = 0;
- else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
- if (startAt < 0) startAt += len;
+ $element.attr('style', styleBuffer);
- for(idx=startAt;idx<len;idx++) {
- if (this[idx] === object) return idx ;
+ this.elementStyle = null;
}
- return -1;
- },
-
- lastIndexOf: function(object, startAt) {
- var idx, len = this.length;
- if (startAt === undefined) startAt = len-1;
- else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
- if (startAt < 0) startAt += len;
+ if (attrs) {
+ for (prop in attrs) {
+ if (attrs.hasOwnProperty(prop)) {
+ $element.attr(prop, attrs[prop]);
+ }
+ }
- for(idx=startAt;idx>=0;idx--) {
- if (this[idx] === object) return idx ;
+ this.elementAttributes = null;
}
- return -1;
+
+ return element;
},
- copy: function() {
- return this.slice();
- }
-});
+ /**
+ @method element
+ @return {DOMElement} The element corresponding to the generated HTML
+ of this buffer
+ */
+ element: function() {
+ var html = this.innerString();
-// Remove any methods implemented natively so we don't override them
-var ignore = ['length'];
-Ember.EnumerableUtils.forEach(NativeArray.keys(), function(methodName) {
- if (Array.prototype[methodName]) ignore.push(methodName);
-});
+ if (html) {
+ this._element = Ember.ViewUtils.setInnerHTML(this._element, html);
+ }
-if (ignore.length>0) {
- NativeArray = NativeArray.without.apply(NativeArray, ignore);
-}
+ return this._element;
+ },
-/**
- The NativeArray mixin contains the properties needed to to make the native
- Array support Ember.MutableArray and all of its dependent APIs. Unless you
- have Ember.EXTEND_PROTOTYPES set to false, this will be applied automatically.
- Otherwise you can apply the mixin at anytime by calling
- `Ember.NativeArray.activate`.
+ /**
+ Generates the HTML content for this buffer.
- @class NativeArray
- @namespace Ember
- @extends Ember.Mixin
- @uses Ember.MutableArray
- @uses Ember.MutableEnumerable
- @uses Ember.Copyable
- @uses Ember.Freezable
-*/
-Ember.NativeArray = NativeArray;
+ @method string
+ @return {String} The generated HTML
+ */
+ string: function() {
+ if (this._element) {
+ return this.element().outerHTML;
+ } else {
+ return this.innerString();
+ }
+ },
-/**
- Creates an Ember.NativeArray from an Array like object.
- Does not modify the original object.
+ innerString: function() {
+ return this.buffer.join('');
+ },
- @method A
- @for Ember
- @return {Ember.NativeArray}
-*/
-Ember.A = function(arr){
- if (arr === undefined) { arr = []; }
- return Ember.NativeArray.apply(arr);
-};
+ _escapeAttribute: function(value) {
+ // Stolen shamelessly from Handlebars
-/**
- Activates the mixin on the Array.prototype if not already applied. Calling
- this method more than once is safe.
+ var escape = {
+ "<": "<",
+ ">": ">",
+ '"': """,
+ "'": "'",
+ "`": "`"
+ };
- @method activate
- @for Ember.NativeArray
- @static
- @return {void}
-*/
-Ember.NativeArray.activate = function() {
- NativeArray.apply(Array.prototype);
+ var badChars = /&(?!\w+;)|[<>"'`]/g;
+ var possible = /[&<>"'`]/;
- Ember.A = function(arr) { return arr || []; };
-};
+ var escapeChar = function(chr) {
+ return escape[chr] || "&";
+ };
-if (Ember.EXTEND_PROTOTYPES) Ember.NativeArray.activate();
+ var string = value.toString();
+ if(!possible.test(string)) { return string; }
+ return string.replace(badChars, escapeChar);
+ }
+};
})();
(function() {
/**
@module ember
-@submodule ember-runtime
+@submodule ember-views
*/
-var get = Ember.get, set = Ember.set;
+var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
+
+/**
+ `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 */{
-Ember._PromiseChain = Ember.Object.extend({
- promises: null,
- failureCallback: Ember.K,
- successCallback: Ember.K,
- abortCallback: Ember.K,
- promiseSuccessCallback: Ember.K,
+ /**
+ @private
- runNextPromise: function() {
- if (get(this, 'isDestroyed')) { return; }
+ The root DOM element to which event listeners should be attached. Event
+ listeners will be attached to the document unless this is overridden.
- var item = get(this, 'promises').shiftObject();
- if (item) {
- var promise = get(item, 'promise') || item;
- Ember.assert("Cannot find promise to invoke", Ember.canInvoke(promise, 'then'));
+ Can be specified as a DOMElement or a selector string.
- var self = this;
+ The default body is a string since this may be evaluated before document.body
+ exists in the DOM.
- var successCallback = function() {
- self.promiseSuccessCallback.call(this, item, arguments);
- self.runNextPromise();
- };
+ @property rootElement
+ @type DOMElement
+ @default 'body'
+ */
+ rootElement: 'body',
+
+ /**
+ @private
+
+ Sets up event listeners for standard browser events.
+
+ This will be called after the browser sends a `DOMContentReady` event. By
+ 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 = {
+ touchstart : 'touchStart',
+ touchmove : 'touchMove',
+ touchend : 'touchEnd',
+ touchcancel : 'touchCancel',
+ keydown : 'keyDown',
+ keyup : 'keyUp',
+ keypress : 'keyPress',
+ mousedown : 'mouseDown',
+ mouseup : 'mouseUp',
+ contextmenu : 'contextMenu',
+ click : 'click',
+ dblclick : 'doubleClick',
+ mousemove : 'mouseMove',
+ focusin : 'focusIn',
+ focusout : 'focusOut',
+ mouseenter : 'mouseEnter',
+ mouseleave : 'mouseLeave',
+ submit : 'submit',
+ input : 'input',
+ change : 'change',
+ dragstart : 'dragStart',
+ drag : 'drag',
+ dragenter : 'dragEnter',
+ dragleave : 'dragLeave',
+ dragover : 'dragOver',
+ drop : 'drop',
+ dragend : 'dragEnd'
+ };
+
+ Ember.$.extend(events, addedEvents || {});
+
+ var rootElement = Ember.$(get(this, 'rootElement'));
+
+ Ember.assert(fmt('You cannot use the same root element (%@) multiple times in an Ember.Application', [rootElement.selector || rootElement[0].tagName]), !rootElement.is('.ember-application'));
+ Ember.assert('You cannot make a new Ember.Application using a root element that is a descendent of an existing Ember.Application', !rootElement.closest('.ember-application').length);
+ Ember.assert('You cannot make a new Ember.Application using a root element that is an ancestor of an existing Ember.Application', !rootElement.find('.ember-application').length);
+
+ rootElement.addClass('ember-application');
- var failureCallback = get(self, 'failureCallback');
+ Ember.assert('Unable to add "ember-application" class to rootElement. Make sure you set rootElement to the body or an element in the body.', rootElement.is('.ember-application'));
- promise.then(successCallback, failureCallback);
- } else {
- this.successCallback();
+ for (event in events) {
+ if (events.hasOwnProperty(event)) {
+ this.setupHandler(rootElement, event, events[event]);
+ }
}
},
- start: function() {
- this.runNextPromise();
- return this;
- },
+ /**
+ @private
- abort: function() {
- this.abortCallback();
- this.destroy();
- },
+ Registers an event listener on the document. If the given event is
+ triggered, the provided event handler will be triggered on the target view.
- init: function() {
- set(this, 'promises', Ember.A(get(this, 'promises')));
- this._super();
- }
-});
+ If the target view does not implement the event handler, or if the handler
+ returns `false`, the parent view will be called. The event will continue to
+ bubble to each successive parent view until it reaches the top.
+ For example, to have the `mouseDown` method called on the target view when
+ a `mousedown` event is received from the browser, do the following:
-})();
+ ```javascript
+ 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
+ */
+ setupHandler: function(rootElement, event, eventName) {
+ 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;
+ manager = self._findNearestEventManager(view,eventName);
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ if (manager && manager !== triggeringManager) {
+ result = self._dispatchEvent(manager, evt, eventName, view);
+ } else if (view) {
+ result = self._bubbleEvent(view,evt,eventName);
+ } else {
+ evt.stopPropagation();
+ }
-var loadHooks = {};
-var loaded = {};
+ return result;
+ }, this);
+ });
-/**
-@method onLoad
-@for Ember
-@param name {String} name of hook
-@param callback {Function} callback to be called
-*/
-Ember.onLoad = function(name, callback) {
- var object;
+ rootElement.delegate('[data-ember-action]', event + '.ember', function(evt) {
+ return Ember.handleErrors(function() {
+ var actionId = Ember.$(evt.currentTarget).attr('data-ember-action'),
+ action = Ember.Handlebars.ActionHelper.registeredActions[actionId],
+ handler = action.handler;
- loadHooks[name] = loadHooks[name] || Ember.A();
- loadHooks[name].pushObject(callback);
+ if (action.eventName === eventName) {
+ return handler(evt);
+ }
+ }, this);
+ });
+ },
- if (object = loaded[name]) {
- callback(object);
- }
-};
+ _findNearestEventManager: function(view, eventName) {
+ var manager = null;
-/**
-@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;
+ while (view) {
+ manager = get(view, 'eventManager');
+ if (manager && manager[eventName]) { break; }
- loaded[name] = object;
+ view = get(view, 'parentView');
+ }
- if (hooks = loadHooks[name]) {
- loadHooks[name].forEach(function(callback) {
- callback(object);
- });
- }
-};
+ return manager;
+ },
-})();
+ _dispatchEvent: function(object, evt, eventName, view) {
+ var result = true;
+
+ var handler = object[eventName];
+ if (Ember.typeOf(handler) === 'function') {
+ result = handler.call(object, evt, view);
+ // Do not preventDefault in eventManagers.
+ evt.stopPropagation();
+ }
+ else {
+ result = this._bubbleEvent(view, evt, eventName);
+ }
+ return result;
+ },
+ _bubbleEvent: function(view, evt, eventName) {
+ return Ember.run(function() {
+ return view.handleEvent(eventName, evt);
+ });
+ },
-(function() {
+ destroy: function() {
+ var rootElement = get(this, 'rootElement');
+ Ember.$(rootElement).undelegate('.ember').removeClass('ember-application');
+ return this._super();
+ }
+});
})();
(function() {
/**
@module ember
-@submodule ember-runtime
+@submodule ember-views
*/
-/**
- 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.
+// Add a new named queue for rendering views that happens
+// after bindings have synced, and a queue for scheduling actions
+// that that should occur after view rendering.
+var queues = Ember.run.queues;
+queues.splice(Ember.$.inArray('actions', queues)+1, 0, 'render', 'afterRender');
- ## 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
+(function() {
+/**
+@module ember
+@submodule ember-views
*/
-Ember.ControllerMixin = Ember.Mixin.create({
- /**
- The object to which events from the view should be sent.
- For example, when a Handlebars template uses the `{{action}}` helper,
- it will attempt to send the event to the view's controller's `target`.
+var get = Ember.get, set = Ember.set;
+
+// Original class declaration and documentation in runtime/lib/controllers/controller.js
+// NOTE: It may be possible with YUIDoc to combine docs in two locations
- By default, a controller's `target` is set to the router after it is
- instantiated by `Ember.Application#initialize`.
+/**
+Additional methods for the ControllerMixin
- @property target
- @default null
- */
+@class ControllerMixin
+@namespace Ember
+*/
+Ember.ControllerMixin.reopen({
target: null,
-
- store: null
+ namespace: null,
+ view: null,
+ container: null
});
-/**
- @class Controller
- @namespace Ember
- @extends Ember.Object
- @uses Ember.ControllerMixin
-*/
-Ember.Controller = Ember.Object.extend(Ember.ControllerMixin);
+})();
+
+
+
+(function() {
})();
(function() {
+var states = {};
+
/**
@module ember
-@submodule ember-runtime
+@submodule ember-views
*/
-var get = Ember.get, set = Ember.set, forEach = Ember.EnumerableUtils.forEach;
+var get = Ember.get, set = Ember.set, addObserver = Ember.addObserver, removeObserver = Ember.removeObserver;
+var meta = Ember.meta, guidFor = Ember.guidFor, fmt = Ember.String.fmt;
+var a_slice = [].slice;
+var a_forEach = Ember.EnumerableUtils.forEach;
+var a_addObject = Ember.EnumerableUtils.addObject;
-/**
- 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:
+var childViewsProperty = Ember.computed(function() {
+ var childViews = this._childViews;
- 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'},
- ];
+ var ret = Ember.A();
- songsController = Ember.ArrayController.create({
- content: songs,
- sortProperties: ['trackNumber']
- });
+ a_forEach(childViews, function(view) {
+ if (view.isVirtual) {
+ ret.pushObjects(get(view, 'childViews'));
+ } else {
+ ret.push(view);
+ }
+ });
- songsController.get('firstObject'); // {trackNumber: 2, title: 'Back in the U.S.S.R.'}
+ return ret;
+});
- songsController.addObject({trackNumber: 1, title: 'Dear Prudence'});
- songsController.get('firstObject'); // {trackNumber: 1, title: 'Dear Prudence'}
+Ember.warn("The VIEW_PRESERVES_CONTEXT flag has been removed and the functionality can no longer be disabled.", Ember.ENV.VIEW_PRESERVES_CONTEXT !== false);
+/**
+ 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.
- @class SortableMixin
- @namespace Ember
- @extends Ember.Mixin
- @uses Ember.MutableEnumerable
+ @property TEMPLATES
+ @for Ember
+ @type Hash
*/
-Ember.SortableMixin = Ember.Mixin.create(Ember.MutableEnumerable, {
- sortProperties: null,
- sortAscending: true,
+Ember.TEMPLATES = {};
- addObject: function(obj) {
- var content = get(this, 'content');
- content.pushObject(obj);
- },
+Ember.CoreView = Ember.Object.extend(Ember.Evented, {
+ isView: true,
- removeObject: function(obj) {
- var content = get(this, 'content');
- content.removeObject(obj);
- },
+ states: states,
- orderBy: function(item1, item2) {
- var result = 0,
- sortProperties = get(this, 'sortProperties'),
- sortAscending = get(this, 'sortAscending');
+ init: function() {
+ this._super();
- Ember.assert("you need to define `sortProperties`", !!sortProperties);
+ // Register the view for event handling. This hash is used by
+ // Ember.EventDispatcher to dispatch incoming events.
+ if (!this.isVirtual) Ember.View.views[this.elementId] = this;
- forEach(sortProperties, function(propertyName) {
- if (result === 0) {
- result = Ember.compare(get(item1, propertyName), get(item2, propertyName));
- if ((result !== 0) && !sortAscending) {
- result = (-1) * result;
- }
- }
+ this.addBeforeObserver('elementId', function() {
+ throw new Error("Changing a view's elementId after creation is not allowed");
});
- return result;
+ this.transitionTo('preRender');
},
- destroy: function() {
- var content = get(this, 'content'),
- sortProperties = get(this, 'sortProperties');
+ /**
+ If the view is currently inserted into the DOM of a parent view, this
+ property will point to the parent of the view.
- if (content && sortProperties) {
- forEach(content, function(item) {
- forEach(sortProperties, function(sortProperty) {
- Ember.removeObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
- }, this);
- }, this);
+ @property parentView
+ @type Ember.View
+ @default null
+ */
+ parentView: Ember.computed(function() {
+ var parent = this._parentView;
+
+ if (parent && parent.isVirtual) {
+ return get(parent, 'parentView');
+ } else {
+ return parent;
}
+ }).property('_parentView'),
- return this._super();
+ state: null,
+
+ _parentView: null,
+
+ // return the current view, not including virtual views
+ concreteView: Ember.computed(function() {
+ if (!this.isVirtual) { return this; }
+ else { return get(this, 'parentView'); }
+ }).property('parentView').volatile(),
+
+ instrumentName: 'core_view',
+
+ instrumentDetails: function(hash) {
+ hash.object = this.toString();
},
- isSorted: Ember.computed('sortProperties', function() {
- return !!get(this, 'sortProperties');
- }),
+ /**
+ @private
- arrangedContent: Ember.computed('content', 'sortProperties.@each', function(key, value) {
- var content = get(this, 'content'),
- isSorted = get(this, 'isSorted'),
- sortProperties = get(this, 'sortProperties'),
- self = this;
+ Invoked by the view system when this view needs to produce an HTML
+ representation. This method will create a new render buffer, if needed,
+ then apply any default attributes, such as class names and visibility.
+ Finally, the `render()` method is invoked, which is responsible for
+ doing the bulk of the rendering.
- if (content && isSorted) {
- content = content.slice();
- content.sort(function(item1, item2) {
- return self.orderBy(item1, item2);
- });
- forEach(content, function(item) {
- forEach(sortProperties, function(sortProperty) {
- Ember.addObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
- }, this);
- }, this);
- return Ember.A(content);
- }
+ You should not need to override this method; instead, implement the
+ `template` property, or if you need more control, override the `render`
+ method.
- return content;
- }).cacheable(),
+ @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.
+ */
+ renderToBuffer: function(parentBuffer, bufferOperation) {
+ var name = 'render.' + this.instrumentName,
+ details = {};
- _contentWillChange: Ember.beforeObserver(function() {
- var content = get(this, 'content'),
- sortProperties = get(this, 'sortProperties');
+ this.instrumentDetails(details);
- if (content && sortProperties) {
- forEach(content, function(item) {
- forEach(sortProperties, function(sortProperty) {
- Ember.removeObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
- }, this);
- }, this);
- }
+ return Ember.instrument(name, details, function() {
+ return this._renderToBuffer(parentBuffer, bufferOperation);
+ }, this);
+ },
- this._super();
- }, 'content'),
+ _renderToBuffer: function(parentBuffer, bufferOperation) {
+ Ember.run.sync();
- sortAscendingWillChange: Ember.beforeObserver(function() {
- this._lastSortAscending = get(this, 'sortAscending');
- }, 'sortAscending'),
+ // If this is the top-most view, start a new buffer. Otherwise,
+ // create a new buffer relative to the original using the
+ // provided buffer operation (for example, `insertAfter` will
+ // insert a new buffer after the "parent buffer").
+ var tagName = this.tagName;
- sortAscendingDidChange: Ember.observer(function() {
- if (get(this, 'sortAscending') !== this._lastSortAscending) {
- var arrangedContent = get(this, 'arrangedContent');
- arrangedContent.reverseObjects();
+ if (tagName === null || tagName === undefined) {
+ tagName = 'div';
}
- }, 'sortAscending'),
- contentArrayWillChange: function(array, idx, removedCount, addedCount) {
- var isSorted = get(this, 'isSorted');
+ var buffer = this.buffer = parentBuffer && parentBuffer.begin(tagName) || Ember.RenderBuffer(tagName);
+ this.transitionTo('inBuffer', false);
- if (isSorted) {
- var arrangedContent = get(this, 'arrangedContent');
- var removedObjects = array.slice(idx, idx+removedCount);
- var sortProperties = get(this, 'sortProperties');
+ this.beforeRender(buffer);
+ this.render(buffer);
+ this.afterRender(buffer);
- forEach(removedObjects, function(item) {
- arrangedContent.removeObject(item);
+ return buffer;
+ },
- forEach(sortProperties, function(sortProperty) {
- Ember.removeObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
- }, this);
- });
+ /**
+ @private
+
+ 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);
+ var method = this[name];
+ if (method) {
+ var args = [], i, l;
+ for (i = 1, l = arguments.length; i < l; i++) {
+ args.push(arguments[i]);
+ }
+ return method.apply(this, args);
}
+ },
- return this._super(array, idx, removedCount, addedCount);
+ has: function(name) {
+ return Ember.typeOf(this[name]) === 'function' || this._super(name);
},
- contentArrayDidChange: function(array, idx, removedCount, addedCount) {
- var isSorted = get(this, 'isSorted'),
- sortProperties = get(this, 'sortProperties');
+ willDestroy: function() {
+ var parent = this._parentView;
- if (isSorted) {
- var addedObjects = array.slice(idx, idx+addedCount);
- var arrangedContent = get(this, 'arrangedContent');
+ // destroy the element -- this will avoid each child view destroying
+ // the element over and over again...
+ if (!this.removedFromDOM) { this.destroyElement(); }
- forEach(addedObjects, function(item) {
- this.insertItemSorted(item);
+ // remove from parent if found. Don't call removeFromParent,
+ // as removeFromParent will try to remove the element from
+ // the DOM again.
+ if (parent) { parent.removeChild(this); }
- forEach(sortProperties, function(sortProperty) {
- Ember.addObserver(item, sortProperty, this, 'contentItemSortPropertyDidChange');
- }, this);
- }, this);
- }
+ this.transitionTo('destroyed');
- return this._super(array, idx, removedCount, addedCount);
+ // next remove view from global hash
+ if (!this.isVirtual) delete Ember.View.views[this.elementId];
},
- insertItemSorted: function(item) {
- var arrangedContent = get(this, 'arrangedContent');
- var length = get(arrangedContent, 'length');
+ clearRenderedChildren: Ember.K,
+ triggerRecursively: Ember.K,
+ invokeRecursively: Ember.K,
+ transitionTo: Ember.K,
+ destroyElement: Ember.K
+});
+
+/**
+ `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.
- var idx = this._binarySearch(item, 0, length);
- arrangedContent.insertAt(idx, item);
- },
+ ## HTML Tag
- contentItemSortPropertyDidChange: function(item) {
- var arrangedContent = get(this, 'arrangedContent'),
- oldIndex = arrangedContent.indexOf(item),
- newIndex = this._binarySearch(item, 0, get(arrangedContent, 'length'));
+ 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:
- if (newIndex !== oldIndex) {
- arrangedContent.removeObject(item);
- this.insertItemSorted(item);
- }
- },
+ ```javascript
+ ParagraphView = Ember.View.extend({
+ tagName: 'em'
+ });
+ ```
- _binarySearch: function(item, low, high) {
- var mid, midItem, res, arrangedContent;
+ Would result in instances with the following HTML:
- if (low === high) {
- return low;
- }
+ ```html
+ <em id="ember1" class="ember-view"></em>
+ ```
- arrangedContent = get(this, 'arrangedContent');
+ ## HTML `class` Attribute
- mid = low + Math.floor((high - low) / 2);
- midItem = arrangedContent.objectAt(mid);
+ 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:
- res = this.orderBy(midItem, item);
+ ```javascript
+ MyView = Ember.View.extend({
+ classNames: ['my-class', 'my-other-class']
+ });
+ ```
- if (res < 0) {
- return this._binarySearch(item, mid+1, high);
- } else if (res > 0) {
- return this._binarySearch(item, low, mid);
- }
+ Will result in view instances with an HTML representation of:
- return mid;
- }
-});
+ ```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:
+ ```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:
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ ```html
+ <div id="ember1" class="ember-view from-a from-b"></div>
+ ```
-var get = Ember.get, set = Ember.set;
+ 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`.
-/**
- 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.
+ ```javascript
+ MyView = Ember.View.extend({
+ classNameBindings: ['hovered'],
+ hovered: true
+ });
+ ```
- The advantage of using an ArrayController is that you only have to set up
- your view bindings once; to change what's displayed, simply swap out the
- `content` property on the controller.
+ Will result in view instances with an HTML representation of:
- 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:
+ ```html
+ <div id="ember1" class="ember-view hovered"></div>
+ ```
- ``` javascript
- MyApp.listController = Ember.ArrayController.create();
+ 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:
- $.get('people.json', function(data) {
- MyApp.listController.set('content', data);
+ ```javascript
+ MyView = Ember.View.extend({
+ classNameBindings: ['awesome:so-very-cool'],
+ awesome: true
});
```
- Then, create a view that binds to your new controller:
+ Will result in view instances with an HTML representation of:
- ``` handlebars
- {{#each MyApp.listController}}
- {{firstName}} {{lastName}}
- {{/each}}
+ ```html
+ <div id="ember1" class="ember-view so-very-cool"></div>
```
- 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
- capability comes from `Ember.ArrayProxy`, which this class inherits from.
+ Boolean value class name bindings whose property names are in a
+ camelCase-style format will be converted to a dasherized format:
- Note: As of this writing, `ArrayController` does not add any functionality
- to its superclass, `ArrayProxy`. The Ember team plans to add additional
- controller-specific functionality in the future, e.g. single or multiple
- selection support. If you are creating something that is conceptually a
- controller, use this class.
+ ```javascript
+ MyView = Ember.View.extend({
+ classNameBindings: ['isUrgent'],
+ isUrgent: true
+ });
+ ```
- @class ArrayController
- @namespace Ember
- @extends Ember.ArrayProxy
- @uses Ember.SortableMixin
- @uses Ember.ControllerMixin
-*/
+ Will result in view instances with an HTML representation of:
-Ember.ArrayController = Ember.ArrayProxy.extend(Ember.ControllerMixin,
- Ember.SortableMixin);
+ ```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:
+ ```javascript
+ MyView = Ember.View.extend({
+ classNameBindings: ['messages.empty']
+ messages: Ember.Object.create({
+ empty: true
+ })
+ });
+ ```
+ Will result in view instances with an HTML representation of:
-(function() {
-/**
-@module ember
-@submodule ember-runtime
-*/
+ ```html
+ <div id="ember1" class="ember-view empty"></div>
+ ```
-/**
- 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.
+ 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:
- Ember.ObjectController derives its functionality from its superclass
- Ember.ObjectProxy and the Ember.ControllerMixin mixin.
+ ```javascript
+ // Applies 'enabled' class when isEnabled is true and 'disabled' when isEnabled is false
+ Ember.View.create({
+ classNameBindings: ['isEnabled:enabled:disabled']
+ isEnabled: true
+ });
+ ```
- @class ObjectController
- @namespace Ember
- @extends Ember.ObjectProxy
- @uses Ember.ControllerMixin
-**/
-Ember.ObjectController = Ember.ObjectProxy.extend(Ember.ControllerMixin);
+ Will result in view instances with an HTML representation of:
-})();
+ ```html
+ <div id="ember1" class="ember-view enabled"></div>
+ ```
+ When isEnabled is `false`, the resulting HTML reprensentation looks like
+ this:
+ ```html
+ <div id="ember1" class="ember-view disabled"></div>
+ ```
-(function() {
+ This syntax offers the convenience to add a class if a property is `false`:
-})();
+ ```javascript
+ // Applies no class when isEnabled is true and class 'disabled' when isEnabled is false
+ Ember.View.create({
+ classNameBindings: ['isEnabled::disabled']
+ isEnabled: true
+ });
+ ```
+ Will result in view instances with an HTML representation of:
+ ```html
+ <div id="ember1" class="ember-view"></div>
+ ```
-(function() {
-/**
-Ember Runtime
+ When the `isEnabled` property on the view is set to `false`, it will result
+ in view instances with an HTML representation of:
-@module ember
-@submodule ember-runtime
-@requires ember-metal
-*/
+ ```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. If the value becomes `false` or `undefined` the class name
+ will be removed.
-(function() {
-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();
-}
+ Both `classNames` and `classNameBindings` are concatenated properties. See
+ `Ember.Object` documentation for more information about concatenated
+ properties.
-function DAG() {
- this.names = [];
- this.vertices = {};
-}
+ ## HTML Attributes
-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;
-};
+ 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:
-DAG.prototype.map = function(name, value) {
- this.add(name).value = value;
-};
+ ```javascript
+ AnchorView = Ember.View.extend({
+ tagName: 'a',
+ attributeBindings: ['href'],
+ href: 'http://google.com'
+ });
+ ```
-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);
-};
+ Will result in view instances with an HTML representation of:
+
+ ```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:
-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);
- }
- }
-};
+ ```javascript
+ MyTextInput = Ember.View.extend({
+ tagName: 'input',
+ attributeBindings: ['disabled'],
+ disabled: true
+ });
+ ```
-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);
+ Will result in view instances with an HTML representation of:
+
+ ```html
+ <input id="ember1" class="ember-view" disabled="disabled" />
+ ```
+
+ `attributeBindings` can refer to computed properties:
+
+ ```javascript
+ MyTextInput = Ember.View.extend({
+ tagName: 'input',
+ attributeBindings: ['disabled'],
+ disabled: function(){
+ if (someLogic) {
+ return true;
+ } else {
+ return false;
}
- }
- }
-};
+ }.property()
+ });
+ ```
-Ember.DAG = DAG;
+ Updates to the the property of an attribute binding will result in automatic
+ update of the HTML attribute in the view's rendered HTML representation.
-})();
+ `attributeBindings` is a concatenated property. See `Ember.Object`
+ documentation for more information about concatenated properties.
+ ## Templates
+ The HTML contents of a view's rendered representation are determined by its
+ template. Templates can be any function that accepts an optional context
+ parameter and returns 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.
-(function() {
-/**
-@module ember
-@submodule ember-application
-*/
+ ```javascript
+ AView = Ember.View.extend({
+ template: Ember.Handlebars.compile('I am the template')
+ });
+ ```
-var get = Ember.get, set = Ember.set;
+ Will result in view instances with an HTML representation of:
-/**
- 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.
+ ```html
+ <div id="ember1" class="ember-view">I am the template</div>
+ ```
+
+ Within an Ember application is more common to define a Handlebars templates as
+ part of a page:
+
+ ```html
+ <script type='text/x-handlebars' data-template-name='some-template'>
+ Hello
+ </script>
+ ```
- 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:
+ And associate it by name using a view's `templateName` property:
```javascript
- window.App = Ember.Application.create();
+ AView = Ember.View.extend({
+ templateName: 'some-template'
+ });
```
- 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.
+ Using a value for `templateName` that does not have a Handlebars template
+ with a matching `data-template-name` attribute will throw an error.
- For example, if you define a view class, it might look like this:
+ Assigning a value to both `template` and `templateName` properties will throw
+ an error.
+
+ For views classes that may have a template later defined (e.g. as the block
+ portion of a `{{view}}` Handlebars helper call in another template or in
+ a subclass), you can provide a `defaultTemplate` property set to compiled
+ template function. If a template is not later provided for the view instance
+ the `defaultTemplate` value will be used:
```javascript
- App.MyView = Ember.View.extend();
+ AView = Ember.View.extend({
+ defaultTemplate: Ember.Handlebars.compile('I was the default'),
+ template: null,
+ templateName: null
+ });
```
- After all of your classes are defined, call `App.initialize()` to start the
- application.
+ Will result in instances with an HTML representation of:
- 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.
+ ```html
+ <div id="ember1" class="ember-view">I was the default</div>
+ ```
- 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.
+ If a `template` or `templateName` is provided it will take precedence over
+ `defaultTemplate`:
- ### Event Delegation
+ ```javascript
+ AView = Ember.View.extend({
+ defaultTemplate: Ember.Handlebars.compile('I was the default')
+ });
- 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`.
+ aView = AView.create({
+ template: Ember.Handlebars.compile('I was the template, not default')
+ });
+ ```
- 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.
+ Will result in the following HTML representation when rendered:
- `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.
+ ```html
+ <div id="ember1" class="ember-view">I was the template, not default</div>
+ ```
+
+ ## View Context
- 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:
+ The default context of the compiled template is the view's controller:
```javascript
- App = Ember.Application.create({
- customEvents: {
- // add support for the loadedmetadata media
- // player event
- 'loadedmetadata': "loadedMetadata"
- }
+ AView = Ember.View.extend({
+ template: Ember.Handlebars.compile('Hello {{excitedGreeting}}')
+ });
+
+ aController = Ember.Object.create({
+ firstName: 'Barry',
+ excitedGreeting: function(){
+ return this.get("content.firstName") + "!!!"
+ }.property()
+ });
+
+ aView = AView.create({
+ controller: aController,
});
```
- 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.
+ Will result in an HTML representation of:
+
+ ```html
+ <div id="ember1" class="ember-view">Hello Barry!!!</div>
+ ```
+
+ A context can also be explicitly supplied through the view's `context`
+ property. If the view has neither `context` nor `controller` properties, the
+ `parentView`'s context will be used.
+
+ ## Layouts
+
+ Views can have a secondary template that wraps their main template. Like
+ primary templates, layouts can be any function that accepts an optional
+ context parameter and returns a string of HTML that will be inserted inside
+ view's tag. Views whose HTML element is self closing (e.g. `<input />`)
+ cannot have a layout and this property will be ignored.
+
+ Most typically in Ember a layout will be a compiled `Ember.Handlebars`
+ template.
- For example, if only events inside a DOM element with the ID of `ember-app` should
- be delegated, set your application's `rootElement` property:
+ A view's layout can be set directly with the `layout` property or reference
+ an existing Handlebars template by name with the `layoutName` property.
+
+ 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:
```javascript
- window.App = Ember.Application.create({
- rootElement: '#ember-app'
+ AViewWithLayout = Ember.View.extend({
+ layout: Ember.Handlebars.compile("<div class='my-decorative-class'>{{yield}}</div>")
+ template: Ember.Handlebars.compile("I got wrapped"),
});
```
- 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!
+ Will result in view instances with an HTML representation of:
+
+ ```html
+ <div id="ember1" class="ember-view">
+ <div class="my-decorative-class">
+ I got wrapped
+ </div>
+ </div>
+ ```
+
+ See `Handlebars.helpers.yield` for more information.
- 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).
+ ## Responding to Browser Events
- ### Dependency Injection
+ 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.
- 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`.
+ ### Method Implementation
- When the `Ember.Application` initializes, it will look for an `Ember.Router` class
- defined on the applications's `Router` property, like this:
+ 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.
```javascript
- App.Router = Ember.Router.extend({
- // ...
+ AView = Ember.View.extend({
+ click: function(event){
+ // will be called when when an instance's
+ // rendered element is clicked
+ }
});
```
- 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.
+ ### Event Managers
- 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.
+ Views can define an object as their `eventManager` property. This object can
+ then implement methods that match the desired event names. Matching events
+ that occur on the view's rendered HTML or the rendered HTML of any of its DOM
+ descendants will trigger this method. A `jQuery.Event` object will be passed
+ as the first argument to the method and an `Ember.View` object as the
+ second. The `Ember.View` will be the view whose rendered HTML was interacted
+ with. This may be the view with the `eventManager` property or one of its
+ descendent views.
- 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.
+ ```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
+ }
+ })
+ });
+ ```
- For example, if you define a controller class:
+ An event defined for an event manager takes precedence over events of the
+ same name handled through methods on the view.
```javascript
- App.MyController = Ember.Controller.extend({
- // ...
+ AView = Ember.View.extend({
+ mouseEnter: function(event){
+ // will never trigger.
+ },
+ eventManager: Ember.Object.create({
+ mouseEnter: function(event, view){
+ // takes presedence over AView#mouseEnter
+ }
+ })
});
```
- 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`:
+ Similarly a view's event manager will take precedence for events of any views
+ rendered as a descendent. A method name that matches an event name will not
+ be called if the view instance was rendered inside the HTML representation of
+ a view that has 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.
```javascript
- Ember.Application.registerInjection({
- name: 'store',
- before: 'controllers',
+ 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.
+ }
+ });
+ ```
+
+ ### 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`
+
+ Keyboard events
- injection: function(app, router, property) {
- if (property === 'Store') {
- set(router, 'store', app[property].create());
- }
- }
- });
- ```
+ * `keyDown`
+ * `keyUp`
+ * `keyPress`
- ### Routing
+ Mouse events
- In addition to creating your application's router, `Ember.Application` is also
- responsible for telling the router when to start routing.
+ * `mouseDown`
+ * `mouseUp`
+ * `contextMenu`
+ * `click`
+ * `doubleClick`
+ * `mouseMove`
+ * `focusIn`
+ * `focusOut`
+ * `mouseEnter`
+ * `mouseLeave`
- 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.
+ Form events:
- 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:
+ * `submit`
+ * `change`
+ * `focusIn`
+ * `focusOut`
+ * `input`
- ```javascript
- window.App = Ember.Application.create({
- ready: function() {
- this.set('router.enableLogging', true);
- }
- });
+ HTML5 drag and drop events:
- 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:
+ * `dragStart`
+ * `drag`
+ * `dragEnter`
+ * `dragLeave`
+ * `drop`
+ * `dragEnd`
- ```javascript
- App.ApplicationView = Ember.View.extend({
- templateName: 'application'
- });
- App.ApplicationController = Ember.Controller.extend();
- ```
+ ## Handlebars `{{view}}` Helper
- @class Application
+ 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.Namespace
+ @extends Ember.Object
+ @uses Ember.Evented
*/
-Ember.Application = Ember.Namespace.extend(
-/** @scope Ember.Application.prototype */{
+Ember.View = Ember.CoreView.extend(
+/** @scope Ember.View.prototype */ {
+
+ concatenatedProperties: ['classNames', 'classNameBindings', 'attributeBindings'],
/**
- 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/).
+ @property isView
+ @type Boolean
+ @default true
+ @final
+ */
+ isView: true,
- 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.
+ // ..........................................................
+ // TEMPLATE SUPPORT
+ //
- @property rootElement
- @type DOMElement
- @default 'body'
+ /**
+ The name of the template to lookup if no template is provided.
+
+ `Ember.View` will look for a template with this name in this view's
+ `templates` object. By default, this will be a global object
+ shared in `Ember.TEMPLATES`.
+
+ @property templateName
+ @type String
+ @default null
*/
- rootElement: 'body',
+ templateName: null,
/**
- 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.
+ The name of the layout to lookup if no layout is provided.
- See the documentation for `Ember.EventDispatcher` for more information.
+ `Ember.View` will look for a template with this name in this view's
+ `templates` object. By default, this will be a global object
+ shared in `Ember.TEMPLATES`.
- @property eventDispatcher
- @type Ember.EventDispatcher
+ @property layoutName
+ @type String
@default null
*/
- eventDispatcher: null,
+ layoutName: null,
/**
- The DOM events for which the event dispatcher should listen.
+ The hash in which to look for `templateName`.
- 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.
+ @property templates
+ @type Ember.Object
+ @default Ember.TEMPLATES
+ */
+ templates: Ember.TEMPLATES,
- 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:
+ /**
+ The template used to render the view. This should be a function that
+ accepts an optional context parameter and returns a string of HTML that
+ will be inserted into the DOM relative to its parent view.
- App = Ember.Application.create({
- customEvents: {
- // add support for the loadedmetadata media
- // player event
- 'loadedmetadata': "loadedMetadata"
- }
- });
+ In general, you should set the `templateName` property instead of setting
+ the template yourself.
- @property customEvents
- @type Object
- @default null
+ @property template
+ @type Function
*/
- customEvents: null,
+ template: Ember.computed(function(key, value) {
+ if (value !== undefined) { return value; }
- autoinit: !Ember.testing,
+ var templateName = get(this, 'templateName'),
+ template = this.templateForName(templateName, 'template');
- isInitialized: false,
+ return template || get(this, 'defaultTemplate');
+ }).property('templateName'),
- init: function() {
- if (!this.$) { this.$ = Ember.$; }
+ container: Ember.computed(function() {
+ var parentView = get(this, '_parentView');
- this._super();
+ if (parentView) { return get(parentView, 'container'); }
- this.createEventDispatcher();
+ return Ember.Container && Ember.Container.defaultContainer;
+ }),
- // Start off the number of deferrals at 1. This will be
- // decremented by the Application's own `initialize` method.
- this._readinessDeferrals = 1;
+ /**
+ The controller managing this view. If this property is set, it will be
+ made available for use by the template.
- this.waitForDOMContentLoaded();
+ @property controller
+ @type Object
+ */
+ controller: Ember.computed(function(key) {
+ var parentView = get(this, '_parentView');
+ return parentView ? get(parentView, 'controller') : null;
+ }).property('_parentView'),
- if (this.autoinit) {
- var self = this;
- this.$().ready(function() {
- if (self.isDestroyed || self.isInitialized) return;
- self.initialize();
- });
- }
- },
+ /**
+ A view may contain a layout. A layout is a regular template but
+ supersedes the `template` property during rendering. It is the
+ responsibility of the layout template to retrieve the `template`
+ property from the view (or alternatively, call `Handlebars.helpers.yield`,
+ `{{yield}}`) to render it in the correct location.
- /** @private */
- createEventDispatcher: function() {
- var rootElement = get(this, 'rootElement'),
- eventDispatcher = Ember.EventDispatcher.create({
- rootElement: rootElement
- });
+ This is useful for a view that has a shared wrapper, but which delegates
+ the rendering of the contents of the wrapper to the `template` property
+ on a subclass.
- set(this, 'eventDispatcher', eventDispatcher);
- },
+ @property layout
+ @type Function
+ */
+ layout: Ember.computed(function(key) {
+ var layoutName = get(this, 'layoutName'),
+ layout = this.templateForName(layoutName, 'layout');
- waitForDOMContentLoaded: function() {
- this.deferReadiness();
+ return layout || get(this, 'defaultLayout');
+ }).property('layoutName'),
- var self = this;
- this.$().ready(function() {
- self.advanceReadiness();
- });
- },
+ templateForName: function(name, type) {
+ if (!name) { return; }
- deferReadiness: function() {
- Ember.assert("You cannot defer readiness since the `ready()` hook has already been called.", this._readinessDeferrals > 0);
- this._readinessDeferrals++;
- },
+ Ember.assert("templateNames are not allowed to contain periods: "+name, name.indexOf('.') === -1);
- advanceReadiness: function() {
- this._readinessDeferrals--;
+ var container = get(this, 'container');
- if (this._readinessDeferrals === 0) {
- Ember.run.once(this, this.didBecomeReady);
+ if (container) {
+ return container.lookup('template:' + name);
}
},
/**
- Instantiate all controllers currently available on the namespace
- and inject them onto a router.
-
- Example:
+ The object from which templates should access properties.
- App.PostsController = Ember.ArrayController.extend();
- App.CommentsController = Ember.ArrayController.extend();
+ This object will be passed to the template function each time the render
+ method is called, but it is up to the individual function to decide what
+ to do with it.
- var router = Ember.Router.create({
- ...
- });
+ By default, this will be the view's controller.
- App.initialize(router);
+ @property context
+ @type Object
+ */
+ context: Ember.computed(function(key, value) {
+ if (arguments.length === 2) {
+ set(this, '_context', value);
+ return value;
+ } else {
+ return get(this, '_context');
+ }
+ }).volatile(),
- router.get('postsController') // <App.PostsController:ember1234>
- router.get('commentsController') // <App.CommentsController:ember1235>
+ /**
+ @private
- router.get('postsController.router') // router
+ Private copy of the view's template context. This can be set directly
+ by Handlebars without triggering the observer that causes the view
+ to be re-rendered.
- @method initialize
- @param router {Ember.Router}
- */
- initialize: function(router) {
- Ember.assert("Application initialize may only be call once", !this.isInitialized);
- Ember.assert("Application not destroyed", !this.isDestroyed);
+ The context of a view is looked up as follows:
- router = this.setupRouter(router);
+ 1. Supplied context (usually by Handlebars)
+ 2. Specified controller
+ 3. `parentView`'s context (for a child of a ContainerView)
- this.runInjections(router);
+ 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.
- Ember.runLoadHooks('application', this);
+ @property _context
+ */
+ _context: Ember.computed(function(key) {
+ var parentView, controller;
- this.isInitialized = true;
+ if (controller = get(this, 'controller')) {
+ return controller;
+ }
- // At this point, any injections or load hooks that would have wanted
- // to defer readiness have fired.
- this.advanceReadiness();
+ parentView = this._parentView;
+ if (parentView) {
+ return get(parentView, '_context');
+ }
- return this;
- },
+ return null;
+ }),
- /** @private */
- runInjections: function(router) {
- var injections = get(this.constructor, 'injections'),
- graph = new Ember.DAG(),
- namespace = this,
- properties, i, injection;
+ /**
+ @private
- for (i=0; i<injections.length; i++) {
- injection = injections[i];
- graph.addEdges(injection.name, injection.injection, injection.before, injection.after);
- }
+ If a value that affects template rendering changes, the view should be
+ re-rendered to reflect the new value.
- graph.topsort(function (vertex) {
- var injection = vertex.value,
- properties = Ember.A(Ember.keys(namespace));
- properties.forEach(function(property) {
- injection(namespace, router, property);
- });
- });
- },
+ @method _displayPropertyDidChange
+ */
+ _contextDidChange: Ember.observer(function() {
+ this.rerender();
+ }, 'context'),
- /** @private */
- setupRouter: function(router) {
- if (!router && Ember.Router.detect(this.Router)) {
- router = this.Router.create();
- this._createdRouter = router;
- }
+ /**
+ If `false`, the view will appear hidden in DOM.
- if (router) {
- set(this, 'router', router);
+ @property isVisible
+ @type Boolean
+ @default null
+ */
+ isVisible: true,
- // By default, the router's namespace is the current application.
- //
- // This allows it to find model classes when a state has a
- // route like `/posts/:post_id`. In that case, it would first
- // convert `post_id` into `Post`, and then look it up on its
- // namespace.
- set(router, 'namespace', this);
- }
+ /**
+ @private
- return router;
- },
+ Array of child views. You should never edit this array directly.
+ Instead, use `appendChild` and `removeFromParent`.
- /** @private */
- didBecomeReady: function() {
- var eventDispatcher = get(this, 'eventDispatcher'),
- customEvents = get(this, 'customEvents'),
- router;
+ @property childViews
+ @type Array
+ @default []
+ */
+ childViews: childViewsProperty,
- eventDispatcher.setup(customEvents);
+ _childViews: [],
- this.ready();
+ // 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');
+ if (parentView) { Ember.propertyWillChange(parentView, 'childViews'); }
+ }
+ }, 'childViews'),
+ // 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');
+ if (parentView) { Ember.propertyDidChange(parentView, 'childViews'); }
+ }
+ }, 'childViews'),
- router = get(this, 'router');
+ /**
+ Return the nearest ancestor that is an instance of the provided
+ class.
- this.createApplicationView(router);
+ @property nearestInstanceOf
+ @param {Class} klass Subclass of Ember.View (or Ember.View itself)
+ @return Ember.View
+ @deprecated
+ */
+ nearestInstanceOf: function(klass) {
+ Ember.deprecate("nearestInstanceOf is deprecated and will be removed from future releases. Use nearestOfType.");
+ var view = get(this, 'parentView');
- if (router && router instanceof Ember.Router) {
- this.startRouting(router);
+ while (view) {
+ if(view instanceof klass) { return view; }
+ view = get(view, 'parentView');
}
},
- createApplicationView: function (router) {
- var rootElement = get(this, 'rootElement'),
- applicationViewOptions = {},
- applicationViewClass = this.ApplicationView,
- applicationTemplate = Ember.TEMPLATES.application,
- applicationController, applicationView;
+ /**
+ Return the nearest ancestor that is an instance of the provided
+ class or mixin.
- // don't do anything unless there is an ApplicationView or application template
- if (!applicationViewClass && !applicationTemplate) return;
+ @property nearestOfType
+ @param {Class,Mixin} klass Subclass of Ember.View (or Ember.View itself),
+ or an instance of Ember.Mixin.
+ @return Ember.View
+ */
+ nearestOfType: function(klass) {
+ var view = get(this, 'parentView'),
+ isOfType = klass instanceof Ember.Mixin ?
+ function(view) { return klass.detect(view); } :
+ function(view) { return klass.detect(view.constructor); };
- if (router) {
- applicationController = get(router, 'applicationController');
- if (applicationController) {
- applicationViewOptions.controller = applicationController;
- }
+ while (view) {
+ if( isOfType(view) ) { return view; }
+ view = get(view, 'parentView');
}
+ },
- if (applicationTemplate) {
- applicationViewOptions.template = applicationTemplate;
- }
+ /**
+ Return the nearest ancestor that has a given property.
+
+ @property nearestWithProperty
+ @param {String} property A property name
+ @return Ember.View
+ */
+ nearestWithProperty: function(property) {
+ var view = get(this, 'parentView');
- if (!applicationViewClass) {
- applicationViewClass = Ember.View;
+ while (view) {
+ if (property in view) { return view; }
+ view = get(view, 'parentView');
}
+ },
- applicationView = applicationViewClass.create(applicationViewOptions);
+ /**
+ Return the nearest ancestor whose parent is an instance of
+ `klass`.
- this._createdApplicationView = applicationView;
+ @property nearestChildOf
+ @param {Class} klass Subclass of Ember.View (or Ember.View itself)
+ @return Ember.View
+ */
+ nearestChildOf: function(klass) {
+ var view = get(this, 'parentView');
- if (router) {
- set(router, 'applicationView', applicationView);
+ while (view) {
+ if(get(view, 'parentView') instanceof klass) { return view; }
+ view = get(view, 'parentView');
}
-
- 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.
+ When the parent view changes, recursively invalidate `controller`
- @method startRouting
- @property router {Ember.Router}
+ @method _parentViewDidChange
*/
- startRouting: function(router) {
- var location = get(router, 'location');
+ _parentViewDidChange: Ember.observer(function() {
+ if (this.isDestroying) { return; }
- 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') );
+ if (get(this, 'parentView.controller') && !get(this, 'controller')) {
+ this.notifyPropertyChange('controller');
+ }
+ }, '_parentView'),
- router.route(location.getURL());
- location.onUpdateURL(function(url) {
- router.route(url);
+ _controllerDidChange: Ember.observer(function() {
+ if (this.isDestroying) { return; }
+
+ this.rerender();
+
+ this.forEachChildView(function(view) {
+ view.propertyDidChange('controller');
});
- },
+ }, 'controller'),
- /**
- Called when the Application has become ready.
- The call will be delayed until the DOM has become ready.
+ cloneKeywords: function() {
+ var templateData = get(this, 'templateData');
- @event ready
- */
- ready: Ember.K,
+ var keywords = templateData ? Ember.copy(templateData.keywords) : {};
+ set(keywords, 'view', get(this, 'concreteView'));
+ set(keywords, '_view', this);
+ set(keywords, 'controller', get(this, 'controller'));
- willDestroy: function() {
- get(this, 'eventDispatcher').destroy();
- if (this._createdRouter) { this._createdRouter.destroy(); }
- if (this._createdApplicationView) { this._createdApplicationView.destroy(); }
+ return keywords;
},
- registerInjection: function(options) {
- this.constructor.registerInjection(options);
- }
-});
-
-Ember.Application.reopenClass({
- concatenatedProperties: ['injections'],
- injections: Ember.A(),
- registerInjection: function(injection) {
- var injections = get(this, 'injections');
+ /**
+ Called on your view when it should push strings of HTML into a
+ `Ember.RenderBuffer`. Most users will want to override the `template`
+ or `templateName` properties instead of this method.
- 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'));
+ By default, `Ember.View` will look for a function in the `template`
+ property and invoke it with the value of `context`. The value of
+ `context` will be the view's controller unless you override it.
- injections.push(injection);
- }
-});
+ @method render
+ @param {Ember.RenderBuffer} buffer The render buffer
+ */
+ render: function(buffer) {
+ // If this view has a layout, it is the responsibility of the
+ // the layout to render the view's template. Otherwise, render the template
+ // directly.
+ var template = get(this, 'layout') || get(this, 'template');
-Ember.Application.registerInjection({
- name: 'controllers',
- injection: function(app, router, property) {
- if (!/^[A-Z].*Controller$/.test(property)) { return; }
+ if (template) {
+ var context = get(this, 'context');
+ var keywords = this.cloneKeywords();
+ var output;
- var name = property.charAt(0).toLowerCase() + property.substr(1),
- controllerClass = app[property], controller;
+ var data = {
+ view: this,
+ buffer: buffer,
+ isRenderData: true,
+ keywords: keywords,
+ insideGroup: get(this, 'templateData.insideGroup')
+ };
- if(!Ember.Object.detect(controllerClass)){ return; }
- controller = app[property].create();
+ // Invoke the template with the provided template context, which
+ // is the view's controller by default. A hash of data is also passed that provides
+ // the template with access to the view and render buffer.
- router.set(name, controller);
+ Ember.assert('template must be a function. Did you mean to call Ember.Handlebars.compile("...") or specify templateName instead?', typeof template === 'function');
+ // The template should write directly to the render buffer instead
+ // of returning a string.
+ output = template(context, { data: data });
- controller.setProperties({
- target: router,
- controllers: router,
- namespace: app
- });
- }
-});
+ // If the template returned a string instead of writing to the buffer,
+ // push the string onto the buffer.
+ if (output !== undefined) { buffer.push(output); }
+ }
+ },
-Ember.runLoadHooks('Ember.Application', Ember.Application);
+ /**
+ Renders the view again. This will work regardless of whether the
+ view is already in the DOM or not. If the view is in the DOM, the
+ rendering process will be deferred to give bindings a chance
+ to synchronize.
+ If children were added during the rendering process using `appendChild`,
+ `rerender` will remove them, because they will be added again
+ if needed by the next `render`.
-})();
+ 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.currentState.rerender(this);
+ },
+ clearRenderedChildren: function() {
+ var lengthBefore = this.lengthBeforeRender,
+ lengthAfter = this.lengthAfterRender;
-(function() {
+ // If there were child views created during the last call to render(),
+ // remove them under the assumption that they will be re-created when
+ // we re-render.
-})();
+ // VIEW-TODO: Unit test this path.
+ var childViews = this._childViews;
+ for (var i=lengthAfter-1; i>=lengthBefore; i--) {
+ if (childViews[i]) { childViews[i].destroy(); }
+ }
+ },
+ /**
+ @private
+ Iterates over the view's `classNameBindings` array, inserts the value
+ 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.
-(function() {
-/**
-Ember Application
+ @method _applyClassNameBindings
+ */
+ _applyClassNameBindings: function(classBindings) {
+ var classNames = this.classNames,
+ elem, newClass, dasherizedClass;
-@module ember
-@submodule ember-application
-@requires ember-views, ember-states, ember-routing
-*/
+ // Loop through all of the configured bindings. These will be either
+ // property names ('isUrgent') or property paths relative to the view
+ // ('content.isUrgent')
+ a_forEach(classBindings, function(binding) {
-})();
+ // Variable in which the old class value is saved. The observer function
+ // 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);
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ // Set up an observer on the context. If the property changes, toggle the
+ // class name.
+ var observer = function() {
+ // Get the current value of the property
+ newClass = this._classStringForProperty(binding);
+ elem = this.$();
-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));
+ // If we had previously added a class to the element, remove it.
+ if (oldClass) {
+ elem.removeClass(oldClass);
+ // Also remove from classNames so that if the view gets rerendered,
+ // the class doesn't get added back to the DOM.
+ classNames.removeObject(oldClass);
+ }
-/**
- Alias for jQuery
+ // If necessary, add a new class. Make sure we keep track of it so
+ // it can be removed in the future.
+ if (newClass) {
+ elem.addClass(newClass);
+ oldClass = newClass;
+ } else {
+ oldClass = null;
+ }
+ };
- @method $
- @for Ember
-*/
-Ember.$ = window.jQuery;
+ // Get the class name for the property at its current value
+ dasherizedClass = this._classStringForProperty(binding);
-})();
+ if (dasherizedClass) {
+ // Ensure that it gets into the classNames array
+ // so it is displayed when we render.
+ a_addObject(classNames, dasherizedClass);
+ // Save a reference to the class name so we can remove it
+ // if the observer fires. Remember that this variable has
+ // been closed over by the observer.
+ oldClass = dasherizedClass;
+ }
+ addObserver(this, parsedPath.path, observer);
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ this.one('willClearRender', function() {
+ removeObserver(this, parsedPath.path, observer);
+ });
+ }, this);
+ },
-// 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');
+ /**
+ @private
-// Copies the `dataTransfer` property from a browser event object onto the
-// jQuery event object for the specified events
-Ember.EnumerableUtils.forEach(dragEvents, function(eventName) {
- Ember.$.event.fixHooks[eventName] = { props: ['dataTransfer'] };
-});
+ 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, attributeBindings) {
+ var attributeValue, elem, type;
+ a_forEach(attributeBindings, function(binding) {
+ var split = binding.split(':'),
+ property = split[0],
+ attributeName = split[1] || property;
+ // Create an observer to add/remove/change the attribute if the
+ // JavaScript property changes.
+ var observer = function() {
+ elem = this.$();
+ if (!elem) { return; }
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ attributeValue = get(this, property);
-var get = Ember.get, set = Ember.set;
-var indexOf = Ember.ArrayPolyfills.indexOf;
+ Ember.View.applyAttributeBindings(elem, attributeName, attributeValue);
+ };
-var ClassSet = function() {
- this.seen = {};
- this.list = [];
-};
+ addObserver(this, property, observer);
-ClassSet.prototype = {
- add: function(string) {
- if (string in this.seen) { return; }
- this.seen[string] = true;
+ this.one('willClearRender', function() {
+ removeObserver(this, property, observer);
+ });
- this.list.push(string);
+ // Determine the current value and add it to the render buffer
+ // if necessary.
+ attributeValue = get(this, property);
+ Ember.View.applyAttributeBindings(buffer, attributeName, attributeValue);
+ }, this);
},
- toDOM: function() {
- return this.list.join(" ");
- }
-};
-
-/**
- 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.
+ /**
+ @private
- @class RenderBuffer
- @namespace Ember
- @constructor
-*/
-Ember.RenderBuffer = function(tagName) {
- return new Ember._RenderBuffer(tagName);
-};
+ Given a property name, returns a dasherized version of that
+ property name if the property evaluates to a non-falsy value.
-Ember._RenderBuffer = function(tagName) {
- this.elementTag = tagName;
- this.childBuffers = [];
-};
+ For example, if the view has property `isUrgent` that evaluates to true,
+ passing `isUrgent` to this method will return `"is-urgent"`.
-Ember._RenderBuffer.prototype =
-/** @scope Ember.RenderBuffer.prototype */ {
+ @method _classStringForProperty
+ @param property
+ */
+ _classStringForProperty: function(property) {
+ var parsedPath = Ember.View._parsePropertyPath(property);
+ var path = parsedPath.path;
- /**
- Array of class-names which will be applied in the class="" attribute
+ var val = get(this, path);
+ if (val === undefined && Ember.isGlobalPath(path)) {
+ val = get(Ember.lookup, path);
+ }
- You should not maintain this array yourself, rather, you should use
- the addClass() method of Ember.RenderBuffer.
+ return Ember.View._classStringForValue(path, val, parsedPath.className, parsedPath.falsyClassName);
+ },
- @property elementClasses
- @type Array
- @default []
- */
- elementClasses: null,
+ // ..........................................................
+ // ELEMENT SUPPORT
+ //
/**
- The id in of the element, to be applied in the id="" attribute
-
- You should not set this property yourself, rather, you should use
- the id() method of Ember.RenderBuffer.
+ Returns the current DOM element for the view.
- @property elementId
- @type String
- @default null
+ @property element
+ @type DOMElement
*/
- elementId: null,
+ element: Ember.computed(function(key, value) {
+ if (value !== undefined) {
+ return this.currentState.setElement(this, value);
+ } else {
+ return this.currentState.getElement(this);
+ }
+ }).property('_parentView'),
/**
- A hash keyed on the name of the attribute and whose value will be
- applied to that attribute. For example, if you wanted to apply a
- data-view="Foo.bar" property to an element, you would set the
- elementAttributes hash to {'data-view':'Foo.bar'}
+ Returns a jQuery object for this view's element. If you pass in a selector
+ string, this method will return a jQuery object, using the current element
+ as its buffer.
- You should not maintain this hash yourself, rather, you should use
- the attr() method of Ember.RenderBuffer.
+ For example, calling `view.$('li')` will return a jQuery object containing
+ all of the `li` elements inside the DOM element of this view.
- @property elementAttributes
- @type Hash
- @default {}
+ @property $
+ @param {String} [selector] a jQuery-compatible selector string
+ @return {jQuery} the CoreQuery object for the DOM node
*/
- elementAttributes: null,
+ $: function(sel) {
+ return this.currentState.$(this, sel);
+ },
- /**
- The tagname of the element an instance of Ember.RenderBuffer represents.
+ mutateChildViews: function(callback) {
+ var childViews = this._childViews,
+ idx = childViews.length,
+ view;
- Usually, this gets set as the first parameter to Ember.RenderBuffer. For
- example, if you wanted to create a `p` tag, then you would call
+ while(--idx >= 0) {
+ view = childViews[idx];
+ callback.call(this, view, idx);
+ }
- Ember.RenderBuffer('p')
+ return this;
+ },
- @property elementTag
- @type String
- @default null
- */
- elementTag: null,
+ forEachChildView: function(callback) {
+ var childViews = this._childViews;
- /**
- A hash keyed on the name of the style attribute and whose value will
- be applied to that attribute. For example, if you wanted to apply a
- background-color:black;" style to an element, you would set the
- elementStyle hash to {'background-color':'black'}
+ if (!childViews) { return this; }
- You should not maintain this hash yourself, rather, you should use
- the style() method of Ember.RenderBuffer.
+ var len = childViews.length,
+ view, idx;
- @property elementStyle
- @type Hash
- @default {}
- */
- elementStyle: null,
+ for(idx = 0; idx < len; idx++) {
+ view = childViews[idx];
+ callback.call(this, view);
+ }
+
+ return this;
+ },
/**
- Nested RenderBuffers will set this to their parent RenderBuffer
- instance.
+ Appends the view's element to the specified parent element.
- @property parentBuffer
- @type Ember._RenderBuffer
- */
- parentBuffer: null,
+ If the view does not have an HTML representation yet, `createElement()`
+ will be called automatically.
- /**
- Adds a string of HTML to the RenderBuffer.
+ Note that this method just schedules the view to be appended; the DOM
+ element will not be appended to the given element until all bindings have
+ finished synchronizing.
- @method push
- @param {String} string HTML to push into the buffer
- @chainable
+ This is not typically a function that you will need to call directly when
+ building your application. You might consider using `Ember.ContainerView`
+ instead. If you do need to use `appendTo`, be sure that the target element
+ you 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
+ @return {Ember.View} receiver
*/
- push: function(string) {
- this.childBuffers.push(String(string));
+ appendTo: function(target) {
+ // Schedule the DOM element to be created and appended to the given
+ // element after bindings have synchronized.
+ this._insertElementLater(function() {
+ Ember.assert("You cannot append to an existing Ember.View. Consider using Ember.ContainerView instead.", !Ember.$(target).is('.ember-view') && !Ember.$(target).parents().is('.ember-view'));
+ this.$().appendTo(target);
+ });
+
return this;
},
/**
- Adds a class to the buffer, which will be rendered to the class attribute.
+ Replaces the content of the specified parent element with this view's
+ element. If the view does not have an HTML representation yet,
+ `createElement()` will be called automatically.
- @method addClass
- @param {String} className Class name to add to the buffer
- @chainable
+ Note that this method just schedules the view to be appended; the DOM
+ 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
+ @return {Ember.View} received
*/
- addClass: function(className) {
- // lazily create elementClasses
- var elementClasses = this.elementClasses = (this.elementClasses || new ClassSet());
- this.elementClasses.add(className);
+ 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'));
+
+ this._insertElementLater(function() {
+ Ember.$(target).empty();
+ this.$().appendTo(target);
+ });
return this;
},
/**
- Sets the elementID to be used for the element.
+ @private
- @method id
- @param {String} id
- @chainable
+ Schedules a DOM operation to occur during the next render phase. This
+ ensures that all bindings have finished synchronizing before the view is
+ rendered.
+
+ To use, pass a function that performs a DOM operation.
+
+ Before your function is called, this view and all child views will receive
+ the `willInsertElement` event. After your function is invoked, this view
+ and all of its child views will receive the `didInsertElement` event.
+
+ ```javascript
+ view._insertElementLater(function() {
+ this.createElement();
+ this.$().appendTo('body');
+ });
+ ```
+
+ @method _insertElementLater
+ @param {Function} fn the function that inserts the element into the DOM
*/
- id: function(id) {
- this.elementId = id;
- return this;
+ _insertElementLater: function(fn) {
+ this._scheduledInsert = Ember.run.scheduleOnce('render', this, '_insertElement', fn);
},
- // duck type attribute functionality like jQuery so a render buffer
- // can be used like a jQuery object in attribute binding scenarios.
+ _insertElement: function (fn) {
+ this._scheduledInsert = null;
+ this.currentState.insertElement(this, fn);
+ },
/**
- Adds an attribute which will be rendered to the element.
+ Appends the view's element to the document body. If the view does
+ not have an HTML representation yet, `createElement()` will be called
+ automatically.
- @method attr
- @param {String} name The name of the attribute
- @param {String} value The value to add to the attribute
- @chainable
- @return {Ember.RenderBuffer|String} this or the current attribute value
+ Note that this method just schedules the view to be appended; the DOM
+ element will not be appended to the document body until all bindings have
+ finished synchronizing.
+
+ @method append
+ @return {Ember.View} receiver
*/
- attr: function(name, value) {
- var attributes = this.elementAttributes = (this.elementAttributes || {});
+ append: function() {
+ return this.appendTo(document.body);
+ },
- if (arguments.length === 1) {
- return attributes[name];
- } else {
- attributes[name] = value;
- }
+ /**
+ Removes the view's element from the element to which it is attached.
- return this;
+ @method remove
+ @return {Ember.View} receiver
+ */
+ remove: function() {
+ // What we should really do here is wait until the end of the run loop
+ // to determine if the element has been re-appended to a different
+ // element.
+ // In the interim, we will just re-render if that happens. It is more
+ // important than elements get garbage collected.
+ this.destroyElement();
+ this.invokeRecursively(function(view) {
+ if (view.clearRenderedChildren) { view.clearRenderedChildren(); }
+ });
},
+ elementId: null,
+
/**
- Remove an attribute from the list of attributes to render.
+ Attempts to discover the element in the parent element. The default
+ implementation looks for an element with an ID of `elementId` (or the
+ view's guid if `elementId` is null). You can override this method to
+ provide your own form of lookup. For example, if you want to discover your
+ element using a CSS class name instead of an ID.
- @method removeAttr
- @param {String} name The name of the attribute
- @chainable
+ @method findElementInParentElement
+ @param {DOMElement} parentElement The parent's DOM element
+ @return {DOMElement} The discovered element
*/
- removeAttr: function(name) {
- var attributes = this.elementAttributes;
- if (attributes) { delete attributes[name]; }
-
- return this;
+ findElementInParentElement: function(parentElem) {
+ var id = "#" + this.elementId;
+ return Ember.$(id)[0] || Ember.$(id, parentElem)[0];
},
/**
- Adds a style to the style attribute which will be rendered to the element.
+ Creates a DOM representation of the view and all of its
+ child views by recursively calling the `render()` method.
- @method style
- @param {String} name Name of the style
- @param {String} value
- @chainable
+ After the element has been created, `didInsertElement` will
+ be called on this view and all of its child views.
+
+ @method createElement
+ @return {Ember.View} receiver
*/
- style: function(name, value) {
- var style = this.elementStyle = (this.elementStyle || {});
+ createElement: function() {
+ if (get(this, 'element')) { return this; }
+
+ var buffer = this.renderToBuffer();
+ set(this, 'element', buffer.element());
- this.elementStyle[name] = value;
return this;
},
/**
- @private
+ Called when a view is going to insert an element into the DOM.
- 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.
+ @event willInsertElement
+ */
+ willInsertElement: Ember.K,
- This is a primitive method used by other public methods: `begin`,
- `prepend`, `replaceWith`, `insertAfter`.
+ /**
+ 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.
- @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.
- @param {Function} fn A callback to invoke with the newly created buffer.
- @param {Object} other Additional properties to add to the newly created
- buffer.
+ @event didInsertElement
*/
- newBuffer: function(tagName, parent, fn, other) {
- var buffer = new Ember._RenderBuffer(tagName);
- buffer.parentBuffer = parent;
+ didInsertElement: Ember.K,
- if (other) { Ember.$.extend(buffer, other); }
- if (fn) { fn.call(this, buffer); }
+ /**
+ 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
- return buffer;
- },
+ @event willClearRender
+ */
+ willClearRender: Ember.K,
/**
@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.
+ Run this callback on the current view and recursively on child views.
- @method replaceWithBuffer
- @param {Ember._RenderBuffer} buffer The buffer to insert in place of
- the existing buffer.
+ @method invokeRecursively
+ @param fn {Function}
*/
- replaceWithBuffer: function(newBuffer) {
- var parent = this.parentBuffer;
- if (!parent) { return; }
+ invokeRecursively: function(fn) {
+ var childViews = [this], currentViews, view;
- var childBuffers = parent.childBuffers;
+ while (childViews.length) {
+ currentViews = childViews.slice();
+ childViews = [];
- var index = indexOf.call(childBuffers, this);
+ for (var i=0, l=currentViews.length; i<l; i++) {
+ view = currentViews[i];
+ fn.call(view, view);
+ if (view._childViews) {
+ childViews.push.apply(childViews, view._childViews);
+ }
+ }
+ }
+ },
- if (newBuffer) {
- childBuffers.splice(index, 1, newBuffer);
- } else {
- childBuffers.splice(index, 1);
+ triggerRecursively: function(eventName) {
+ var childViews = [this], currentViews, view;
+
+ while (childViews.length) {
+ currentViews = childViews.slice();
+ childViews = [];
+
+ for (var i=0, l=currentViews.length; i<l; i++) {
+ view = currentViews[i];
+ if (view.trigger) { view.trigger(eventName); }
+ if (view._childViews) {
+ childViews.push.apply(childViews, view._childViews);
+ }
+ }
}
},
/**
- Creates a new Ember.RenderBuffer object with the provided tagName as
- the element tag and with its parentBuffer property set to the current
- Ember.RenderBuffer.
+ Destroys any existing element along with the element for any child views
+ as well. If the view does not currently have a element, then this method
+ will do nothing.
+
+ If you implement `willDestroyElement()` on your view, then this method will
+ be invoked on your view before your element is destroyed to give you a
+ chance to clean up any event handlers, etc.
+
+ If you write a `willDestroyElement()` handler, you can assume that your
+ `didInsertElement()` handler was called earlier for the same element.
- @method begin
- @param {String} tagName Tag name to use for the child buffer's element
- @return {Ember.RenderBuffer} A new RenderBuffer object
+ Normally you will not call or override this method yourself, but you may
+ want to implement the above callbacks when it is run.
+
+ @method destroyElement
+ @return {Ember.View} receiver
*/
- begin: function(tagName) {
- return this.newBuffer(tagName, this, function(buffer) {
- this.childBuffers.push(buffer);
- });
+ destroyElement: function() {
+ return this.currentState.destroyElement(this);
},
/**
- Prepend a new child buffer to the current render buffer.
+ 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.
- @method prepend
- @param {String} tagName Tag name to use for the child buffer's element
+ @event willDestroyElement
*/
- prepend: function(tagName) {
- return this.newBuffer(tagName, this, function(buffer) {
- this.childBuffers.splice(0, 0, buffer);
- });
- },
+ willDestroyElement: function() {},
/**
- Replace the current buffer with a new render buffer.
+ @private
- @method replaceWith
- @param {String} tagName Tag name to use for the new buffer's element
+ Triggers the `willDestroyElement` event (which invokes the
+ `willDestroyElement()` method if it exists) on this view and all child
+ views.
+
+ Before triggering `willDestroyElement`, it first triggers the
+ `willClearRender` event recursively.
+
+ @method _notifyWillDestroyElement
*/
- replaceWith: function(tagName) {
- var parentBuffer = this.parentBuffer;
+ _notifyWillDestroyElement: function() {
+ this.triggerRecursively('willClearRender');
+ this.triggerRecursively('willDestroyElement');
+ },
- return this.newBuffer(tagName, parentBuffer, function(buffer) {
- this.replaceWithBuffer(buffer);
+ _elementWillChange: Ember.beforeObserver(function() {
+ this.forEachChildView(function(view) {
+ Ember.propertyWillChange(view, 'element');
});
- },
+ }, 'element'),
/**
- Insert a new render buffer after the current render buffer.
+ @private
- @method insertAfter
- @param {String} tagName Tag name to use for the new buffer's element
- */
- insertAfter: function(tagName) {
- var parentBuffer = get(this, 'parentBuffer');
+ If this view's element changes, we need to invalidate the caches of our
+ child views so that we do not retain references to DOM elements that are
+ no longer needed.
- return this.newBuffer(tagName, parentBuffer, function(buffer) {
- var siblings = parentBuffer.childBuffers;
- var index = indexOf.call(siblings, this);
- siblings.splice(index + 1, 0, buffer);
+ @method _elementDidChange
+ */
+ _elementDidChange: Ember.observer(function() {
+ this.forEachChildView(function(view) {
+ Ember.propertyDidChange(view, 'element');
});
- },
+ }, 'element'),
/**
- Closes the current buffer and adds its content to the parentBuffer.
+ Called when the parentView property has changed.
- @method end
- @return {Ember.RenderBuffer} The parentBuffer, if one exists. Otherwise, this
+ @event parentViewDidChange
*/
- end: function() {
- var parent = this.parentBuffer;
- return parent || this;
- },
+ parentViewDidChange: Ember.K,
- remove: function() {
- this.replaceWithBuffer(null);
- },
+ instrumentName: 'view',
- /**
- @method element
- @return {DOMElement} The element corresponding to the generated HTML
- of this buffer
- */
- element: function() {
- return Ember.$(this.string())[0];
+ instrumentDetails: function(hash) {
+ hash.template = get(this, 'templateName');
+ this._super(hash);
},
- /**
- Generates the HTML content for this buffer.
-
- @method string
- @return {String} The generated HTMl
- */
- string: function() {
- var content = '', tag = this.elementTag, openTag;
-
- if (tag) {
- var id = this.elementId,
- classes = this.elementClasses,
- attrs = this.elementAttributes,
- style = this.elementStyle,
- styleBuffer = '', prop;
+ _renderToBuffer: function(parentBuffer, bufferOperation) {
+ this.lengthBeforeRender = this._childViews.length;
+ var buffer = this._super(parentBuffer, bufferOperation);
+ this.lengthAfterRender = this._childViews.length;
- openTag = ["<" + tag];
+ return buffer;
+ },
- if (id) { openTag.push('id="' + this._escapeAttribute(id) + '"'); }
- if (classes) { openTag.push('class="' + this._escapeAttribute(classes.toDOM()) + '"'); }
+ renderToBufferIfNeeded: function () {
+ return this.currentState.renderToBufferIfNeeded(this, this);
+ },
- if (style) {
- for (prop in style) {
- if (style.hasOwnProperty(prop)) {
- styleBuffer += (prop + ':' + this._escapeAttribute(style[prop]) + ';');
- }
- }
+ beforeRender: function(buffer) {
+ this.applyAttributesToBuffer(buffer);
+ buffer.pushOpeningTag();
+ },
- openTag.push('style="' + styleBuffer + '"');
- }
+ afterRender: function(buffer) {
+ buffer.pushClosingTag();
+ },
- if (attrs) {
- for (prop in attrs) {
- if (attrs.hasOwnProperty(prop)) {
- openTag.push(prop + '="' + this._escapeAttribute(attrs[prop]) + '"');
- }
- }
- }
+ applyAttributesToBuffer: function(buffer) {
+ // Creates observers for all registered class name and attribute bindings,
+ // then adds them to the element.
+ var classNameBindings = get(this, 'classNameBindings');
+ if (classNameBindings.length) {
+ this._applyClassNameBindings(classNameBindings);
+ }
- openTag = openTag.join(" ") + '>';
+ // Pass the render buffer so the method can apply attributes directly.
+ // This isn't needed for class name bindings because they use the
+ // existing classNames infrastructure.
+ var attributeBindings = get(this, 'attributeBindings');
+ if (attributeBindings.length) {
+ this._applyAttributeBindings(buffer, attributeBindings);
}
- var childBuffers = this.childBuffers;
+ buffer.setClasses(this.classNames);
+ buffer.id(this.elementId);
- Ember.ArrayPolyfills.forEach.call(childBuffers, function(buffer) {
- var stringy = typeof buffer === 'string';
- content += (stringy ? buffer : buffer.string());
- });
+ var role = get(this, 'ariaRole');
+ if (role) {
+ buffer.attr('role', role);
+ }
- if (tag) {
- return openTag + content + "</" + tag + ">";
- } else {
- return content;
+ if (get(this, 'isVisible') === false) {
+ buffer.style('display', 'none');
}
},
- _escapeAttribute: function(value) {
- // Stolen shamelessly from Handlebars
+ // ..........................................................
+ // STANDARD RENDER PROPERTIES
+ //
- var escape = {
- "<": "<",
- ">": ">",
- '"': """,
- "'": "'",
- "`": "`"
- };
+ /**
+ Tag name for the view's outer element. The tag name is only used when an
+ element is first created. If you change the `tagName` for an element, you
+ must destroy and recreate the view element.
- var badChars = /&(?!\w+;)|[<>"'`]/g;
- var possible = /[&<>"'`]/;
+ By default, the render buffer will use a `<div>` tag for views.
- var escapeChar = function(chr) {
- return escape[chr] || "&";
- };
+ @property tagName
+ @type String
+ @default null
+ */
- var string = value.toString();
+ // We leave this null by default so we can tell the difference between
+ // the default case and a user-specified tag.
+ tagName: null,
- if(!possible.test(string)) { return string; }
- return string.replace(badChars, escapeChar);
- }
+ /**
+ The WAI-ARIA role of the control represented by this view. For example, a
+ button may have a role of type 'button', or a pane may have a role of
+ type 'alertdialog'. This property is used by assistive software to help
+ visually challenged users navigate rich web applications.
-};
+ 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
+ */
+ ariaRole: null,
+ /**
+ Standard CSS class names to apply to the view's outer element. This
+ property automatically inherits any class names defined by the view's
+ superclasses as well.
+ @property classNames
+ @type Array
+ @default ['ember-view']
+ */
+ classNames: ['ember-view'],
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ /**
+ A list of properties of the view to apply as class names. If the property
+ is a string value, the value of that string will be applied as a class
+ name.
+
+ ```javascript
+ // Applies the 'high' class to the view element
+ Ember.View.create({
+ classNameBindings: ['priority']
+ priority: 'high'
+ });
+ ```
+
+ If the value of the property is a Boolean, the name of that property is
+ added as a dasherized class name.
+
+ ```javascript
+ // Applies the 'is-urgent' class to the view element
+ Ember.View.create({
+ classNameBindings: ['isUrgent']
+ isUrgent: true
+ });
+ ```
+
+ If you would prefer to use a custom value instead of the dasherized
+ property name, you can pass a binding like this:
-var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
+ ```javascript
+ // Applies the 'urgent' class to the view element
+ Ember.View.create({
+ classNameBindings: ['isUrgent:urgent']
+ isUrgent: true
+ });
+ ```
-/**
- 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.
+ This list of properties is inherited from the view's superclasses as well.
- @class EventDispatcher
- @namespace Ember
- @private
- @extends Ember.Object
-*/
-Ember.EventDispatcher = Ember.Object.extend(
-/** @scope Ember.EventDispatcher.prototype */{
+ @property classNameBindings
+ @type Array
+ @default []
+ */
+ classNameBindings: [],
/**
- @private
+ A list of properties of the view to apply as attributes. If the property is
+ a string value, the value of that string will be applied as the attribute.
- The root DOM element to which event listeners should be attached. Event
- listeners will be attached to the document unless this is overridden.
+ ```javascript
+ // Applies the type attribute to the element
+ // with the value "button", like <div type="button">
+ Ember.View.create({
+ attributeBindings: ['type'],
+ type: 'button'
+ });
+ ```
- Can be specified as a DOMElement or a selector string.
+ If the value of the property is a Boolean, the name of that property is
+ added as an attribute.
- The default body is a string since this may be evaluated before document.body
- exists in the DOM.
+ ```javascript
+ // Renders something like <div enabled="enabled">
+ Ember.View.create({
+ attributeBindings: ['enabled'],
+ enabled: true
+ });
+ ```
- @property rootElement
- @type DOMElement
- @default 'body'
+ @property attributeBindings
*/
- rootElement: 'body',
+ attributeBindings: [],
+
+ // .......................................................
+ // CORE DISPLAY METHODS
+ //
/**
@private
- Sets up event listeners for standard browser events.
-
- This will be called after the browser sends a DOMContentReady event. By
- 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.
+ Setup a view, but do not finish waking it up.
+ - configure `childViews`
+ - register the view with the global views hash, which is used for event
+ dispatch
- @method setup
- @param addedEvents {Hash}
+ @method init
*/
- setup: function(addedEvents) {
- var event, events = {
- touchstart : 'touchStart',
- touchmove : 'touchMove',
- touchend : 'touchEnd',
- touchcancel : 'touchCancel',
- keydown : 'keyDown',
- keyup : 'keyUp',
- keypress : 'keyPress',
- mousedown : 'mouseDown',
- mouseup : 'mouseUp',
- contextmenu : 'contextMenu',
- click : 'click',
- dblclick : 'doubleClick',
- mousemove : 'mouseMove',
- focusin : 'focusIn',
- focusout : 'focusOut',
- mouseenter : 'mouseEnter',
- mouseleave : 'mouseLeave',
- submit : 'submit',
- input : 'input',
- change : 'change',
- dragstart : 'dragStart',
- drag : 'drag',
- dragenter : 'dragEnter',
- dragleave : 'dragLeave',
- dragover : 'dragOver',
- drop : 'drop',
- dragend : 'dragEnd'
- };
-
- Ember.$.extend(events, addedEvents || {});
+ init: function() {
+ this.elementId = this.elementId || guidFor(this);
- var rootElement = Ember.$(get(this, 'rootElement'));
+ this._super();
- Ember.assert(fmt('You cannot use the same root element (%@) multiple times in an Ember.Application', [rootElement.selector || rootElement[0].tagName]), !rootElement.is('.ember-application'));
- Ember.assert('You cannot make a new Ember.Application using a root element that is a descendent of an existing Ember.Application', !rootElement.closest('.ember-application').length);
- Ember.assert('You cannot make a new Ember.Application using a root element that is an ancestor of an existing Ember.Application', !rootElement.find('.ember-application').length);
+ // setup child views. be sure to clone the child views array first
+ this._childViews = this._childViews.slice();
- rootElement.addClass('ember-application');
+ Ember.assert("Only arrays are allowed for 'classNameBindings'", Ember.typeOf(this.classNameBindings) === 'array');
+ this.classNameBindings = Ember.A(this.classNameBindings.slice());
- Ember.assert('Unable to add "ember-application" class to rootElement. Make sure you set rootElement to the body or an element in the body.', rootElement.is('.ember-application'));
+ Ember.assert("Only arrays are allowed for 'classNames'", Ember.typeOf(this.classNames) === 'array');
+ this.classNames = Ember.A(this.classNames.slice());
- for (event in events) {
- if (events.hasOwnProperty(event)) {
- this.setupHandler(rootElement, event, events[event]);
+ var viewController = get(this, 'viewController');
+ if (viewController) {
+ viewController = get(viewController);
+ if (viewController) {
+ set(viewController, 'view', this);
}
}
},
- /**
- @private
+ appendChild: function(view, options) {
+ return this.currentState.appendChild(this, view, options);
+ },
- Registers an event listener on the document. If the given event is
- triggered, the provided event handler will be triggered on the target
- view.
+ /**
+ Removes the child view from the parent view.
- If the target view does not implement the event handler, or if the handler
- returns false, the parent view will be called. The event will continue to
- bubble to each successive parent view until it reaches the top.
+ @method removeChild
+ @param {Ember.View} view
+ @return {Ember.View} receiver
+ */
+ removeChild: function(view) {
+ // If we're destroying, the entire subtree will be
+ // freed, and the DOM will be handled separately,
+ // so no need to mess with childViews.
+ if (this.isDestroying) { return; }
- For example, to have the `mouseDown` method called on the target view when
- a `mousedown` event is received from the browser, do the following:
+ // update parent node
+ set(view, '_parentView', null);
- setupHandler('mousedown', 'mouseDown');
+ // remove view from childViews array.
+ var childViews = this._childViews;
- @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
- */
- setupHandler: function(rootElement, event, eventName) {
- var self = this;
+ Ember.EnumerableUtils.removeObject(childViews, view);
- rootElement.delegate('.ember-view', event + '.ember', function(evt, triggeringManager) {
- return Ember.handleErrors(function() {
- var view = Ember.View.views[this.id],
- result = true, manager = null;
+ this.propertyDidChange('childViews'); // HUH?! what happened to will change?
- manager = self._findNearestEventManager(view,eventName);
+ return this;
+ },
- if (manager && manager !== triggeringManager) {
- result = self._dispatchEvent(manager, evt, eventName, view);
- } else if (view) {
- result = self._bubbleEvent(view,evt,eventName);
- } else {
- evt.stopPropagation();
- }
+ /**
+ Removes all children from the `parentView`.
- return result;
- }, this);
+ @method removeAllChildren
+ @return {Ember.View} receiver
+ */
+ removeAllChildren: function() {
+ return this.mutateChildViews(function(view) {
+ this.removeChild(view);
});
+ },
- rootElement.delegate('[data-ember-action]', event + '.ember', function(evt) {
- 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);
- }
- }, this);
+ destroyAllChildren: function() {
+ return this.mutateChildViews(function(view) {
+ view.destroy();
});
},
- _findNearestEventManager: function(view, eventName) {
- var manager = null;
+ /**
+ Removes the view from its `parentView`, if one is found. Otherwise
+ does nothing.
- while (view) {
- manager = get(view, 'eventManager');
- if (manager && manager[eventName]) { break; }
+ @method removeFromParent
+ @return {Ember.View} receiver
+ */
+ removeFromParent: function() {
+ var parent = this._parentView;
- view = get(view, 'parentView');
- }
+ // Remove DOM element from parent
+ this.remove();
- return manager;
+ if (parent) { parent.removeChild(this); }
+ return this;
},
- _dispatchEvent: function(object, evt, eventName, view) {
- var result = true;
+ /**
+ You must call `destroy` on a view to destroy the view (and all of its
+ 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.
- var handler = object[eventName];
- if (Ember.typeOf(handler) === 'function') {
- result = handler.call(object, evt, view);
- // Do not preventDefault in eventManagers.
- evt.stopPropagation();
- }
- else {
- result = this._bubbleEvent(view, evt, eventName);
+ @method willDestroy
+ */
+ willDestroy: function() {
+ // calling this._super() will nuke computed properties and observers,
+ // so collect any information we need before calling super.
+ var childViews = this._childViews,
+ parent = this._parentView,
+ childLen;
+
+ // destroy the element -- this will avoid each child view destroying
+ // the element over and over again...
+ if (!this.removedFromDOM) { this.destroyElement(); }
+
+ // remove from non-virtual parent view if viewName was specified
+ if (this.viewName) {
+ var nonVirtualParentView = get(this, 'parentView');
+ if (nonVirtualParentView) {
+ set(nonVirtualParentView, this.viewName, null);
+ }
}
- return result;
- },
+ // remove from parent if found. Don't call removeFromParent,
+ // as removeFromParent will try to remove the element from
+ // the DOM again.
+ if (parent) { parent.removeChild(this); }
- _bubbleEvent: function(view, evt, eventName) {
- return Ember.run(function() {
- return view.handleEvent(eventName, evt);
- });
+ this.transitionTo('destroyed');
+
+ childLen = childViews.length;
+ for (var i=childLen-1; i>=0; i--) {
+ childViews[i].removedFromDOM = true;
+ childViews[i].destroy();
+ }
+
+ // next remove view from global hash
+ if (!this.isVirtual) delete Ember.View.views[get(this, 'elementId')];
},
- destroy: function() {
- var rootElement = get(this, 'rootElement');
- Ember.$(rootElement).undelegate('.ember').removeClass('ember-application');
- return this._super();
- }
-});
+ /**
+ Instantiates a view to be added to the childViews array during view
+ initialization. You generally will not call this method directly unless
+ you are overriding `createChildViews()`. Note that this method will
+ 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
+ @return {Ember.View} new instance
+ */
+ createChildView: function(view, attrs) {
+ if (view.isView && view._parentView === this) { return view; }
+ if (Ember.CoreView.detect(view)) {
+ attrs = attrs || {};
+ attrs._parentView = this;
+ attrs.templateData = attrs.templateData || get(this, 'templateData');
+ view = view.create(attrs);
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ // don't set the property on a virtual view, as they are invisible to
+ // consumers of the view API
+ if (view.viewName) { set(get(this, 'concreteView'), view.viewName, view); }
+ } else {
+ Ember.assert('You must pass instance or subclass of View', view.isView);
-// Add a new named queue for rendering views that happens
-// after bindings have synced.
-var queues = Ember.run.queues;
-queues.splice(Ember.$.inArray('actions', queues)+1, 0, 'render');
+ if (attrs) {
+ view.setProperties(attrs);
+ }
-})();
+ if (!get(view, 'templateData')) {
+ set(view, 'templateData', get(this, 'templateData'));
+ }
+ set(view, '_parentView', this);
+ }
+ return view;
+ },
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ becameVisible: Ember.K,
+ becameHidden: Ember.K,
-var get = Ember.get, set = Ember.set;
+ /**
+ @private
-// Original class declaration and documentation in runtime/lib/controllers/controller.js
-// NOTE: It may be possible with YUIDoc to combine docs in two locations
+ When the view's `isVisible` property changes, toggle the visibility
+ element of the actual DOM element.
-/**
-Additional methods for the ControllerMixin
+ @method _isVisibleDidChange
+ */
+ _isVisibleDidChange: Ember.observer(function() {
+ var $el = this.$();
+ if (!$el) { return; }
-@class ControllerMixin
-@namespace Ember
-*/
-Ember.ControllerMixin.reopen({
+ var isVisible = get(this, 'isVisible');
- target: null,
- controllers: null,
- namespace: null,
- view: null,
+ $el.toggle(isVisible);
- /**
- `connectOutlet` creates a new instance of a provided view
- class, wires it up to its associated controller, and
- assigns the new view to a property on the current controller.
+ if (this._isAncestorHidden()) { return; }
- The purpose of this method is to enable views that use
- outlets to quickly assign new views for a given outlet.
+ if (isVisible) {
+ this._notifyBecameVisible();
+ } else {
+ this._notifyBecameHidden();
+ }
+ }, 'isVisible'),
- For example, an application view's template may look like
- this:
+ _notifyBecameVisible: function() {
+ this.trigger('becameVisible');
- ``` handlebars
- <h1>My Blog</h1>
- {{outlet}}
- ```
+ this.forEachChildView(function(view) {
+ var isVisible = get(view, 'isVisible');
- 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:
+ if (isVisible || isVisible === null) {
+ view._notifyBecameVisible();
+ }
+ });
+ },
- ``` javascript
- applicationController.connectOutlet('posts');
- ```
+ _notifyBecameHidden: function() {
+ this.trigger('becameHidden');
+ this.forEachChildView(function(view) {
+ var isVisible = get(view, 'isVisible');
- In general, you will also want to assign a controller
- to the newly created view. By convention, a controller
- named `postsController` will be assigned as the view's
- controller.
+ if (isVisible || isVisible === null) {
+ view._notifyBecameHidden();
+ }
+ });
+ },
- In an application initialized using `app.initialize(router)`,
- `connectOutlet` will look for `postsController` on the
- router. The initialization process will automatically
- create an instance of `App.PostsController` called
- `postsController`, so you don't need to do anything
- beyond `connectOutlet` to assign your view and wire it
- up to its associated controller.
+ _isAncestorHidden: function() {
+ var parent = get(this, 'parentView');
- You can supply a `content` for the controller by supplying
- a final argument after the view class:
+ while (parent) {
+ if (get(parent, 'isVisible') === false) { return true; }
- ``` javascript
- applicationController.connectOutlet('posts', App.Post.find());
- ```
+ parent = get(parent, 'parentView');
+ }
- You can specify a particular outlet to use. For example, if your main
- template looks like:
+ return false;
+ },
- ``` handlebars
- <h1>My Blog</h1>
- {{outlet master}}
- {{outlet detail}}
- ```
+ clearBuffer: function() {
+ this.invokeRecursively(function(view) {
+ view.buffer = null;
+ });
+ },
- You can assign an `App.PostsView` to the master outlet:
+ transitionTo: function(state, children) {
+ this.currentState = this.states[state];
+ this.state = state;
- ``` javascript
- applicationController.connectOutlet({
- name: 'posts',
- outletName: 'master',
- context: App.Post.find()
- });
- ```
+ if (children !== false) {
+ this.forEachChildView(function(view) {
+ view.transitionTo(state);
+ });
+ }
+ },
- You can write this as:
+ // .......................................................
+ // EVENT HANDLING
+ //
- ``` javascript
- applicationController.connectOutlet('master', 'posts', App.Post.find());
- ```
+ /**
+ @private
+ Handle events from `Ember.EventDispatcher`
- @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
- controller's `content` property, if a controller can be
- found (optional)
+ @method handleEvent
+ @param eventName {String}
+ @param evt {Event}
*/
- connectOutlet: function(name, context) {
- // Normalize arguments. Supported arguments:
- //
- // name
- // name, context
- // outletName, name
- // outletName, name, context
- // options
- //
- // The options hash has the following keys:
- //
- // name: the name of the controller and view
- // to use. If this is passed, the name
- // determines the view and controller.
- // outletName: the name of the outlet to
- // fill in. default: 'view'
- // viewClass: the class of the view to instantiate
- // controller: the controller instance to pass
- // to the view
- // context: an object that should become the
- // controller's `content` and thus the
- // template's context.
-
- var outletName, viewClass, view, controller, options;
-
- if (Ember.typeOf(context) === 'string') {
- outletName = name;
- name = context;
- context = arguments[2];
- }
+ handleEvent: function(eventName, evt) {
+ return this.currentState.handleEvent(this, eventName, evt);
+ }
- if (arguments.length === 1) {
- if (Ember.typeOf(name) === 'object') {
- options = name;
- outletName = options.outletName;
- name = options.name;
- viewClass = options.viewClass;
- controller = options.controller;
- context = options.context;
- }
- } else {
- options = {};
- }
+});
- outletName = outletName || 'view';
-
- Ember.assert("The viewClass is either missing or the one provided did not resolve to a view", !!name || (!name && !!viewClass));
-
- Ember.assert("You must supply a name or a viewClass to connectOutlet, but not both", (!!name && !viewClass && !controller) || (!name && !!viewClass));
+/*
+ Describe how the specified actions should behave in the various
+ states that a view can exist in. Possible states:
- if (name) {
- var namespace = get(this, 'namespace'),
- controllers = get(this, 'controllers');
+ * preRender: when a view is first instantiated, and after its
+ element was destroyed, it is in the preRender state
+ * inBuffer: once a view has been rendered, but before it has
+ been inserted into the DOM, it is in the inBuffer state
+ * inDOM: once a view has been inserted into the DOM it is in
+ the inDOM state. A view spends the vast majority of its
+ existence in this state.
+ * destroyed: once a view has been destroyed (using the destroy
+ method), it is in this state. No further actions can be invoked
+ on a destroyed view.
+*/
- var viewClassName = name.charAt(0).toUpperCase() + name.substr(1) + "View";
- viewClass = get(namespace, viewClassName);
- controller = get(controllers, name + 'Controller');
+ // in the destroyed state, everything is illegal
- Ember.assert("The name you supplied " + name + " did not resolve to a view " + viewClassName, !!viewClass);
- Ember.assert("The name you supplied " + name + " did not resolve to a controller " + name + 'Controller', (!!controller && !!context) || !context);
- }
+ // before rendering has begun, all legal manipulations are noops.
- if (controller && context) { set(controller, 'content', context); }
+ // inside the buffer, legal manipulations are done on the buffer
- view = this.createOutletView(outletName, viewClass);
+ // once the view has been inserted into the DOM, legal manipulations
+ // are done on the DOM element.
- if (controller) { set(view, 'controller', controller); }
- set(this, outletName, view);
+var DOMManager = {
+ prepend: function(view, html) {
+ view.$().prepend(html);
+ },
- return view;
+ after: function(view, html) {
+ view.$().after(html);
},
- /**
- Convenience method to connect controllers. This method makes other controllers
- available on the controller the method was invoked on.
+ html: function(view, html) {
+ view.$().html(html);
+ },
- For example, to make the `personController` and the `postController` available
- on the `overviewController`, you would call:
+ replace: function(view) {
+ var element = get(view, 'element');
- overviewController.connectControllers('person', 'post');
+ set(view, 'element', null);
- @method connectControllers
- @param {String...} controllerNames the controllers to make available
- */
- connectControllers: function() {
- var controllers = get(this, 'controllers'),
- controllerNames = Array.prototype.slice.apply(arguments),
- controllerName;
+ view._insertElementLater(function() {
+ Ember.$(element).replaceWith(get(view, 'element'));
+ });
+ },
- for (var i=0, l=controllerNames.length; i<l; i++) {
- controllerName = controllerNames[i] + 'Controller';
- set(this, controllerName, get(controllers, controllerName));
- }
+ remove: function(view) {
+ view.$().remove();
},
- /**
- `disconnectOutlet` removes previously attached view from given outlet.
+ empty: function(view) {
+ view.$().empty();
+ }
+};
- @method disconnectOutlet
- @param {String} outletName the outlet name. (optional)
- */
- disconnectOutlet: function(outletName) {
- outletName = outletName || 'view';
+Ember.View.reopen({
+ domManager: DOMManager
+});
- set(this, outletName, null);
- },
+Ember.View.reopenClass({
/**
- `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.
+ @private
- @method createOutletView
- @param outletName {String}
- @param viewClass {Ember.View}
- */
- createOutletView: function(outletName, viewClass) {
- return viewClass.create();
- }
-});
+ Parse a path and return an object which holds the parsed properties.
-})();
+ For example a path like "content.isEnabled:enabled:disabled" wil return the
+ following object:
+ ```javascript
+ {
+ path: "content.isEnabled",
+ className: "enabled",
+ falsyClassName: "disabled",
+ classNames: ":enabled:disabled"
+ }
+ ```
+ @method _parsePropertyPath
+ @static
+ */
+ _parsePropertyPath: function(path) {
+ var split = path.split(':'),
+ propertyPath = split[0],
+ classNames = "",
+ className,
+ falsyClassName;
-(function() {
+ // check if the property is defined as prop:class or prop:trueClass:falseClass
+ if (split.length > 1) {
+ className = split[1];
+ if (split.length === 3) { falsyClassName = split[2]; }
-})();
+ classNames = ':' + className;
+ if (falsyClassName) { classNames += ":" + falsyClassName; }
+ }
+ return {
+ path: propertyPath,
+ classNames: classNames,
+ className: (className === '') ? undefined : className,
+ falsyClassName: falsyClassName
+ };
+ },
+ /**
+ @private
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ Get the class name for a given value, based on the path, optional
+ `className` and optional `falsyClassName`.
+
+ - 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 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) {
+ // 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;
-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;
+ } else if (falsyClassName && !val) {
+ return falsyClassName;
-var childViewsProperty = Ember.computed(function() {
- var childViews = this._childViews;
+ } else {
+ return null;
+ }
- var ret = Ember.A();
+ // If value is a Boolean and true, return the dasherized property
+ // name.
+ } else if (val === true) {
+ // 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]);
- a_forEach(childViews, function(view) {
- if (view.isVirtual) {
- ret.pushObjects(get(view, 'childViews'));
+ // If the value is not false, undefined, or null, return the current
+ // value of the property.
+ } else if (val !== false && val !== undefined && val !== null) {
+ return val;
+
+ // Nothing to display. Return null so that the old class is removed
+ // but no new class is added.
} else {
- ret.push(view);
+ return null;
}
- });
-
- return ret;
-}).property().cacheable();
-
-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);
+ }
+});
/**
- 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.
+ Global views hash
- @property TEMPLATES
- @for Ember
+ @property views
+ @static
@type Hash
*/
-Ember.TEMPLATES = {};
-
-var invokeForState = {
- preRender: {},
- inBuffer: {},
- hasElement: {},
- inDOM: {},
- destroyed: {}
-};
-
-/**
- `Ember.View` is the class in Ember responsible for encapsulating templates of HTML
- content, combining templates with data to render as sections of a page's DOM, and
- registering and responding to user-initiated events.
-
- ## HTML Tag
- The default HTML tag name used for a view's DOM representation is `div`. This can be
- customized by setting the `tagName` property. The following view class:
-
- ``` javascript
- ParagraphView = Ember.View.extend({
- tagName: 'em'
- });
- ```
-
- Would result in instances with the following HTML:
-
- ``` 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:
-
- ``` javascript
- MyView = Ember.View.extend({
- classNames: ['my-class', 'my-other-class']
- });
- ```
-
- Will result in view instances with an HTML representation of:
-
- ``` html
- <div id="ember1" class="ember-view my-class my-other-class"></div>
- ```
+Ember.View.views = {};
- `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:
+// If someone overrides the child views computed property when
+// defining their class, we want to be able to process the user's
+// supplied childViews and then restore the original computed property
+// at view initialization time. This happens in Ember.ContainerView's init
+// method.
+Ember.View.childViewsProperty = childViewsProperty;
- ``` javascript
- MyView = Ember.View.extend({
- classNameBindings: ['propertyA', 'propertyB'],
- propertyA: 'from-a',
- propertyB: function(){
- if(someLogic){ return 'from-b'; }
- }.property()
- });
- ```
+Ember.View.applyAttributeBindings = function(elem, name, value) {
+ var type = Ember.typeOf(value);
+ var currentValue = elem.attr(name);
- Will result in view instances with an HTML representation of:
+ // if this changes, also change the logic in ember-handlebars/lib/helpers/binding.js
+ if ((type === 'string' || (type === 'number' && !isNaN(value))) && value !== currentValue) {
+ elem.attr(name, value);
+ } else if (value && type === 'boolean') {
+ elem.attr(name, name);
+ } else if (!value) {
+ elem.removeAttr(name);
+ }
+};
- ``` html
- <div id="ember1" class="ember-view from-a from-b"></div>
- ```
+Ember.View.states = states;
- 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`.
+})();
- ``` javascript
- MyView = Ember.View.extend({
- classNameBindings: ['hovered'],
- hovered: true
- });
- ```
- Will result in view instances with an HTML representation of:
- ``` html
- <div id="ember1" class="ember-view hovered"></div>
- ```
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- 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:
+var get = Ember.get, set = Ember.set;
- ``` javascript
- MyView = Ember.View.extend({
- classNameBindings: ['awesome:so-very-cool'],
- awesome: true
- });
- ```
+Ember.View.states._default = {
+ // appendChild is only legal while rendering the buffer.
+ appendChild: function() {
+ throw "You can't use appendChild outside of the rendering process";
+ },
- Will result in view instances with an HTML representation of:
+ $: function() {
+ return undefined;
+ },
- ``` html
- <div id="ember1" class="ember-view so-very-cool"></div>
- ```
+ getElement: function() {
+ return null;
+ },
+ // Handle events from `Ember.EventDispatcher`
+ handleEvent: function() {
+ return true; // continue event propagation
+ },
- Boolean value class name bindings whose property names are in a camelCase-style
- format will be converted to a dasherized format:
+ destroyElement: function(view) {
+ set(view, 'element', null);
+ if (view._scheduledInsert) {
+ Ember.run.cancel(view._scheduledInsert);
+ view._scheduledInsert = null;
+ }
+ return view;
+ },
- ``` javascript
- MyView = Ember.View.extend({
- classNameBindings: ['isUrgent'],
- isUrgent: true
- });
- ```
+ renderToBufferIfNeeded: function () {
+ return false;
+ },
- Will result in view instances with an HTML representation of:
+ rerender: Ember.K
+};
- ``` 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:
- ``` javascript
- MyView = Ember.View.extend({
- classNameBindings: ['messages.empty']
- messages: Ember.Object.create({
- empty: true
- })
- });
- ```
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- Will result in view instances with an HTML representation of:
+var preRender = Ember.View.states.preRender = Ember.create(Ember.View.states._default);
- ``` html
- <div id="ember1" class="ember-view empty"></div>
- ```
+Ember.merge(preRender, {
+ // a view leaves the preRender state once its element has been
+ // created (createElement).
+ insertElement: function(view, fn) {
+ view.createElement();
+ view.triggerRecursively('willInsertElement');
+ // after createElement, the view will be in the hasElement state.
+ fn.call(view);
+ view.transitionTo('inDOM');
+ view.triggerRecursively('didInsertElement');
+ },
+ renderToBufferIfNeeded: function(view) {
+ return view.renderToBuffer();
+ },
- 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:
+ empty: Ember.K,
- ```
- // Applies 'enabled' class when isEnabled is true and 'disabled' when isEnabled is false
- Ember.View.create({
- classNameBindings: ['isEnabled:enabled:disabled']
- isEnabled: true
- });
- ```
+ setElement: function(view, value) {
+ if (value !== null) {
+ view.transitionTo('hasElement');
+ }
+ return value;
+ }
+});
- Will result in view instances with an HTML representation of:
+})();
- ``` html
- <div id="ember1" class="ember-view enabled"></div>
- ```
- When isEnabled is `false`, the resulting HTML reprensentation looks like this:
- ``` html
- <div id="ember1" class="ember-view disabled"></div>
- ```
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- This syntax offers the convenience to add a class if a property is `false`:
+var get = Ember.get, set = Ember.set, meta = Ember.meta;
- ``` javascript
- // Applies no class when isEnabled is true and class 'disabled' when isEnabled is false
- Ember.View.create({
- classNameBindings: ['isEnabled::disabled']
- isEnabled: true
- });
- ```
+var inBuffer = Ember.View.states.inBuffer = Ember.create(Ember.View.states._default);
- Will result in view instances with an HTML representation of:
+Ember.merge(inBuffer, {
+ $: function(view, sel) {
+ // if we don't have an element yet, someone calling this.$() is
+ // trying to update an element that isn't in the DOM. Instead,
+ // rerender the view to allow the render method to reflect the
+ // changes.
+ view.rerender();
+ return Ember.$();
+ },
- ``` html
- <div id="ember1" class="ember-view"></div>
- ```
+ // when a view is rendered in a buffer, rerendering it simply
+ // replaces the existing buffer with a new one
+ rerender: function(view) {
+ throw new Ember.Error("Something you did caused a view to re-render after it rendered but before it was inserted into the DOM.");
+ },
- When the `isEnabled` property on the view is set to `false`, it will result
- in view instances with an HTML representation of:
+ // when a view is rendered in a buffer, appending a child
+ // view will render that view and append the resulting
+ // buffer into its buffer.
+ appendChild: function(view, childView, options) {
+ var buffer = view.buffer;
- ``` html
- <div id="ember1" class="ember-view disabled"></div>
- ```
+ childView = view.createChildView(childView, options);
+ view._childViews.push(childView);
- Updates to the the value of a class name binding will result in automatic update
- of the HTML `class` attribute in the view's rendered HTML representation.
- If the value becomes `false` or `undefined` the class name will be removed.
+ childView.renderToBuffer(buffer);
- Both `classNames` and `classNameBindings` are concatenated properties.
- See `Ember.Object` documentation for more information about concatenated properties.
+ view.propertyDidChange('childViews');
- ## HTML Attributes
+ return childView;
+ },
- 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:
+ // when a view is rendered in a buffer, destroying the
+ // element will simply destroy the buffer and put the
+ // state back into the preRender state.
+ destroyElement: function(view) {
+ view.clearBuffer();
+ view._notifyWillDestroyElement();
+ view.transitionTo('preRender');
- ``` javascript
- AnchorView = Ember.View.extend({
- tagName: 'a',
- attributeBindings: ['href'],
- href: 'http://google.com'
- });
- ```
+ return view;
+ },
- Will result in view instances with an HTML representation of:
+ empty: function() {
+ Ember.assert("Emptying a view in the inBuffer state is not allowed and should not happen under normal circumstances. Most likely there is a bug in your application. This may be due to excessive property change notifications.");
+ },
- ``` html
- <a id="ember1" class="ember-view" href="http://google.com"></a>
- ```
+ renderToBufferIfNeeded: function (view) {
+ return view.buffer;
+ },
- 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:
+ // It should be impossible for a rendered view to be scheduled for
+ // insertion.
+ insertElement: function() {
+ throw "You can't insert an element that has already been rendered";
+ },
- ``` javascript
- MyTextInput = Ember.View.extend({
- tagName: 'input',
- attributeBindings: ['disabled'],
- disabled: true
- });
- ```
+ setElement: function(view, value) {
+ if (value === null) {
+ view.transitionTo('preRender');
+ } else {
+ view.clearBuffer();
+ view.transitionTo('hasElement');
+ }
- Will result in view instances with an HTML representation of:
+ return value;
+ }
+});
- ``` html
- <input id="ember1" class="ember-view" disabled="disabled" />
- ```
- `attributeBindings` can refer to computed properties:
+})();
- ``` 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.
- `attributeBindings` is a concatenated property. See `Ember.Object` documentation
- for more information about concatenated properties.
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- ## Templates
- The HTML contents of a view's rendered representation are determined by its template.
- Templates can be any function that accepts an optional context parameter and returns
- 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.
+var get = Ember.get, set = Ember.set, meta = Ember.meta;
- ``` javascript
- AView = Ember.View.extend({
- template: Ember.Handlebars.compile('I am the template')
- });
- ```
+var hasElement = Ember.View.states.hasElement = Ember.create(Ember.View.states._default);
- Will result in view instances with an HTML representation of:
+Ember.merge(hasElement, {
+ $: function(view, sel) {
+ var elem = get(view, 'element');
+ return sel ? Ember.$(sel, elem) : Ember.$(elem);
+ },
- ``` html
- <div id="ember1" class="ember-view">I am the template</div>
- ```
+ getElement: function(view) {
+ var parent = get(view, 'parentView');
+ if (parent) { parent = get(parent, 'element'); }
+ if (parent) { return view.findElementInParentElement(parent); }
+ return Ember.$("#" + get(view, 'elementId'))[0];
+ },
- The default context of the compiled template will be the view instance itself:
+ setElement: function(view, value) {
+ if (value === null) {
+ view.transitionTo('preRender');
+ } else {
+ throw "You cannot set an element to a non-null value when the element is already in the DOM.";
+ }
- ``` javascript
- AView = Ember.View.extend({
- template: Ember.Handlebars.compile('Hello {{excitedGreeting}}')
- });
+ return value;
+ },
- aView = AView.create({
- content: Ember.Object.create({
- firstName: 'Barry'
- })
- excitedGreeting: function(){
- return this.get("content.firstName") + "!!!"
- }
- });
- ```
+ // once the view has been inserted into the DOM, rerendering is
+ // deferred to allow bindings to synchronize.
+ rerender: function(view) {
+ view.triggerRecursively('willClearRender');
- Will result in an HTML representation of:
+ view.clearRenderedChildren();
- ``` html
- <div id="ember1" class="ember-view">Hello Barry!!!</div>
- ```
+ view.domManager.replace(view);
+ return view;
+ },
- Within an Ember application is more common to define a Handlebars templates as
- part of a page:
+ // once the view is already in the DOM, destroying it removes it
+ // from the DOM, nukes its element, and puts it back into the
+ // preRender state if inDOM.
- ``` handlebars
- <script type='text/x-handlebars' data-template-name='some-template'>
- Hello
- </script>
- ```
+ destroyElement: function(view) {
+ view._notifyWillDestroyElement();
+ view.domManager.remove(view);
+ set(view, 'element', null);
+ if (view._scheduledInsert) {
+ Ember.run.cancel(view._scheduledInsert);
+ view._scheduledInsert = null;
+ }
+ return view;
+ },
- And associate it by name using a view's `templateName` property:
+ empty: function(view) {
+ var _childViews = view._childViews, len, idx;
+ if (_childViews) {
+ len = _childViews.length;
+ for (idx = 0; idx < len; idx++) {
+ _childViews[idx]._notifyWillDestroyElement();
+ }
+ }
+ view.domManager.empty(view);
+ },
- ``` javascript
- AView = Ember.View.extend({
- templateName: 'some-template'
- });
- ```
+ // Handle events from `Ember.EventDispatcher`
+ handleEvent: function(view, eventName, evt) {
+ if (view.has(eventName)) {
+ // Handler should be able to re-dispatch events, so we don't
+ // preventDefault or stopPropagation.
+ return view.trigger(eventName, evt);
+ } else {
+ return true; // continue event propagation
+ }
+ }
+});
- Using a value for `templateName` that does not have a Handlebars template with a
- matching `data-template-name` attribute will throw an error.
+var inDOM = Ember.View.states.inDOM = Ember.create(hasElement);
- Assigning a value to both `template` and `templateName` properties will throw an error.
+Ember.merge(inDOM, {
+ insertElement: function(view, fn) {
+ throw "You can't insert an element into the DOM that has already been inserted";
+ }
+});
- For views classes that may have a template later defined (e.g. as the block portion of a `{{view}}`
- Handlebars helper call in another template or in a subclass), you can provide a `defaultTemplate`
- property set to compiled template function. If a template is not later provided for the view
- instance the `defaultTemplate` value will be used:
+})();
- ``` 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:
- ``` html
- <div id="ember1" class="ember-view">I was the default</div>
- ```
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- If a `template` or `templateName` is provided it will take precedence over `defaultTemplate`:
+var destroyedError = "You can't call %@ on a destroyed view", fmt = Ember.String.fmt;
- ``` javascript
- AView = Ember.View.extend({
- defaultTemplate: Ember.Handlebars.compile('I was the default')
- });
+var destroyed = Ember.View.states.destroyed = Ember.create(Ember.View.states._default);
- aView = AView.create({
- template: Ember.Handlebars.compile('I was the template, not default')
- });
- ```
+Ember.merge(destroyed, {
+ appendChild: function() {
+ throw fmt(destroyedError, ['appendChild']);
+ },
+ rerender: function() {
+ throw fmt(destroyedError, ['rerender']);
+ },
+ destroyElement: function() {
+ throw fmt(destroyedError, ['destroyElement']);
+ },
+ empty: function() {
+ throw fmt(destroyedError, ['empty']);
+ },
- Will result in the following HTML representation when rendered:
+ setElement: function() {
+ throw fmt(destroyedError, ["set('element', ...)"]);
+ },
- ``` html
- <div id="ember1" class="ember-view">I was the template, not default</div>
- ```
+ renderToBufferIfNeeded: function() {
+ throw fmt(destroyedError, ["renderToBufferIfNeeded"]);
+ },
- ## Layouts
+ // Since element insertion is scheduled, don't do anything if
+ // the view has been destroyed between scheduling and execution
+ insertElement: Ember.K
+});
- Views can have a secondary template that wraps their main template. Like
- primary templates, layouts can be any function that accepts an optional context
- parameter and returns a string of HTML that will be inserted inside view's tag. Views whose HTML
- element is self closing (e.g. `<input />`) cannot have a layout and this property will be ignored.
-
- Most typically in Ember a layout will be a compiled Ember.Handlebars template.
- A view's layout can be set directly with the `layout` property or reference an
- existing Handlebars template by name with the `layoutName` property.
+})();
- 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:
- ``` 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:
+(function() {
+Ember.View.cloneStates = function(from) {
+ var into = {};
- ``` html
- <div id="ember1" class="ember-view">
- <div class="my-decorative-class">
- I got wrapped
- </div>
- </div>
- ```
+ into._default = {};
+ into.preRender = Ember.create(into._default);
+ into.destroyed = Ember.create(into._default);
+ into.inBuffer = Ember.create(into._default);
+ into.hasElement = Ember.create(into._default);
+ into.inDOM = Ember.create(into.hasElement);
- See `Handlebars.helpers.yield` for more information.
+ var viewState;
- ## Responding to Browser Events
+ for (var stateName in from) {
+ if (!from.hasOwnProperty(stateName)) { continue; }
+ Ember.merge(into[stateName], from[stateName]);
+ }
- 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.
+ return into;
+};
- ### 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.
- ``` javascript
- AView = Ember.View.extend({
- click: function(event){
- // will be called when when an instance's
- // rendered element is clicked
- }
- });
- ```
- ### Event Managers
+(function() {
+var states = Ember.View.cloneStates(Ember.View.states);
- Views can define an object as their `eventManager` property. This object can then
- implement methods that match the desired event names. Matching events that occur
- on the view's rendered HTML or the rendered HTML of any of its DOM descendants
- will trigger this method. A `jQuery.Event` object will be passed as the first
- argument to the method and an `Ember.View` object as the second. The `Ember.View`
- will be the view whose rendered HTML was interacted with. This may be the view with
- the `eventManager` property or one of its descendent views.
+/**
+@module ember
+@submodule ember-views
+*/
- ``` 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
- }
- })
- });
- ```
+var get = Ember.get, set = Ember.set, meta = Ember.meta;
+var forEach = Ember.EnumerableUtils.forEach;
+var childViewsProperty = Ember.computed(function() {
+ return get(this, '_childViews');
+}).property('_childViews');
- An event defined for an event manager takes precedence over events of the same
- name handled through methods on the view.
+/**
+ 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.
- ``` javascript
- AView = Ember.View.extend({
- mouseEnter: function(event){
- // will never trigger.
- },
- eventManager: Ember.Object.create({
- mouseEnter: function(event, view){
- // takes presedence over AView#mouseEnter
- }
- })
- });
- ```
+ ## Setting Initial Child Views
- Similarly a view's event manager will take precedence for events of any views
- rendered as a descendent. A method name that matches an event name will not be called
- if the view instance was rendered inside the HTML representation of a view that has
- 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.
+ 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`:
- ``` 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
- }
- })
+ ```javascript
+ aContainer = Ember.ContainerView.create({
+ childViews: [Ember.View.create(), Ember.View.create()]
});
+ ```
- 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.
- }
+ You can also provide a list of property names whose values are instances of
+ `Ember.View`:
+
+ ```javascript
+ aContainer = Ember.ContainerView.create({
+ childViews: ['aView', 'bView', 'cView'],
+ aView: Ember.View.create(),
+ bView: Ember.View.create(),
+ cView: Ember.View.create()
});
```
- ### Handlebars `{{action}}` Helper
+ The two strategies can be combined:
- See `Handlebars.helpers.action`.
+ ```javascript
+ aContainer = Ember.ContainerView.create({
+ childViews: ['aView', Ember.View.create()],
+ aView: Ember.View.create()
+ });
+ ```
- ### Event Names
+ 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.
- Possible events names for any of the responding approaches described above are:
+ ## Adding and Removing Child Views
- Touch events: 'touchStart', 'touchMove', 'touchEnd', 'touchCancel'
+ The views in a container's `childViews` array should be added and removed by
+ manipulating the `childViews` property directly.
- Keyboard events: 'keyDown', 'keyUp', 'keyPress'
+ To remove a view pass that view into a `removeObject` call on the container's
+ `childViews` property.
- Mouse events: 'mouseDown', 'mouseUp', 'contextMenu', 'click', 'doubleClick', 'mouseMove',
- 'focusIn', 'focusOut', 'mouseEnter', 'mouseLeave'
+ Given an empty `<body>` the following code
- Form events: 'submit', 'change', 'focusIn', 'focusOut', 'input'
+ ```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")
+ })
+ });
- 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.
+ aContainer.appendTo('body');
+ ```
- @class View
- @namespace Ember
- @extends Ember.Object
- @uses Ember.Evented
-*/
-Ember.View = Ember.Object.extend(Ember.Evented,
-/** @scope Ember.View.prototype */ {
+ Results in the HTML
- concatenatedProperties: ['classNames', 'classNameBindings', 'attributeBindings'],
+ ```html
+ <div class="ember-view the-container">
+ <div class="ember-view">A</div>
+ <div class="ember-view">B</div>
+ </div>
+ ```
- /**
- @property isView
- @type Boolean
- @default true
- @final
- */
- isView: true,
+ Removing a view
- // ..........................................................
- // TEMPLATE SUPPORT
- //
+ ```javascript
+ aContainer.get('childViews'); // [aContainer.aView, aContainer.bView]
+ aContainer.get('childViews').removeObject(aContainer.get('bView'));
+ aContainer.get('childViews'); // [aContainer.aView]
+ ```
- /**
- The name of the template to lookup if no template is provided.
+ Will result in the following HTML
- Ember.View will look for a template with this name in this view's
- `templates` object. By default, this will be a global object
- shared in `Ember.TEMPLATES`.
+ ```html
+ <div class="ember-view the-container">
+ <div class="ember-view">A</div>
+ </div>
+ ```
- @property templateName
- @type String
- @default null
- */
- templateName: null,
+ Similarly, adding a child view is accomplished by adding `Ember.View` instances to the
+ container's `childViews` property.
- /**
- The name of the layout to lookup if no layout is provided.
+ Given an empty `<body>` the following code
- Ember.View will look for a template with this name in this view's
- `templates` object. By default, this will be a global object
- shared in `Ember.TEMPLATES`.
+ ```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")
+ })
+ });
- @property layoutName
- @type String
- @default null
- */
- layoutName: null,
+ aContainer.appendTo('body');
+ ```
- /**
- The hash in which to look for `templateName`.
+ Results in the HTML
- @property templates
- @type Ember.Object
- @default Ember.TEMPLATES
- */
- templates: Ember.TEMPLATES,
+ ```html
+ <div class="ember-view the-container">
+ <div class="ember-view">A</div>
+ <div class="ember-view">B</div>
+ </div>
+ ```
- /**
- The template used to render the view. This should be a function that
- accepts an optional context parameter and returns a string of HTML that
- will be inserted into the DOM relative to its parent view.
+ Adding a view
- In general, you should set the `templateName` property instead of setting
- the template yourself.
+ ```javascript
+ AnotherViewClass = Ember.View.extend({
+ template: Ember.Handlebars.compile("Another view")
+ });
- @property template
- @type Function
- */
- template: Ember.computed(function(key, value) {
- if (value !== undefined) { return value; }
+ aContainer.get('childViews'); // [aContainer.aView, aContainer.bView]
+ aContainer.get('childViews').pushObject(AnotherViewClass.create());
+ aContainer.get('childViews'); // [aContainer.aView, aContainer.bView, <AnotherViewClass instance>]
+ ```
- var templateName = get(this, 'templateName'),
- template = this.templateForName(templateName, 'template');
+ Will result in the following HTML
- return template || get(this, 'defaultTemplate');
- }).property('templateName').cacheable(),
+ ```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>
+ ```
- /**
- The controller managing this view. If this property is set, it will be
- made available for use by the template.
+ Direct manipulation of `childViews` presence or absence in the DOM via calls
+ to `remove` or `removeFromParent` or calls to a container's `removeChild` may
+ not behave correctly.
- @property controller
- @type Object
- */
- controller: Ember.computed(function(key, value) {
- var parentView;
+ Calling `remove()` on a child view will remove the view's HTML, but it will
+ remain as part of its container's `childView`s property.
- if (arguments.length === 2) {
- return value;
- } else {
- parentView = get(this, 'parentView');
- return parentView ? get(parentView, 'controller') : null;
- }
- }).property().cacheable(),
+ Calling `removeChild()` on the container will remove the passed view instance
+ from the container's `childView`s but keep its HTML within the container's
+ rendered view.
- /**
- A view may contain a layout. A layout is a regular template but
- supersedes the `template` property during rendering. It is the
- responsibility of the layout template to retrieve the `template`
- property from the view (or alternatively, call `Handlebars.helpers.yield`,
- `{{yield}}`) to render it in the correct location.
+ Calling `removeFromParent()` behaves as expected but should be avoided in
+ favor of direct manipulation of a container's `childViews` property.
- This is useful for a view that has a shared wrapper, but which delegates
- the rendering of the contents of the wrapper to the `template` property
- on a subclass.
+ ```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")
+ })
+ });
- @property layout
- @type Function
- */
- layout: Ember.computed(function(key, value) {
- if (arguments.length === 2) { return value; }
+ aContainer.appendTo('body');
+ ```
- var layoutName = get(this, 'layoutName'),
- layout = this.templateForName(layoutName, 'layout');
+ Results in the HTML
- return layout || get(this, 'defaultLayout');
- }).property('layoutName').cacheable(),
+ ```html
+ <div class="ember-view the-container">
+ <div class="ember-view">A</div>
+ <div class="ember-view">B</div>
+ </div>
+ ```
- templateForName: function(name, type) {
- if (!name) { return; }
+ Calling `aContainer.get('aView').removeFromParent()` will result in the
+ following HTML
- var templates = get(this, 'templates'),
- template = get(templates, name);
+ ```html
+ <div class="ember-view the-container">
+ <div class="ember-view">B</div>
+ </div>
+ ```
- if (!template) {
- throw new Ember.Error(fmt('%@ - Unable to find %@ "%@".', [this, type, name]));
- }
+ And the `Ember.View` instance stored in `aContainer.aView` will be removed from `aContainer`'s
+ `childViews` array.
- return template;
- },
+ ## Templates and Layout
- /**
- The object from which templates should access properties.
+ 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 of its child views.
- This object will be passed to the template function each time the render
- method is called, but it is up to the individual function to decide what
- to do with it.
+ ## Binding a View to Display
- By default, this will be the view itself.
+ If you would like to display a single view in your ContainerView, you can set
+ its `currentView` property. When the `currentView` property is set to a view
+ instance, it will be added to the ContainerView's `childViews` array. If the
+ `currentView` property is later changed to a different view, the new view
+ will replace the old view. If `currentView` is set to `null`, the last
+ `currentView` will be removed.
- @property context
- @type Object
- */
- context: Ember.computed(function(key, value) {
- if (arguments.length === 2) {
- set(this, '_context', value);
- return value;
- } else {
- return get(this, '_context');
- }
- }).volatile(),
+ This functionality is useful for cases where you want to bind the display of
+ a ContainerView to a controller or state manager. For example, you can bind
+ the `currentView` of a container to a controller like this:
- /**
- @private
+ ```javascript
+ App.appController = Ember.Object.create({
+ view: Ember.View.create({
+ templateName: 'person_template'
+ })
+ });
+ ```
- Private copy of the view's template context. This can be set directly
- by Handlebars without triggering the observer that causes the view
- to be re-rendered.
+ ```handlebars
+ {{view Ember.ContainerView currentViewBinding="App.appController.view"}}
+ ```
- The context of a view is looked up as follows:
+ @class ContainerView
+ @namespace Ember
+ @extends Ember.View
+*/
- 1. Supplied context (usually by Handlebars)
- 2. Specified controller
- 3. `parentView`'s context (for a child of a ContainerView)
+Ember.ContainerView = Ember.View.extend({
+ states: states,
- 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.
+ init: function() {
+ this._super();
- @property _context
- */
- _context: Ember.computed(function(key, value) {
- var parentView, controller;
+ var childViews = get(this, 'childViews');
+ Ember.defineProperty(this, 'childViews', childViewsProperty);
- if (arguments.length === 2) {
- return value;
- }
+ var _childViews = this._childViews;
- if (VIEW_PRESERVES_CONTEXT) {
- if (controller = get(this, 'controller')) {
- return controller;
- }
+ forEach(childViews, function(viewName, idx) {
+ var view;
- parentView = get(this, '_parentView');
- if (parentView) {
- return get(parentView, '_context');
+ if ('string' === typeof viewName) {
+ view = get(this, viewName);
+ view = this.createChildView(view);
+ set(this, viewName, view);
+ } else {
+ view = this.createChildView(viewName);
}
- }
- return this;
- }).cacheable(),
+ _childViews[idx] = view;
+ }, this);
- /**
- @private
+ var currentView = get(this, 'currentView');
+ if (currentView) _childViews.push(this.createChildView(currentView));
- If a value that affects template rendering changes, the view should be
- re-rendered to reflect the new value.
+ // Make the _childViews array observable
+ Ember.A(_childViews);
- @method _displayPropertyDidChange
- */
- _displayPropertyDidChange: Ember.observer(function() {
- this.rerender();
- }, 'context', 'controller'),
+ // Sets up an array observer on the child views array. This
+ // observer will detect when child views are added or removed
+ // and update the DOM to reflect the mutation.
+ get(this, 'childViews').addArrayObserver(this, {
+ willChange: 'childViewsWillChange',
+ didChange: 'childViewsDidChange'
+ });
+ },
/**
- 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
- */
- parentView: Ember.computed(function() {
- var parent = get(this, '_parentView');
+ @private
- if (parent && parent.isVirtual) {
- return get(parent, 'parentView');
- } else {
- return parent;
- }
- }).property('_parentView').volatile(),
+ Instructs each child view to render to the passed render buffer.
- _parentView: null,
+ @method render
+ @param {Ember.RenderBuffer} buffer the buffer to render to
+ */
+ render: function(buffer) {
+ this.forEachChildView(function(view) {
+ view.renderToBuffer(buffer);
+ });
+ },
- // return the current view, not including virtual views
- concreteView: Ember.computed(function() {
- if (!this.isVirtual) { return this; }
- else { return get(this, 'parentView'); }
- }).property('_parentView').volatile(),
+ instrumentName: 'render.container',
/**
- If false, the view will appear hidden in DOM.
+ @private
- @property isVisible
- @type Boolean
- @default null
+ When the container view is destroyed, tear down the child views
+ array observer.
+
+ @method willDestroy
*/
- isVisible: true,
+ willDestroy: function() {
+ get(this, 'childViews').removeArrayObserver(this, {
+ willChange: 'childViewsWillChange',
+ didChange: 'childViewsDidChange'
+ });
+
+ this._super();
+ },
/**
@private
- Array of child views. You should never edit this array directly.
- Instead, use appendChild and removeFromParent.
+ When a child view is removed, destroy its element so that
+ it is removed from the DOM.
- @property childViews
- @type Array
- @default []
- */
- childViews: childViewsProperty,
+ The array observer that triggers this action is set up in the
+ `renderToBuffer` method.
- _childViews: [],
+ @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
+ **/
+ childViewsWillChange: function(views, start, removed) {
+ if (removed === 0) { return; }
- // 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');
- if (parentView) { Ember.propertyWillChange(parentView, 'childViews'); }
- }
- }, 'childViews'),
+ var changedViews = views.slice(start, start+removed);
+ this.initializeViews(changedViews, null, null);
- // 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');
- if (parentView) { Ember.propertyDidChange(parentView, 'childViews'); }
- }
- }, 'childViews'),
+ this.currentState.childViewsWillChange(this, views, start, removed);
+ },
/**
- Return the nearest ancestor that is an instance of the provided
- class.
+ @private
- @property nearestInstanceOf
- @param {Class} klass Subclass of Ember.View (or Ember.View itself)
- @return Ember.View
+ 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
+ create an element and insert it into the DOM. If the enclosing container
+ view has already written to a buffer, but not yet converted that buffer
+ into an element, we insert the string representation of the child into the
+ appropriate place in the buffer.
+
+ @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
+ @param {Number} the number of child views added
*/
- nearestInstanceOf: function(klass) {
- var view = get(this, 'parentView');
+ childViewsDidChange: function(views, start, removed, added) {
+ var len = get(views, 'length');
- while (view) {
- if(view instanceof klass) { return view; }
- view = get(view, 'parentView');
- }
- },
+ // No new child views were added; bail out.
+ if (added === 0) return;
- /**
- Return the nearest ancestor that has a given property.
+ var changedViews = views.slice(start, start+added);
+ this.initializeViews(changedViews, this, get(this, 'templateData'));
- @property nearestWithProperty
- @param {String} property A property name
- @return Ember.View
- */
- nearestWithProperty: function(property) {
- var view = get(this, 'parentView');
+ // Let the current state handle the changes
+ this.currentState.childViewsDidChange(this, views, start, added);
+ },
- while (view) {
- if (property in view) { return view; }
- view = get(view, 'parentView');
- }
+ initializeViews: function(views, parentView, templateData) {
+ forEach(views, function(view) {
+ set(view, '_parentView', parentView);
+
+ if (!get(view, 'templateData')) {
+ set(view, 'templateData', templateData);
+ }
+ });
},
- /**
- Return the nearest ancestor whose parent is an instance of
- `klass`.
+ currentView: null,
- @property nearestChildOf
- @param {Class} klass Subclass of Ember.View (or Ember.View itself)
- @return Ember.View
- */
- nearestChildOf: function(klass) {
- var view = get(this, 'parentView');
+ _currentViewWillChange: Ember.beforeObserver(function() {
+ var childViews = get(this, 'childViews'),
+ currentView = get(this, 'currentView');
- while (view) {
- if(get(view, 'parentView') instanceof klass) { return view; }
- view = get(view, 'parentView');
+ if (currentView) {
+ currentView.destroy();
+ childViews.removeObject(currentView);
}
- },
+ }, 'currentView'),
- /**
- Return the nearest ancestor that is an Ember.CollectionView
+ _currentViewDidChange: Ember.observer(function() {
+ var childViews = get(this, 'childViews'),
+ currentView = get(this, 'currentView');
- @property collectionView
- @return Ember.CollectionView
- */
- collectionView: Ember.computed(function() {
- return this.nearestInstanceOf(Ember.CollectionView);
- }).cacheable(),
+ if (currentView) {
+ childViews.pushObject(currentView);
+ }
+ }, 'currentView'),
- /**
- Return the nearest ancestor that is a direct child of
- an Ember.CollectionView
+ _ensureChildrenAreInDOM: function () {
+ this.currentState.ensureChildrenAreInDOM(this);
+ }
+});
- @property itemView
- @return Ember.View
- */
- itemView: Ember.computed(function() {
- return this.nearestChildOf(Ember.CollectionView);
- }).cacheable(),
+Ember.merge(states._default, {
+ childViewsWillChange: Ember.K,
+ childViewsDidChange: Ember.K,
+ ensureChildrenAreInDOM: Ember.K
+});
- /**
- Return the nearest ancestor that has the property
- `content`.
+Ember.merge(states.inBuffer, {
+ childViewsDidChange: function(parentView, views, start, added) {
+ throw new Error('You cannot modify child views while in the inBuffer state');
+ }
+});
- @property contentView
- @return Ember.View
- */
- contentView: Ember.computed(function() {
- return this.nearestWithProperty('content');
- }).cacheable(),
+Ember.merge(states.hasElement, {
+ childViewsWillChange: function(view, views, start, removed) {
+ for (var i=start; i<start+removed; i++) {
+ views[i].remove();
+ }
+ },
- /**
- @private
+ childViewsDidChange: function(view, views, start, added) {
+ Ember.run.scheduleOnce('render', view, '_ensureChildrenAreInDOM');
+ },
- When the parent view changes, recursively invalidate
- collectionView, itemView, and contentView
+ ensureChildrenAreInDOM: function(view) {
+ var childViews = view.get('childViews'), i, len, childView, previous, buffer;
+ for (i = 0, len = childViews.length; i < len; i++) {
+ childView = childViews[i];
+ buffer = childView.renderToBufferIfNeeded();
+ if (buffer) {
+ childView.triggerRecursively('willInsertElement');
+ if (previous) {
+ previous.domManager.after(previous, buffer.string());
+ } else {
+ view.domManager.prepend(view, buffer.string());
+ }
+ childView.transitionTo('inDOM');
+ childView.propertyDidChange('element');
+ childView.triggerRecursively('didInsertElement');
+ }
+ previous = childView;
+ }
+ }
+});
- @method _parentViewDidChange
- */
- _parentViewDidChange: Ember.observer(function() {
- if (this.isDestroying) { return; }
+})();
- this.invokeRecursively(function(view) {
- view.propertyDidChange('collectionView');
- view.propertyDidChange('itemView');
- view.propertyDidChange('contentView');
- });
- if (get(this, 'parentView.controller') && !get(this, 'controller')) {
- this.notifyPropertyChange('controller');
- }
- }, '_parentView'),
- _controllerDidChange: Ember.observer(function() {
- if (this.isDestroying) { return; }
+(function() {
+/**
+@module ember
+@submodule ember-views
+*/
- this.forEachChildView(function(view) {
- view.propertyDidChange('controller');
- });
- }, 'controller'),
+var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
- cloneKeywords: function() {
- var templateData = get(this, 'templateData');
+/**
+ `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 views and their associated rendered HTML are updated when items in
+ the array are added, removed, or replaced.
- var keywords = templateData ? Ember.copy(templateData.keywords) : {};
- set(keywords, 'view', get(this, 'concreteView'));
- set(keywords, 'controller', get(this, 'controller'));
+ ## Setting content
- return keywords;
- },
+ The managed collection of objects is referenced as the `Ember.CollectionView`
+ instance's `content` property.
- /**
- Called on your view when it should push strings of HTML into a
- Ember.RenderBuffer. Most users will want to override the `template`
- or `templateName` properties instead of this method.
+ ```javascript
+ someItemsView = Ember.CollectionView.create({
+ content: ['A', 'B','C']
+ })
+ ```
- By default, Ember.View will look for a function in the `template`
- property and invoke it with the value of `context`. The value of
- `context` will be the view's controller unless you override it.
+ The view for each item in the collection will have its `content` property set
+ to the item.
- @method render
- @param {Ember.RenderBuffer} buffer The render buffer
- */
- render: function(buffer) {
- // If this view has a layout, it is the responsibility of the
- // the layout to render the view's template. Otherwise, render the template
- // directly.
- var template = get(this, 'layout') || get(this, 'template');
+ ## Specifying itemViewClass
- if (template) {
- var context = get(this, 'context');
- var keywords = this.cloneKeywords();
+ By default the view class for each item in the managed collection will be an
+ instance of `Ember.View`. You can supply a different class by setting the
+ `CollectionView`'s `itemViewClass` property.
- var data = {
- view: this,
- buffer: buffer,
- isRenderData: true,
- keywords: keywords
- };
+ Given an empty `<body>` and the following code:
- // Invoke the template with the provided template context, which
- // is the view by default. A hash of data is also passed that provides
- // the template with access to the view and render buffer.
+ ```javascript
+ someItemsView = Ember.CollectionView.create({
+ classNames: ['a-collection'],
+ content: ['A','B','C'],
+ itemViewClass: Ember.View.extend({
+ template: Ember.Handlebars.compile("the letter: {{view.content}}")
+ })
+ });
- Ember.assert('template must be a function. Did you mean to call Ember.Handlebars.compile("...") or specify templateName instead?', typeof template === 'function');
- // The template should write directly to the render buffer instead
- // of returning a string.
- var output = template(context, { data: data });
+ someItemsView.appendTo('body');
+ ```
- // If the template returned a string instead of writing to the buffer,
- // push the string onto the buffer.
- if (output !== undefined) { buffer.push(output); }
- }
- },
+ Will result in the following HTML structure
+
+ ```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>
+ ```
- invokeForState: function(name) {
- var stateName = this.state, args, fn;
+ ## Automatic matching of parent/child tagNames
- // try to find the function for the state in the cache
- if (fn = invokeForState[stateName][name]) {
- args = a_slice.call(arguments);
- args[0] = this;
+ Setting the `tagName` property of a `CollectionView` to any of
+ "ul", "ol", "table", "thead", "tbody", "tfoot", "tr", or "select" will result
+ in the item views receiving an appropriately matched `tagName` property.
- return fn.apply(this, args);
- }
+ Given an empty `<body>` and the following code:
+
+ ```javascript
+ anUndorderedListView = Ember.CollectionView.create({
+ tagName: 'ul',
+ content: ['A','B','C'],
+ itemViewClass: Ember.View.extend({
+ template: Ember.Handlebars.compile("the letter: {{view.content}}")
+ })
+ });
- // otherwise, find and cache the function for this state
- var parent = this, states = parent.states, state;
+ anUndorderedListView.appendTo('body');
+ ```
- while (states) {
- state = states[stateName];
+ Will result in the following HTML structure
- while (state) {
- fn = state[name];
+ ```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>
+ ```
- if (fn) {
- invokeForState[stateName][name] = fn;
+ Additional `tagName` pairs can be provided by adding to
+ `Ember.CollectionView.CONTAINER_MAP `
- args = a_slice.call(arguments, 1);
- args.unshift(this);
+ ```javascript
+ Ember.CollectionView.CONTAINER_MAP['article'] = 'section'
+ ```
- return fn.apply(this, args);
- }
+ ## Programatic creation of child views
- state = state.parentState;
- }
+ For cases where additional customization beyond the use of a single
+ `itemViewClass` or `tagName` matching is required CollectionView's
+ `createChildView` method can be overidden:
- states = states.parent;
+ ```javascript
+ CustomCollectionView = Ember.CollectionView.extend({
+ createChildView: function(viewClass, attrs) {
+ if (attrs.content.kind == 'album') {
+ viewClass = App.AlbumView;
+ } else {
+ viewClass = App.SongView;
+ }
+ this._super(viewClass, attrs);
}
- },
+ });
+ ```
- /**
- Renders the view again. This will work regardless of whether the
- view is already in the DOM or not. If the view is in the DOM, the
- rendering process will be deferred to give bindings a chance
- to synchronize.
+ ## Empty View
- If children were added during the rendering process using `appendChild`,
- `rerender` will remove them, because they will be added again
- if needed by the next `render`.
+ You can provide an `Ember.View` subclass to the `Ember.CollectionView`
+ instance as its `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.
- 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.
+ ```javascript
+ aListWithNothing = Ember.CollectionView.create({
+ classNames: ['nothing']
+ content: null,
+ emptyView: Ember.View.extend({
+ template: Ember.Handlebars.compile("The collection is empty")
+ })
+ });
- @method rerender
- */
- rerender: function() {
- return this.invokeForState('rerender');
- },
+ aListWithNothing.appendTo('body');
+ ```
- clearRenderedChildren: function() {
- var lengthBefore = this.lengthBeforeRender,
- lengthAfter = this.lengthAfterRender;
+ Will result in the following HTML structure
- // If there were child views created during the last call to render(),
- // remove them under the assumption that they will be re-created when
- // we re-render.
+ ```html
+ <div class="ember-view nothing">
+ <div class="ember-view">
+ The collection is empty
+ </div>
+ </div>
+ ```
- // VIEW-TODO: Unit test this path.
- var childViews = this._childViews;
- for (var i=lengthAfter-1; i>=lengthBefore; i--) {
- if (childViews[i]) { childViews[i].destroy(); }
- }
- },
+ ## Adding and Removing items
- /**
- @private
+ The `childViews` property of a `CollectionView` should not be directly
+ manipulated. Instead, add, remove, replace items from its `content` property.
+ This will trigger appropriate changes to its rendered HTML.
- Iterates over the view's `classNameBindings` array, inserts the value
- 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.
+ ## Use in templates via the `{{collection}}` `Ember.Handlebars` helper
- @method _applyClassNameBindings
- */
- _applyClassNameBindings: function() {
- var classBindings = get(this, 'classNameBindings'),
- classNames = get(this, 'classNames'),
- elem, newClass, dasherizedClass;
+ `Ember.Handlebars` provides a helper specifically for adding
+ `CollectionView`s to templates. See `Ember.Handlebars.collection` for more
+ details
- if (!classBindings) { return; }
+ @class CollectionView
+ @namespace Ember
+ @extends Ember.ContainerView
+ @since Ember 0.9
+*/
+Ember.CollectionView = Ember.ContainerView.extend(
+/** @scope Ember.CollectionView.prototype */ {
- // Loop through all of the configured bindings. These will be either
- // property names ('isUrgent') or property paths relative to the view
- // ('content.isUrgent')
- a_forEach(classBindings, function(binding) {
+ /**
+ A list of items to be displayed by the `Ember.CollectionView`.
- // Variable in which the old class value is saved. The observer function
- // 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);
+ @property content
+ @type Ember.Array
+ @default null
+ */
+ content: null,
- // Set up an observer on the context. If the property changes, toggle the
- // class name.
- var observer = function() {
- // Get the current value of the property
- newClass = this._classStringForProperty(binding);
- elem = this.$();
- if (!elem) {
- removeObserver(this, parsedPath.path, observer);
- return;
- }
+ /**
+ @private
- // If we had previously added a class to the element, remove it.
- if (oldClass) {
- elem.removeClass(oldClass);
- // Also remove from classNames so that if the view gets rerendered,
- // the class doesn't get added back to the DOM.
- classNames.removeObject(oldClass);
- }
+ This provides metadata about what kind of empty view class this
+ collection would like if it is being instantiated from another
+ system (like Handlebars)
- // If necessary, add a new class. Make sure we keep track of it so
- // it can be removed in the future.
- if (newClass) {
- elem.addClass(newClass);
- oldClass = newClass;
- } else {
- oldClass = null;
- }
- };
+ @property emptyViewClass
+ */
+ emptyViewClass: Ember.View,
- // Get the class name for the property at its current value
- dasherizedClass = this._classStringForProperty(binding);
+ /**
+ An optional view to display if content is set to an empty array.
- if (dasherizedClass) {
- // Ensure that it gets into the classNames array
- // so it is displayed when we render.
- classNames.push(dasherizedClass);
+ @property emptyView
+ @type Ember.View
+ @default null
+ */
+ emptyView: null,
- // Save a reference to the class name so we can remove it
- // if the observer fires. Remember that this variable has
- // been closed over by the observer.
- oldClass = dasherizedClass;
- }
+ /**
+ @property itemViewClass
+ @type Ember.View
+ @default Ember.View
+ */
+ itemViewClass: Ember.View,
- addObserver(this, parsedPath.path, observer);
- }, this);
+ init: function() {
+ var ret = this._super();
+ this._contentDidChange();
+ return ret;
},
+ _contentWillChange: Ember.beforeObserver(function() {
+ var content = this.get('content');
+
+ if (content) { content.removeArrayObserver(this); }
+ var len = content ? get(content, 'length') : 0;
+ this.arrayWillChange(content, 0, len);
+ }, 'content'),
+
/**
@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.
+ Check to make sure that the content has changed, and if so,
+ update the children directly. This is always scheduled
+ asynchronously, to allow the element to be created before
+ bindings have synchronized and vice versa.
- @method _applyAttributeBindings
- @param {Ember.RenderBuffer} buffer
+ @method _contentDidChange
*/
- _applyAttributeBindings: function(buffer) {
- var attributeBindings = get(this, 'attributeBindings'),
- attributeValue, elem, type;
+ _contentDidChange: Ember.observer(function() {
+ var content = get(this, 'content');
- if (!attributeBindings) { return; }
+ if (content) {
+ Ember.assert(fmt("an Ember.CollectionView's content must implement Ember.Array. You passed %@", [content]), Ember.Array.detect(content));
+ content.addArrayObserver(this);
+ }
- a_forEach(attributeBindings, function(binding) {
- var split = binding.split(':'),
- property = split[0],
- attributeName = split[1] || property;
+ var len = content ? get(content, 'length') : 0;
+ this.arrayDidChange(content, 0, null, len);
+ }, 'content'),
- // Create an observer to add/remove/change the attribute if the
- // JavaScript property changes.
- var observer = function() {
- elem = this.$();
- if (!elem) { return; }
+ willDestroy: function() {
+ var content = get(this, 'content');
+ if (content) { content.removeArrayObserver(this); }
- attributeValue = get(this, property);
+ this._super();
+ },
- Ember.View.applyAttributeBindings(elem, attributeName, attributeValue);
- };
+ arrayWillChange: function(content, start, removedCount) {
+ // If the contents were empty before and this template collection has an
+ // empty view remove it now.
+ var emptyView = get(this, 'emptyView');
+ if (emptyView && emptyView instanceof Ember.View) {
+ emptyView.removeFromParent();
+ }
- addObserver(this, property, observer);
+ // Loop through child views that correspond with the removed items.
+ // Note that we loop from the end of the array to the beginning because
+ // we are mutating it as we go.
+ var childViews = get(this, 'childViews'), childView, idx, len;
- // Determine the current value and add it to the render buffer
- // if necessary.
- attributeValue = get(this, property);
- Ember.View.applyAttributeBindings(buffer, attributeName, attributeValue);
- }, this);
+ len = get(childViews, 'length');
+
+ var removingAll = removedCount === len;
+
+ if (removingAll) {
+ this.currentState.empty(this);
+ }
+
+ for (idx = start + removedCount - 1; idx >= start; idx--) {
+ childView = childViews[idx];
+ if (removingAll) { childView.removedFromDOM = true; }
+ childView.destroy();
+ }
},
/**
- @private
+ Called when a mutation to the underlying content array occurs.
- Given a property name, returns a dasherized version of that
- property name if the property evaluates to a non-falsy value.
+ This method will replay that mutation against the views that compose the
+ `Ember.CollectionView`, ensuring that the view reflects the model.
- For example, if the view has property `isUrgent` that evaluates to true,
- passing `isUrgent` to this method will return `"is-urgent"`.
+ This array observer is added in `contentDidChange`.
- @method _classStringForProperty
- @param property
+ @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
*/
- _classStringForProperty: function(property) {
- var parsedPath = Ember.View._parsePropertyPath(property);
- var path = parsedPath.path;
+ arrayDidChange: function(content, start, removed, added) {
+ var itemViewClass = get(this, 'itemViewClass'),
+ childViews = get(this, 'childViews'),
+ addedViews = [], view, item, idx, len, itemTagName;
- var val = get(this, path);
- if (val === undefined && Ember.isGlobalPath(path)) {
- val = get(window, path);
+ if ('string' === typeof itemViewClass) {
+ itemViewClass = get(itemViewClass);
}
- return Ember.View._classStringForValue(path, val, parsedPath.className, parsedPath.falsyClassName);
- },
+ Ember.assert(fmt("itemViewClass must be a subclass of Ember.View, not %@", [itemViewClass]), Ember.View.detect(itemViewClass));
- // ..........................................................
- // ELEMENT SUPPORT
- //
+ len = content ? get(content, 'length') : 0;
+ if (len) {
+ for (idx = start; idx < start+added; idx++) {
+ item = content.objectAt(idx);
- /**
- Returns the current DOM element for the view.
+ view = this.createChildView(itemViewClass, {
+ content: item,
+ contentIndex: idx
+ });
- @property element
- @type DOMElement
- */
- element: Ember.computed(function(key, value) {
- if (value !== undefined) {
- return this.invokeForState('setElement', value);
+ addedViews.push(view);
+ }
} else {
- return this.invokeForState('getElement');
+ var emptyView = get(this, 'emptyView');
+ if (!emptyView) { return; }
+
+ emptyView = this.createChildView(emptyView);
+ addedViews.push(emptyView);
+ set(this, 'emptyView', emptyView);
}
- }).property('_parentView').cacheable(),
+ childViews.replace(start, 0, addedViews);
+ },
- /**
- Returns a jQuery object for this view's element. If you pass in a selector
- string, this method will return a jQuery object, using the current element
- as its buffer.
+ createChildView: function(view, attrs) {
+ view = this._super(view, attrs);
- For example, calling `view.$('li')` will return a jQuery object containing
- all of the `li` elements inside the DOM element of this view.
+ var itemTagName = get(view, 'tagName');
+ var tagName = (itemTagName === null || itemTagName === undefined) ? Ember.CollectionView.CONTAINER_MAP[get(this, 'tagName')] : itemTagName;
- @property $
- @param {String} [selector] a jQuery-compatible selector string
- @return {jQuery} the CoreQuery object for the DOM node
- */
- $: function(sel) {
- return this.invokeForState('$', sel);
- },
+ set(view, 'tagName', tagName);
- mutateChildViews: function(callback) {
- var childViews = this._childViews,
- idx = childViews.length,
- view;
+ return view;
+ }
+});
- while(--idx >= 0) {
- view = childViews[idx];
- callback.call(this, view, idx);
- }
+/**
+ 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.
- return this;
- },
+ @property CONTAINER_MAP
+ @type Hash
+ @static
+ @final
+*/
+Ember.CollectionView.CONTAINER_MAP = {
+ ul: 'li',
+ ol: 'li',
+ table: 'tr',
+ thead: 'tr',
+ tbody: 'tr',
+ tfoot: 'tr',
+ tr: 'td',
+ select: 'option'
+};
- forEachChildView: function(callback) {
- var childViews = this._childViews;
+})();
- if (!childViews) { return this; }
- var len = childViews.length,
- view, idx;
- for(idx = 0; idx < len; idx++) {
- view = childViews[idx];
- callback.call(this, view);
- }
+(function() {
- return this;
- },
+})();
- /**
- Appends the view's element to the specified parent element.
- If the view does not have an HTML representation yet, `createElement()`
- will be called automatically.
- Note that this method just schedules the view to be appended; the DOM
- element will not be appended to the given element until all bindings have
- finished synchronizing.
+(function() {
+/*globals jQuery*/
+/**
+Ember Views
- This is not typically a function that you will need to call directly
- when building your application. You might consider using Ember.ContainerView
- instead. If you do need to use appendTo, be sure that the target element you
- are providing is associated with an Ember.Application and does not have an
- ancestor element that is associated with an Ember view.
+@module ember
+@submodule ember-views
+@requires ember-runtime
+@main ember-views
+*/
- @method appendTo
- @param {String|DOMElement|jQuery} A selector, element, HTML string, or jQuery object
- @return {Ember.View} receiver
- */
- appendTo: function(target) {
- // Schedule the DOM element to be created and appended to the given
- // element after bindings have synchronized.
- this._insertElementLater(function() {
- Ember.assert("You cannot append to an existing Ember.View. Consider using Ember.ContainerView instead.", !Ember.$(target).is('.ember-view') && !Ember.$(target).parents().is('.ember-view'));
- this.$().appendTo(target);
- });
+})();
- return this;
- },
+(function() {
+define("metamorph",
+ [],
+ function() {
+ "use strict";
+ // ==========================================================================
+ // Project: metamorph
+ // Copyright: ©2011 My Company Inc. All rights reserved.
+ // ==========================================================================
+
+ var K = function(){},
+ guid = 0,
+ document = window.document,
+
+ // Feature-detect the W3C range API, the extended check is for IE9 which only partially supports ranges
+ supportsRange = ('createRange' in document) && (typeof Range !== 'undefined') && Range.prototype.createContextualFragment,
+
+ // Internet Explorer prior to 9 does not allow setting innerHTML if the first element
+ // is a "zero-scope" element. This problem can be worked around by making
+ // the first node an invisible text node. We, like Modernizr, use ­
+ needsShy = (function(){
+ var testEl = document.createElement('div');
+ testEl.innerHTML = "<div></div>";
+ testEl.firstChild.innerHTML = "<script></script>";
+ return testEl.firstChild.innerHTML === '';
+ })(),
+
+
+ // IE 8 (and likely earlier) likes to move whitespace preceeding
+ // a script tag to appear after it. This means that we can
+ // accidentally remove whitespace when updating a morph.
+ movesWhitespace = (function() {
+ var testEl = document.createElement('div');
+ testEl.innerHTML = "Test: <script type='text/x-placeholder'></script>Value";
+ return testEl.childNodes[0].nodeValue === 'Test:' &&
+ testEl.childNodes[2].nodeValue === ' Value';
+ })();
+
+ // Constructor that supports either Metamorph('foo') or new
+ // Metamorph('foo');
+ //
+ // Takes a string of HTML as the argument.
- /**
- Replaces the content of the specified parent element with this view's element.
- If the view does not have an HTML representation yet, `createElement()`
- will be called automatically.
+ var Metamorph = function(html) {
+ var self;
- Note that this method just schedules the view to be appended; the DOM
- element will not be appended to the given element until all bindings have
- finished synchronizing
+ if (this instanceof Metamorph) {
+ self = this;
+ } else {
+ self = new K();
+ }
- @method replaceIn
- @param {String|DOMElement|jQuery} A selector, element, HTML string, or jQuery object
- @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'));
+ self.innerHTML = html;
+ var myGuid = 'metamorph-'+(guid++);
+ self.start = myGuid + '-start';
+ self.end = myGuid + '-end';
- this._insertElementLater(function() {
- Ember.$(target).empty();
- this.$().appendTo(target);
- });
+ return self;
+ };
- return this;
- },
+ K.prototype = Metamorph.prototype;
- /**
- @private
+ var rangeFor, htmlFunc, removeFunc, outerHTMLFunc, appendToFunc, afterFunc, prependFunc, startTagFunc, endTagFunc;
- Schedules a DOM operation to occur during the next render phase. This
- ensures that all bindings have finished synchronizing before the view is
- rendered.
+ outerHTMLFunc = function() {
+ return this.startTag() + this.innerHTML + this.endTag();
+ };
- To use, pass a function that performs a DOM operation..
+ startTagFunc = function() {
+ /*
+ * We replace chevron by its hex code in order to prevent escaping problems.
+ * Check this thread for more explaination:
+ * http://stackoverflow.com/questions/8231048/why-use-x3c-instead-of-when-generating-html-from-javascript
+ */
+ return "<script id='" + this.start + "' type='text/x-placeholder'>\x3C/script>";
+ };
- Before your function is called, this view and all child views will receive
- the `willInsertElement` event. After your function is invoked, this view
- and all of its child views will receive the `didInsertElement` event.
+ endTagFunc = function() {
+ /*
+ * We replace chevron by its hex code in order to prevent escaping problems.
+ * Check this thread for more explaination:
+ * http://stackoverflow.com/questions/8231048/why-use-x3c-instead-of-when-generating-html-from-javascript
+ */
+ return "<script id='" + this.end + "' type='text/x-placeholder'>\x3C/script>";
+ };
+
+ // If we have the W3C range API, this process is relatively straight forward.
+ if (supportsRange) {
- view._insertElementLater(function() {
- this.createElement();
- this.$().appendTo('body');
- });
+ // Get a range for the current morph. Optionally include the starting and
+ // ending placeholders.
+ rangeFor = function(morph, outerToo) {
+ var range = document.createRange();
+ var before = document.getElementById(morph.start);
+ var after = document.getElementById(morph.end);
- @method _insertElementLater
- @param {Function} fn the function that inserts the element into the DOM
- */
- _insertElementLater: function(fn) {
- this._scheduledInsert = Ember.run.scheduleOnce('render', this, '_insertElement', fn);
- },
+ if (outerToo) {
+ range.setStartBefore(before);
+ range.setEndAfter(after);
+ } else {
+ range.setStartAfter(before);
+ range.setEndBefore(after);
+ }
- /**
- @private
- */
- _insertElement: function (fn) {
- this._scheduledInsert = null;
- this.invokeForState('insertElement', fn);
- },
+ return range;
+ };
- /**
- Appends the view's element to the document body. If the view does
- not have an HTML representation yet, `createElement()` will be called
- automatically.
+ htmlFunc = function(html, outerToo) {
+ // get a range for the current metamorph object
+ var range = rangeFor(this, outerToo);
- Note that this method just schedules the view to be appended; the DOM
- element will not be appended to the document body until all bindings have
- finished synchronizing.
+ // delete the contents of the range, which will be the
+ // nodes between the starting and ending placeholder.
+ range.deleteContents();
- @method append
- @return {Ember.View} receiver
- */
- append: function() {
- return this.appendTo(document.body);
- },
+ // create a new document fragment for the HTML
+ var fragment = range.createContextualFragment(html);
- /**
- Removes the view's element from the element to which it is attached.
+ // insert the fragment into the range
+ range.insertNode(fragment);
+ };
- @method remove
- @return {Ember.View} receiver
- */
- remove: function() {
- // What we should really do here is wait until the end of the run loop
- // to determine if the element has been re-appended to a different
- // element.
- // In the interim, we will just re-render if that happens. It is more
- // important than elements get garbage collected.
- this.destroyElement();
- this.invokeRecursively(function(view) {
- view.clearRenderedChildren();
- });
- },
+ removeFunc = function() {
+ // get a range for the current metamorph object including
+ // the starting and ending placeholders.
+ var range = rangeFor(this, true);
- /**
- The ID to use when trying to locate the element in the DOM. If you do not
- 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.
+ // delete the entire range.
+ range.deleteContents();
+ };
- @property elementId
- @type String
- */
- elementId: Ember.computed(function(key, value) {
- return value !== undefined ? value : Ember.guidFor(this);
- }).cacheable(),
+ appendToFunc = function(node) {
+ var range = document.createRange();
+ range.setStart(node);
+ range.collapse(false);
+ var frag = range.createContextualFragment(this.outerHTML());
+ node.appendChild(frag);
+ };
- // 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'),
+ afterFunc = function(html) {
+ var range = document.createRange();
+ var after = document.getElementById(this.end);
- /**
- Attempts to discover the element in the parent element. The default
- implementation looks for an element with an ID of elementId (or the view's
- guid if elementId is null). You can override this method to provide your
- own form of lookup. For example, if you want to discover your element
- using a CSS class name instead of an ID.
+ range.setStartAfter(after);
+ range.setEndAfter(after);
- @method findElementInParentElement
- @param {DOMElement} parentElement The parent's DOM element
- @return {DOMElement} The discovered element
- */
- findElementInParentElement: function(parentElem) {
- var id = "#" + get(this, 'elementId');
- return Ember.$(id)[0] || Ember.$(id, parentElem)[0];
- },
+ var fragment = range.createContextualFragment(html);
+ range.insertNode(fragment);
+ };
- /**
- Creates a new renderBuffer with the passed tagName. You can override this
- method to provide further customization to the buffer if needed. Normally
- you will not need to call or override this method.
+ prependFunc = function(html) {
+ var range = document.createRange();
+ var start = document.getElementById(this.start);
- @method renderBuffer
- @param [tagName] {String}
- @return {Ember.RenderBuffer}
- */
- renderBuffer: function(tagName) {
- tagName = tagName || get(this, 'tagName');
+ range.setStartAfter(start);
+ range.setEndAfter(start);
- // Explicitly check for null or undefined, as tagName
- // may be an empty string, which would evaluate to false.
- if (tagName === null || tagName === undefined) {
- tagName = 'div';
- }
+ var fragment = range.createContextualFragment(html);
+ range.insertNode(fragment);
+ };
- return Ember.RenderBuffer(tagName);
- },
+ } else {
+ /**
+ * This code is mostly taken from jQuery, with one exception. In jQuery's case, we
+ * have some HTML and we need to figure out how to convert it into some nodes.
+ *
+ * In this case, jQuery needs to scan the HTML looking for an opening tag and use
+ * that as the key for the wrap map. In our case, we know the parent node, and
+ * can use its type as the key for the wrap map.
+ **/
+ var wrapMap = {
+ select: [ 1, "<select multiple='multiple'>", "</select>" ],
+ fieldset: [ 1, "<fieldset>", "</fieldset>" ],
+ table: [ 1, "<table>", "</table>" ],
+ tbody: [ 2, "<table><tbody>", "</tbody></table>" ],
+ tr: [ 3, "<table><tbody><tr>", "</tr></tbody></table>" ],
+ colgroup: [ 2, "<table><tbody></tbody><colgroup>", "</colgroup></table>" ],
+ map: [ 1, "<map>", "</map>" ],
+ _default: [ 0, "", "" ]
+ };
- /**
- Creates a DOM representation of the view and all of its
- child views by recursively calling the `render()` method.
+ var findChildById = function(element, id) {
+ if (element.getAttribute('id') === id) { return element; }
- After the element has been created, `didInsertElement` will
- be called on this view and all of its child views.
+ var len = element.childNodes.length, idx, node, found;
+ for (idx=0; idx<len; idx++) {
+ node = element.childNodes[idx];
+ found = node.nodeType === 1 && findChildById(node, id);
+ if (found) { return found; }
+ }
+ };
- @method createElement
- @return {Ember.View} receiver
- */
- createElement: function() {
- if (get(this, 'element')) { return this; }
+ var setInnerHTML = function(element, html) {
+ var matches = [];
+ if (movesWhitespace) {
+ // Right now we only check for script tags with ids with the
+ // goal of targeting morphs.
+ html = html.replace(/(\s+)(<script id='([^']+)')/g, function(match, spaces, tag, id) {
+ matches.push([id, spaces]);
+ return tag;
+ });
+ }
- var buffer = this.renderToBuffer();
- set(this, 'element', buffer.element());
+ element.innerHTML = html;
- return this;
- },
+ // If we have to do any whitespace adjustments do them now
+ if (matches.length > 0) {
+ var len = matches.length, idx;
+ for (idx=0; idx<len; idx++) {
+ var script = findChildById(element, matches[idx][0]),
+ node = document.createTextNode(matches[idx][1]);
+ script.parentNode.insertBefore(node, script);
+ }
+ }
+ };
- /**
- Called when a view is going to insert an element into the DOM.
+ /**
+ * Given a parent node and some HTML, generate a set of nodes. Return the first
+ * node, which will allow us to traverse the rest using nextSibling.
+ *
+ * We need to do this because innerHTML in IE does not really parse the nodes.
+ **/
+ var firstNodeFor = function(parentNode, html) {
+ var arr = wrapMap[parentNode.tagName.toLowerCase()] || wrapMap._default;
+ var depth = arr[0], start = arr[1], end = arr[2];
- @event willInsertElement
- */
- willInsertElement: Ember.K,
+ if (needsShy) { html = '­'+html; }
- /**
- 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.
+ var element = document.createElement('div');
- @event didInsertElement
- */
- didInsertElement: Ember.K,
+ setInnerHTML(element, start + html + end);
- /**
- 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
+ for (var i=0; i<=depth; i++) {
+ element = element.firstChild;
+ }
- @event willRerender
- */
- willRerender: Ember.K,
+ // Look for ­ to remove it.
+ if (needsShy) {
+ var shyElement = element;
- /**
- @private
+ // Sometimes we get nameless elements with the shy inside
+ while (shyElement.nodeType === 1 && !shyElement.nodeName) {
+ shyElement = shyElement.firstChild;
+ }
- Run this callback on the current view and recursively on child views.
+ // At this point it's the actual unicode character.
+ if (shyElement.nodeType === 3 && shyElement.nodeValue.charAt(0) === "\u00AD") {
+ shyElement.nodeValue = shyElement.nodeValue.slice(1);
+ }
+ }
- @method invokeRecursively
- @param fn {Function}
- */
- invokeRecursively: function(fn) {
- fn.call(this, this);
+ return element;
+ };
- this.forEachChildView(function(view) {
- view.invokeRecursively(fn);
- });
- },
+ /**
+ * In some cases, Internet Explorer can create an anonymous node in
+ * the hierarchy with no tagName. You can create this scenario via:
+ *
+ * div = document.createElement("div");
+ * div.innerHTML = "<table>­<script></script><tr><td>hi</td></tr></table>";
+ * div.firstChild.firstChild.tagName //=> ""
+ *
+ * If our script markers are inside such a node, we need to find that
+ * node and use *it* as the marker.
+ **/
+ var realNode = function(start) {
+ while (start.parentNode.tagName === "") {
+ start = start.parentNode;
+ }
- /**
- Invalidates the cache for a property on all child views.
+ return start;
+ };
- @method invalidateRecursively
- */
- invalidateRecursively: function(key) {
- this.forEachChildView(function(view) {
- view.propertyDidChange(key);
- });
- },
+ /**
+ * When automatically adding a tbody, Internet Explorer inserts the
+ * tbody immediately before the first <tr>. Other browsers create it
+ * before the first node, no matter what.
+ *
+ * This means the the following code:
+ *
+ * div = document.createElement("div");
+ * div.innerHTML = "<table><script id='first'></script><tr><td>hi</td></tr><script id='last'></script></table>
+ *
+ * Generates the following DOM in IE:
+ *
+ * + div
+ * + table
+ * - script id='first'
+ * + tbody
+ * + tr
+ * + td
+ * - "hi"
+ * - script id='last'
+ *
+ * Which means that the two script tags, even though they were
+ * inserted at the same point in the hierarchy in the original
+ * HTML, now have different parents.
+ *
+ * This code reparents the first script tag by making it the tbody's
+ * first child.
+ **/
+ var fixParentage = function(start, end) {
+ if (start.parentNode !== end.parentNode) {
+ end.parentNode.insertBefore(start, end.parentNode.firstChild);
+ }
+ };
- /**
- @private
+ htmlFunc = function(html, outerToo) {
+ // get the real starting node. see realNode for details.
+ var start = realNode(document.getElementById(this.start));
+ var end = document.getElementById(this.end);
+ var parentNode = end.parentNode;
+ var node, nextSibling, last;
+
+ // make sure that the start and end nodes share the same
+ // parent. If not, fix it.
+ fixParentage(start, end);
+
+ // remove all of the nodes after the starting placeholder and
+ // before the ending placeholder.
+ node = start.nextSibling;
+ while (node) {
+ nextSibling = node.nextSibling;
+ last = node === end;
+
+ // if this is the last node, and we want to remove it as well,
+ // set the `end` node to the next sibling. This is because
+ // for the rest of the function, we insert the new nodes
+ // before the end (note that insertBefore(node, null) is
+ // the same as appendChild(node)).
+ //
+ // if we do not want to remove it, just break.
+ if (last) {
+ if (outerToo) { end = node.nextSibling; } else { break; }
+ }
- Invokes the receiver's willInsertElement() method if it exists and then
- invokes the same on all child views.
+ node.parentNode.removeChild(node);
- 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.
+ // if this is the last node and we didn't break before
+ // (because we wanted to remove the outer nodes), break
+ // now.
+ if (last) { break; }
- @method _notifyWillInsertElement
- */
- _notifyWillInsertElement: function() {
- this.invokeRecursively(function(view) {
- view.trigger('willInsertElement');
- });
- },
+ node = nextSibling;
+ }
- /**
- @private
+ // get the first node for the HTML string, even in cases like
+ // tables and lists where a simple innerHTML on a div would
+ // swallow some of the content.
+ node = firstNodeFor(start.parentNode, html);
+
+ // copy the nodes for the HTML between the starting and ending
+ // placeholder.
+ while (node) {
+ nextSibling = node.nextSibling;
+ parentNode.insertBefore(node, end);
+ node = nextSibling;
+ }
+ };
- Invokes the receiver's didInsertElement() method if it exists and then
- invokes the same on all child views.
+ // remove the nodes in the DOM representing this metamorph.
+ //
+ // this includes the starting and ending placeholders.
+ removeFunc = function() {
+ var start = realNode(document.getElementById(this.start));
+ var end = document.getElementById(this.end);
+
+ this.html('');
+ start.parentNode.removeChild(start);
+ end.parentNode.removeChild(end);
+ };
- @method _notifyDidInsertElement
- */
- _notifyDidInsertElement: function() {
- this.invokeRecursively(function(view) {
- view.trigger('didInsertElement');
- });
- },
+ appendToFunc = function(parentNode) {
+ var node = firstNodeFor(parentNode, this.outerHTML());
+ var nextSibling;
- /**
- @private
+ while (node) {
+ nextSibling = node.nextSibling;
+ parentNode.appendChild(node);
+ node = nextSibling;
+ }
+ };
- Invokes the receiver's willRerender() method if it exists and then
- invokes the same on all child views.
+ afterFunc = function(html) {
+ // get the real starting node. see realNode for details.
+ var end = document.getElementById(this.end);
+ var insertBefore = end.nextSibling;
+ var parentNode = end.parentNode;
+ var nextSibling;
+ var node;
+
+ // get the first node for the HTML string, even in cases like
+ // tables and lists where a simple innerHTML on a div would
+ // swallow some of the content.
+ node = firstNodeFor(parentNode, html);
+
+ // copy the nodes for the HTML between the starting and ending
+ // placeholder.
+ while (node) {
+ nextSibling = node.nextSibling;
+ parentNode.insertBefore(node, insertBefore);
+ node = nextSibling;
+ }
+ };
- @method _notifyWillRerender
- */
- _notifyWillRerender: function() {
- this.invokeRecursively(function(view) {
- view.trigger('willRerender');
- });
- },
+ prependFunc = function(html) {
+ var start = document.getElementById(this.start);
+ var parentNode = start.parentNode;
+ var nextSibling;
+ var node;
- /**
- Destroys any existing element along with the element for any child views
- as well. If the view does not currently have a element, then this method
- will do nothing.
+ node = firstNodeFor(parentNode, html);
+ var insertBefore = start.nextSibling;
- If you implement willDestroyElement() on your view, then this method will
- be invoked on your view before your element is destroyed to give you a
- chance to clean up any event handlers, etc.
+ while (node) {
+ nextSibling = node.nextSibling;
+ parentNode.insertBefore(node, insertBefore);
+ node = nextSibling;
+ }
+ };
+ }
- If you write a willDestroyElement() handler, you can assume that your
- didInsertElement() handler was called earlier for the same element.
+ Metamorph.prototype.html = function(html) {
+ this.checkRemoved();
+ if (html === undefined) { return this.innerHTML; }
- Normally you will not call or override this method yourself, but you may
- want to implement the above callbacks when it is run.
+ htmlFunc.call(this, html);
- @method destroyElement
- @return {Ember.View} receiver
- */
- destroyElement: function() {
- return this.invokeForState('destroyElement');
- },
+ this.innerHTML = html;
+ };
- /**
- 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.
+ Metamorph.prototype.replaceWith = function(html) {
+ this.checkRemoved();
+ htmlFunc.call(this, html, true);
+ };
- @event willDestroyElement
- */
- willDestroyElement: function() {},
+ Metamorph.prototype.remove = removeFunc;
+ Metamorph.prototype.outerHTML = outerHTMLFunc;
+ Metamorph.prototype.appendTo = appendToFunc;
+ Metamorph.prototype.after = afterFunc;
+ Metamorph.prototype.prepend = prependFunc;
+ Metamorph.prototype.startTag = startTagFunc;
+ Metamorph.prototype.endTag = endTagFunc;
- /**
- @private
+ Metamorph.prototype.isRemoved = function() {
+ var before = document.getElementById(this.start);
+ var after = document.getElementById(this.end);
- Invokes the `willDestroyElement` callback on the view and child views.
+ return !before || !after;
+ };
- @method _notifyWillDestroyElement
- */
- _notifyWillDestroyElement: function() {
- this.invokeRecursively(function(view) {
- view.trigger('willDestroyElement');
- });
- },
+ Metamorph.prototype.checkRemoved = function() {
+ if (this.isRemoved()) {
+ throw new Error("Cannot perform operations on a Metamorph that is not in the DOM.");
+ }
+ };
- _elementWillChange: Ember.beforeObserver(function() {
- this.forEachChildView(function(view) {
- Ember.propertyWillChange(view, 'element');
- });
- }, 'element'),
+ return Metamorph;
+ });
- /**
- @private
+})();
- If this view's element changes, we need to invalidate the caches of our
- child views so that we do not retain references to DOM elements that are
- no longer needed.
+(function() {
+/**
+@module ember
+@submodule ember-handlebars
+*/
- @method _elementDidChange
- */
- _elementDidChange: Ember.observer(function() {
- this.forEachChildView(function(view) {
- Ember.propertyDidChange(view, 'element');
- });
- }, 'element'),
+// Eliminate dependency on any Ember to simplify precompilation workflow
+var objectCreate = Object.create || function(parent) {
+ function F() {}
+ F.prototype = parent;
+ return new F();
+};
- /**
- Called when the parentView property has changed.
+var Handlebars = this.Handlebars || Ember.imports.Handlebars;
+Ember.assert("Ember Handlebars requires Handlebars 1.0.beta.5 or greater", Handlebars && Handlebars.VERSION.match(/^1\.0\.beta\.[56789]$|^1\.0\.rc\.[123456789]+/));
- @event parentViewDidChange
- */
- parentViewDidChange: Ember.K,
+/**
+ Prepares the Handlebars templating library for use inside Ember's view
+ system.
- /**
- @private
+ The `Ember.Handlebars` object is the standard Handlebars library, extended to
+ use Ember's `get()` method instead of direct property access, which allows
+ computed properties to be used inside templates.
- Invoked by the view system when this view needs to produce an HTML
- representation. This method will create a new render buffer, if needed,
- then apply any default attributes, such as class names and visibility.
- Finally, the `render()` method is invoked, which is responsible for
- doing the bulk of the rendering.
+ To create an `Ember.Handlebars` template, call `Ember.Handlebars.compile()`.
+ This will return a function that can be used by `Ember.View` for rendering.
- You should not need to override this method; instead, implement the
- `template` property, or if you need more control, override the `render`
- method.
+ @class Handlebars
+ @namespace Ember
+*/
+Ember.Handlebars = objectCreate(Handlebars);
- @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.
- */
- renderToBuffer: function(parentBuffer, bufferOperation) {
- var buffer;
+/**
+@class helpers
+@namespace Ember.Handlebars
+*/
+Ember.Handlebars.helpers = objectCreate(Handlebars.helpers);
- Ember.run.sync();
+/**
+ Override the the opcode compiler and JavaScript compiler for Handlebars.
- // Determine where in the parent buffer to start the new buffer.
- // By default, a new buffer will be appended to the parent buffer.
- // The buffer operation may be changed if the child views array is
- // mutated by Ember.ContainerView.
- bufferOperation = bufferOperation || 'begin';
+ @class Compiler
+ @namespace Ember.Handlebars
+ @private
+ @constructor
+*/
+Ember.Handlebars.Compiler = function() {};
- // If this is the top-most view, start a new buffer. Otherwise,
- // create a new buffer relative to the original using the
- // provided buffer operation (for example, `insertAfter` will
- // insert a new buffer after the "parent buffer").
- if (parentBuffer) {
- var tagName = get(this, 'tagName');
- if (tagName === null || tagName === undefined) {
- tagName = 'div';
- }
+// Handlebars.Compiler doesn't exist in runtime-only
+if (Handlebars.Compiler) {
+ Ember.Handlebars.Compiler.prototype = objectCreate(Handlebars.Compiler.prototype);
+}
- buffer = parentBuffer[bufferOperation](tagName);
- } else {
- buffer = this.renderBuffer();
- }
+Ember.Handlebars.Compiler.prototype.compiler = Ember.Handlebars.Compiler;
- this.buffer = buffer;
- this.transitionTo('inBuffer', false);
+/**
+ @class JavaScriptCompiler
+ @namespace Ember.Handlebars
+ @private
+ @constructor
+*/
+Ember.Handlebars.JavaScriptCompiler = function() {};
- this.lengthBeforeRender = this._childViews.length;
+// Handlebars.JavaScriptCompiler doesn't exist in runtime-only
+if (Handlebars.JavaScriptCompiler) {
+ Ember.Handlebars.JavaScriptCompiler.prototype = objectCreate(Handlebars.JavaScriptCompiler.prototype);
+ Ember.Handlebars.JavaScriptCompiler.prototype.compiler = Ember.Handlebars.JavaScriptCompiler;
+}
- this.beforeRender(buffer);
- this.render(buffer);
- this.afterRender(buffer);
- this.lengthAfterRender = this._childViews.length;
+Ember.Handlebars.JavaScriptCompiler.prototype.namespace = "Ember.Handlebars";
- return buffer;
- },
- renderToBufferIfNeeded: function () {
- return this.invokeForState('renderToBufferIfNeeded', this);
- },
+Ember.Handlebars.JavaScriptCompiler.prototype.initializeBuffer = function() {
+ return "''";
+};
- beforeRender: function(buffer) {
- this.applyAttributesToBuffer(buffer);
- },
+/**
+ @private
- afterRender: Ember.K,
+ 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.
- applyAttributesToBuffer: function(buffer) {
- // Creates observers for all registered class name and attribute bindings,
- // then adds them to the element.
- this._applyClassNameBindings();
+ @method appendToBuffer
+ @param string {String}
+*/
+Ember.Handlebars.JavaScriptCompiler.prototype.appendToBuffer = function(string) {
+ return "data.buffer.push("+string+");";
+};
- // Pass the render buffer so the method can apply attributes directly.
- // This isn't needed for class name bindings because they use the
- // existing classNames infrastructure.
- this._applyAttributeBindings(buffer);
+/**
+ @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.
- a_forEach(get(this, 'classNames'), function(name){ buffer.addClass(name); });
- buffer.id(get(this, 'elementId'));
+ @method mustache
+ @for Ember.Handlebars.Compiler
+ @param mustache
+*/
+Ember.Handlebars.Compiler.prototype.mustache = function(mustache) {
+ if (mustache.params.length || mustache.hash) {
+ return Handlebars.Compiler.prototype.mustache.call(this, mustache);
+ } else {
+ var id = new Handlebars.AST.IdNode(['_triageMustache']);
- var role = get(this, 'ariaRole');
- if (role) {
- buffer.attr('role', role);
+ // Update the mustache node to include a hash value indicating whether the original node
+ // was escaped. This will allow us to properly escape values when the underlying value
+ // changes and we need to re-render the value.
+ if(!mustache.escaped) {
+ mustache.hash = mustache.hash || new Handlebars.AST.HashNode([]);
+ mustache.hash.pairs.push(["unescaped", new Handlebars.AST.StringNode("true")]);
}
+ mustache = new Handlebars.AST.MustacheNode([id].concat([mustache.id]), mustache.hash, !mustache.escaped);
+ return Handlebars.Compiler.prototype.mustache.call(this, mustache);
+ }
+};
- if (get(this, 'isVisible') === false) {
- buffer.style('display', 'none');
- }
- },
+/**
+ Used for precompilation of Ember Handlebars templates. This will not be used
+ during normal app execution.
- // ..........................................................
- // STANDARD RENDER PROPERTIES
- //
+ @method precompile
+ @for Ember.Handlebars
+ @static
+ @param {String} string The template to precompile
+*/
+Ember.Handlebars.precompile = function(string) {
+ var ast = Handlebars.parse(string);
- /**
- Tag name for the view's outer element. The tag name is only used when
- an element is first created. If you change the tagName for an element, you
- must destroy and recreate the view element.
+ var options = {
+ knownHelpers: {
+ action: true,
+ unbound: true,
+ bindAttr: true,
+ template: true,
+ view: true,
+ _triageMustache: true
+ },
+ data: true,
+ stringParams: true
+ };
- By default, the render buffer will use a `<div>` tag for views.
+ var environment = new Ember.Handlebars.Compiler().compile(ast, options);
+ return new Ember.Handlebars.JavaScriptCompiler().compile(environment, options, undefined, true);
+};
- @property tagName
- @type String
- @default null
+// We don't support this for Handlebars runtime-only
+if (Handlebars.compile) {
+ /**
+ 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);
+ var options = { data: true, stringParams: true };
+ var environment = new Ember.Handlebars.Compiler().compile(ast, options);
+ var templateSpec = new Ember.Handlebars.JavaScriptCompiler().compile(environment, options, undefined, true);
- // We leave this null by default so we can tell the difference between
- // the default case and a user-specified tag.
- tagName: null,
+ return Ember.Handlebars.template(templateSpec);
+ };
+}
- /**
- The WAI-ARIA role of the control represented by this view. For example, a
- button may have a role of type 'button', or a pane may have a role of
- type 'alertdialog'. This property is used by assistive software to help
- visually challenged users navigate rich web applications.
- 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
- */
- ariaRole: null,
+(function() {
+/**
+ @private
- /**
- Standard CSS class names to apply to the view's outer element. This
- property automatically inherits any class names defined by the view's
- superclasses as well.
+ If a path starts with a reserved keyword, returns the root
+ that should be used.
- @property classNames
- @type Array
- @default ['ember-view']
- */
- classNames: ['ember-view'],
+ @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) || {},
+ keyword, isKeyword;
- /**
- A list of properties of the view to apply as class names. If the property
- is a string value, the value of that string will be applied as a class
- name.
+ // Get the first segment of the path. For example, if the
+ // path is "foo.bar.baz", returns "foo".
+ keyword = path.split('.', 1)[0];
- // Applies the 'high' class to the view element
- Ember.View.create({
- classNameBindings: ['priority']
- priority: 'high'
- });
+ // Test to see if the first path is a keyword that has been
+ // passed along in the view's data hash. If so, we will treat
+ // that object as the new root.
+ if (keywords.hasOwnProperty(keyword)) {
+ // Look up the value in the template's data hash.
+ root = keywords[keyword];
+ isKeyword = true;
- If the value of the property is a Boolean, the name of that property is
- added as a dasherized class name.
+ // Handle cases where the entire path is the reserved
+ // word. In that case, return the object itself.
+ if (path === keyword) {
+ path = '';
+ } else {
+ // Strip the keyword from the path and look up
+ // the remainder from the newly found root.
+ path = path.substr(keyword.length+1);
+ }
+ }
- // Applies the 'is-urgent' class to the view element
- Ember.View.create({
- classNameBindings: ['isUrgent']
- isUrgent: true
- });
+ return { root: root, path: path, isKeyword: isKeyword };
+};
- If you would prefer to use a custom value instead of the dasherized
- property name, you can pass a binding like this:
- // Applies the 'urgent' class to the view element
- Ember.View.create({
- classNameBindings: ['isUrgent:urgent']
- isUrgent: true
- });
+/**
+ 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.
- This list of properties is inherited from the view's superclasses as well.
+ @method get
+ @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.get = function(root, path, options) {
+ var data = options && options.data,
+ normalizedPath = normalizePath(root, path, data),
+ value;
- @property classNameBindings
- @type Array
- @default []
- */
- classNameBindings: [],
+ // In cases where the path begins with a keyword, change the
+ // root to the value represented by that keyword, and ensure
+ // the path is relative to it.
+ root = normalizedPath.root;
+ path = normalizedPath.path;
- /**
- A list of properties of the view to apply as attributes. If the property is
- a string value, the value of that string will be applied as the attribute.
+ value = Ember.get(root, path);
- // Applies the type attribute to the element
- // with the value "button", like <div type="button">
- Ember.View.create({
- attributeBindings: ['type'],
- type: 'button'
- });
+ // If the path starts with a capital letter, look it up on Ember.lookup,
+ // which defaults to the `window` object in browsers.
+ if (value === undefined && root !== Ember.lookup && Ember.isGlobalPath(path)) {
+ value = Ember.get(Ember.lookup, path);
+ }
+ return value;
+};
+Ember.Handlebars.getPath = Ember.deprecateFunc('`Ember.Handlebars.getPath` has been changed to `Ember.Handlebars.get` for consistency.', Ember.Handlebars.get);
- If the value of the property is a Boolean, the name of that property is
- added as an attribute.
+/**
+ @private
- // Renders something like <div enabled="enabled">
- Ember.View.create({
- attributeBindings: ['enabled'],
- enabled: true
- });
+ 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.
+
+ This throws an exception with a more helpful error message so the user can
+ track down where the problem is happening.
- @property attributeBindings
- */
- attributeBindings: [],
+ @method helperMissing
+ @for Ember.Handlebars.helpers
+ @param {String} path
+ @param {Hash} options
+*/
+Ember.Handlebars.registerHelper('helperMissing', function(path, options) {
+ var error, view = "";
- state: 'preRender',
+ error = "%@ Handlebars error: Could not find property '%@' on object %@.";
+ if (options.data){
+ view = options.data.view;
+ }
+ throw new Ember.Error(Ember.String.fmt(error, [view, path, this]));
+});
- // .......................................................
- // CORE DISPLAY METHODS
- //
+/**
+ Register a bound handlebars helper. Bound helpers behave similarly to regular
+ handlebars helpers, with the added ability to re-render when the underlying data
+ changes.
- /**
- @private
+ ## Simple example
- Setup a view, but do not finish waking it up.
- - configure childViews
- - register the view with the global views hash, which is used for event
- dispatch
+ ```javascript
+ Ember.Handlebars.registerBoundHelper('capitalize', function(value) {
+ return value.toUpperCase();
+ });
+ ```
- @method init
- */
- init: function() {
- this._super();
+ The above bound helper can be used inside of templates as follows:
- // Register the view for event handling. This hash is used by
- // Ember.EventDispatcher to dispatch incoming events.
- if (!this.isVirtual) Ember.View.views[get(this, 'elementId')] = this;
+ ```handlebars
+ {{capitalize name}}
+ ```
- // setup child views. be sure to clone the child views array first
- this._childViews = this._childViews.slice();
+ In this case, when the `name` property of the template's context changes,
+ the rendered value of the helper will update to reflect this change.
- Ember.assert("Only arrays are allowed for 'classNameBindings'", Ember.typeOf(this.classNameBindings) === 'array');
- this.classNameBindings = Ember.A(this.classNameBindings.slice());
+ ## Example with options
- Ember.assert("Only arrays are allowed for 'classNames'", Ember.typeOf(this.classNames) === 'array');
- this.classNames = Ember.A(this.classNames.slice());
+ Like normal handlebars helpers, bound helpers have access to the options
+ passed into the helper call.
- var viewController = get(this, 'viewController');
- if (viewController) {
- viewController = get(viewController);
- if (viewController) {
- set(viewController, 'view', this);
- }
+ ```javascript
+ Ember.Handlebars.registerBoundHelper('repeat', function(value, options) {
+ var count = options.hash.count;
+ var a = [];
+ while(a.length < count){
+ a.push(value);
}
- },
+ return a.join('');
+ });
+ ```
- appendChild: function(view, options) {
- return this.invokeForState('appendChild', view, options);
- },
+ This helper could be used in a template as follows:
- /**
- Removes the child view from the parent view.
+ ```handlebars
+ {{repeat text count=3}}
+ ```
- @method removeChild
- @param {Ember.View} view
- @return {Ember.View} receiver
- */
- removeChild: function(view) {
- // If we're destroying, the entire subtree will be
- // freed, and the DOM will be handled separately,
- // so no need to mess with childViews.
- if (this.isDestroying) { return; }
+ ## Example with extra dependencies
- // update parent node
- set(view, '_parentView', null);
+ The `Ember.Handlebars.registerBoundHelper` method takes a variable length
+ third parameter which indicates extra dependencies on the passed in value.
+ This allows the handlebars helper to update when these dependencies change.
- // remove view from childViews array.
- var childViews = this._childViews;
+ ```javascript
+ Ember.Handlebars.registerBoundHelper('capitalizeName', function(value) {
+ return value.get('name').toUpperCase();
+ }, 'name');
+ ```
- Ember.EnumerableUtils.removeObject(childViews, view);
+ @method registerBoundHelper
+ @for Ember.Handlebars
+ @param {String} name
+ @param {Function} function
+ @param {String} dependentKeys*
+*/
+Ember.Handlebars.registerBoundHelper = function(name, fn) {
+ var dependentKeys = Array.prototype.slice.call(arguments, 2);
+ Ember.Handlebars.registerHelper(name, function(property, options) {
+ var data = options.data,
+ view = data.view,
+ currentContext = (options.contexts && options.contexts[0]) || this,
+ pathRoot, path, normalized,
+ observer, loc;
- this.propertyDidChange('childViews'); // HUH?! what happened to will change?
+ normalized = Ember.Handlebars.normalizePath(currentContext, property, data);
- return this;
- },
+ pathRoot = normalized.root;
+ path = normalized.path;
- /**
- Removes all children from the parentView.
+ var bindView = new Ember._SimpleHandlebarsView(
+ path, pathRoot, !options.hash.unescaped, options.data
+ );
- @method removeAllChildren
- @return {Ember.View} receiver
- */
- removeAllChildren: function() {
- return this.mutateChildViews(function(view) {
- this.removeChild(view);
- });
- },
+ bindView.normalizedValue = function() {
+ var value = Ember._SimpleHandlebarsView.prototype.normalizedValue.call(bindView);
+ return fn.call(view, value, options);
+ };
- destroyAllChildren: function() {
- return this.mutateChildViews(function(view) {
- view.destroy();
- });
- },
+ view.appendChild(bindView);
- /**
- Removes the view from its parentView, if one is found. Otherwise
- does nothing.
+ observer = function() {
+ Ember.run.scheduleOnce('render', bindView, 'rerender');
+ };
- @method removeFromParent
- @return {Ember.View} receiver
- */
- removeFromParent: function() {
- var parent = get(this, '_parentView');
+ Ember.addObserver(pathRoot, path, observer);
+ loc = 0;
+ while(loc < dependentKeys.length) {
+ Ember.addObserver(pathRoot, path + '.' + dependentKeys[loc], observer);
+ loc += 1;
+ }
- // Remove DOM element from parent
- this.remove();
+ view.one('willClearRender', function() {
+ Ember.removeObserver(pathRoot, path, observer);
+ loc = 0;
+ while(loc < dependentKeys.length) {
+ Ember.removeObserver(pathRoot, path + '.' + dependentKeys[loc], observer);
+ loc += 1;
+ }
+ });
+ });
+};
- if (parent) { parent.removeChild(this); }
- return this;
- },
+/**
+ @private
- /**
- You must call `destroy` on a view to destroy the view (and all of its
- 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.
+ Overrides Handlebars.template so that we can distinguish
+ user-created, top-level templates from inner contexts.
- @method willDestroy
- */
- willDestroy: function() {
- // calling this._super() will nuke computed properties and observers,
- // so collect any information we need before calling super.
- var childViews = this._childViews,
- parent = get(this, '_parentView'),
- childLen;
+ @method template
+ @for Ember.Handlebars
+ @param {String} template spec
+*/
+Ember.Handlebars.template = function(spec){
+ var t = Handlebars.template(spec);
+ t.isTop = true;
+ return t;
+};
- // destroy the element -- this will avoid each child view destroying
- // the element over and over again...
- if (!this.removedFromDOM) { this.destroyElement(); }
- // remove from non-virtual parent view if viewName was specified
- if (this.viewName) {
- var nonVirtualParentView = get(this, 'parentView');
- if (nonVirtualParentView) {
- set(nonVirtualParentView, this.viewName, null);
- }
- }
+})();
- // remove from parent if found. Don't call removeFromParent,
- // as removeFromParent will try to remove the element from
- // the DOM again.
- if (parent) { parent.removeChild(this); }
- this.state = 'destroyed';
- childLen = childViews.length;
- for (var i=childLen-1; i>=0; i--) {
- childViews[i].removedFromDOM = true;
- childViews[i].destroy();
- }
+(function() {
+/**
+ @method htmlSafe
+ @for Ember.String
+ @static
+*/
+Ember.String.htmlSafe = function(str) {
+ return new Handlebars.SafeString(str);
+};
- // next remove view from global hash
- if (!this.isVirtual) delete Ember.View.views[get(this, 'elementId')];
- },
+var htmlSafe = Ember.String.htmlSafe;
+
+if (Ember.EXTEND_PROTOTYPES === true || Ember.EXTEND_PROTOTYPES.String) {
/**
- Instantiates a view to be added to the childViews array during view
- initialization. You generally will not call this method directly unless
- you are overriding createChildViews(). Note that this method will
- automatically configure the correct settings on the new view instance to
- act as a child of the parent.
+ See {{#crossLink "Ember.String/htmlSafe"}}{{/crossLink}}
- @method createChildView
- @param {Class} viewClass
- @param {Hash} [attrs] Attributes to add
- @return {Ember.View} new instance
+ @method htmlSafe
+ @for String
*/
- createChildView: function(view, attrs) {
- if (Ember.View.detect(view)) {
- attrs = attrs || {};
- attrs._parentView = this;
- attrs.templateData = attrs.templateData || get(this, 'templateData');
-
- view = view.create(attrs);
-
- // don't set the property on a virtual view, as they are invisible to
- // consumers of the view API
- if (view.viewName) { set(get(this, 'concreteView'), view.viewName, view); }
- } else {
- Ember.assert('You must pass instance or subclass of View', view instanceof Ember.View);
- Ember.assert("You can only pass attributes when a class is provided", !attrs);
-
- if (!get(view, 'templateData')) {
- set(view, 'templateData', get(this, 'templateData'));
- }
-
- set(view, '_parentView', this);
- }
+ String.prototype.htmlSafe = function() {
+ return htmlSafe(this);
+ };
+}
- return view;
- },
+})();
- becameVisible: Ember.K,
- becameHidden: Ember.K,
- /**
- @private
- When the view's `isVisible` property changes, toggle the visibility
- element of the actual DOM element.
+(function() {
+Ember.Handlebars.resolvePaths = function(options) {
+ var ret = [],
+ contexts = options.contexts,
+ roots = options.roots,
+ data = options.data;
+
+ for (var i=0, l=contexts.length; i<l; i++) {
+ ret.push( Ember.Handlebars.get(roots[i], contexts[i], { data: data }) );
+ }
- @method _isVisibleDidChange
- */
- _isVisibleDidChange: Ember.observer(function() {
- var $el = this.$();
- if (!$el) { return; }
+ return ret;
+};
- var isVisible = get(this, 'isVisible');
+})();
- $el.toggle(isVisible);
- if (this._isAncestorHidden()) { return; }
- if (isVisible) {
- this._notifyBecameVisible();
- } else {
- this._notifyBecameHidden();
- }
- }, 'isVisible'),
+(function() {
+/*jshint newcap:false*/
+/**
+@module ember
+@submodule ember-handlebars
+*/
- _notifyBecameVisible: function() {
- this.trigger('becameVisible');
+var set = Ember.set, get = Ember.get;
+var Metamorph = requireModule('metamorph');
- this.forEachChildView(function(view) {
- var isVisible = get(view, 'isVisible');
+// DOMManager should just abstract dom manipulation between jquery and metamorph
+var DOMManager = {
+ remove: function(view) {
+ view.morph.remove();
+ },
- if (isVisible || isVisible === null) {
- view._notifyBecameVisible();
- }
- });
+ prepend: function(view, html) {
+ view.morph.prepend(html);
},
- _notifyBecameHidden: function() {
- this.trigger('becameHidden');
- this.forEachChildView(function(view) {
- var isVisible = get(view, 'isVisible');
+ after: function(view, html) {
+ view.morph.after(html);
+ },
- if (isVisible || isVisible === null) {
- view._notifyBecameHidden();
- }
- });
+ html: function(view, html) {
+ view.morph.html(html);
},
- _isAncestorHidden: function() {
- var parent = get(this, 'parentView');
+ // This is messed up.
+ replace: function(view) {
+ var morph = view.morph;
- while (parent) {
- if (get(parent, 'isVisible') === false) { return true; }
+ view.transitionTo('preRender');
- parent = get(parent, 'parentView');
- }
+ Ember.run.schedule('render', this, function() {
+ if (get(view, 'isDestroyed')) { return; }
- return false;
- },
+ view.clearRenderedChildren();
+ var buffer = view.renderToBuffer();
- clearBuffer: function() {
- this.invokeRecursively(function(view) {
- this.buffer = null;
+ view.invokeRecursively(function(view) {
+ view.propertyDidChange('element');
+ });
+
+ view.triggerRecursively('willInsertElement');
+ morph.replaceWith(buffer.string());
+ view.transitionTo('inDOM');
+ view.triggerRecursively('didInsertElement');
});
},
- transitionTo: function(state, children) {
- this.state = state;
+ empty: function(view) {
+ view.morph.html("");
+ }
+};
- if (children !== false) {
- this.forEachChildView(function(view) {
- view.transitionTo(state);
- });
- }
- },
+// The `morph` and `outerHTML` properties are internal only
+// and not observable.
- /**
- @private
+/**
+ @class _Metamorph
+ @namespace Ember
+ @extends Ember.Mixin
+ @private
+*/
+Ember._Metamorph = Ember.Mixin.create({
+ isVirtual: true,
+ tagName: '',
- Override the default event firing from Ember.Evented to
- also call methods with the given name.
+ instrumentName: 'render.metamorph',
- @method trigger
- @param name {String}
- */
- trigger: function(name) {
- this._super.apply(this, arguments);
- var method = this[name];
- if (method) {
- var args = [], i, l;
- for (i = 1, l = arguments.length; i < l; i++) {
- args.push(arguments[i]);
- }
- return method.apply(this, args);
- }
+ init: function() {
+ this._super();
+ this.morph = Metamorph();
},
- has: function(name) {
- return Ember.typeOf(this[name]) === 'function' || this._super(name);
+ beforeRender: function(buffer) {
+ buffer.push(this.morph.startTag());
+ buffer.pushOpeningTag();
},
- // .......................................................
- // EVENT HANDLING
- //
+ afterRender: function(buffer) {
+ buffer.pushClosingTag();
+ buffer.push(this.morph.endTag());
+ },
- /**
- @private
+ createElement: function() {
+ var buffer = this.renderToBuffer();
+ this.outerHTML = buffer.string();
+ this.clearBuffer();
+ },
- Handle events from `Ember.EventDispatcher`
+ domManager: DOMManager
+});
- @method handleEvent
- @param eventName {String}
- @param evt {Event}
- */
- handleEvent: function(eventName, evt) {
- return this.invokeForState('handleEvent', eventName, evt);
- }
+/**
+ @class _MetamorphView
+ @namespace Ember
+ @extends Ember.View
+ @uses Ember._Metamorph
+ @private
+*/
+Ember._MetamorphView = Ember.View.extend(Ember._Metamorph);
-});
+/**
+ @class _SimpleMetamorphView
+ @namespace Ember
+ @extends Ember.View
+ @uses Ember._Metamorph
+ @private
+*/
+Ember._SimpleMetamorphView = Ember.CoreView.extend(Ember._Metamorph);
-/*
- Describe how the specified actions should behave in the various
- states that a view can exist in. Possible states:
- * preRender: when a view is first instantiated, and after its
- element was destroyed, it is in the preRender state
- * inBuffer: once a view has been rendered, but before it has
- been inserted into the DOM, it is in the inBuffer state
- * inDOM: once a view has been inserted into the DOM it is in
- the inDOM state. A view spends the vast majority of its
- existence in this state.
- * destroyed: once a view has been destroyed (using the destroy
- method), it is in this state. No further actions can be invoked
- on a destroyed view.
+})();
+
+
+
+(function() {
+/*globals Handlebars */
+/*jshint newcap:false*/
+/**
+@module ember
+@submodule ember-handlebars
*/
- // in the destroyed state, everything is illegal
+var get = Ember.get, set = Ember.set, handlebarsGet = Ember.Handlebars.get;
+var Metamorph = requireModule('metamorph');
+function SimpleHandlebarsView(path, pathRoot, isEscaped, templateData) {
+ this.path = path;
+ this.pathRoot = pathRoot;
+ this.isEscaped = isEscaped;
+ this.templateData = templateData;
- // before rendering has begun, all legal manipulations are noops.
+ this.morph = Metamorph();
+ this.state = 'preRender';
+ this.updateId = null;
+}
- // inside the buffer, legal manipulations are done on the buffer
+Ember._SimpleHandlebarsView = SimpleHandlebarsView;
- // once the view has been inserted into the DOM, legal manipulations
- // are done on the DOM element.
+SimpleHandlebarsView.prototype = {
+ isVirtual: true,
+ isView: true,
-var DOMManager = {
- prepend: function(view, html) {
- view.$().prepend(html);
+ destroy: function () {
+ if (this.updateId) {
+ Ember.run.cancel(this.updateId);
+ this.updateId = null;
+ }
+ this.morph = null;
},
- after: function(view, html) {
- view.$().after(html);
+ propertyDidChange: Ember.K,
+
+ normalizedValue: function() {
+ var path = this.path,
+ pathRoot = this.pathRoot,
+ result, templateData;
+
+ // Use the pathRoot as the result if no path is provided. This
+ // happens if the path is `this`, which gets normalized into
+ // a `pathRoot` of the current Handlebars context and a path
+ // of `''`.
+ if (path === '') {
+ result = pathRoot;
+ } else {
+ templateData = this.templateData;
+ result = handlebarsGet(pathRoot, path, { data: templateData });
+ }
+
+ return result;
},
- html: function(view, html) {
- view.$().html(html);
+ renderToBuffer: function(buffer) {
+ var string = '';
+
+ string += this.morph.startTag();
+ string += this.render();
+ string += this.morph.endTag();
+
+ buffer.push(string);
},
- replace: function(view) {
- var element = get(view, 'element');
+ render: function() {
+ // If not invoked via a triple-mustache ({{{foo}}}), escape
+ // the content of the template.
+ var escape = this.isEscaped;
+ var result = this.normalizedValue();
- set(view, 'element', null);
+ if (result === null || result === undefined) {
+ result = "";
+ } else if (!(result instanceof Handlebars.SafeString)) {
+ result = String(result);
+ }
- view._insertElementLater(function() {
- Ember.$(element).replaceWith(get(view, 'element'));
- });
+ if (escape) { result = Handlebars.Utils.escapeExpression(result); }
+ return result;
},
- remove: function(view) {
- view.$().remove();
+ rerender: function() {
+ switch(this.state) {
+ case 'preRender':
+ case 'destroyed':
+ break;
+ case 'inBuffer':
+ throw new Ember.Error("Something you did tried to replace an {{expression}} before it was inserted into the DOM.");
+ case 'hasElement':
+ case 'inDOM':
+ this.updateId = Ember.run.scheduleOnce('render', this, 'update');
+ break;
+ }
+
+ return this;
},
- empty: function(view) {
- view.$().empty();
+ update: function () {
+ this.updateId = null;
+ this.morph.html(this.render());
+ },
+
+ transitionTo: function(state) {
+ this.state = state;
}
};
-Ember.View.reopen({
- states: Ember.View.states,
- domManager: DOMManager
+var states = Ember.View.cloneStates(Ember.View.states), merge = Ember.merge;
+
+merge(states._default, {
+ rerenderIfNeeded: Ember.K
});
-Ember.View.reopenClass({
+merge(states.inDOM, {
+ rerenderIfNeeded: function(view) {
+ if (get(view, 'normalizedValue') !== view._lastNormalizedValue) {
+ view.rerender();
+ }
+ }
+});
- /**
- @private
+/**
+ `Ember._HandlebarsBoundView` is a private view created by the Handlebars
+ `{{bind}}` helpers that is used to keep track of bound properties.
- Parse a path and return an object which holds the parsed properties.
+ Every time a property is bound using a `{{mustache}}`, an anonymous subclass
+ 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.
- For example a path like "content.isEnabled:enabled:disabled" wil return the
- following object:
+ @class _HandlebarsBoundView
+ @namespace Ember
+ @extends Ember._MetamorphView
+ @private
+*/
+Ember._HandlebarsBoundView = Ember._MetamorphView.extend({
+ instrumentName: 'render.boundHandlebars',
+ states: states,
- {
- path: "content.isEnabled",
- className: "enabled",
- falsyClassName: "disabled",
- classNames: ":enabled:disabled"
- }
+ /**
+ 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.
- @method _parsePropertyPath
- @static
+ @property shouldDisplayFunc
+ @type Function
+ @default null
*/
- _parsePropertyPath: function(path) {
- var split = path.split(':'),
- propertyPath = split[0],
- classNames = "",
- className,
- falsyClassName;
+ shouldDisplayFunc: null,
- // check if the property is defined as prop:class or prop:trueClass:falseClass
- if (split.length > 1) {
- className = split[1];
- if (split.length === 3) { falsyClassName = split[2]; }
+ /**
+ Whether the template rendered by this view gets passed the context object
+ of its parent template, or gets passed the value of retrieving `path`
+ from the `pathRoot`.
- classNames = ':' + className;
- if (falsyClassName) { classNames += ":" + falsyClassName; }
- }
+ For example, this is true when using the `{{#if}}` helper, because the
+ template inside the helper should look up properties relative to the same
+ object as outside the block. This would be `false` when used with `{{#with
+ foo}}` because the template should receive the object found by evaluating
+ `foo`.
- return {
- path: propertyPath,
- classNames: classNames,
- className: (className === '') ? undefined : className,
- falsyClassName: falsyClassName
- };
- },
+ @property preserveContext
+ @type Boolean
+ @default false
+ */
+ preserveContext: false,
+
+ /**
+ If `preserveContext` is true, this is the object that will be used
+ to render the template.
+
+ @property previousContext
+ @type Object
+ */
+ previousContext: null,
/**
- @private
+ The template to render when `shouldDisplayFunc` evaluates to `true`.
- Get the class name for a given value, based on the path, optional className
- and optional falsyClassName.
+ @property displayTemplate
+ @type Function
+ @default null
+ */
+ displayTemplate: null,
- - 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 not false, undefined or null, the value is returned
- - if none of the above rules apply, null is returned
+ /**
+ The template to render when `shouldDisplayFunc` evaluates to `false`.
- @method _classStringForValue
- @param path
- @param val
- @param className
- @param falsyClassName
- @static
+ @property inverseTemplate
+ @type Function
+ @default null
*/
- _classStringForValue: function(path, val, className, falsyClassName) {
- // 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;
+ inverseTemplate: null,
- } else if (falsyClassName && !val) {
- return falsyClassName;
- } else {
- return null;
- }
+ /**
+ The path to look up on `pathRoot` that is passed to
+ `shouldDisplayFunc` to determine which template to render.
- // If value is a Boolean and true, return the dasherized property
- // name.
- } else if (val === true) {
- // 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]);
+ In addition, if `preserveContext` is `false,` the object at this path will
+ be passed to the template when rendering.
- // If the value is not false, undefined, or null, return the current
- // value of the property.
- } else if (val !== false && val !== undefined && val !== null) {
- return val;
+ @property path
+ @type String
+ @default null
+ */
+ path: null,
- // Nothing to display. Return null so that the old class is removed
- // but no new class is added.
- } else {
- return null;
- }
- }
-});
+ /**
+ The object from which the `path` will be looked up. Sometimes this is the
+ same as the `previousContext`, but in cases where this view has been
+ generated for paths that start with a keyword such as `view` or
+ `controller`, the path root will be that resolved object.
-/**
- Global views hash
+ @property pathRoot
+ @type Object
+ */
+ pathRoot: null,
- @property views
- @static
- @type Hash
-*/
-Ember.View.views = {};
+ normalizedValue: Ember.computed(function() {
+ var path = get(this, 'path'),
+ pathRoot = get(this, 'pathRoot'),
+ valueNormalizer = get(this, 'valueNormalizerFunc'),
+ result, templateData;
-// If someone overrides the child views computed property when
-// defining their class, we want to be able to process the user's
-// supplied childViews and then restore the original computed property
-// at view initialization time. This happens in Ember.ContainerView's init
-// method.
-Ember.View.childViewsProperty = childViewsProperty;
+ // Use the pathRoot as the result if no path is provided. This
+ // happens if the path is `this`, which gets normalized into
+ // a `pathRoot` of the current Handlebars context and a path
+ // of `''`.
+ if (path === '') {
+ result = pathRoot;
+ } else {
+ templateData = get(this, 'templateData');
+ result = handlebarsGet(pathRoot, path, { data: templateData });
+ }
-Ember.View.applyAttributeBindings = function(elem, name, value) {
- var type = Ember.typeOf(value);
- var currentValue = elem.attr(name);
+ return valueNormalizer ? valueNormalizer(result) : result;
+ }).property('path', 'pathRoot', 'valueNormalizerFunc').volatile(),
- // if this changes, also change the logic in ember-handlebars/lib/helpers/binding.js
- if ((type === 'string' || (type === 'number' && !isNaN(value))) && value !== currentValue) {
- elem.attr(name, value);
- } else if (value && type === 'boolean') {
- elem.attr(name, name);
- } else if (!value) {
- elem.removeAttr(name);
- }
-};
+ rerenderIfNeeded: function() {
+ this.currentState.rerenderIfNeeded(this);
+ },
-})();
+ /**
+ Determines which template to invoke, sets up the correct state based on
+ that logic, then invokes the default `Ember.View` `render` implementation.
+ This method will first look up the `path` key on `pathRoot`,
+ then pass that value to the `shouldDisplayFunc` function. If that returns
+ `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}}` 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`.
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ @method render
+ @param {Ember.RenderBuffer} buffer
+ */
+ render: function(buffer) {
+ // If not invoked via a triple-mustache ({{{foo}}}), escape
+ // the content of the template.
+ var escape = get(this, 'isEscaped');
-var get = Ember.get, set = Ember.set;
+ var shouldDisplay = get(this, 'shouldDisplayFunc'),
+ preserveContext = get(this, 'preserveContext'),
+ context = get(this, 'previousContext');
-Ember.View.states = {
- _default: {
- // appendChild is only legal while rendering the buffer.
- appendChild: function() {
- throw "You can't use appendChild outside of the rendering process";
- },
+ var inverseTemplate = get(this, 'inverseTemplate'),
+ displayTemplate = get(this, 'displayTemplate');
- $: function() {
- return undefined;
- },
+ var result = get(this, 'normalizedValue');
+ this._lastNormalizedValue = result;
- getElement: function() {
- return null;
- },
+ // First, test the conditional to see if we should
+ // render the template or not.
+ if (shouldDisplay(result)) {
+ set(this, 'template', displayTemplate);
- // Handle events from `Ember.EventDispatcher`
- handleEvent: function() {
- return true; // continue event propagation
- },
+ // If we are preserving the context (for example, if this
+ // is an #if block, call the template with the same object.
+ if (preserveContext) {
+ set(this, '_context', context);
+ } else {
+ // Otherwise, determine if this is a block bind or not.
+ // If so, pass the specified object to the template
+ if (displayTemplate) {
+ set(this, '_context', result);
+ } else {
+ // This is not a bind block, just push the result of the
+ // expression to the render context and return.
+ if (result === null || result === undefined) {
+ result = "";
+ } else if (!(result instanceof Handlebars.SafeString)) {
+ result = String(result);
+ }
- destroyElement: function(view) {
- set(view, 'element', null);
- if (view._scheduledInsert) {
- Ember.run.cancel(view._scheduledInsert);
- view._scheduledInsert = null;
+ if (escape) { result = Handlebars.Utils.escapeExpression(result); }
+ buffer.push(result);
+ return;
+ }
}
- return view;
- },
+ } else if (inverseTemplate) {
+ set(this, 'template', inverseTemplate);
- renderToBufferIfNeeded: function () {
- return false;
+ if (preserveContext) {
+ set(this, '_context', context);
+ } else {
+ set(this, '_context', result);
+ }
+ } else {
+ set(this, 'template', function() { return ''; });
}
- }
-};
-Ember.View.reopen({
- states: Ember.View.states
+ return this._super(buffer);
+ }
});
})();
(function() {
/**
@module ember
-@submodule ember-views
+@submodule ember-handlebars
*/
-Ember.View.states.preRender = {
- parentState: Ember.View.states._default,
+var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
+var handlebarsGet = Ember.Handlebars.get, normalizePath = Ember.Handlebars.normalizePath;
+var forEach = Ember.ArrayPolyfills.forEach;
- // a view leaves the preRender state once its element has been
- // created (createElement).
- insertElement: function(view, fn) {
- view.createElement();
- view._notifyWillInsertElement();
- // after createElement, the view will be in the hasElement state.
- fn.call(view);
- view.transitionTo('inDOM');
- view._notifyDidInsertElement();
- },
+var EmberHandlebars = Ember.Handlebars, helpers = EmberHandlebars.helpers;
- renderToBufferIfNeeded: function(view) {
- return view.renderToBuffer();
- },
+// 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.
+function bind(property, options, preserveContext, shouldDisplay, valueNormalizer) {
+ var data = options.data,
+ fn = options.fn,
+ inverse = options.inverse,
+ view = data.view,
+ currentContext = this,
+ pathRoot, path, normalized,
+ observer;
- empty: Ember.K,
+ normalized = normalizePath(currentContext, property, data);
- setElement: function(view, value) {
- if (value !== null) {
- view.transitionTo('hasElement');
- }
- return value;
- }
-};
+ pathRoot = normalized.root;
+ path = normalized.path;
-})();
+ // Set up observers for observable objects
+ if ('object' === typeof this) {
+ if (data.insideGroup) {
+ observer = function() {
+ Ember.run.once(view, 'rerender');
+ };
+ var template, context, result = handlebarsGet(pathRoot, path, options);
+ result = valueNormalizer(result);
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ context = preserveContext ? currentContext : result;
+ if (shouldDisplay(result)) {
+ template = fn;
+ } else if (inverse) {
+ template = inverse;
+ }
-var get = Ember.get, set = Ember.set, meta = Ember.meta;
+ template(context, { data: options.data });
+ } else {
+ // Create the view that will wrap the output of this template/property
+ // and add it to the nearest view's childViews array.
+ // See the documentation of Ember._HandlebarsBoundView for more.
+ var bindView = view.createChildView(Ember._HandlebarsBoundView, {
+ preserveContext: preserveContext,
+ shouldDisplayFunc: shouldDisplay,
+ valueNormalizerFunc: valueNormalizer,
+ displayTemplate: fn,
+ inverseTemplate: inverse,
+ path: path,
+ pathRoot: pathRoot,
+ previousContext: currentContext,
+ isEscaped: !options.hash.unescaped,
+ templateData: options.data
+ });
-Ember.View.states.inBuffer = {
- parentState: Ember.View.states._default,
+ view.appendChild(bindView);
- $: function(view, sel) {
- // if we don't have an element yet, someone calling this.$() is
- // trying to update an element that isn't in the DOM. Instead,
- // rerender the view to allow the render method to reflect the
- // changes.
- view.rerender();
- return Ember.$();
- },
+ observer = function() {
+ Ember.run.scheduleOnce('render', bindView, 'rerenderIfNeeded');
+ };
+ }
- // when a view is rendered in a buffer, rerendering it simply
- // replaces the existing buffer with a new one
- rerender: function(view) {
- Ember.deprecate("Something you did caused a view to re-render after it rendered but before it was inserted into the DOM. Because this is avoidable and the cause of significant performance issues in applications, this behavior is deprecated. If you want to use the debugger to find out what caused this, you can set ENV.RAISE_ON_DEPRECATION to true.");
+ // Observes the given property on the context and
+ // tells the Ember._HandlebarsBoundView to re-render. If property
+ // is an empty string, we are printing the current context
+ // object ({{this}}) so updating it is not our responsibility.
+ if (path !== '') {
+ Ember.addObserver(pathRoot, path, observer);
- view._notifyWillRerender();
+ view.one('willClearRender', function() {
+ Ember.removeObserver(pathRoot, path, observer);
+ });
+ }
+ } else {
+ // The object is not observable, so just render it out and
+ // be done with it.
+ data.buffer.push(handlebarsGet(pathRoot, path, options));
+ }
+}
- view.clearRenderedChildren();
- view.renderToBuffer(view.buffer, 'replaceWith');
- },
+function simpleBind(property, options) {
+ var data = options.data,
+ view = data.view,
+ currentContext = this,
+ pathRoot, path, normalized,
+ observer;
- // when a view is rendered in a buffer, appending a child
- // view will render that view and append the resulting
- // buffer into its buffer.
- appendChild: function(view, childView, options) {
- var buffer = view.buffer;
+ normalized = normalizePath(currentContext, property, data);
- childView = this.createChildView(childView, options);
- view._childViews.push(childView);
+ pathRoot = normalized.root;
+ path = normalized.path;
- childView.renderToBuffer(buffer);
+ // Set up observers for observable objects
+ if ('object' === typeof this) {
+ if (data.insideGroup) {
+ observer = function() {
+ Ember.run.once(view, 'rerender');
+ };
- view.propertyDidChange('childViews');
+ var result = handlebarsGet(pathRoot, path, options);
+ if (result === null || result === undefined) { result = ""; }
+ data.buffer.push(result);
+ } else {
+ var bindView = new Ember._SimpleHandlebarsView(
+ path, pathRoot, !options.hash.unescaped, options.data
+ );
- return childView;
- },
+ bindView._parentView = view;
+ view.appendChild(bindView);
- // when a view is rendered in a buffer, destroying the
- // element will simply destroy the buffer and put the
- // state back into the preRender state.
- destroyElement: function(view) {
- view.clearBuffer();
- view._notifyWillDestroyElement();
- view.transitionTo('preRender');
+ observer = function() {
+ Ember.run.scheduleOnce('render', bindView, 'rerender');
+ };
+ }
- return view;
- },
+ // Observes the given property on the context and
+ // tells the Ember._HandlebarsBoundView to re-render. If property
+ // is an empty string, we are printing the current context
+ // object ({{this}}) so updating it is not our responsibility.
+ if (path !== '') {
+ Ember.addObserver(pathRoot, path, observer);
- empty: function() {
- Ember.assert("Emptying a view in the inBuffer state is not allowed and should not happen under normal circumstances. Most likely there is a bug in your application. This may be due to excessive property change notifications.");
- },
+ view.one('willClearRender', function() {
+ Ember.removeObserver(pathRoot, path, observer);
+ });
+ }
+ } else {
+ // The object is not observable, so just render it out and
+ // be done with it.
+ data.buffer.push(handlebarsGet(pathRoot, path, options));
+ }
+}
- renderToBufferIfNeeded: function (view) {
- return view.buffer;
- },
+/**
+ @private
- // It should be impossible for a rendered view to be scheduled for
- // insertion.
- insertElement: function() {
- throw "You can't insert an element that has already been rendered";
- },
+ '_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
+ helper resolves that.
- setElement: function(view, value) {
- if (value === null) {
- view.transitionTo('preRender');
- } else {
- view.clearBuffer();
- view.transitionTo('hasElement');
- }
+ This would not be typically invoked by directly.
- return value;
+ @method _triageMustache
+ @for Ember.Handlebars.helpers
+ @param {String} property Property/helperID to triage
+ @param {Function} fn Context to provide for rendering
+ @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);
+ if (helpers[property]) {
+ return helpers[property].call(this, fn);
}
-};
+ else {
+ return helpers.bind.apply(this, arguments);
+ }
+});
+/**
+ @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`:
+ ```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 DOM. Note
+ that if you need to support IE7 and IE8 you must modify the model objects
+ properties using `Ember.get()` and `Ember.set()` for this to work as it
+ relies on Ember's KVO system. For all other browsers this will be handled for
+ you automatically.
-(function() {
-/**
-@module ember
-@submodule ember-views
+ @method bind
+ @for Ember.Handlebars.helpers
+ @param {String} property Property to bind
+ @param {Function} fn Context to provide for rendering
+ @return {String} HTML string
*/
+EmberHandlebars.registerHelper('bind', function(property, options) {
+ Ember.assert("You cannot pass more than one argument to the bind helper", arguments.length <= 2);
-var get = Ember.get, set = Ember.set, meta = Ember.meta;
+ var context = (options.contexts && options.contexts[0]) || this;
-Ember.View.states.hasElement = {
- parentState: Ember.View.states._default,
+ if (!options.fn) {
+ return simpleBind.call(context, property, options);
+ }
- $: function(view, sel) {
- var elem = get(view, 'element');
- return sel ? Ember.$(sel, elem) : Ember.$(elem);
- },
+ return bind.call(context, property, options, false, function(result) {
+ return !Ember.isNone(result);
+ });
+});
- getElement: function(view) {
- var parent = get(view, 'parentView');
- if (parent) { parent = get(parent, 'element'); }
- if (parent) { return view.findElementInParentElement(parent); }
- return Ember.$("#" + get(view, 'elementId'))[0];
- },
+/**
+ @private
- setElement: function(view, value) {
- if (value === null) {
- view.transitionTo('preRender');
+ Use the `boundIf` helper to create a conditional that re-evaluates
+ whenever the truthiness of the bound value changes.
+
+ ```handlebars
+ {{#boundIf "content.shouldDisplayTitle"}}
+ {{content.title}}
+ {{/boundIf}}
+ ```
+
+ @method boundIf
+ @for Ember.Handlebars.helpers
+ @param {String} property Property to bind
+ @param {Function} fn Context to provide for rendering
+ @return {String} HTML string
+*/
+EmberHandlebars.registerHelper('boundIf', function(property, fn) {
+ var context = (fn.contexts && fn.contexts[0]) || this;
+ var func = function(result) {
+ if (Ember.typeOf(result) === 'array') {
+ return get(result, 'length') !== 0;
} else {
- throw "You cannot set an element to a non-null value when the element is already in the DOM.";
+ return !!result;
}
+ };
- return value;
- },
+ return bind.call(context, property, fn, true, func, func);
+});
- // once the view has been inserted into the DOM, rerendering is
- // deferred to allow bindings to synchronize.
- rerender: function(view) {
- view._notifyWillRerender();
+/**
+ @method with
+ @for Ember.Handlebars.helpers
+ @param {Function} context
+ @param {Hash} options
+ @return {String} HTML string
+*/
+EmberHandlebars.registerHelper('with', function(context, options) {
+ if (arguments.length === 4) {
+ var keywordName, path, rootPath, normalized;
- view.clearRenderedChildren();
+ Ember.assert("If you pass more than one argument to the with helper, it must be in the form #with foo as bar", arguments[1] === "as");
+ options = arguments[3];
+ keywordName = arguments[2];
+ path = arguments[0];
- view.domManager.replace(view);
- return view;
- },
+ Ember.assert("You must pass a block to the with helper", options.fn && options.fn !== Handlebars.VM.noop);
- // once the view is already in the DOM, destroying it removes it
- // from the DOM, nukes its element, and puts it back into the
- // preRender state if inDOM.
+ if (Ember.isGlobalPath(path)) {
+ Ember.bind(options.data.keywords, keywordName, path);
+ } else {
+ normalized = normalizePath(this, path, options.data);
+ path = normalized.path;
+ rootPath = normalized.root;
- destroyElement: function(view) {
- view._notifyWillDestroyElement();
- view.domManager.remove(view);
- set(view, 'element', null);
- if (view._scheduledInsert) {
- Ember.run.cancel(view._scheduledInsert);
- view._scheduledInsert = null;
- }
- return view;
- },
+ // This is a workaround for the fact that you cannot bind separate objects
+ // together. When we implement that functionality, we should use it here.
+ var contextKey = Ember.$.expando + Ember.guidFor(rootPath);
+ options.data.keywords[contextKey] = rootPath;
- empty: function(view) {
- var _childViews = view._childViews, len, idx;
- if (_childViews) {
- len = _childViews.length;
- for (idx = 0; idx < len; idx++) {
- _childViews[idx]._notifyWillDestroyElement();
- }
+ // if the path is '' ("this"), just bind directly to the current context
+ var contextPath = path ? contextKey + '.' + path : contextKey;
+ Ember.bind(options.data.keywords, keywordName, contextPath);
}
- view.domManager.empty(view);
- },
- // Handle events from `Ember.EventDispatcher`
- handleEvent: function(view, eventName, evt) {
- if (view.has(eventName)) {
- // Handler should be able to re-dispatch events, so we don't
- // preventDefault or stopPropagation.
- return view.trigger(eventName, evt);
- } else {
- return true; // continue event propagation
- }
+ return bind.call(this, path, options, true, function(result) {
+ return !Ember.isNone(result);
+ });
+ } else {
+ Ember.assert("You must pass exactly one argument to the with helper", arguments.length === 2);
+ Ember.assert("You must pass a block to the with helper", options.fn && options.fn !== Handlebars.VM.noop);
+ return helpers.bind.call(options.contexts[0], context, options);
}
-};
+});
-Ember.View.states.inDOM = {
- parentState: Ember.View.states.hasElement,
- insertElement: function(view, fn) {
- throw "You can't insert an element into the DOM that has already been inserted";
- }
-};
+/**
+ See `boundIf`
-})();
+ @method if
+ @for Ember.Handlebars.helpers
+ @param {Function} context
+ @param {Hash} options
+ @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);
+ Ember.assert("You must pass a block to the if helper", options.fn && options.fn !== Handlebars.VM.noop);
+
+ return helpers.boundIf.call(options.contexts[0], context, options);
+});
+
+/**
+ @method unless
+ @for Ember.Handlebars.helpers
+ @param {Function} context
+ @param {Hash} options
+ @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);
+ Ember.assert("You must pass a block to the unless helper", options.fn && options.fn !== Handlebars.VM.noop);
+ var fn = options.fn, inverse = options.inverse;
+
+ options.fn = inverse;
+ options.inverse = fn;
+ return helpers.boundIf.call(options.contexts[0], context, options);
+});
-(function() {
/**
-@module ember
-@submodule ember-views
-*/
+ `bindAttr` allows you to create a binding between DOM element attributes and
+ Ember objects. For example:
-var destroyedError = "You can't call %@ on a destroyed view", fmt = Ember.String.fmt;
+ ```handlebars
+ <img {{bindAttr src="imageUrl" alt="imageTitle"}}>
+ ```
-Ember.View.states.destroyed = {
- parentState: Ember.View.states._default,
+ The above handlebars template will fill the `<img>`'s `src` attribute will
+ the value of the property referenced with `"imageUrl"` and its `alt`
+ attribute with the value of the property referenced with `"imageTitle"`.
- appendChild: function() {
- throw fmt(destroyedError, ['appendChild']);
- },
- rerender: function() {
- throw fmt(destroyedError, ['rerender']);
- },
- destroyElement: function() {
- throw fmt(destroyedError, ['destroyElement']);
- },
- empty: function() {
- throw fmt(destroyedError, ['empty']);
- },
+ If the rendering context of this template is the following object:
- setElement: function() {
- throw fmt(destroyedError, ["set('element', ...)"]);
- },
+ ```javascript
+ {
+ imageUrl: 'http://lolcats.info/haz-a-funny',
+ imageTitle: 'A humorous image of a cat'
+ }
+ ```
- renderToBufferIfNeeded: function() {
- throw fmt(destroyedError, ["renderToBufferIfNeeded"]);
- },
+ The resulting HTML output will be:
- // Since element insertion is scheduled, don't do anything if
- // the view has been destroyed between scheduling and execution
- insertElement: Ember.K
-};
+ ```html
+ <img src="http://lolcats.info/haz-a-funny" alt="A humorous image of a cat">
+ ```
+ `bindAttr` cannot redeclare existing DOM element attributes. The use of `src`
+ in the following `bindAttr` example will be ignored and the hard coded value
+ of `src="/failwhale.gif"` will take precedence:
-})();
+ ```handlebars
+ <img src="/failwhale.gif" {{bindAttr src="imageUrl" alt="imageTitle"}}>
+ ```
+ ### `bindAttr` and the `class` attribute
+ `bindAttr` supports a special syntax for handling a number of cases unique
+ to the `class` DOM element attribute. The `class` attribute combines
+ multiple discreet values into a single attribute as a space-delimited
+ list of strings. Each string can be:
-(function() {
+ * a string return value of an object's property.
+ * a boolean return value of an object's property
+ * a hard-coded value
-})();
+ A string return value works identically to other uses of `bindAttr`. The
+ return value of the property will become the value of the attribute. For
+ example, the following view and template:
+ ```javascript
+ AView = Ember.View.extend({
+ someProperty: function(){
+ return "aValue";
+ }.property()
+ })
+ ```
+ ```handlebars
+ <img {{bindAttr class="view.someProperty}}>
+ ```
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ Result in the following rendered output:
-var get = Ember.get, set = Ember.set, meta = Ember.meta;
-var forEach = Ember.EnumerableUtils.forEach;
+ ```html
+ <img class="aValue">
+ ```
-var childViewsProperty = Ember.computed(function() {
- return get(this, '_childViews');
-}).property('_childViews').cacheable();
+ A boolean return value will insert a specified class name if the property
+ returns `true` and remove the class name if the property returns `false`.
-/**
- 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.
+ A class name is provided via the syntax
+ `somePropertyName:class-name-if-true`.
- ## Setting Initial Child Views
- 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`:
+ ```javascript
+ AView = Ember.View.extend({
+ someBool: true
+ })
+ ```
- ``` javascript
- aContainer = Ember.ContainerView.create({
- childViews: [Ember.View.create(), Ember.View.create()]
- });
+ ```handlebars
+ <img {{bindAttr class="view.someBool:class-name-if-true"}}>
```
- You can also provide a list of property names whose values are instances of `Ember.View`:
+ Result in the following rendered output:
- ``` javascript
- aContainer = Ember.ContainerView.create({
- childViews: ['aView', 'bView', 'cView'],
- aView: Ember.View.create(),
- bView: Ember.View.create()
- cView: Ember.View.create()
- });
+ ```html
+ <img class="class-name-if-true">
```
- The two strategies can be combined:
+ An additional section of the binding can be provided if you want to
+ replace the existing class instead of removing it when the boolean
+ value changes:
- ``` javascript
- aContainer = Ember.ContainerView.create({
- childViews: ['aView', Ember.View.create()],
- aView: Ember.View.create()
- });
+ ```handlebars
+ <img {{bindAttr class="view.someBool:class-name-if-true:class-name-if-false"}}>
```
- 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.
+ A hard-coded value can be used by prepending `:` to the desired
+ class name: `:class-name-to-always-apply`.
- ## Adding and Removing Child Views
- The views in a container's `childViews` array should be added and removed by manipulating
- the `childViews` property directly.
+ ```handlebars
+ <img {{bindAttr class=":class-name-to-always-apply"}}>
+ ```
- To remove a view pass that view into a `removeObject` call on the container's `childViews` property.
+ Results in the following rendered output:
- Given an empty `<body>` the following code
+ ```html
+ <img class=":class-name-to-always-apply">
+ ```
- ``` 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")
- })
- });
+ All three strategies - string return value, boolean return value, and
+ hard-coded value – can be combined in a single declaration:
- aContainer.appendTo('body');
- ```
+ ```handlebars
+ <img {{bindAttr class=":class-name-to-always-apply view.someBool:class-name-if-true view.someProperty"}}>
+ ```
- Results in the HTML
+ @method bindAttr
+ @for Ember.Handlebars.helpers
+ @param {Hash} options
+ @return {String} HTML string
+*/
+EmberHandlebars.registerHelper('bindAttr', function(options) {
- ``` html
- <div class="ember-view the-container">
- <div class="ember-view">A</div>
- <div class="ember-view">B</div>
- </div>
- ```
+ var attrs = options.hash;
- Removing a view
+ Ember.assert("You must specify at least one hash argument to bindAttr", !!Ember.keys(attrs).length);
- ``` javascript
- aContainer.get('childViews'); // [aContainer.aView, aContainer.bView]
- aContainer.get('childViews').removeObject(aContainer.get('bView'));
- aContainer.get('childViews'); // [aContainer.aView]
- ```
+ var view = options.data.view;
+ var ret = [];
+ var ctx = this;
- Will result in the following HTML
+ // Generate a unique id for this element. This will be added as a
+ // data attribute to the element so it can be looked up when
+ // the bound property changes.
+ var dataId = ++Ember.uuid;
- ``` html
- <div class="ember-view the-container">
- <div class="ember-view">A</div>
- </div>
- ```
+ // Handle classes differently, as we can bind multiple classes
+ var classBindings = attrs['class'];
+ if (classBindings !== null && classBindings !== undefined) {
+ var classResults = EmberHandlebars.bindClasses(this, classBindings, view, dataId, options);
+ ret.push('class="' + Handlebars.Utils.escapeExpression(classResults.join(' ')) + '"');
+ delete attrs['class'];
+ }
- Similarly, adding a child view is accomplished by adding `Ember.View` instances to the
- container's `childViews` property.
+ var attrKeys = Ember.keys(attrs);
- Given an empty `<body>` the following code
+ // For each attribute passed, create an observer and emit the
+ // current value of the property as an attribute.
+ forEach.call(attrKeys, function(attr) {
+ var path = attrs[attr],
+ pathRoot, normalized;
- ``` 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")
- })
- });
+ Ember.assert(fmt("You must provide a String for a bound attribute, not %@", [path]), typeof path === 'string');
- aContainer.appendTo('body');
- ```
+ normalized = normalizePath(ctx, path, options.data);
- Results in the HTML
+ pathRoot = normalized.root;
+ path = normalized.path;
- ``` html
- <div class="ember-view the-container">
- <div class="ember-view">A</div>
- <div class="ember-view">B</div>
- </div>
- ```
+ var value = (path === 'this') ? pathRoot : handlebarsGet(pathRoot, path, options),
+ type = Ember.typeOf(value);
- Adding a view
+ Ember.assert(fmt("Attributes must be numbers, strings or booleans, not %@", [value]), value === null || value === undefined || type === 'number' || type === 'string' || type === 'boolean');
- ``` javascript
- AnotherViewClass = Ember.View.extend({
- template: Ember.Handlebars.compile("Another view")
- });
+ var observer, invoker;
- aContainer.get('childViews'); // [aContainer.aView, aContainer.bView]
- aContainer.get('childViews').pushObject(AnotherViewClass.create());
- aContainer.get('childViews'); // [aContainer.aView, aContainer.bView, <AnotherViewClass instance>]
- ```
+ observer = function observer() {
+ var result = handlebarsGet(pathRoot, path, options);
- Will result in the following HTML
+ Ember.assert(fmt("Attributes must be numbers, strings or booleans, not %@", [result]), result === null || result === undefined || typeof result === 'number' || typeof result === 'string' || typeof result === 'boolean');
- ``` 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>
- ```
+ var elem = view.$("[data-bindattr-" + dataId + "='" + dataId + "']");
+
+ // If we aren't able to find the element, it means the element
+ // to which we were bound has been removed from the view.
+ // In that case, we can assume the template has been re-rendered
+ // and we need to clean up the observer.
+ if (!elem || elem.length === 0) {
+ Ember.removeObserver(pathRoot, path, invoker);
+ return;
+ }
+ Ember.View.applyAttributeBindings(elem, attr, result);
+ };
- Direct manipulation of childViews presence or absence in the DOM via calls to
- `remove` or `removeFromParent` or calls to a container's `removeChild` may not behave
- correctly.
+ invoker = function() {
+ Ember.run.scheduleOnce('render', observer);
+ };
- Calling `remove()` on a child view will remove the view's HTML, but it will remain as part of its
- container's `childView`s property.
+ // Add an observer to the view for when the property changes.
+ // When the observer fires, find the element using the
+ // unique data id and update the attribute to the new value.
+ if (path !== 'this') {
+ Ember.addObserver(pathRoot, path, invoker);
- Calling `removeChild()` on the container will remove the passed view instance from the container's
- `childView`s but keep its HTML within the container's rendered view.
+ view.one('willClearRender', function() {
+ Ember.removeObserver(pathRoot, path, invoker);
+ });
+ }
- Calling `removeFromParent()` behaves as expected but should be avoided in favor of direct
- manipulation of a container's `childViews` property.
+ // if this changes, also change the logic in ember-views/lib/views/view.js
+ if ((type === 'string' || (type === 'number' && !isNaN(value)))) {
+ ret.push(attr + '="' + Handlebars.Utils.escapeExpression(value) + '"');
+ } else if (value && type === 'boolean') {
+ // The developer controls the attr name, so it should always be safe
+ ret.push(attr + '="' + attr + '"');
+ }
+ }, this);
- ``` 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")
- })
- });
+ // Add the unique identifier
+ // NOTE: We use all lower-case since Firefox has problems with mixed case in SVG
+ ret.push('data-bindattr-' + dataId + '="' + dataId + '"');
+ return new EmberHandlebars.SafeString(ret.join(' '));
+});
- aContainer.appendTo('body');
- ```
+/**
+ @private
- Results in the HTML
+ 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
+ change, the correct class name will be reapplied to the DOM element.
- ``` html
- <div class="ember-view the-container">
- <div class="ember-view">A</div>
- <div class="ember-view">B</div>
- </div>
- ```
+ For example, if you pass the string "fooBar", it will first look up the
+ "fooBar" value of the context. If that value is true, it will add the
+ "foo-bar" class to the current element (i.e., the dasherized form of
+ "fooBar"). If the value is a string, it will add that string as the class.
+ Otherwise, it will not add any new class name.
- Calling `aContainer.get('aView').removeFromParent()` will result in the following HTML
+ @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;
- ``` html
- <div class="ember-view the-container">
- <div class="ember-view">B</div>
- </div>
- ```
+ // Helper method to retrieve the property from the context and
+ // determine which class string to return, based on whether it is
+ // a Boolean or not.
+ var classStringForPath = function(root, parsedPath, options) {
+ var val,
+ path = parsedPath.path;
- And the `Ember.View` instance stored in `aContainer.aView` will be removed from `aContainer`'s
- `childViews` array.
+ if (path === 'this') {
+ val = root;
+ } else if (path === '') {
+ val = true;
+ } else {
+ val = handlebarsGet(root, path, options);
+ }
- ## Templates and Layout
+ return Ember.View._classStringForValue(path, val, parsedPath.className, parsedPath.falsyClassName);
+ };
- 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
- of its child views.
+ // For each property passed, loop through and setup
+ // an observer.
+ forEach.call(classBindings.split(' '), function(binding) {
- ## Binding a View to Display
+ // Variable in which the old class value is saved. The observer function
+ // closes over this variable, so it knows which string to remove when
+ // the property changes.
+ var oldClass;
- If you would like to display a single view in your ContainerView, you can set its `currentView`
- property. When the `currentView` property is set to a view instance, it will be added to the
- ContainerView's `childViews` array. If the `currentView` property is later changed to a
- different view, the new view will replace the old view. If `currentView` is set to `null`, the
- last `currentView` will be removed.
+ var observer, invoker;
- This functionality is useful for cases where you want to bind the display of a ContainerView to
- a controller or state manager. For example, you can bind the `currentView` of a container to
- a controller like this:
+ var parsedPath = Ember.View._parsePropertyPath(binding),
+ path = parsedPath.path,
+ pathRoot = context,
+ normalized;
- ``` javascript
- App.appController = Ember.Object.create({
- view: Ember.View.create({
- templateName: 'person_template'
- })
- });
- ```
+ if (path !== '' && path !== 'this') {
+ normalized = normalizePath(context, path, options.data);
- ``` handlebars
- {{view Ember.ContainerView currentViewBinding="App.appController.view"}}
- ```
+ pathRoot = normalized.root;
+ path = normalized.path;
+ }
- @class ContainerView
- @namespace Ember
- @extends Ember.View
-*/
+ // Set up an observer on the context. If the property changes, toggle the
+ // class name.
+ observer = function() {
+ // Get the current value of the property
+ newClass = classStringForPath(pathRoot, parsedPath, options);
+ elem = bindAttrId ? view.$("[data-bindattr-" + bindAttrId + "='" + bindAttrId + "']") : view.$();
-Ember.ContainerView = Ember.View.extend({
+ // If we can't find the element anymore, a parent template has been
+ // re-rendered and we've been nuked. Remove the observer.
+ if (!elem || elem.length === 0) {
+ Ember.removeObserver(pathRoot, path, invoker);
+ } else {
+ // If we had previously added a class to the element, remove it.
+ if (oldClass) {
+ elem.removeClass(oldClass);
+ }
- init: function() {
- this._super();
+ // If necessary, add a new class. Make sure we keep track of it so
+ // it can be removed in the future.
+ if (newClass) {
+ elem.addClass(newClass);
+ oldClass = newClass;
+ } else {
+ oldClass = null;
+ }
+ }
+ };
- var childViews = get(this, 'childViews');
- Ember.defineProperty(this, 'childViews', childViewsProperty);
+ invoker = function() {
+ Ember.run.scheduleOnce('render', observer);
+ };
- var _childViews = this._childViews;
+ if (path !== '' && path !== 'this') {
+ Ember.addObserver(pathRoot, path, invoker);
- forEach(childViews, function(viewName, idx) {
- var view;
+ view.one('willClearRender', function() {
+ Ember.removeObserver(pathRoot, path, invoker);
+ });
+ }
- if ('string' === typeof viewName) {
- view = get(this, viewName);
- view = this.createChildView(view);
- set(this, viewName, view);
- } else {
- view = this.createChildView(viewName);
- }
+ // We've already setup the observer; now we just need to figure out the
+ // correct behavior right now on the first pass through.
+ value = classStringForPath(pathRoot, parsedPath, options);
- _childViews[idx] = view;
- }, this);
+ if (value) {
+ ret.push(value);
- var currentView = get(this, 'currentView');
- if (currentView) _childViews.push(this.createChildView(currentView));
+ // Make sure we save the current value so that it can be removed if the
+ // observer fires.
+ oldClass = value;
+ }
+ });
- // Make the _childViews array observable
- Ember.A(_childViews);
+ return ret;
+};
- // Sets up an array observer on the child views array. This
- // observer will detect when child views are added or removed
- // and update the DOM to reflect the mutation.
- get(this, 'childViews').addArrayObserver(this, {
- willChange: 'childViewsWillChange',
- didChange: 'childViewsDidChange'
- });
- },
- /**
- @private
+})();
- Instructs each child view to render to the passed render buffer.
- @method render
- @param {Ember.RenderBuffer} buffer the buffer to render to
- */
- render: function(buffer) {
- this.forEachChildView(function(view) {
- view.renderToBuffer(buffer);
- });
- },
- /**
- @private
+(function() {
+/*globals Handlebars */
- When the container view is destroyed, tear down the child views
- array observer.
+// TODO: Don't require the entire module
+/**
+@module ember
+@submodule ember-handlebars
+*/
- @method willDestroy
- */
- willDestroy: function() {
- get(this, 'childViews').removeArrayObserver(this, {
- willChange: 'childViewsWillChange',
- didChange: 'childViewsDidChange'
- });
+var get = Ember.get, set = Ember.set;
+var PARENT_VIEW_PATH = /^parentView\./;
+var EmberHandlebars = Ember.Handlebars;
- this._super();
- },
+EmberHandlebars.ViewHelper = Ember.Object.create({
- /**
- @private
+ propertiesFromHTMLOptions: function(options, thisContext) {
+ var hash = options.hash, data = options.data;
+ var extensions = {},
+ classes = hash['class'],
+ dup = false;
- When a child view is removed, destroy its element so that
- it is removed from the DOM.
+ if (hash.id) {
+ extensions.elementId = hash.id;
+ dup = true;
+ }
- The array observer that triggers this action is set up in the
- `renderToBuffer` method.
+ if (classes) {
+ classes = classes.split(' ');
+ extensions.classNames = classes;
+ dup = true;
+ }
- @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
- **/
- childViewsWillChange: function(views, start, removed) {
- if (removed === 0) { return; }
+ if (hash.classBinding) {
+ extensions.classNameBindings = hash.classBinding.split(' ');
+ dup = true;
+ }
- var changedViews = views.slice(start, start+removed);
- this.initializeViews(changedViews, null, null);
+ if (hash.classNameBindings) {
+ if (extensions.classNameBindings === undefined) extensions.classNameBindings = [];
+ extensions.classNameBindings = extensions.classNameBindings.concat(hash.classNameBindings.split(' '));
+ dup = true;
+ }
- this.invokeForState('childViewsWillChange', views, start, removed);
- },
+ if (hash.attributeBindings) {
+ Ember.assert("Setting 'attributeBindings' via Handlebars is not allowed. Please subclass Ember.View and set it there instead.");
+ extensions.attributeBindings = null;
+ dup = true;
+ }
- /**
- @private
+ if (dup) {
+ hash = Ember.$.extend({}, hash);
+ delete hash.id;
+ delete hash['class'];
+ delete hash.classBinding;
+ }
- When a child view is added, make sure the DOM gets updated appropriately.
+ // Set the proper context for all bindings passed to the helper. This applies to regular attribute bindings
+ // as well as class name bindings. If the bindings are local, make them relative to the current context
+ // instead of the view.
+ var path;
- If the view has already rendered an element, we tell the child view to
- create an element and insert it into the DOM. If the enclosing container view
- has already written to a buffer, but not yet converted that buffer into an
- element, we insert the string representation of the child into the appropriate
- place in the buffer.
+ // Evaluate the context of regular attribute bindings:
+ for (var prop in hash) {
+ if (!hash.hasOwnProperty(prop)) { continue; }
- @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
- @param {Number} the number of child views added
- */
- childViewsDidChange: function(views, start, removed, added) {
- var len = get(views, 'length');
+ // Test if the property ends in "Binding"
+ if (Ember.IS_BINDING.test(prop) && typeof hash[prop] === 'string') {
+ path = this.contextualizeBindingPath(hash[prop], data);
+ if (path) { hash[prop] = path; }
+ }
+ }
- // No new child views were added; bail out.
- if (added === 0) return;
+ // Evaluate the context of class name bindings:
+ if (extensions.classNameBindings) {
+ for (var b in extensions.classNameBindings) {
+ var full = extensions.classNameBindings[b];
+ if (typeof full === 'string') {
+ // Contextualize the path of classNameBinding so this:
+ //
+ // classNameBinding="isGreen:green"
+ //
+ // is converted to this:
+ //
+ // classNameBinding="_parentView.context.isGreen:green"
+ var parsedPath = Ember.View._parsePropertyPath(full);
+ path = this.contextualizeBindingPath(parsedPath.path, data);
+ if (path) { extensions.classNameBindings[b] = path + parsedPath.classNames; }
+ }
+ }
+ }
- var changedViews = views.slice(start, start+added);
- this.initializeViews(changedViews, this, get(this, 'templateData'));
+ return Ember.$.extend(hash, extensions);
+ },
- // Let the current state handle the changes
- this.invokeForState('childViewsDidChange', views, start, added);
+ // Transform bindings from the current context to a context that can be evaluated within the view.
+ // Returns null if the path shouldn't be changed.
+ //
+ // TODO: consider the addition of a prefix that would allow this method to return `path`.
+ contextualizeBindingPath: function(path, data) {
+ var normalized = Ember.Handlebars.normalizePath(null, path, data);
+ if (normalized.isKeyword) {
+ return 'templateData.keywords.' + path;
+ } else if (Ember.isGlobalPath(path)) {
+ return null;
+ } else if (path === 'this') {
+ return '_parentView.context';
+ } else {
+ return '_parentView.context.' + path;
+ }
},
- initializeViews: function(views, parentView, templateData) {
- forEach(views, function(view) {
- set(view, '_parentView', parentView);
+ helper: function(thisContext, path, options) {
+ var inverse = options.inverse,
+ data = options.data,
+ view = data.view,
+ fn = options.fn,
+ hash = options.hash,
+ newView;
- if (!get(view, 'templateData')) {
- set(view, 'templateData', templateData);
- }
- });
- },
+ if ('string' === typeof path) {
+ newView = EmberHandlebars.get(thisContext, path, options);
+ Ember.assert("Unable to find view at path '" + path + "'", !!newView);
+ } else {
+ newView = path;
+ }
- currentView: null,
+ Ember.assert(Ember.String.fmt('You must pass a view to the #view helper, not %@ (%@)', [path, newView]), Ember.View.detect(newView) || Ember.View.detectInstance(newView));
- _currentViewWillChange: Ember.beforeObserver(function() {
- var childViews = get(this, 'childViews'),
- currentView = get(this, 'currentView');
+ var viewOptions = this.propertiesFromHTMLOptions(options, thisContext);
+ var currentView = data.view;
+ viewOptions.templateData = options.data;
+ var newViewProto = newView.proto ? newView.proto() : newView;
- if (currentView) {
- childViews.removeObject(currentView);
- currentView.destroy();
+ if (fn) {
+ Ember.assert("You cannot provide a template block if you also specified a templateName", !get(viewOptions, 'templateName') && !get(newViewProto, 'templateName'));
+ viewOptions.template = fn;
}
- }, 'currentView'),
-
- _currentViewDidChange: Ember.observer(function() {
- var childViews = get(this, 'childViews'),
- currentView = get(this, 'currentView');
- if (currentView) {
- childViews.pushObject(currentView);
+ // We only want to override the `_context` computed property if there is
+ // no specified controller. See View#_context for more information.
+ if (!newViewProto.controller && !newViewProto.controllerBinding && !viewOptions.controller && !viewOptions.controllerBinding) {
+ viewOptions._context = thisContext;
}
- }, 'currentView'),
- _ensureChildrenAreInDOM: function () {
- this.invokeForState('ensureChildrenAreInDOM', this);
+ currentView.appendChild(newView, viewOptions);
}
});
-// Ember.ContainerView extends the default view states to provide different
-// behavior for childViewsWillChange and childViewsDidChange.
-Ember.ContainerView.states = {
- parent: Ember.View.states,
-
- inBuffer: {
- childViewsDidChange: function(parentView, views, start, added) {
- var buffer = parentView.buffer,
- startWith, prev, prevBuffer, view;
-
- // Determine where to begin inserting the child view(s) in the
- // render buffer.
- if (start === 0) {
- // If views were inserted at the beginning, prepend the first
- // view to the render buffer, then begin inserting any
- // additional views at the beginning.
- view = views[start];
- startWith = start + 1;
- view.renderToBuffer(buffer, 'prepend');
- } else {
- // Otherwise, just insert them at the same place as the child
- // views mutation.
- view = views[start - 1];
- startWith = start;
- }
+/**
+ `{{view}}` inserts a new instance of `Ember.View` into a template passing its
+ options to the `Ember.View`'s `create` method and using the supplied block as
+ the view's own template.
- for (var i=startWith; i<start+added; i++) {
- prev = view;
- view = views[i];
- prevBuffer = prev.buffer;
- view.renderToBuffer(prevBuffer, 'insertAfter');
- }
- }
- },
+ An empty `<body>` and the following template:
- hasElement: {
- childViewsWillChange: function(view, views, start, removed) {
- for (var i=start; i<start+removed; i++) {
- views[i].remove();
- }
- },
+ ```handlebars
+ A span:
+ {{#view tagName="span"}}
+ hello.
+ {{/view}}
+ ```
- childViewsDidChange: function(view, views, start, added) {
- Ember.run.scheduleOnce('render', this, '_ensureChildrenAreInDOM');
- },
+ Will result in HTML structure:
- ensureChildrenAreInDOM: function(view) {
- var childViews = view.get('childViews'), i, len, childView, previous, buffer;
- for (i = 0, len = childViews.length; i < len; i++) {
- childView = childViews[i];
- buffer = childView.renderToBufferIfNeeded();
- if (buffer) {
- childView._notifyWillInsertElement();
- if (previous) {
- previous.domManager.after(previous, buffer.string());
- } else {
- view.domManager.prepend(view, buffer.string());
- }
- childView.transitionTo('inDOM');
- childView.propertyDidChange('element');
- childView._notifyDidInsertElement();
- }
- previous = childView;
- }
- }
- }
-};
+ ```html
+ <body>
+ <!-- Note: the handlebars template script
+ also results in a rendered Ember.View
+ which is the outer <div> here -->
-Ember.ContainerView.states.inDOM = {
- parentState: Ember.ContainerView.states.hasElement
-};
+ <div class="ember-view">
+ A span:
+ <span id="ember1" class="ember-view">
+ Hello.
+ </span>
+ </div>
+ </body>
+ ```
-Ember.ContainerView.reopen({
- states: Ember.ContainerView.states
-});
+ ### `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.
+ ```javascript
+ aView = Ember.View.create({
+ template: Ember.Handlebars.compile("{{#view}} my parent: {{parentView.elementId}} {{/view}}")
+ });
+ aView.appendTo('body');
+ ```
-(function() {
-/**
-@module ember
-@submodule ember-views
-*/
+ Will result in HTML structure:
-var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
+ ```html
+ <div id="ember1" class="ember-view">
+ <div id="ember2" class="ember-view">
+ my parent: ember1
+ </div>
+ </div>
+ ```
-/**
- `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
- views and their associated rendered HTML are updated when items in the array
- are added, removed, or replaced.
+ ### Setting CSS id and class attributes
- ## Setting content
- The managed collection of objects is referenced as the `Ember.CollectionView` instance's
- `content` property.
+ 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`.
- ``` javascript
- someItemsView = Ember.CollectionView.create({
- content: ['A', 'B','C']
- })
+ ```handlebars
+ {{#view tagName="span" id="a-custom-id"}}
+ hello.
+ {{/view}}
```
- The view for each item in the collection will have its `content` property set
- to the item.
-
- ## Specifying itemViewClass
- By default the view class for each item in the managed collection will be an instance
- of `Ember.View`. You can supply a different class by setting the `CollectionView`'s
- `itemViewClass` property.
+ Results in the following HTML structure:
- Given an empty `<body>` and the following code:
+ ```html
+ <div class="ember-view">
+ <span id="a-custom-id" class="ember-view">
+ hello.
+ </span>
+ </div>
+ ```
- ``` javascript
- someItemsView = Ember.CollectionView.create({
- classNames: ['a-collection'],
- content: ['A','B','C'],
- itemViewClass: Ember.View.extend({
- template: Ember.Handlebars.compile("the letter: {{view.content}}")
- })
- });
+ The HTML `class` attribute can be set on the `{{view}}`'s resulting element
+ with the `class` or `classNameBindings` options. The `class` option will
+ directly set the CSS `class` attribute and will not be passed to
+ `Ember.View.create`. `classNameBindings` will be passed to `create` and use
+ `Ember.View`'s class name binding functionality:
- someItemsView.appendTo('body');
+ ```handlebars
+ {{#view tagName="span" class="a-custom-class"}}
+ hello.
+ {{/view}}
```
- Will result in the following HTML structure
+ Results in the following HTML structure:
- ``` 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>
+ ```html
+ <div class="ember-view">
+ <span id="ember2" class="ember-view a-custom-class">
+ hello.
+ </span>
</div>
```
- ## Automatic matching of parent/child tagNames
+ ### Supplying a different view class
- Setting the `tagName` property of a `CollectionView` to any of
- "ul", "ol", "table", "thead", "tbody", "tfoot", "tr", or "select" will result
- in the item views receiving an appropriately matched `tagName` property.
+ `{{view}}` can take an optional first argument before its supplied options to
+ specify a path to a custom view class.
+ ```handlebars
+ {{#view "MyApp.CustomView"}}
+ hello.
+ {{/view}}
+ ```
- Given an empty `<body>` and the following code:
+ 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:
- ``` javascript
- anUndorderedListView = Ember.CollectionView.create({
- tagName: 'ul',
- content: ['A','B','C'],
- itemViewClass: Ember.View.extend({
- template: Ember.Handlebars.compile("the letter: {{view.content}}")
- })
+ ```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}}')
});
- anUndorderedListView.appendTo('body');
+ MyApp.OuterView.create().appendTo('body');
```
- Will result in the following HTML structure
+ Will result in the following HTML:
- ``` 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>
+ ```html
+ <div id="ember1" class="ember-view">
+ <div id="ember2" class="ember-view a-custom-view-class-as-property">
+ hi
+ </div>
+ </div>
```
- Additional tagName pairs can be provided by adding to `Ember.CollectionView.CONTAINER_MAP `
+ ### Blockless use
- ``` javascript
- Ember.CollectionView.CONTAINER_MAP['article'] = 'section'
+ If you supply a custom `Ember.View` subclass that specifies its own template
+ or provide a `templateName` option to `{{view}}` it can be used without
+ supplying a block. Attempts to use both a `templateName` option and supply a
+ block will throw an error.
+
+ ```handlebars
+ {{view "MyApp.ViewWithATemplateDefined"}}
```
+ ### `viewName` property
- ## Empty View
- You can provide an `Ember.View` subclass to the `Ember.CollectionView` instance as its
- `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.
+ 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.
- ``` javascript
- aListWithNothing = Ember.CollectionView.create({
- classNames: ['nothing']
- content: null,
- emptyView: Ember.View.extend({
- template: Ember.Handlebars.compile("The collection is empty")
- })
+ ```javascript
+ aView = Ember.View.create({
+ template: Ember.Handlebars.compile('{{#view viewName="aChildByName"}} hi {{/view}}')
});
- aListWithNothing.appendTo('body');
+ aView.appendTo('body');
+ aView.get('aChildByName') // the instance of Ember.View created by {{view}} helper
```
- Will result in the following HTML structure
+ @method view
+ @for Ember.Handlebars.helpers
+ @param {String} path
+ @param {Hash} options
+ @return {String} HTML string
+*/
+EmberHandlebars.registerHelper('view', function(path, options) {
+ Ember.assert("The view helper only takes a single argument", arguments.length <= 2);
- ``` html
- <div class="ember-view nothing">
- <div class="ember-view">
- The collection is empty
- </div>
+ // If no path is provided, treat path param as options.
+ if (path && path.data && path.data.isRenderData) {
+ options = path;
+ path = "Ember.View";
+ }
+
+ return EmberHandlebars.ViewHelper.helper(this, path, options);
+});
+
+
+})();
+
+
+
+(function() {
+/*globals Handlebars */
+
+// TODO: Don't require all of this module
+/**
+@module ember
+@submodule ember-handlebars
+*/
+
+var get = Ember.get, handlebarsGet = Ember.Handlebars.get, fmt = Ember.String.fmt;
+
+/**
+ `{{collection}}` is a `Ember.Handlebars` helper for adding instances of
+ `Ember.CollectionView` to a template. See `Ember.CollectionView` for
+ additional information on how a `CollectionView` functions.
+
+ `{{collection}}`'s primary use is as a block helper with a `contentBinding`
+ option pointing towards an `Ember.Array`-compatible object. An `Ember.View`
+ instance will be created for each item in its `content` property. Each view
+ will have its own `content` property set to the appropriate item in the
+ collection.
+
+ The provided block will be applied as the template for each item's view.
+
+ Given an empty `<body>` the following template:
+
+ ```handlebars
+ {{#collection contentBinding="App.items"}}
+ Hi {{view.content.name}}
+ {{/collection}}
+ ```
+
+ And the following application code
+
+ ```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
+
+ ```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>
```
- ## Adding and Removing items
- The `childViews` property of a `CollectionView` should not be directly manipulated. Instead,
- add, remove, replace items from its `content` property. This will trigger
- appropriate changes to its rendered HTML.
-
- ## Use in templates via the `{{collection}}` Ember.Handlebars helper
- Ember.Handlebars provides a helper specifically for adding `CollectionView`s to templates.
- See `Ember.Handlebars.collection` for more details
-
- @class CollectionView
- @namespace Ember
- @extends Ember.ContainerView
- @since Ember 0.9
-*/
-Ember.CollectionView = Ember.ContainerView.extend(
-/** @scope Ember.CollectionView.prototype */ {
-
- /**
- A list of items to be displayed by the Ember.CollectionView.
+ ### Blockless Use
- @property content
- @type Ember.Array
- @default null
- */
- content: null,
+ If you provide an `itemViewClass` option that has its own `template` you can
+ omit the block.
- /**
- @private
+ The following template:
- This provides metadata about what kind of empty view class this
- collection would like if it is being instantiated from another
- system (like Handlebars)
+ ```handlebars
+ {{collection contentBinding="App.items" itemViewClass="App.AnItemView"}}
+ ```
- @property emptyViewClass
- */
- emptyViewClass: Ember.View,
+ And application code
- /**
- An optional view to display if content is set to an empty array.
+ ```javascript
+ App = Ember.Application.create();
+ App.items = [
+ Ember.Object.create({name: 'Dave'}),
+ Ember.Object.create({name: 'Mary'}),
+ Ember.Object.create({name: 'Sara'})
+ ];
- @property emptyView
- @type Ember.View
- @default null
- */
- emptyView: null,
+ App.AnItemView = Ember.View.extend({
+ template: Ember.Handlebars.compile("Greetings {{view.content.name}}")
+ });
+ ```
- /**
- @property itemViewClass
- @type Ember.View
- @default Ember.View
- */
- itemViewClass: Ember.View,
+ Will result in the HTML structure below
- init: function() {
- var ret = this._super();
- this._contentDidChange();
- return ret;
- },
+ ```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>
+ ```
- _contentWillChange: Ember.beforeObserver(function() {
- var content = this.get('content');
+ ### Specifying a CollectionView subclass
- if (content) { content.removeArrayObserver(this); }
- var len = content ? get(content, 'length') : 0;
- this.arrayWillChange(content, 0, len);
- }, 'content'),
+ 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:
- /**
- @private
+ ```handlebars
+ {{#collection App.MyCustomCollectionClass contentBinding="App.items"}}
+ Hi {{view.content.name}}
+ {{/collection}}
+ ```
- Check to make sure that the content has changed, and if so,
- update the children directly. This is always scheduled
- asynchronously, to allow the element to be created before
- bindings have synchronized and vice versa.
+ ### Forwarded `item.*`-named Options
- @method _contentDidChange
- */
- _contentDidChange: Ember.observer(function() {
- var content = get(this, 'content');
+ As with the `{{view}}`, helper options passed to the `{{collection}}` will be
+ set on the resulting `Ember.CollectionView` as properties. Additionally,
+ options prefixed with `item` will be applied to the views rendered for each
+ item (note the camelcasing):
+
+ ```handlebars
+ {{#collection contentBinding="App.items"
+ itemTagName="p"
+ itemClassNames="greeting"}}
+ Howdy {{view.content.name}}
+ {{/collection}}
+ ```
- if (content) {
- Ember.assert(fmt("an Ember.CollectionView's content must implement Ember.Array. You passed %@", [content]), Ember.Array.detect(content));
- content.addArrayObserver(this);
- }
+ Will result in the following HTML structure:
- var len = content ? get(content, 'length') : 0;
- this.arrayDidChange(content, 0, null, len);
- }, 'content'),
+ ```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>
+ ```
- willDestroy: function() {
- var content = get(this, 'content');
- if (content) { content.removeArrayObserver(this); }
+ @method collection
+ @for Ember.Handlebars.helpers
+ @param {String} path
+ @param {Hash} options
+ @return {String} HTML string
+ @deprecated Use `{{each}}` helper instead.
+*/
+Ember.Handlebars.registerHelper('collection', function(path, options) {
+ Ember.deprecate("Using the {{collection}} helper without specifying a class has been deprecated as the {{each}} helper now supports the same functionality.", path !== 'collection');
- this._super();
- },
+ // If no path is provided, treat path param as options.
+ if (path && path.data && path.data.isRenderData) {
+ options = path;
+ path = undefined;
+ Ember.assert("You cannot pass more than one argument to the collection helper", arguments.length === 1);
+ } else {
+ Ember.assert("You cannot pass more than one argument to the collection helper", arguments.length === 2);
+ }
- arrayWillChange: function(content, start, removedCount) {
- // If the contents were empty before and this template collection has an
- // empty view remove it now.
- var emptyView = get(this, 'emptyView');
- if (emptyView && emptyView instanceof Ember.View) {
- emptyView.removeFromParent();
- }
+ var fn = options.fn;
+ var data = options.data;
+ var inverse = options.inverse;
+ var view = options.data.view;
- // Loop through child views that correspond with the removed items.
- // Note that we loop from the end of the array to the beginning because
- // we are mutating it as we go.
- var childViews = get(this, 'childViews'), childView, idx, len;
+ // If passed a path string, convert that into an object.
+ // Otherwise, just default to the standard class.
+ var collectionClass;
+ collectionClass = path ? handlebarsGet(this, path, options) : Ember.CollectionView;
+ Ember.assert(fmt("%@ #collection: Could not find collection class %@", [data.view, path]), !!collectionClass);
- len = get(childViews, 'length');
+ var hash = options.hash, itemHash = {}, match;
- var removingAll = removedCount === len;
+ // Extract item view class if provided else default to the standard class
+ var itemViewClass, itemViewPath = hash.itemViewClass;
+ var collectionPrototype = collectionClass.proto();
+ delete hash.itemViewClass;
+ itemViewClass = itemViewPath ? handlebarsGet(collectionPrototype, itemViewPath, options) : collectionPrototype.itemViewClass;
+ Ember.assert(fmt("%@ #collection: Could not find itemViewClass %@", [data.view, itemViewPath]), !!itemViewClass);
- if (removingAll) {
- this.invokeForState('empty');
- }
+ // Go through options passed to the {{collection}} helper and extract options
+ // that configure item views instead of the collection itself.
+ for (var prop in hash) {
+ if (hash.hasOwnProperty(prop)) {
+ match = prop.match(/^item(.)(.*)$/);
- for (idx = start + removedCount - 1; idx >= start; idx--) {
- childView = childViews[idx];
- if (removingAll) { childView.removedFromDOM = true; }
- childView.destroy();
+ if(match) {
+ // Convert itemShouldFoo -> shouldFoo
+ itemHash[match[1].toLowerCase() + match[2]] = hash[prop];
+ // Delete from hash as this will end up getting passed to the
+ // {{view}} helper method.
+ delete hash[prop];
+ }
}
- },
-
- /**
- Called when a mutation to the underlying content array occurs.
+ }
- This method will replay that mutation against the views that compose the
- Ember.CollectionView, ensuring that the view reflects the model.
+ var tagName = hash.tagName || collectionPrototype.tagName;
- This array observer is added in contentDidChange.
+ if (fn) {
+ itemHash.template = fn;
+ delete options.fn;
+ }
- @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'),
- childViews = get(this, 'childViews'),
- addedViews = [], view, item, idx, len, itemTagName;
+ var emptyViewClass;
+ if (inverse && inverse !== Handlebars.VM.noop) {
+ emptyViewClass = get(collectionPrototype, 'emptyViewClass');
+ emptyViewClass = emptyViewClass.extend({
+ template: inverse,
+ tagName: itemHash.tagName
+ });
+ } else if (hash.emptyViewClass) {
+ emptyViewClass = handlebarsGet(this, hash.emptyViewClass, options);
+ }
+ hash.emptyView = emptyViewClass;
- if ('string' === typeof itemViewClass) {
- itemViewClass = get(itemViewClass);
- }
+ if (hash.eachHelper === 'each') {
+ itemHash._context = Ember.computed(function() {
+ return get(this, 'content');
+ }).property('content');
+ delete hash.eachHelper;
+ }
- Ember.assert(fmt("itemViewClass must be a subclass of Ember.View, not %@", [itemViewClass]), Ember.View.detect(itemViewClass));
+ var viewString = view.toString();
- len = content ? get(content, 'length') : 0;
- if (len) {
- for (idx = start; idx < start+added; idx++) {
- item = content.objectAt(idx);
+ var viewOptions = Ember.Handlebars.ViewHelper.propertiesFromHTMLOptions({ data: data, hash: itemHash }, this);
+ hash.itemViewClass = itemViewClass.extend(viewOptions);
- view = this.createChildView(itemViewClass, {
- content: item,
- contentIndex: idx
- });
+ return Ember.Handlebars.helpers.view.call(this, collectionClass, options);
+});
- addedViews.push(view);
- }
- } else {
- var emptyView = get(this, 'emptyView');
- if (!emptyView) { return; }
- emptyView = this.createChildView(emptyView);
- addedViews.push(emptyView);
- set(this, 'emptyView', emptyView);
- }
- childViews.replace(start, 0, addedViews);
- },
+})();
- createChildView: function(view, attrs) {
- view = this._super(view, attrs);
- var itemTagName = get(view, 'tagName');
- var tagName = (itemTagName === null || itemTagName === undefined) ? Ember.CollectionView.CONTAINER_MAP[get(this, 'tagName')] : itemTagName;
- set(view, 'tagName', tagName);
+(function() {
+/*globals Handlebars */
+/**
+@module ember
+@submodule ember-handlebars
+*/
- return view;
- }
-});
+var handlebarsGet = Ember.Handlebars.get;
/**
- 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.
+ `unbound` allows you to output a property without binding. *Important:* The
+ output will not be updated if the property changes. Use with caution.
- @property CONTAINER_MAP
- @type Hash
- @static
- @final
+ ```handlebars
+ <div>{{unbound somePropertyThatDoesntChange}}</div>
+ ```
+
+ @method unbound
+ @for Ember.Handlebars.helpers
+ @param {String} property
+ @return {String} HTML string
*/
-Ember.CollectionView.CONTAINER_MAP = {
- ul: 'li',
- ol: 'li',
- table: 'tr',
- thead: 'tr',
- tbody: 'tr',
- tfoot: 'tr',
- tr: 'td',
- select: 'option'
-};
+Ember.Handlebars.registerHelper('unbound', function(property, fn) {
+ var context = (fn.contexts && fn.contexts[0]) || this;
+ return handlebarsGet(context, property, fn);
+});
})();
(function() {
+/*jshint debug:true*/
+/**
+@module ember
+@submodule ember-handlebars
+*/
-})();
+var handlebarsGet = Ember.Handlebars.get, normalizePath = Ember.Handlebars.normalizePath;
+/**
+ `log` allows you to output the value of a value in the current rendering
+ context.
+ ```handlebars
+ {{log myVariable}}
+ ```
+
+ @method log
+ @for Ember.Handlebars.helpers
+ @param {String} property
+*/
+Ember.Handlebars.registerHelper('log', function(property, options) {
+ var context = (options.contexts && options.contexts[0]) || this,
+ normalized = normalizePath(context, property, options.data),
+ pathRoot = normalized.root,
+ path = normalized.path,
+ value = (path === 'this') ? pathRoot : handlebarsGet(pathRoot, path, options);
+ Ember.Logger.log(value);
+});
-(function() {
-/*globals jQuery*/
/**
-Ember Views
+ Execute the `debugger` statement in the current context.
-@module ember
-@submodule ember-views
-@require ember-runtime
-@main ember-views
+ ```handlebars
+ {{debugger}}
+ ```
+
+ @method debugger
+ @for Ember.Handlebars.helpers
+ @param {String} property
*/
+Ember.Handlebars.registerHelper('debugger', function() {
+ debugger;
+});
})();
-(function() {
-var get = Ember.get, set = Ember.set;
+
+(function() {
/**
@module ember
-@submodule ember-states
+@submodule ember-handlebars
*/
-/**
- @class State
- @namespace Ember
- @extends Ember.Object
- @uses Ember.Evented
-*/
-Ember.State = Ember.Object.extend(Ember.Evented,
-/** @scope Ember.State.prototype */{
- isState: true,
+var get = Ember.get, set = Ember.set;
- /**
- A reference to the parent state.
+Ember.Handlebars.EachView = Ember.CollectionView.extend(Ember._Metamorph, {
+ itemViewClass: Ember._MetamorphView,
+ emptyViewClass: Ember._MetamorphView,
- @property parentState
- @type Ember.State
- */
- parentState: null,
- start: null,
+ createChildView: function(view, attrs) {
+ view = this._super(view, attrs);
- /**
- The name of this state.
+ // At the moment, if a container view subclass wants
+ // to insert keywords, it is responsible for cloning
+ // the keywords hash. This will be fixed momentarily.
+ var keyword = get(this, 'keyword');
- @property name
- @type String
- */
- name: null,
+ if (keyword) {
+ var data = get(view, 'templateData');
- /**
- The full path to this state.
+ data = Ember.copy(data);
+ data.keywords = view.cloneKeywords();
+ set(view, 'templateData', data);
- @property path
- @type String
- */
- path: Ember.computed(function() {
- var parentPath = get(this, 'parentState.path'),
- path = get(this, 'name');
+ var content = get(view, 'content');
- if (parentPath) {
- path = parentPath + '.' + path;
+ // In this case, we do not bind, because the `content` of
+ // a #each item cannot change.
+ data.keywords[keyword] = content;
}
- return path;
- }).property().cacheable(),
+ return view;
+ }
+});
- /**
- @private
+var GroupedEach = Ember.Handlebars.GroupedEach = function(context, path, options) {
+ var self = this,
+ normalized = Ember.Handlebars.normalizePath(context, path, options.data);
- Override the default event firing from Ember.Evented to
- also call methods with the given name.
+ this.context = context;
+ this.path = path;
+ this.options = options;
+ this.template = options.fn;
+ this.containingView = options.data.view;
+ this.normalizedRoot = normalized.root;
+ this.normalizedPath = normalized.path;
+ this.content = this.lookupContent();
- @method trigger
- @param name
- */
- trigger: function(name) {
- if (this[name]) {
- this[name].apply(this, [].slice.call(arguments, 1));
- }
- this._super.apply(this, arguments);
- },
+ this.addContentObservers();
+ this.addArrayObservers();
- init: function() {
- var states = get(this, 'states'), foundStates;
- set(this, 'childStates', Ember.A());
- set(this, 'eventTransitions', get(this, 'eventTransitions') || {});
+ this.containingView.on('willClearRender', function() {
+ self.destroy();
+ });
+};
- var name, value, transitionTarget;
+GroupedEach.prototype = {
+ contentWillChange: function() {
+ this.removeArrayObservers();
+ },
- // As a convenience, loop over the properties
- // of this state and look for any that are other
- // Ember.State instances or classes, and move them
- // to the `states` hash. This avoids having to
- // create an explicit separate hash.
+ contentDidChange: function() {
+ this.content = this.lookupContent();
+ this.addArrayObservers();
+ this.rerenderContainingView();
+ },
- if (!states) {
- states = {};
+ contentArrayWillChange: Ember.K,
- for (name in this) {
- if (name === "constructor") { continue; }
+ contentArrayDidChange: function() {
+ this.rerenderContainingView();
+ },
- if (value = this[name]) {
- if (transitionTarget = value.transitionTarget) {
- this.eventTransitions[name] = transitionTarget;
- }
+ lookupContent: function() {
+ return Ember.Handlebars.get(this.normalizedRoot, this.normalizedPath, this.options);
+ },
- this.setupChild(states, name, value);
- }
- }
+ addArrayObservers: function() {
+ this.content.addArrayObserver(this, {
+ willChange: 'contentArrayWillChange',
+ didChange: 'contentArrayDidChange'
+ });
+ },
- set(this, 'states', states);
- } else {
- for (name in states) {
- this.setupChild(states, name, states[name]);
- }
- }
+ removeArrayObservers: function() {
+ this.content.removeArrayObserver(this, {
+ willChange: 'contentArrayWillChange',
+ didChange: 'contentArrayDidChange'
+ });
+ },
- set(this, 'pathsCache', {});
- set(this, 'pathsCacheNoContext', {});
+ addContentObservers: function() {
+ Ember.addBeforeObserver(this.normalizedRoot, this.normalizedPath, this, this.contentWillChange);
+ Ember.addObserver(this.normalizedRoot, this.normalizedPath, this, this.contentDidChange);
},
- setupChild: function(states, name, value) {
- if (!value) { return false; }
+ removeContentObservers: function() {
+ Ember.removeBeforeObserver(this.normalizedRoot, this.normalizedPath, this.contentWillChange);
+ Ember.removeObserver(this.normalizedRoot, this.normalizedPath, this.contentDidChange);
+ },
- if (value.isState) {
- set(value, 'name', name);
- } else if (Ember.State.detect(value)) {
- value = value.create({
- name: name
- });
- }
+ render: function() {
+ var content = this.content,
+ contentLength = get(content, 'length'),
+ data = this.options.data,
+ template = this.template;
- if (value.isState) {
- set(value, 'parentState', this);
- get(this, 'childStates').pushObject(value);
- states[name] = value;
- return value;
+ data.insideEach = true;
+ for (var i = 0; i < contentLength; i++) {
+ template(content.objectAt(i), { data: data });
}
},
- lookupEventTransition: function(name) {
- var path, state = this;
+ rerenderContainingView: function() {
+ Ember.run.scheduleOnce('render', this.containingView, 'rerender');
+ },
- while(state && !path) {
- path = state.eventTransitions[name];
- state = state.get('parentState');
- }
+ destroy: function() {
+ this.removeContentObservers();
+ this.removeArrayObservers();
+ }
+};
- return path;
- },
+/**
+ The `{{#each}}` helper loops over elements in a collection, rendering its
+ block once for each item:
- /**
- A Boolean value indicating whether the state is a leaf state
- in the state hierarchy. This is false if the state has child
- states; otherwise it is true.
+ ```javascript
+ Developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}];
+ ```
- @property isLeaf
- @type Boolean
- */
- isLeaf: Ember.computed(function() {
- return !get(this, 'childStates').length;
- }).cacheable(),
+ ```handlebars
+ {{#each Developers}}
+ {{name}}
+ {{/each}}
+ ```
- /**
- A boolean value indicating whether the state takes a context.
- By default we assume all states take contexts.
+ `{{each}}` supports an alternative syntax with element naming:
- @property hasContext
- @default true
- */
- hasContext: true,
+ ```handlebars
+ {{#each person in Developers}}
+ {{person.name}}
+ {{/each}}
+ ```
- /**
- This is the default transition event.
+ When looping over objects that do not have properties, `{{this}}` can be used
+ to render the object:
- @event setup
- @param {Ember.StateManager} manager
- @param context
- @see Ember.StateManager#transitionEvent
- */
- setup: Ember.K,
+ ```javascript
+ DeveloperNames = ['Yehuda', 'Tom', 'Paul']
+ ```
- /**
- This event fires when the state is entered.
+ ```handlebars
+ {{#each DeveloperNames}}
+ {{this}}
+ {{/each}}
+ ```
- @event enter
- @param {Ember.StateManager} manager
- */
- enter: Ember.K,
+ ### Blockless Use
- /**
- This event fires when the state is exited.
+ 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.
- @event exit
- @param {Ember.StateManager} manager
- */
- exit: Ember.K
-});
+ The following template:
+
+ ```handlebars
+ {{#view App.MyView }}
+ {{each view.items itemViewClass="App.AnItemView"}}
+ {{/view}}
+ ```
+
+ And application code
-var Event = Ember.$ && Ember.$.Event;
+ ```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'})
+ ]
+ })
+ });
-Ember.State.reopenClass(
-/** @scope Ember.State */{
+ App.AnItemView = Ember.View.extend({
+ template: Ember.Handlebars.compile("Greetings {{name}}")
+ });
- /**
- Creates an action function for transitioning to the named state while preserving context.
+ App.initialize();
+ ```
- The following example StateManagers are equivalent:
+ Will result in the HTML structure below
- aManager = Ember.StateManager.create({
- stateOne: Ember.State.create({
- changeToStateTwo: Ember.State.transitionTo('stateTwo')
- }),
- stateTwo: Ember.State.create({})
- })
+ ```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>
+ ```
- bManager = Ember.StateManager.create({
- stateOne: Ember.State.create({
- changeToStateTwo: function(manager, context){
- manager.transitionTo('stateTwo', context)
- }
- }),
- stateTwo: Ember.State.create({})
- })
+ @method each
+ @for Ember.Handlebars.helpers
+ @param [name] {String} name for item (used with `in`)
+ @param path {String} path
+*/
+Ember.Handlebars.registerHelper('each', function(path, options) {
+ if (arguments.length === 4) {
+ Ember.assert("If you pass more than one argument to the each helper, it must be in the form #each foo in bar", arguments[1] === "in");
- @method transitionTo
- @static
- @param {String} target
- */
- transitionTo: function(target) {
- var event = function(stateManager, context) {
- if (Event && context instanceof Event) {
- if (context.hasOwnProperty('context')) {
- context = context.context;
- } else {
- // If we received an event and it doesn't contain
- // a context, don't pass along a superfluous
- // context to the target of the event.
- return stateManager.transitionTo(target);
- }
- }
+ var keywordName = arguments[0];
- stateManager.transitionTo(target, context);
- };
+ options = arguments[3];
+ path = arguments[2];
+ if (path === '') { path = "this"; }
+
+ options.hash.keyword = keywordName;
+ } else {
+ options.hash.eachHelper = 'each';
+ }
- event.transitionTarget = target;
+ options.hash.contentBinding = path;
+ // Set up emptyView as a metamorph with no tag
+ //options.hash.emptyViewClass = Ember._MetamorphView;
- return event;
+ if (options.data.insideGroup && !options.hash.groupedRows && !options.hash.itemViewClass) {
+ new Ember.Handlebars.GroupedEach(this, path, options).render();
+ } else {
+ return Ember.Handlebars.helpers.collection.call(this, 'Ember.Handlebars.EachView', options);
}
});
(function() {
/**
@module ember
-@submodule ember-states
+@submodule ember-handlebars
*/
-var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
-var arrayForEach = Ember.ArrayPolyfills.forEach;
/**
- A Transition takes the enter, exit and resolve states and normalizes
- them:
+ `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:
- * takes any passed in contexts into consideration
- * adds in `initialState`s
+ ```html
+ <script type="text/x-handlebars" data-template-name="logged_in_user">
+ {{#with loggedInUser}}
+ Last Login: {{lastLogin}}
+ User Info: {{template "user_info"}}
+ {{/with}}
+ </script>
+ ```
- @class Transition
- @private
-*/
-var Transition = function(raw) {
- this.enterStates = raw.enterStates.slice();
- this.exitStates = raw.exitStates.slice();
- this.resolveState = raw.resolveState;
+ ```html
+ <script type="text/x-handlebars" data-template-name="user_info">
+ Name: <em>{{name}}</em>
+ Karma: <em>{{karma}}</em>
+ </script>
+ ```
- this.finalState = raw.enterStates[raw.enterStates.length - 1] || raw.resolveState;
-};
+ 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,
+ they will be compiled and placed in this hash automatically.
-Transition.prototype = {
- /**
- Normalize the passed in enter, exit and resolve states.
+ You can also manually register templates by adding them to the hash:
- This process also adds `finalState` and `contexts` to the Transition object.
+ ```javascript
+ Ember.TEMPLATES["my_cool_template"] = Ember.Handlebars.compile('<b>{{user}}</b>');
+ ```
- @method normalize
- @param {Ember.StateManager} manager the state manager running the transition
- @param {Array} contexts a list of contexts passed into `transitionTo`
- */
- normalize: function(manager, contexts) {
- this.matchContextsToStates(contexts);
- this.addInitialStates();
- this.removeUnchangedContexts(manager);
- return this;
- },
+ @method template
+ @for Ember.Handlebars.helpers
+ @param {String} templateName the template to render
+*/
- /**
- 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.
+Ember.Handlebars.registerHelper('template', function(name, options) {
+ var template = Ember.TEMPLATES[name];
- @method matchContextsToStates
- @param {Array} contexts a list of contexts passed into `transitionTo`
- */
- matchContextsToStates: function(contexts) {
- var stateIdx = this.enterStates.length - 1,
- matchedContexts = [],
- state,
- context;
+ Ember.assert("Unable to find template with name '"+name+"'.", !!template);
- // Next, we will match the passed in contexts to the states they
- // represent.
- //
- // First, assign a context to each enter state in reverse order. If
- // any contexts are left, add a parent state to the list of states
- // to enter and exit, and assign a context to the parent state.
- //
- // If there are still contexts left when the state manager is
- // reached, raise an exception.
- //
- // This allows the following:
- //
- // |- root
- // | |- post
- // | | |- comments
- // | |- about (* current state)
- //
- // For `transitionTo('post.comments', post, post.get('comments')`,
- // the first context (`post`) will be assigned to `root.post`, and
- // the second context (`post.get('comments')`) will be assigned
- // to `root.post.comments`.
- //
- // For the following:
- //
- // |- root
- // | |- post
- // | | |- index (* current state)
- // | | |- comments
- //
- // For `transitionTo('post.comments', otherPost, otherPost.get('comments')`,
- // the `<root.post>` state will be added to the list of enter and exit
- // states because its context has changed.
+ Ember.TEMPLATES[name](this, { data: options.data });
+});
- while (contexts.length > 0) {
- if (stateIdx >= 0) {
- state = this.enterStates[stateIdx--];
- } else {
- if (this.enterStates.length) {
- state = get(this.enterStates[0], 'parentState');
- if (!state) { throw "Cannot match all contexts to states"; }
- } else {
- // If re-entering the current state with a context, the resolve
- // state will be the current state.
- state = this.resolveState;
- }
+Ember.Handlebars.registerHelper('partial', function(name, options) {
+ var nameParts = name.split("/"),
+ lastPart = nameParts[nameParts.length - 1];
- this.enterStates.unshift(state);
- this.exitStates.unshift(state);
- }
+ nameParts[nameParts.length - 1] = "_" + lastPart;
- // in routers, only states with dynamic segments have a context
- if (get(state, 'hasContext')) {
- context = contexts.pop();
- } else {
- context = null;
- }
+ var underscoredName = nameParts.join("/");
- matchedContexts.unshift(context);
- }
+ var template = Ember.TEMPLATES[underscoredName],
+ deprecatedTemplate = Ember.TEMPLATES[name];
- this.contexts = matchedContexts;
- },
+ Ember.deprecate("You tried to render the partial " + name + ", which should be at '" + underscoredName + "', but Ember found '" + name + "'. Please use a leading underscore in your partials", template);
+ Ember.assert("Unable to find partial with name '"+name+"'.", template || deprecatedTemplate);
- /**
- Add any `initialState`s to the list of enter states.
+ template = template || deprecatedTemplate;
- @method addInitialStates
- */
- addInitialStates: function() {
- var finalState = this.finalState, initialState;
+ template(this, { data: options.data });
+});
- while(true) {
- initialState = get(finalState, 'initialState') || 'start';
- finalState = get(finalState, 'states.' + initialState);
+})();
- if (!finalState) { break; }
- this.finalState = finalState;
- this.enterStates.push(finalState);
- this.contexts.push(undefined);
- }
- },
- /**
- 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.
+(function() {
+/**
+@module ember
+@submodule ember-handlebars
+*/
- @method removeUnchangedContexts
- @param {Ember.StateManager} manager passed in to look up the last
- context for a states
- */
- removeUnchangedContexts: function(manager) {
- // Start from the beginning of the enter states. If the state was added
- // to the list during the context matching phase, make sure the context
- // has actually changed since the last time the state was entered.
- while (this.enterStates.length > 0) {
- if (this.enterStates[0] !== this.exitStates[0]) { break; }
+var get = Ember.get, set = Ember.set;
- if (this.enterStates.length === this.contexts.length) {
- if (manager.getStateMeta(this.enterStates[0], 'context') !== this.contexts[0]) { break; }
- this.contexts.shift();
- }
+/**
+ When used in a Handlebars template that is assigned to an `Ember.View`
+ instance's `layout` property Ember will render the layout template first,
+ inserting the view's own rendered output at the `{{yield}}` location.
- this.resolveState = this.enterStates.shift();
- this.exitStates.shift();
- }
- }
-};
+ An empty `<body>` and the following application code:
-/**
- 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.
+ ```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>')
+ });
- ## Defining States
+ aView = AView.create();
+ aView.appendTo('body');
+ ```
- The states of StateManager can be declared in one of two ways. First, you can define
- a `states` property that contains all the states:
+ Will result in the following HTML output:
- managerA = Ember.StateManager.create({
- states: {
- stateOne: Ember.State.create(),
- stateTwo: Ember.State.create()
- }
- })
+ ```html
+ <body>
+ <div class='ember-view a-view-with-layout'>
+ <div class="wrapper">
+ <span>I am wrapped</span>
+ </div>
+ </div>
+ </body>
+ ```
- managerA.get('states')
- // {
- // stateOne: Ember.State.create(),
- // stateTwo: Ember.State.create()
- // }
+ 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.
- You can also add instances of `Ember.State` (or an `Ember.State` subclass) directly as properties
- of a StateManager. These states will be collected into the `states` property for you.
+ ```javascript
+ BView = Ember.View.extend({
+ classNames: ['a-view-with-layout'],
+ template: Ember.Handlebars.compile('{{yield}}')
+ });
- managerA = Ember.StateManager.create({
- stateOne: Ember.State.create(),
- stateTwo: Ember.State.create()
- })
+ bView = BView.create();
+ bView.appendTo('body');
- managerA.get('states')
- // {
- // stateOne: Ember.State.create(),
- // stateTwo: Ember.State.create()
- // }
+ // throws
+ // Uncaught Error: assertion failed: You called yield in a template that was not a layout
+ ```
- ## The Initial State
- When created a StateManager instance will immediately enter into the state
- defined as its `start` property or the state referenced by name in its
- `initialState` property:
+ @method yield
+ @for Ember.Handlebars.helpers
+ @param {Hash} options
+ @return {String} HTML string
+*/
+Ember.Handlebars.registerHelper('yield', function(options) {
+ var view = options.data.view, template;
- managerA = Ember.StateManager.create({
- start: Ember.State.create({})
- })
+ while (view && !get(view, 'layout')) {
+ view = get(view, 'parentView');
+ }
- managerA.get('currentState.name') // 'start'
+ Ember.assert("You called yield in a template that was not a layout", !!view);
- managerB = Ember.StateManager.create({
- initialState: 'beginHere',
- beginHere: Ember.State.create({})
- })
+ template = get(view, 'template');
- managerB.get('currentState.name') // 'beginHere'
+ if (template) { template(this, options); }
+});
- Because it is a property you may also provide a computed function if you wish to derive
- an `initialState` programmatically:
+})();
- managerC = Ember.StateManager.create({
- initialState: function(){
- if (someLogic) {
- return 'active';
- } else {
- return 'passive';
- }
- }.property(),
- active: Ember.State.create({}),
- passive: Ember.State.create({})
- })
- ## Moving Between States
- A StateManager can have any number of Ember.State objects as properties
- and can have a single one of these states as its current state.
- Calling `transitionTo` transitions between states:
+(function() {
- robotManager = Ember.StateManager.create({
- initialState: 'poweredDown',
- poweredDown: Ember.State.create({}),
- poweredUp: Ember.State.create({})
- })
+})();
- robotManager.get('currentState.name') // 'poweredDown'
- robotManager.transitionTo('poweredUp')
- robotManager.get('currentState.name') // 'poweredUp'
- Before transitioning into a new state the existing `currentState` will have its
- `exit` method called with the StateManager instance as its first argument and
- an object representing the transition as its second argument.
- After transitioning into a new state the new `currentState` will have its
- `enter` method called with the StateManager instance as its first argument and
- an object representing the transition as its second argument.
-
- robotManager = Ember.StateManager.create({
- initialState: 'poweredDown',
- poweredDown: Ember.State.create({
- exit: function(stateManager){
- console.log("exiting the poweredDown state")
- }
- }),
- poweredUp: Ember.State.create({
- enter: function(stateManager){
- console.log("entering the poweredUp state. Destroy all humans.")
- }
- })
- })
+(function() {
- robotManager.get('currentState.name') // 'poweredDown'
- robotManager.transitionTo('poweredUp')
- // will log
- // 'exiting the poweredDown state'
- // 'entering the poweredUp state. Destroy all humans.'
+})();
- Once a StateManager is already in a state, subsequent attempts to enter that state will
- not trigger enter or exit method calls. Attempts to transition into a state that the
- manager does not have will result in no changes in the StateManager's current state:
- robotManager = Ember.StateManager.create({
- initialState: 'poweredDown',
- poweredDown: Ember.State.create({
- exit: function(stateManager){
- console.log("exiting the poweredDown state")
- }
- }),
- poweredUp: Ember.State.create({
- enter: function(stateManager){
- console.log("entering the poweredUp state. Destroy all humans.")
- }
- })
- })
+(function() {
+/**
+@module ember
+@submodule ember-handlebars
+*/
- robotManager.get('currentState.name') // 'poweredDown'
- robotManager.transitionTo('poweredUp')
- // will log
- // 'exiting the poweredDown state'
- // 'entering the poweredUp state. Destroy all humans.'
- robotManager.transitionTo('poweredUp') // no logging, no state change
-
- robotManager.transitionTo('someUnknownState') // silently fails
- robotManager.get('currentState.name') // 'poweredUp'
-
-
- Each state property may itself contain properties that are instances of Ember.State.
- The StateManager can transition to specific sub-states in a series of transitionTo method calls or
- via a single transitionTo with the full path to the specific state. The StateManager will also
- keep track of the full path to its currentState
-
- robotManager = Ember.StateManager.create({
- initialState: 'poweredDown',
- poweredDown: Ember.State.create({
- charging: Ember.State.create(),
- charged: Ember.State.create()
- }),
- poweredUp: Ember.State.create({
- mobile: Ember.State.create(),
- stationary: Ember.State.create()
- })
- })
+var set = Ember.set, get = Ember.get;
- robotManager.get('currentState.name') // 'poweredDown'
+/**
+ 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.
- robotManager.transitionTo('poweredUp')
- robotManager.get('currentState.name') // 'poweredUp'
+ Example:
- robotManager.transitionTo('mobile')
- robotManager.get('currentState.name') // 'mobile'
+ ```handlebars
+ {{view Ember.Checkbox checkedBinding="receiveEmail"}}
+ ```
- // transition via a state path
- robotManager.transitionTo('poweredDown.charging')
- robotManager.get('currentState.name') // 'charging'
+ You can add a `label` tag yourself in the template where the `Ember.Checkbox`
+ is being used.
- robotManager.get('currentState.path') // 'poweredDown.charging'
+ ```html
+ <label>
+ {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}}
+ Some Title
+ </label>
+ ```
- Enter transition methods will be called for each state and nested child state in their
- hierarchical order. Exit methods will be called for each state and its nested states in
- reverse hierarchical order.
+ The `checked` attribute of an `Ember.Checkbox` object should always be set
+ through the Ember object or by interacting with its rendered element
+ representation via the mouse, keyboard, or touch. Updating the value of the
+ checkbox via jQuery will result in the checked value of the object and its
+ element losing synchronization.
- Exit transitions for a parent state are not called when entering into one of its child states,
- only when transitioning to a new section of possible states in the hierarchy.
+ ## Layout and LayoutName properties
- robotManager = Ember.StateManager.create({
- initialState: 'poweredDown',
- poweredDown: Ember.State.create({
- enter: function(){},
- exit: function(){
- console.log("exited poweredDown state")
- },
- charging: Ember.State.create({
- enter: function(){},
- exit: function(){}
- }),
- charged: Ember.State.create({
- enter: function(){
- console.log("entered charged state")
- },
- exit: function(){
- console.log("exited charged state")
- }
- })
- }),
- poweredUp: Ember.State.create({
- enter: function(){
- console.log("entered poweredUp state")
- },
- exit: function(){},
- mobile: Ember.State.create({
- enter: function(){
- console.log("entered mobile state")
- },
- exit: function(){}
- }),
- stationary: Ember.State.create({
- enter: function(){},
- exit: function(){}
- })
- })
- })
+ 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({
+ classNames: ['ember-checkbox'],
- robotManager.get('currentState.path') // 'poweredDown'
- robotManager.transitionTo('charged')
- // logs 'entered charged state'
- // but does *not* log 'exited poweredDown state'
- robotManager.get('currentState.name') // 'charged
+ tagName: 'input',
- robotManager.transitionTo('poweredUp.mobile')
- // logs
- // 'exited charged state'
- // 'exited poweredDown state'
- // 'entered poweredUp state'
- // 'entered mobile state'
+ attributeBindings: ['type', 'checked', 'disabled', 'tabindex'],
- During development you can set a StateManager's `enableLogging` property to `true` to
- receive console messages of state transitions.
+ type: "checkbox",
+ checked: false,
+ disabled: false,
- robotManager = Ember.StateManager.create({
- enableLogging: true
- })
+ init: function() {
+ this._super();
+ this.on("change", this, this._updateElementValue);
+ },
- ## Managing currentState with Actions
- To control which transitions between states are possible for a given state, StateManager
- can receive and route action messages to its states via the `send` method. Calling to `send` with
- an action name will begin searching for a method with the same name starting at the current state
- and moving up through the parent states in a state hierarchy until an appropriate method is found
- or the StateManager instance itself is reached.
-
- If an appropriately named method is found it will be called with the state manager as the first
- argument and an optional `context` object as the second argument.
-
- managerA = Ember.StateManager.create({
- initialState: 'stateOne.substateOne.subsubstateOne',
- stateOne: Ember.State.create({
- substateOne: Ember.State.create({
- anAction: function(manager, context){
- console.log("an action was called")
- },
- subsubstateOne: Ember.State.create({})
- })
- })
- })
+ _updateElementValue: function() {
+ set(this, 'checked', this.$().prop('checked'));
+ }
+});
- managerA.get('currentState.name') // 'subsubstateOne'
- managerA.send('anAction')
- // 'stateOne.substateOne.subsubstateOne' has no anAction method
- // so the 'anAction' method of 'stateOne.substateOne' is called
- // and logs "an action was called"
- // with managerA as the first argument
- // and no second argument
+})();
- someObject = {}
- managerA.send('anAction', someObject)
- // the 'anAction' method of 'stateOne.substateOne' is called again
- // with managerA as the first argument and
- // someObject as the second argument.
- If the StateManager attempts to send an action but does not find an appropriately named
- method in the current state or while moving upwards through the state hierarchy
- it will throw a new Ember.Error. Action detection only moves upwards through the state hierarchy
- from the current state. It does not search in other portions of the hierarchy.
-
- managerB = Ember.StateManager.create({
- initialState: 'stateOne.substateOne.subsubstateOne',
- stateOne: Ember.State.create({
- substateOne: Ember.State.create({
- subsubstateOne: Ember.State.create({})
- })
- }),
- stateTwo: Ember.State.create({
- anAction: function(manager, context){
- // will not be called below because it is
- // not a parent of the current state
- }
- })
- })
+(function() {
+/**
+@module ember
+@submodule ember-handlebars
+*/
- managerB.get('currentState.name') // 'subsubstateOne'
- managerB.send('anAction')
- // Error: <Ember.StateManager:ember132> could not
- // respond to event anAction in state stateOne.substateOne.subsubstateOne.
+var get = Ember.get, set = Ember.set;
- Inside of an action method the given state should delegate `transitionTo` calls on its
- StateManager.
+/**
+ Shared mixin used by `Ember.TextField` and `Ember.TextArea`.
- robotManager = Ember.StateManager.create({
- initialState: 'poweredDown.charging',
- poweredDown: Ember.State.create({
- charging: Ember.State.create({
- chargeComplete: function(manager, context){
- manager.transitionTo('charged')
- }
- }),
- charged: Ember.State.create({
- boot: function(manager, context){
- manager.transitionTo('poweredUp')
- }
- })
- }),
- poweredUp: Ember.State.create({
- beginExtermination: function(manager, context){
- manager.transitionTo('rampaging')
- },
- rampaging: Ember.State.create()
- })
- })
+ @class TextSupport
+ @namespace Ember
+ @extends Ember.Mixin
+ @private
+*/
+Ember.TextSupport = Ember.Mixin.create({
+ value: "",
- robotManager.get('currentState.name') // 'charging'
- robotManager.send('boot') // throws error, no boot action
- // in current hierarchy
- robotManager.get('currentState.name') // remains 'charging'
+ attributeBindings: ['placeholder', 'disabled', 'maxlength', 'tabindex'],
+ placeholder: null,
+ disabled: false,
+ maxlength: null,
- robotManager.send('beginExtermination') // throws error, no beginExtermination
- // action in current hierarchy
- robotManager.get('currentState.name') // remains 'charging'
+ insertNewline: Ember.K,
+ cancel: Ember.K,
- robotManager.send('chargeComplete')
- robotManager.get('currentState.name') // 'charged'
+ init: function() {
+ this._super();
+ this.on("focusOut", this, this._elementValueDidChange);
+ this.on("change", this, this._elementValueDidChange);
+ this.on("paste", this, this._elementValueDidChange);
+ this.on("cut", this, this._elementValueDidChange);
+ this.on("input", this, this._elementValueDidChange);
+ this.on("keyUp", this, this.interpretKeyEvents);
+ },
- robotManager.send('boot')
- robotManager.get('currentState.name') // 'poweredUp'
+ interpretKeyEvents: function(event) {
+ var map = Ember.TextSupport.KEY_EVENTS;
+ var method = map[event.keyCode];
- robotManager.send('beginExtermination', allHumans)
- robotManager.get('currentState.name') // 'rampaging'
+ this._elementValueDidChange();
+ if (method) { return this[method](event); }
+ },
- Transition actions can also be created using the `transitionTo` method of the Ember.State class. The
- following example StateManagers are equivalent:
+ _elementValueDidChange: function() {
+ set(this, 'value', this.$().val());
+ }
- aManager = Ember.StateManager.create({
- stateOne: Ember.State.create({
- changeToStateTwo: Ember.State.transitionTo('stateTwo')
- }),
- stateTwo: Ember.State.create({})
- })
+});
- bManager = Ember.StateManager.create({
- stateOne: Ember.State.create({
- changeToStateTwo: function(manager, context){
- manager.transitionTo('stateTwo', context)
- }
- }),
- stateTwo: Ember.State.create({})
- })
+Ember.TextSupport.KEY_EVENTS = {
+ 13: 'insertNewline',
+ 27: 'cancel'
+};
- @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();
- set(this, 'stateMeta', Ember.Map.create());
+(function() {
+/**
+@module ember
+@submodule ember-handlebars
+*/
- var initialState = get(this, 'initialState');
+var get = Ember.get, set = Ember.set;
- if (!initialState && get(this, 'states.start')) {
- initialState = 'start';
- }
+/**
+ 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`),
+ live-updating as the user inputs text.
- if (initialState) {
- this.transitionTo(initialState);
- Ember.assert('Failed to transition to initial state "' + initialState + '"', !!get(this, 'currentState'));
- }
- },
+ Example:
- stateMetaFor: function(state) {
- var meta = get(this, 'stateMeta'),
- stateMeta = meta.get(state);
+ ```handlebars
+ {{view Ember.TextField valueBinding="firstName"}}
+ ```
- if (!stateMeta) {
- stateMeta = {};
- meta.set(state, stateMeta);
- }
+ ## Layout and LayoutName properties
- return stateMeta;
- },
+ Because HTML `input` elements are self closing `layout` and `layoutName`
+ properties will not be applied. See `Ember.View`'s layout section for more
+ information.
- setStateMeta: function(state, key, value) {
- return set(this.stateMetaFor(state), key, value);
- },
+ ## HTML Attributes
- getStateMeta: function(state, key) {
- return get(this.stateMetaFor(state), key);
- },
+ By default `Ember.TextField` provides support for `type`, `value`, `size`,
+ `placeholder`, `disabled`, `maxlength` and `tabindex` attributes on a
+ test field. If you need to support more attributes have a look at the
+ `attributeBindings` property in `Ember.View`'s HTML Attributes section.
- /**
- 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.
+ To globally add support for additional attributes you can reopen
+ `Ember.TextField` or `Ember.TextSupport`.
- @property currentState
- @type Ember.State
- */
- currentState: null,
+ ```javascript
+ Ember.TextSupport.reopen({
+ attributeBindings: ["required"]
+ })
+ ```
- /**
- The path of the current state. Returns a string representation of the current
- state.
+ @class TextField
+ @namespace Ember
+ @extends Ember.View
+ @uses Ember.TextSupport
+*/
+Ember.TextField = Ember.View.extend(Ember.TextSupport,
+ /** @scope Ember.TextField.prototype */ {
- @property currentPath
- @type String
- */
- currentPath: Ember.computed('currentState', function() {
- return get(this, 'currentState.path');
- }).cacheable(),
+ classNames: ['ember-text-field'],
+ tagName: "input",
+ attributeBindings: ['type', 'value', 'size'],
/**
- The name of transitionEvent that this stateManager will dispatch
+ The `value` attribute of the input element. As the user inputs text, this
+ property is updated live.
- @property transitionEvent
+ @property value
@type String
- @default 'setup'
+ @default ""
*/
- transitionEvent: 'setup',
+ value: "",
/**
- If set to true, `errorOnUnhandledEvents` will cause an exception to be
- 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.
+ The `type` attribute of the input element.
- @property errorOnUnhandledEvents
- @type Boolean
- @default true
+ @property type
+ @type String
+ @default "text"
*/
- errorOnUnhandledEvent: true,
-
- send: function(event, context) {
- Ember.assert('Cannot send event "' + event + '" while currentState is ' + get(this, 'currentState'), get(this, 'currentState'));
- return this.sendRecursively(event, get(this, 'currentState'), context);
- },
-
- sendRecursively: function(event, currentState, context) {
- var log = this.enableLogging,
- action = currentState[event];
-
- // Test to see if the action is a method that
- // can be invoked. Don't blindly check just for
- // existence, because it is possible the state
- // manager has a child state of the given name,
- // and we should still raise an exception in that
- // case.
- if (typeof action === 'function') {
- if (log) { Ember.Logger.log(fmt("STATEMANAGER: Sending event '%@' to state %@.", [event, get(currentState, 'path')])); }
- return action.call(currentState, this, context);
- } else {
- var parentState = get(currentState, 'parentState');
- if (parentState) {
- return this.sendRecursively(event, parentState, context);
- } else if (get(this, 'errorOnUnhandledEvent')) {
- throw new Ember.Error(this.toString() + " could not respond to event " + event + " in state " + get(this, 'currentState.path') + ".");
- }
- }
- },
+ type: "text",
/**
- Finds a state by its state path.
-
- Example:
+ The `size` of the text field in characters.
- manager = Ember.StateManager.create({
- root: Ember.State.create({
- dashboard: Ember.State.create()
- })
- });
+ @property size
+ @type String
+ @default null
+ */
+ size: null,
- manager.getStateByPath(manager, "root.dashboard")
+ /**
+ The action to be sent when the user presses the return key.
- // returns the dashboard state
+ This is similar to the `{{action}}` helper, but is fired when
+ the user presses the return key when editing a text field, and sends
+ the value of the field as the context.
- @method getStateByPath
- @param {Ember.State} root the state to start searching from
- @param {String} path the state path to follow
- @return {Ember.State} the state at the end of the path
+ @property action
+ @type String
+ @default null
*/
- getStateByPath: function(root, path) {
- var parts = path.split('.'),
- state = root;
-
- for (var i=0, l=parts.length; i<l; i++) {
- state = get(get(state, 'states'), parts[i]);
- if (!state) { break; }
- }
-
- return state;
- },
+ action: null,
- findStateByPath: function(state, path) {
- var possible;
+ insertNewline: function() {
+ var controller = get(this, 'controller'),
+ action = get(this, 'action');
- while (!possible && state) {
- possible = this.getStateByPath(state, path);
- state = get(state, 'parentState');
+ if (action) {
+ controller.send(action, get(this, 'value'));
}
- return possible;
- },
+ return false;
+ }
+});
- /**
- 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`.
+})();
- 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; }
- var r = path.split('.'),
- ret = [];
- for (var i=0, len = r.length; i < len; i++) {
- var states = get(origin, 'states');
+(function() {
+/**
+@module ember
+@submodule ember-handlebars
+*/
- if (!states) { return undefined; }
+var get = Ember.get, set = Ember.set;
- var s = get(states, r[i]);
- if (s) { origin = s; ret.push(s); }
- else { return undefined; }
- }
+/**
+ @class Button
+ @namespace Ember
+ @extends Ember.View
+ @uses Ember.TargetActionSupport
+ @deprecated
+*/
+Ember.Button = Ember.View.extend(Ember.TargetActionSupport, {
+ classNames: ['ember-button'],
+ classNameBindings: ['isActive'],
- return ret;
- },
+ tagName: 'button',
- goToState: function() {
- // not deprecating this yet so people don't constantly need to
- // make trivial changes for little reason.
- return this.transitionTo.apply(this, arguments);
- },
+ propagateEvents: false,
- transitionTo: function(path, context) {
- // XXX When is transitionTo called with no path
- if (Ember.empty(path)) { return; }
+ attributeBindings: ['type', 'disabled', 'href', 'tabindex'],
- // The ES6 signature of this function is `path, ...contexts`
- var contexts = context ? Array.prototype.slice.call(arguments, 1) : [],
- currentState = get(this, 'currentState') || this;
+ /**
+ @private
- // First, get the enter, exit and resolve states for the current state
- // and specified path. If possible, use an existing cache.
- var hash = this.contextFreeTransition(currentState, path);
+ Overrides `TargetActionSupport`'s `targetObject` computed
+ property to use Handlebars-specific path resolution.
- // Next, process the raw state information for the contexts passed in.
- var transition = new Transition(hash).normalize(this, contexts);
+ @property targetObject
+ */
+ targetObject: Ember.computed(function() {
+ var target = get(this, 'target'),
+ root = get(this, 'context'),
+ data = get(this, 'templateData');
- this.enterState(transition);
- this.triggerSetupContext(transition);
- },
+ if (typeof target !== 'string') { return target; }
- contextFreeTransition: function(currentState, path) {
- var cache = currentState.pathsCache[path];
- if (cache) { return cache; }
+ return Ember.Handlebars.get(root, target, { data: data });
+ }).property('target'),
- var enterStates = this.findStatesByPath(currentState, path),
- exitStates = [],
- resolveState = currentState;
+ // Defaults to 'button' if tagName is 'input' or 'button'
+ type: Ember.computed(function(key) {
+ var tagName = this.tagName;
+ if (tagName === 'input' || tagName === 'button') { return 'button'; }
+ }),
- // Walk up the states. For each state, check whether a state matching
- // the `path` is nested underneath. This will find the closest
- // parent state containing `path`.
- //
- // This allows the user to pass in a relative path. For example, for
- // the following state hierarchy:
- //
- // | |root
- // | |- posts
- // | | |- show (* current)
- // | |- comments
- // | | |- show
- //
- // If the current state is `<root.posts.show>`, an attempt to
- // transition to `comments.show` will match `<root.comments.show>`.
- //
- // First, this code will look for root.posts.show.comments.show.
- // Next, it will look for root.posts.comments.show. Finally,
- // it will look for `root.comments.show`, and find the state.
- //
- // After this process, the following variables will exist:
- //
- // * resolveState: a common parent state between the current
- // and target state. In the above example, `<root>` is the
- // `resolveState`.
- // * enterStates: a list of all of the states represented
- // by the path from the `resolveState`. For example, for
- // the path `root.comments.show`, `enterStates` would have
- // `[<root.comments>, <root.comments.show>]`
- // * exitStates: a list of all of the states from the
- // `resolveState` to the `currentState`. In the above
- // example, `exitStates` would have
- // `[<root.posts>`, `<root.posts.show>]`.
- while (resolveState && !enterStates) {
- exitStates.unshift(resolveState);
+ disabled: false,
- resolveState = get(resolveState, 'parentState');
- if (!resolveState) {
- enterStates = this.findStatesByPath(this, path);
- if (!enterStates) {
- Ember.assert('Could not find state for path: "'+path+'"');
- return;
- }
- }
- enterStates = this.findStatesByPath(resolveState, path);
- }
+ // Allow 'a' tags to act like buttons
+ href: Ember.computed(function() {
+ return this.tagName === 'a' ? '#' : null;
+ }),
- // If the path contains some states that are parents of both the
- // current state and the target state, remove them.
- //
- // For example, in the following hierarchy:
- //
- // |- root
- // | |- post
- // | | |- index (* current)
- // | | |- show
- //
- // If the `path` is `root.post.show`, the three variables will
- // be:
- //
- // * resolveState: `<state manager>`
- // * enterStates: `[<root>, <root.post>, <root.post.show>]`
- // * exitStates: `[<root>, <root.post>, <root.post.index>]`
- //
- // The goal of this code is to remove the common states, so we
- // have:
- //
- // * resolveState: `<root.post>`
- // * enterStates: `[<root.post.show>]`
- // * exitStates: `[<root.post.index>]`
- //
- // This avoid unnecessary calls to the enter and exit transitions.
- while (enterStates.length > 0 && enterStates[0] === exitStates[0]) {
- resolveState = enterStates.shift();
- exitStates.shift();
+ mouseDown: function() {
+ if (!get(this, 'disabled')) {
+ set(this, 'isActive', true);
+ this._mouseDown = true;
+ this._mouseEntered = true;
}
+ return get(this, 'propagateEvents');
+ },
- // Cache the enterStates, exitStates, and resolveState for the
- // current state and the `path`.
- var transitions = currentState.pathsCache[path] = {
- exitStates: exitStates,
- enterStates: enterStates,
- resolveState: resolveState
- };
-
- return transitions;
+ mouseLeave: function() {
+ if (this._mouseDown) {
+ set(this, 'isActive', false);
+ this._mouseEntered = false;
+ }
},
- triggerSetupContext: function(transitions) {
- var contexts = transitions.contexts,
- offset = transitions.enterStates.length - contexts.length,
- enterStates = transitions.enterStates,
- transitionEvent = get(this, 'transitionEvent');
+ mouseEnter: function() {
+ if (this._mouseDown) {
+ set(this, 'isActive', true);
+ this._mouseEntered = true;
+ }
+ },
- Ember.assert("More contexts provided than states", offset >= 0);
+ mouseUp: function(event) {
+ if (get(this, 'isActive')) {
+ // Actually invoke the button's target and action.
+ // This method comes from the Ember.TargetActionSupport mixin.
+ this.triggerAction();
+ set(this, 'isActive', false);
+ }
- arrayForEach.call(enterStates, function(state, idx) {
- state.trigger(transitionEvent, this, contexts[idx-offset]);
- }, this);
+ this._mouseDown = false;
+ this._mouseEntered = false;
+ return get(this, 'propagateEvents');
},
- getState: function(name) {
- var state = get(this, name),
- parentState = get(this, 'parentState');
+ keyDown: function(event) {
+ // Handle space or enter
+ if (event.keyCode === 13 || event.keyCode === 32) {
+ this.mouseDown();
+ }
+ },
- if (state) {
- return state;
- } else if (parentState) {
- return parentState.getState(name);
+ keyUp: function(event) {
+ // Handle space or enter
+ if (event.keyCode === 13 || event.keyCode === 32) {
+ this.mouseUp();
}
},
- enterState: function(transition) {
- var log = this.enableLogging;
+ // TODO: Handle proper touch behavior. Including should make inactive when
+ // finger moves more than 20x outside of the edge of the button (vs mouse
+ // which goes inactive as soon as mouse goes out of edges.)
- var exitStates = transition.exitStates.slice(0).reverse();
- arrayForEach.call(exitStates, function(state) {
- state.trigger('exit', this);
- }, this);
+ touchStart: function(touch) {
+ return this.mouseDown(touch);
+ },
- arrayForEach.call(transition.enterStates, function(state) {
- if (log) { Ember.Logger.log("STATEMANAGER: Entering " + get(state, 'path')); }
- state.trigger('enter', this);
- }, this);
+ touchEnd: function(touch) {
+ return this.mouseUp(touch);
+ },
- set(this, 'currentState', transition.finalState);
+ init: function() {
+ Ember.deprecate("Ember.Button is deprecated and will be removed from future releases. Consider using the `{{action}}` helper.");
+ this._super();
}
});
(function() {
/**
-Ember States
-
@module ember
-@submodule ember-states
-@requires ember-runtime
+@submodule ember-handlebars
*/
-})();
+var get = Ember.get, set = Ember.set;
-(function() {
-var get = Ember.get;
+/**
+ 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`),
+ live-updating as the user inputs text.
-Ember._ResolvedState = Ember.Object.extend({
- manager: null,
- state: null,
- match: null,
+ ## Layout and LayoutName properties
- object: Ember.computed(function(key, value) {
- if (arguments.length === 2) {
- this._object = value;
- return value;
- } else {
- if (this._object) {
- return this._object;
- } else {
- var state = get(this, 'state'),
- match = get(this, 'match'),
- manager = get(this, 'manager');
- return state.deserialize(manager, match.hash);
- }
- }
- }).property(),
+ 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.
- hasPromise: Ember.computed(function() {
- return Ember.canInvoke(get(this, 'object'), 'then');
- }).property('object'),
+ ## HTML Attributes
- promise: Ember.computed(function() {
- var object = get(this, 'object');
- if (Ember.canInvoke(object, 'then')) {
- return object;
- } else {
- return {
- then: function(success) { success(object); }
- };
+ By default `Ember.TextArea` provides support for `rows`, `cols`,
+ `placeholder`, `disabled`, `maxlength` and `tabindex` attributes on a
+ textarea. If you need to support more attributes have a look at the
+ `attributeBindings` property in `Ember.View`'s HTML Attributes section.
+
+ To globally add support for additional attributes you can reopen
+ `Ember.TextArea` or `Ember.TextSupport`.
+
+ ```javascript
+ Ember.TextSupport.reopen({
+ attributeBindings: ["required"]
+ })
+ ```
+
+ @class TextArea
+ @namespace Ember
+ @extends Ember.View
+ @uses Ember.TextSupport
+*/
+Ember.TextArea = Ember.View.extend(Ember.TextSupport, {
+ classNames: ['ember-text-area'],
+
+ tagName: "textarea",
+ attributeBindings: ['rows', 'cols'],
+ rows: null,
+ cols: null,
+
+ _updateElementValue: Ember.observer(function() {
+ // We do this check so cursor position doesn't get affected in IE
+ var value = get(this, 'value'),
+ $el = this.$();
+ if ($el && value !== $el.val()) {
+ $el.val(value);
}
- }).property('object'),
+ }, 'value'),
- transition: function() {
- var manager = get(this, 'manager'),
- path = get(this, 'state.path'),
- object = get(this, 'object');
- manager.transitionTo(path, object);
+ init: function() {
+ this._super();
+ this.on("didInsertElement", this, this._updateElementValue);
}
+
});
})();
(function() {
+/*jshint eqeqeq:false */
+
/**
@module ember
-@submodule ember-routing
+@submodule ember-handlebars
*/
-var get = Ember.get;
+var set = Ember.set,
+ get = Ember.get,
+ indexOf = Ember.EnumerableUtils.indexOf,
+ indexesOf = Ember.EnumerableUtils.indexesOf,
+ replace = Ember.EnumerableUtils.replace,
+ isArray = Ember.isArray,
+ precompileTemplate = Ember.Handlebars.compile;
-// The Ember Routable mixin assumes the existance of a simple
-// routing shim that supports the following three behaviors:
-//
-// * .getURL() - this is called when the page loads
-// * .setURL(newURL) - this is called from within the state
-// manager when the state changes to a routable state
-// * .onURLChange(callback) - this happens when the user presses
-// the back or forward button
-
-var paramForClass = function(classObject) {
- var className = classObject.toString(),
- parts = className.split("."),
- last = parts[parts.length - 1];
-
- return Ember.String.underscore(last) + "_id";
-};
+/**
+ 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.
-var merge = function(original, hash) {
- for (var prop in hash) {
- if (!hash.hasOwnProperty(prop)) { continue; }
- if (original.hasOwnProperty(prop)) { continue; }
+ The text and `value` property of each `<option>` element within the
+ `<select>` element are populated from the objects in the `Element.Select`'s
+ `content` property. The underlying data object of the selected `<option>` is
+ stored in the `Element.Select`'s `value` property.
- original[prop] = hash[prop];
- }
-};
+ ### `content` as an array of Strings
+
+ The simplest version of an `Ember.Select` takes an array of strings as its
+ `content` property. The string will be used as both the `value` property and
+ the inner text of each `<option>` element inside the rendered `<select>`.
+
+ Example:
+
+ ```javascript
+ App.names = ["Yehuda", "Tom"];
+ ```
+
+ ```handlebars
+ {{view Ember.Select contentBinding="App.names"}}
+ ```
+
+ Would result in the following HTML:
+
+ ```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:
+
+ ```javascript
+ App.names = Ember.Object.create({
+ selected: 'Tom',
+ content: ["Yehuda", "Tom"]
+ });
+ ```
+
+ ```handlebars
+ {{view Ember.Select
+ contentBinding="App.names.content"
+ valueBinding="App.names.selected"
+ }}
+ ```
+
+ Would result in the following HTML with the `<option>` for 'Tom' selected:
+
+ ```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.names.selected` to "Yehuda".
+
+ ### `content` as an Array of Objects
+
+ An `Ember.Select` can also take an array of JavaScript or Ember objects as
+ its `content` property.
+
+ When using objects you need to tell the `Ember.Select` which property should
+ be accessed on each object to supply the `value` attribute of the `<option>`
+ and which property should be used to supply the element text.
+
+ The `optionValuePath` option is used to specify the path on each object to
+ the desired property for the `value` attribute. The `optionLabelPath`
+ specifies the path on each object to the desired property for the
+ element's text. Both paths must reference each object itself as `content`:
+
+ ```javascript
+ App.programmers = [
+ Ember.Object.create({firstName: "Yehuda", id: 1}),
+ Ember.Object.create({firstName: "Tom", id: 2})
+ ];
+ ```
+
+ ```handlebars
+ {{view Ember.Select
+ contentBinding="App.programmers"
+ optionValuePath="content.id"
+ optionLabelPath="content.firstName"}}
+ ```
+
+ Would result in the following HTML:
+
+ ```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.currentProgrammer = Ember.Object.create({
+ id: 2
+ });
+ ```
+
+ ```handlebars
+ {{view Ember.Select
+ contentBinding="App.programmers"
+ optionValuePath="content.id"
+ optionLabelPath="content.firstName"
+ valueBinding="App.currentProgrammer.id"}}
+ ```
+
+ Would result in the following HTML with a selected option:
+
+ ```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`
+ to match the `value` property of the newly selected `<option>`.
+
+ Alternatively, you can control selection through the underlying objects
+ used to render each object providing a `selectionBinding`. When the selected
+ `<option>` is changed, the property path provided to `selectionBinding`
+ will be updated to match the content object of the rendered `<option>`
+ element:
+
+ ```javascript
+ App.controller = Ember.Object.create({
+ selectedPerson: null,
+ content: [
+ Ember.Object.create({firstName: "Yehuda", id: 1}),
+ Ember.Object.create({firstName: "Tom", id: 2})
+ ]
+ });
+ ```
+
+ ```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:
+
+ ```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 `selectedPerson` value of `App.controller`
+ to match the content object of the newly selected `<option>`. In this
+ 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:
+
+ ```javascript
+ App.controller = Ember.Object.create({
+ selected: null,
+ content: [
+ "Yehuda",
+ "Tom"
+ ]
+ });
+ ```
+
+ ``` handlebars
+ {{view Ember.Select
+ contentBinding="App.controller.content"
+ valueBinding="App.controller.selected"
+ }}
+ ```
+
+ Would result in the following HTML:
+
+ ```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
+ first item as though it were selected. You can supply a string
+ value for the `Ember.Select` to display when there is no selection
+ with the `prompt` option:
+
+ ```javascript
+ App.controller = Ember.Object.create({
+ selected: null,
+ content: [
+ "Yehuda",
+ "Tom"
+ ]
+ });
+ ```
+
+ ```handlebars
+ {{view Ember.Select
+ contentBinding="App.controller.content"
+ valueBinding="App.controller.selected"
+ prompt="Please select a name"
+ }}
+ ```
+
+ Would result in the following HTML:
+
+ ```html
+ <select class="ember-select">
+ <option>Please select a name</option>
+ <option value="Yehuda">Yehuda</option>
+ <option value="Tom">Tom</option>
+ </select>
+ ```
-/**
- @class Routable
+ @class Select
@namespace Ember
- @extends Ember.Mixin
+ @extends Ember.View
*/
-Ember.Routable = Ember.Mixin.create({
- init: function() {
- var redirection;
- 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);
-
- this.connectOutlets = function(router) {
- router.transitionTo(redirection);
- };
- }
+Ember.Select = Ember.View.extend(
+ /** @scope Ember.Select.prototype */ {
- // normalize empty route to '/'
- var route = get(this, 'route');
- if (route === '') {
- route = '/';
- }
+ tagName: 'select',
+ classNames: ['ember-select'],
+ defaultTemplate: Ember.Handlebars.template(function anonymous(Handlebars,depth0,helpers,partials,data) {
+helpers = helpers || Ember.Handlebars.helpers; data = data || {};
+ var buffer = '', stack1, escapeExpression=this.escapeExpression, self=this;
- this._super();
+function program1(depth0,data) {
+
+ var buffer = '', stack1;
+ data.buffer.push("<option value=\"\">");
+ stack1 = helpers._triageMustache.call(depth0, "view.prompt", {hash:{},contexts:[depth0],data:data});
+ data.buffer.push(escapeExpression(stack1) + "</option>");
+ return buffer;}
- Ember.assert("You cannot use `redirectsTo` on a state that has child states", !redirection || (!!redirection && !!get(this, 'isLeaf')));
- },
+function program3(depth0,data) {
+
+ var stack1;
+ stack1 = {};
+ stack1['contentBinding'] = "this";
+ stack1 = helpers.view.call(depth0, "Ember.SelectOption", {hash:stack1,contexts:[depth0],data:data});
+ data.buffer.push(escapeExpression(stack1));}
- setup: function() {
- return this.connectOutlets.apply(this, arguments);
- },
+ stack1 = helpers['if'].call(depth0, "view.prompt", {hash:{},inverse:self.noop,fn:self.program(1, program1, data),contexts:[depth0],data:data});
+ if(stack1 || stack1 === 0) { data.buffer.push(stack1); }
+ stack1 = helpers.each.call(depth0, "view.content", {hash:{},inverse:self.noop,fn:self.program(3, program3, data),contexts:[depth0],data:data});
+ if(stack1 || stack1 === 0) { data.buffer.push(stack1); }
+ return buffer;
+}),
+ attributeBindings: ['multiple', 'disabled', 'tabindex'],
/**
- @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.
+ The `multiple` attribute of the select element. Indicates whether multiple
+ options can be selected.
- @method stashContext
- @param manager {Ember.StateManager}
- @param context
+ @property multiple
+ @type Boolean
+ @default false
*/
- stashContext: function(manager, context) {
- this.router = manager;
-
- var serialized = this.serialize(manager, context);
- Ember.assert('serialize must return a hash', !serialized || typeof serialized === 'object');
-
- manager.setStateMeta(this, 'context', context);
- manager.setStateMeta(this, 'serialized', serialized);
+ multiple: false,
- if (get(this, 'isRoutable') && !get(manager, 'isRouting')) {
- this.updateRoute(manager, get(manager, 'location'));
- }
- },
+ disabled: false,
/**
- @private
+ The list of options.
+
+ If `optionLabelPath` and `optionValuePath` are not overridden, this should
+ be a list of strings, which will serve simultaneously as labels and values.
- Whenever a routable state is entered, the router's location object
- is notified to set the URL to the current absolute path.
+ Otherwise, this should be a list of objects. For instance:
- In general, this will update the browser's URL.
+ ```javascript
+ Ember.Select.create({
+ content: Ember.A([
+ { id: 1, firstName: 'Yehuda' },
+ { id: 2, firstName: 'Tom' }
+ ]),
+ optionLabelPath: 'content.firstName',
+ optionValuePath: 'content.id'
+ });
+ ```
- @method updateRoute
- @param manager {Ember.StateManager}
- @param location {Ember.Location}
+ @property content
+ @type Array
+ @default null
*/
- updateRoute: function(manager, location) {
- if (get(this, 'isLeafRoute')) {
- var path = this.absoluteRoute(manager);
- location.setURL(path);
- }
- },
+ content: null,
/**
- @private
-
- Get the absolute route for the current state and a given
- hash.
+ When `multiple` is `false`, the element of `content` that is currently
+ selected, if any.
- This method is private, as it expects a serialized hash,
- not the original context object.
+ When `multiple` is `true`, an array of such elements.
- @method absoluteRoute
- @param manager {Ember.StateManager}
- @param hash {Hash}
+ @property selection
+ @type Object or Array
+ @default null
*/
- absoluteRoute: function(manager, hash) {
- var parentState = get(this, 'parentState');
- var path = '', generated;
-
- // If the parent state is routable, use its current path
- // as this route's prefix.
- if (get(parentState, 'isRoutable')) {
- path = parentState.absoluteRoute(manager, hash);
- }
-
- var matcher = get(this, 'routeMatcher'),
- serialized = manager.getStateMeta(this, 'serialized');
-
- // merge the existing serialized object in with the passed
- // in hash.
- hash = hash || {};
- merge(hash, serialized);
-
- generated = matcher && matcher.generate(hash);
-
- if (generated) {
- path = path + '/' + generated;
- }
-
- return path;
- },
+ selection: null,
/**
- @private
+ In single selection mode (when `multiple` is `false`), value can be used to
+ get the current selection's value or set the selection by it's value.
- At the moment, a state is routable if it has a string `route`
- property. This heuristic may change.
+ It is not currently supported in multiple selection mode.
- @property isRoutable
- @type Boolean
+ @property value
+ @type String
+ @default null
*/
- isRoutable: Ember.computed(function() {
- return typeof get(this, 'route') === 'string';
- }).cacheable(),
+ value: Ember.computed(function(key, value) {
+ if (arguments.length === 2) { return value; }
+ var valuePath = get(this, 'optionValuePath').replace(/^content\.?/, '');
+ return valuePath ? get(this, 'selection.' + valuePath) : get(this, 'selection');
+ }).property('selection'),
/**
- @private
-
- Determine if this is the last routeable state
+ If given, a top-most dummy option will be rendered to serve as a user
+ prompt.
- @property isLeafRoute
- @type Boolean
+ @property prompt
+ @type String
+ @default null
*/
- isLeafRoute: Ember.computed(function() {
- if (get(this, 'isLeaf')) { return true; }
- return !get(this, 'childStates').findProperty('isRoutable');
- }).cacheable(),
+ prompt: null,
/**
- @private
-
- A _RouteMatcher object generated from the current route's `route`
- string property.
+ The path of the option labels. See `content`.
- @property routeMatcher
- @type Ember._RouteMatcher
+ @property optionLabelPath
+ @type String
+ @default 'content'
*/
- routeMatcher: Ember.computed(function() {
- var route = get(this, 'route');
- if (route) {
- return Ember._RouteMatcher.create({ route: route });
- }
- }).cacheable(),
+ optionLabelPath: 'content',
/**
- @private
-
- Check whether the route has dynamic segments and therefore takes
- a context.
+ The path of the option values. See `content`.
- @property hasContext
- @type Boolean
+ @property optionValuePath
+ @type String
+ @default 'content'
*/
- hasContext: Ember.computed(function() {
- var routeMatcher = get(this, 'routeMatcher');
- if (routeMatcher) {
- return routeMatcher.identifiers.length > 0;
+ optionValuePath: 'content',
+
+ _change: function() {
+ if (get(this, 'multiple')) {
+ this._changeMultiple();
+ } else {
+ this._changeSingle();
}
- }).cacheable(),
+ },
- /**
- @private
+ selectionDidChange: Ember.observer(function() {
+ var selection = get(this, 'selection');
+ if (get(this, 'multiple')) {
+ if (!isArray(selection)) {
+ set(this, 'selection', Ember.A([selection]));
+ return;
+ }
+ this._selectionDidChangeMultiple();
+ } else {
+ this._selectionDidChangeSingle();
+ }
+ }, 'selection.@each'),
- 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.
+ valueDidChange: Ember.observer(function() {
+ var content = get(this, 'content'),
+ value = get(this, 'value'),
+ valuePath = get(this, 'optionValuePath').replace(/^content\.?/, ''),
+ selectedValue = (valuePath ? get(this, 'selection.' + valuePath) : get(this, 'selection')),
+ selection;
- @property modelClass
- @type Ember.Object
- */
- modelClass: Ember.computed(function() {
- var modelType = get(this, 'modelType');
+ if (value !== selectedValue) {
+ selection = content.find(function(obj) {
+ return value === (valuePath ? get(obj, valuePath) : obj);
+ });
- if (typeof modelType === 'string') {
- return Ember.get(window, modelType);
- } else {
- return modelType;
+ this.set('selection', selection);
}
- }).cacheable(),
+ }, 'value'),
- /**
- @private
- Get the model class for the state. The heuristic is:
+ _triggerChange: function() {
+ var selection = get(this, 'selection');
+ var value = get(this, 'value');
- * The state must have a single dynamic segment
- * The dynamic segment must end in `_id`
- * A dynamic segment like `blog_post_id` is converted into `BlogPost`
- * The name is then looked up on the passed in namespace
+ if (selection) { this.selectionDidChange(); }
+ if (value) { this.valueDidChange(); }
- The process of initializing an application with a router will
- pass the application's namespace into the router, which will be
- used here.
+ this._change();
+ },
- @method modelClassFor
- @param namespace {Ember.Namespace}
- */
- modelClassFor: function(namespace) {
- var modelClass, routeMatcher, identifiers, match, className;
+ _changeSingle: function() {
+ var selectedIndex = this.$()[0].selectedIndex,
+ content = get(this, 'content'),
+ prompt = get(this, 'prompt');
- // if an explicit modelType was specified, use that
- if (modelClass = get(this, 'modelClass')) { return modelClass; }
+ if (!get(content, 'length')) { return; }
+ if (prompt && selectedIndex === 0) { set(this, 'selection', null); return; }
- // if the router has no lookup namespace, we won't be able to guess
- // the modelType
- if (!namespace) { return; }
+ if (prompt) { selectedIndex -= 1; }
+ set(this, 'selection', content.objectAt(selectedIndex));
+ },
- // make sure this state is actually a routable state
- routeMatcher = get(this, 'routeMatcher');
- if (!routeMatcher) { return; }
- // only guess modelType for states with a single dynamic segment
- // (no more, no fewer)
- identifiers = routeMatcher.identifiers;
- if (identifiers.length !== 2) { return; }
+ _changeMultiple: function() {
+ var options = this.$('option:selected'),
+ prompt = get(this, 'prompt'),
+ offset = prompt ? 1 : 0,
+ content = get(this, 'content'),
+ selection = get(this, 'selection');
- // extract the `_id` from the end of the dynamic segment; if the
- // dynamic segment does not end in `_id`, we can't guess the
- // modelType
- match = identifiers[1].match(/^(.*)_id$/);
- if (!match) { return; }
+ if (!content){ return; }
+ if (options) {
+ var selectedIndexes = options.map(function(){
+ return this.index - offset;
+ }).toArray();
+ var newSelection = content.objectsAt(selectedIndexes);
- // convert the underscored type into a class form and look it up
- // on the router's namespace
- className = Ember.String.classify(match[1]);
- return get(namespace, className);
+ if (isArray(selection)) {
+ replace(selection, 0, get(selection, 'length'), newSelection);
+ } else {
+ set(this, 'selection', newSelection);
+ }
+ }
},
- /**
- The default method that takes a `params` object and converts
- it into an object.
+ _selectionDidChangeSingle: function() {
+ var el = this.get('element');
+ if (!el) { return; }
- By default, a params hash that looks like `{ post_id: 1 }`
- 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.
+ var content = get(this, 'content'),
+ selection = get(this, 'selection'),
+ selectionIndex = content ? indexOf(content, selection) : -1,
+ prompt = get(this, 'prompt');
- @method deserialize
- @param manager {Ember.StateManager}
- @param params {Hash}
- */
- deserialize: function(manager, params) {
- var modelClass, routeMatcher, param;
+ if (prompt) { selectionIndex += 1; }
+ if (el) { el.selectedIndex = selectionIndex; }
+ },
- if (modelClass = this.modelClassFor(get(manager, 'namespace'))) {
- Ember.assert("Expected "+modelClass.toString()+" to implement `find` for use in '"+this.get('path')+"' `deserialize`. Please implement the `find` method or overwrite `deserialize`.", modelClass.find);
- return modelClass.find(params[paramForClass(modelClass)]);
- }
+ _selectionDidChangeMultiple: function() {
+ var content = get(this, 'content'),
+ selection = get(this, 'selection'),
+ selectedIndexes = content ? indexesOf(content, selection) : [-1],
+ prompt = get(this, 'prompt'),
+ offset = prompt ? 1 : 0,
+ options = this.$('option'),
+ adjusted;
- return params;
+ if (options) {
+ options.each(function() {
+ adjusted = this.index > -1 ? this.index - offset : -1;
+ this.selected = indexOf(selectedIndexes, adjusted) > -1;
+ });
+ }
},
- /**
- The default method that takes an object and converts it into
- a params hash.
+ init: function() {
+ this._super();
+ this.on("didInsertElement", this, this._triggerChange);
+ this.on("change", this, this._change);
+ }
+});
- By default, if there is a single dynamic segment named
- `blog_post_id` and the object is a `BlogPost` with an
- `id` of `12`, the serialize method will produce:
+Ember.SelectOption = Ember.View.extend({
+ tagName: 'option',
+ attributeBindings: ['value', 'selected'],
- { blog_post_id: 12 }
+ defaultTemplate: function(context, options) {
+ options = { data: options.data, hash: {} };
+ Ember.Handlebars.helpers.bind.call(context, "view.label", options);
+ },
- @method serialize
- @param manager {Ember.StateManager}
- @param context
- */
- serialize: function(manager, context) {
- var modelClass, routeMatcher, namespace, param, id;
+ init: function() {
+ this.labelPathDidChange();
+ this.valuePathDidChange();
- if (Ember.empty(context)) { return ''; }
+ this._super();
+ },
- if (modelClass = this.modelClassFor(get(manager, 'namespace'))) {
- param = paramForClass(modelClass);
- id = get(context, 'id');
- context = {};
- context[param] = id;
+ selected: Ember.computed(function() {
+ var content = get(this, 'content'),
+ selection = get(this, 'parentView.selection');
+ if (get(this, 'parentView.multiple')) {
+ return selection && indexOf(selection, content.valueOf()) > -1;
+ } else {
+ // Primitives get passed through bindings as objects... since
+ // `new Number(4) !== 4`, we use `==` below
+ return content == selection;
}
+ }).property('content', 'parentView.selection').volatile(),
+
+ labelPathDidChange: Ember.observer(function() {
+ var labelPath = get(this, 'parentView.optionLabelPath');
+
+ if (!labelPath) { return; }
+
+ Ember.defineProperty(this, 'label', Ember.computed(function() {
+ return get(this, labelPath);
+ }).property(labelPath));
+ }, 'parentView.optionLabelPath'),
+
+ valuePathDidChange: Ember.observer(function() {
+ var valuePath = get(this, 'parentView.optionValuePath');
+
+ if (!valuePath) { return; }
+
+ Ember.defineProperty(this, 'value', Ember.computed(function() {
+ return get(this, valuePath);
+ }).property(valuePath));
+ }, 'parentView.optionValuePath')
+});
+
+})();
+
+
+
+(function() {
+
+})();
- return context;
- },
- /**
- @private
- @method resolvePath
- @param manager {Ember.StateManager}
- @param path {String}
- */
- resolvePath: function(manager, path) {
- if (get(this, 'isLeafRoute')) { return Ember.A(); }
- var childStates = get(this, 'childStates'), match;
+(function() {
+/*globals Handlebars */
+/**
+@module ember
+@submodule ember-handlebars
+*/
- childStates = Ember.A(childStates.filterProperty('isRoutable'));
+/**
+ @private
- childStates = childStates.sort(function(a, b) {
- var aDynamicSegments = get(a, 'routeMatcher.identifiers.length'),
- bDynamicSegments = get(b, 'routeMatcher.identifiers.length'),
- aRoute = get(a, 'route'),
- bRoute = get(b, 'route');
+ 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.
- if (aRoute.indexOf(bRoute) === 0) {
- return -1;
- } else if (bRoute.indexOf(aRoute) === 0) {
- return 1;
- }
+ 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.
- if (aDynamicSegments !== bDynamicSegments) {
- return aDynamicSegments - bDynamicSegments;
- }
+ @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"]';
- return get(b, 'route.length') - get(a, 'route.length');
- });
+ Ember.$(selectors, ctx)
+ .each(function() {
+ // Get a reference to the script tag
+ var script = Ember.$(this),
+ type = script.attr('type');
- var state = childStates.find(function(state) {
- var matcher = get(state, 'routeMatcher');
- if (match = matcher.match(path)) { return true; }
- });
+ var compile = (script.attr('type') === 'text/x-raw-handlebars') ?
+ Ember.$.proxy(Handlebars.compile, Handlebars) :
+ Ember.$.proxy(Ember.Handlebars.compile, Ember.Handlebars),
+ // 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') || 'application',
+ template = compile(script.html());
- Ember.assert("Could not find state for path " + path, !!state);
+ // For templates which have a name, we save them and then remove them from the DOM
+ Ember.TEMPLATES[templateName] = template;
- var resolvedState = Ember._ResolvedState.create({
- manager: manager,
- state: state,
- match: match
- });
+ // Remove script tag from DOM
+ script.remove();
+ });
+};
- var states = state.resolvePath(manager, match.remaining);
+function bootstrap() {
+ Ember.Handlebars.bootstrap( Ember.$(document) );
+}
- return Ember.A([resolvedState]).pushObjects(states);
- },
+/*
+ We tie this to application.load to ensure that we've at least
+ attempted to bootstrap at the point that the application is loaded.
- /**
- @private
+ We also tie this to document ready since we're guaranteed that all
+ the inline templates are present at this point.
- Once `unroute` has finished unwinding, `routePath` will be called
- with the remainder of the route.
+ There's no harm to running this twice, since we remove the templates
+ from the DOM after processing.
+*/
- 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`.
+Ember.onLoad('application', bootstrap);
- @method routePath
- @param manager {Ember.StateManager}
- @param path {String}
- */
- routePath: function(manager, path) {
- if (get(this, 'isLeafRoute')) { return; }
+})();
- var resolvedStates = this.resolvePath(manager, path),
- hasPromises = resolvedStates.some(function(s) { return get(s, 'hasPromise'); });
- function runTransition() {
- resolvedStates.forEach(function(rs) { rs.transition(); });
- }
- if (hasPromises) {
- manager.transitionTo('loading');
+(function() {
+/**
+Ember Handlebars
- Ember.assert('Loading state should be the child of a route', Ember.Routable.detect(get(manager, 'currentState.parentState')));
- Ember.assert('Loading state should not be a route', !Ember.Routable.detect(get(manager, 'currentState')));
+@module ember
+@submodule ember-handlebars
+@requires ember-views
+*/
- manager.handleStatePromises(resolvedStates, runTransition);
- } else {
- runTransition();
- }
- },
+Ember.runLoadHooks('Ember.Handlebars', Ember.Handlebars);
- /**
- @private
+})();
- When you move to a new route by pressing the back
- or forward button, this method is called first.
+(function() {
+define("route-recognizer",
+ [],
+ function() {
+ "use strict";
+ var specials = [
+ '/', '.', '*', '+', '?', '|',
+ '(', ')', '[', ']', '{', '}', '\\'
+ ];
- Its job is to move the state manager into a parent
- state of the state it will eventually move into.
+ var escapeRegex = new RegExp('(\\' + specials.join('|\\') + ')', 'g');
- @method unroutePath
- @param router {Ember.Router}
- @param path {String}
- */
- unroutePath: function(router, path) {
- var parentState = get(this, 'parentState');
+ // A Segment represents a segment in the original route description.
+ // Each Segment type provides an `eachChar` and `regex` method.
+ //
+ // The `eachChar` method invokes the callback with one or more character
+ // specifications. A character specification consumes one or more input
+ // characters.
+ //
+ // The `regex` method returns a regex fragment for the segment. If the
+ // segment is a dynamic of star segment, the regex fragment also includes
+ // a capture.
+ //
+ // A character specification contains:
+ //
+ // * `validChars`: a String with a list of all valid characters, or
+ // * `invalidChars`: a String with a list of all invalid characters
+ // * `repeat`: true if the character specification can repeat
+
+ function StaticSegment(string) { this.string = string; }
+ StaticSegment.prototype = {
+ eachChar: function(callback) {
+ var string = this.string, char;
+
+ for (var i=0, l=string.length; i<l; i++) {
+ char = string.charAt(i);
+ callback({ validChars: char });
+ }
+ },
- // If we're at the root state, we're done
- if (parentState === router) {
- return;
- }
+ regex: function() {
+ return this.string.replace(escapeRegex, '\\$1');
+ },
- path = path.replace(/^(?=[^\/])/, "/");
- var absolutePath = this.absoluteRoute(router);
+ generate: function() {
+ return this.string;
+ }
+ };
- var route = get(this, 'route');
+ function DynamicSegment(name) { this.name = name; }
+ DynamicSegment.prototype = {
+ eachChar: function(callback) {
+ callback({ invalidChars: "/", repeat: true });
+ },
- // If the current path is empty, move up one state,
- // because the index ('/') state must be a leaf node.
- if (route !== '/') {
- // If the current path is a prefix of the path we're trying
- // to go to, we're done.
- var index = path.indexOf(absolutePath),
- next = path.charAt(absolutePath.length);
+ regex: function() {
+ return "([^/]+)";
+ },
- if (index === 0 && (next === "/" || next === "")) {
- return;
+ generate: function(params) {
+ return params[this.name];
}
- }
-
- // Transition to the parent and call unroute again.
- router.enterState({
- exitStates: [this],
- enterStates: [],
- finalState: parentState
- });
+ };
- router.send('unroutePath', path);
- },
+ function StarSegment(name) { this.name = name; }
+ StarSegment.prototype = {
+ eachChar: function(callback) {
+ callback({ invalidChars: "", repeat: true });
+ },
- parentTemplate: Ember.computed(function() {
- var state = this, parentState, template;
+ regex: function() {
+ return "(.+)";
+ },
- while (state = get(state, 'parentState')) {
- if (template = get(state, 'template')) {
- return template;
+ generate: function(params) {
+ return params[this.name];
}
- }
+ };
- return 'application';
- }).cacheable(),
+ function EpsilonSegment() {}
+ EpsilonSegment.prototype = {
+ eachChar: function() {},
+ regex: function() { return ""; },
+ generate: function() { return ""; }
+ };
- _template: Ember.computed(function(key, value) {
- if (arguments.length > 1) { return value; }
+ function parse(route, names, types) {
+ // normalize route as not starting with a "/". Recognition will
+ // also normalize.
+ if (route.charAt(0) === "/") { route = route.substr(1); }
+
+ var segments = route.split("/"), results = [];
+
+ for (var i=0, l=segments.length; i<l; i++) {
+ var segment = segments[i], match;
+
+ if (match = segment.match(/^:([^\/]+)$/)) {
+ results.push(new DynamicSegment(match[1]));
+ names.push(match[1]);
+ types.dynamics++;
+ } else if (match = segment.match(/^\*([^\/]+)$/)) {
+ results.push(new StarSegment(match[1]));
+ names.push(match[1]);
+ types.stars++;
+ } else if(segment === "") {
+ results.push(new EpsilonSegment());
+ } else {
+ results.push(new StaticSegment(segment));
+ types.statics++;
+ }
+ }
- if (value = get(this, 'template')) {
- return value;
+ return results;
}
- // 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);
+ // A State has a character specification and (`charSpec`) and a list of possible
+ // subsequent states (`nextStates`).
+ //
+ // If a State is an accepting state, it will also have several additional
+ // properties:
+ //
+ // * `regex`: A regular expression that is used to extract parameters from paths
+ // that reached this accepting state.
+ // * `handlers`: Information on how to convert the list of captures into calls
+ // to registered handlers with the specified parameters
+ // * `types`: How many static, dynamic or star segments in this route. Used to
+ // decide which route to use if multiple registered routes match a path.
+ //
+ // Currently, State is implemented naively by looping over `nextStates` and
+ // comparing a character specification against a character. A more efficient
+ // implementation would use a hash of keys pointing at one or more next states.
+
+ function State(charSpec) {
+ this.charSpec = charSpec;
+ this.nextStates = [];
}
- }).cacheable(),
- render: function(options) {
- options = options || {};
+ State.prototype = {
+ get: function(charSpec) {
+ var nextStates = this.nextStates;
- var template = options.template || get(this, '_template'),
- parentTemplate = options.into || get(this, 'parentTemplate'),
- controller = get(this.router, parentTemplate + "Controller");
+ for (var i=0, l=nextStates.length; i<l; i++) {
+ var child = nextStates[i];
- var viewName = Ember.String.classify(template) + "View",
- viewClass = get(get(this.router, 'namespace'), viewName);
+ var isEqual = child.charSpec.validChars === charSpec.validChars;
+ isEqual = isEqual && child.charSpec.invalidChars === charSpec.invalidChars;
- viewClass = (viewClass || Ember.View).extend({
- templateName: template
- });
+ if (isEqual) { return child; }
+ }
+ },
- controller.set('view', viewClass.create());
- },
+ put: function(charSpec) {
+ var state;
- /**
- The `connectOutlets` event will be triggered once a
- state has been entered. It will be called with the
- route's context.
+ // If the character specification already exists in a child of the current
+ // state, just return that state.
+ if (state = this.get(charSpec)) { return state; }
- @event connectOutlets
- @param router {Ember.Router}
- @param [context*]
- */
- connectOutlets: Ember.K,
+ // Make a new state for the character spec
+ state = new State(charSpec);
- /**
- The `navigateAway` event will be triggered when the
- URL changes due to the back/forward button
+ // Insert the new state as a child of the current state
+ this.nextStates.push(state);
- @event navigateAway
- */
- navigateAway: Ember.K
-});
+ // If this character specification repeats, insert the new state as a child
+ // of itself. Note that this will not trigger an infinite loop because each
+ // transition during recognition consumes a character.
+ if (charSpec.repeat) {
+ state.nextStates.push(state);
+ }
-})();
+ // Return the new state
+ return state;
+ },
+ // Find a list of child states matching the next character
+ match: function(char) {
+ // DEBUG "Processing `" + char + "`:"
+ var nextStates = this.nextStates,
+ child, charSpec, chars;
+ // DEBUG " " + debugState(this)
+ var returned = [];
-(function() {
-/**
-@module ember
-@submodule ember-routing
-*/
+ for (var i=0, l=nextStates.length; i<l; i++) {
+ child = nextStates[i];
-/**
- @class Route
- @namespace Ember
- @extends Ember.State
- @uses Ember.Routable
-*/
-Ember.Route = Ember.State.extend(Ember.Routable);
+ charSpec = child.charSpec;
-})();
+ if (typeof (chars = charSpec.validChars) !== 'undefined') {
+ if (chars.indexOf(char) !== -1) { returned.push(child); }
+ } else if (typeof (chars = charSpec.invalidChars) !== 'undefined') {
+ if (chars.indexOf(char) === -1) { returned.push(child); }
+ }
+ }
+ return returned;
+ }
+ /** IF DEBUG
+ , debug: function() {
+ var charSpec = this.charSpec,
+ debug = "[",
+ chars = charSpec.validChars || charSpec.invalidChars;
-(function() {
-var escapeForRegex = function(text) {
- return text.replace(/[\-\[\]{}()*+?.,\\\^\$|#\s]/g, "\\$&");
-};
+ if (charSpec.invalidChars) { debug += "^"; }
+ debug += chars;
+ debug += "]";
-/**
- @class _RouteMatcher
- @namespace Ember
- @private
- @extends Ember.Object
-*/
-Ember._RouteMatcher = Ember.Object.extend({
- state: null,
+ if (charSpec.repeat) { debug += "+"; }
- init: function() {
- var route = this.route,
- identifiers = [],
- count = 1,
- escaped;
+ return debug;
+ }
+ END IF **/
+ };
- // Strip off leading slash if present
- if (route.charAt(0) === '/') {
- route = this.route = route.substr(1);
+ /** IF DEBUG
+ function debug(log) {
+ console.log(log);
}
- escaped = escapeForRegex(route);
+ function debugState(state) {
+ return state.nextStates.map(function(n) {
+ if (n.nextStates.length === 0) { return "( " + n.debug() + " [accepting] )"; }
+ return "( " + n.debug() + " <then> " + n.nextStates.map(function(s) { return s.debug() }).join(" or ") + " )";
+ }).join(", ")
+ }
+ END IF **/
- var regex = escaped.replace(/:([a-z_]+)(?=$|\/)/gi, function(match, id) {
- identifiers[count++] = id;
- return "([^/]+)";
- });
+ // This is a somewhat naive strategy, but should work in a lot of cases
+ // A better strategy would properly resolve /posts/:id/new and /posts/edit/:id
+ function sortSolutions(states) {
+ return states.sort(function(a, b) {
+ if (a.types.stars !== b.types.stars) { return a.types.stars - b.types.stars; }
+ if (a.types.dynamics !== b.types.dynamics) { return a.types.dynamics - b.types.dynamics; }
+ if (a.types.statics !== b.types.statics) { return a.types.statics - b.types.statics; }
- this.identifiers = identifiers;
- this.regex = new RegExp("^/?" + regex);
- },
+ return 0;
+ });
+ }
- match: function(path) {
- var match = path.match(this.regex);
+ function recognizeChar(states, char) {
+ var nextStates = [];
- if (match) {
- var identifiers = this.identifiers,
- hash = {};
+ for (var i=0, l=states.length; i<l; i++) {
+ var state = states[i];
- for (var i=1, l=identifiers.length; i<l; i++) {
- hash[identifiers[i]] = match[i];
+ nextStates = nextStates.concat(state.match(char));
}
- return {
- remaining: path.substr(match[0].length),
- hash: identifiers.length > 0 ? hash : null
- };
+ return nextStates;
}
- },
- generate: function(hash) {
- var identifiers = this.identifiers, route = this.route, id;
- for (var i=1, l=identifiers.length; i<l; i++) {
- id = identifiers[i];
- route = route.replace(new RegExp(":" + id), hash[id]);
+ function findHandler(state, path) {
+ var handlers = state.handlers, regex = state.regex;
+ var captures = path.match(regex), currentCapture = 1;
+ var result = [];
+
+ for (var i=0, l=handlers.length; i<l; i++) {
+ var handler = handlers[i], names = handler.names, params = {};
+
+ for (var j=0, m=names.length; j<m; j++) {
+ params[names[j]] = captures[currentCapture++];
+ }
+
+ result.push({ handler: handler.handler, params: params, isDynamic: !!names.length });
+ }
+
+ return result;
}
- return route;
- }
-});
-})();
+ function addSegment(currentState, segment) {
+ segment.eachChar(function(char) {
+ var state;
+ currentState = currentState.put(char);
+ });
+ return currentState;
+ }
-(function() {
-/**
-@module ember
-@submodule ember-routing
-*/
+ // The main interface
-var get = Ember.get, set = Ember.set;
+ var RouteRecognizer = function() {
+ this.rootState = new State();
+ this.names = {};
+ };
-/*
- This file implements the `location` API used by Ember's router.
- That API is:
+ RouteRecognizer.prototype = {
+ add: function(routes, options) {
+ var currentState = this.rootState, regex = "^",
+ types = { statics: 0, dynamics: 0, stars: 0 },
+ handlers = [], allSegments = [], name;
- getURL: returns the current URL
- setURL(path): sets the current URL
- onUpdateURL(callback): triggers the callback when the URL changes
- formatURL(url): formats `url` to be placed into `href` attribute
+ var isEmpty = true;
- Calling setURL will not trigger onUpdateURL callbacks.
+ for (var i=0, l=routes.length; i<l; i++) {
+ var route = routes[i], names = [];
- TODO: This should perhaps be moved so that it's visible in the doc output.
-*/
+ var segments = parse(route.path, names, types);
-/**
- Ember.Location returns an instance of the correct implementation of
- the `location` API.
+ allSegments = allSegments.concat(segments);
- You can pass it a `implementation` ('hash', 'history', 'none') to force a
- particular implementation.
+ for (var j=0, m=segments.length; j<m; j++) {
+ var segment = segments[j];
- @class Location
- @namespace Ember
- @static
-*/
-Ember.Location = {
- create: function(options) {
- var implementation = options && options.implementation;
- Ember.assert("Ember.Location.create: you must specify a 'implementation' option", !!implementation);
+ if (segment instanceof EpsilonSegment) { continue; }
- var implementationClass = this.implementations[implementation];
- Ember.assert("Ember.Location.create: " + implementation + " is not a valid implementation", !!implementationClass);
+ isEmpty = false;
- return implementationClass.create.apply(implementationClass, arguments);
- },
+ // Add a "/" for the new segment
+ currentState = currentState.put({ validChars: "/" });
+ regex += "/";
- registerImplementation: function(name, implementation) {
- this.implementations[name] = implementation;
- },
+ // Add a representation of the segment to the NFA and regex
+ currentState = addSegment(currentState, segment);
+ regex += segment.regex();
+ }
- implementations: {}
-};
+ handlers.push({ handler: route.handler, names: names });
+ }
-})();
+ if (isEmpty) {
+ currentState = currentState.put({ validChars: "/" });
+ regex += "/";
+ }
+ currentState.handlers = handlers;
+ currentState.regex = new RegExp(regex + "$");
+ currentState.types = types;
+ if (name = options && options.as) {
+ this.names[name] = {
+ segments: allSegments,
+ handlers: handlers
+ };
+ }
+ },
-(function() {
-/**
-@module ember
-@submodule ember-routing
-*/
+ handlersFor: function(name) {
+ var route = this.names[name], result = [];
+ if (!route) { throw new Error("There is no route named " + name); }
-var get = Ember.get, set = Ember.set;
+ for (var i=0, l=route.handlers.length; i<l; i++) {
+ result.push(route.handlers[i]);
+ }
-/**
- 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).
+ return result;
+ },
- @class NoneLocation
- @namespace Ember
- @extends Ember.Object
-*/
-Ember.NoneLocation = Ember.Object.extend({
- path: '',
+ hasRoute: function(name) {
+ return !!this.names[name];
+ },
- getURL: function() {
- return get(this, 'path');
- },
+ generate: function(name, params) {
+ var route = this.names[name], output = "";
+ if (!route) { throw new Error("There is no route named " + name); }
- setURL: function(path) {
- set(this, 'path', path);
- },
+ var segments = route.segments;
- onUpdateURL: function(callback) {
- // We are not wired up to the browser, so we'll never trigger the callback.
- },
+ for (var i=0, l=segments.length; i<l; i++) {
+ var segment = segments[i];
- formatURL: function(url) {
- // The return value is not overly meaningful, but we do not want to throw
- // errors when test code renders templates containing {{action href=true}}
- // helpers.
- return url;
- }
-});
+ if (segment instanceof EpsilonSegment) { continue; }
-Ember.Location.registerImplementation('none', Ember.NoneLocation);
+ output += "/";
+ output += segment.generate(params);
+ }
-})();
+ if (output.charAt(0) !== '/') { output = '/' + output; }
+
+ return output;
+ },
+ recognize: function(path) {
+ var states = [ this.rootState ], i, l;
+ // DEBUG GROUP path
-(function() {
-/**
-@module ember
-@submodule ember-routing
-*/
+ var pathLen = path.length;
-var get = Ember.get, set = Ember.set;
+ if (path.charAt(0) !== "/") { path = "/" + path; }
-/**
- Ember.HashLocation implements the location API using the browser's
- hash. At present, it relies on a hashchange event existing in the
- browser.
+ if (pathLen > 1 && path.charAt(pathLen - 1) === "/") {
+ path = path.substr(0, pathLen - 1);
+ }
- @class HashLocation
- @namespace Ember
- @extends Ember.Object
-*/
-Ember.HashLocation = Ember.Object.extend({
+ for (i=0, l=path.length; i<l; i++) {
+ states = recognizeChar(states, path.charAt(i));
+ if (!states.length) { break; }
+ }
- init: function() {
- set(this, 'location', get(this, 'location') || window.location);
- },
+ // END DEBUG GROUP
- /**
- @private
+ var solutions = [];
+ for (i=0, l=states.length; i<l; i++) {
+ if (states[i].handlers) { solutions.push(states[i]); }
+ }
- Returns the current `location.hash`, minus the '#' at the front.
+ states = sortSolutions(solutions);
- @method getURL
- */
- getURL: function() {
- return get(this, 'location').hash.substr(1);
- },
+ var state = solutions[0];
- /**
- @private
+ if (state && state.handlers) {
+ return findHandler(state, path);
+ }
+ }
+ };
- Set the `location.hash` and remembers what was set. This prevents
- `onUpdateURL` callbacks from triggering when the hash was set by
- `HashLocation`.
+ function Target(path, matcher, delegate) {
+ this.path = path;
+ this.matcher = matcher;
+ this.delegate = delegate;
+ }
- @method setURL
- @param path {String}
- */
- setURL: function(path) {
- get(this, 'location').hash = path;
- set(this, 'lastSetURL', path);
- },
+ Target.prototype = {
+ to: function(target, callback) {
+ var delegate = this.delegate;
- /**
- @private
+ if (delegate && delegate.willAddRoute) {
+ target = delegate.willAddRoute(this.matcher.target, target);
+ }
- 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.
+ this.matcher.add(this.path, target);
- @method onUpdateURL
- @param callback {Function}
- */
- onUpdateURL: function(callback) {
- var self = this;
- var guid = Ember.guidFor(this);
+ if (callback) {
+ if (callback.length === 0) { throw new Error("You must have an argument in the function passed to `to`"); }
+ this.matcher.addChild(this.path, target, callback, this.delegate);
+ }
+ }
+ };
- Ember.$(window).bind('hashchange.ember-location-'+guid, function() {
- var path = location.hash.substr(1);
- if (get(self, 'lastSetURL') === path) { return; }
+ function Matcher(target) {
+ this.routes = {};
+ this.children = {};
+ this.target = target;
+ }
- set(self, 'lastSetURL', null);
+ Matcher.prototype = {
+ add: function(path, handler) {
+ this.routes[path] = handler;
+ },
- callback(location.hash.substr(1));
- });
- },
+ addChild: function(path, target, callback, delegate) {
+ var matcher = new Matcher(target);
+ this.children[path] = matcher;
- /**
- @private
+ var match = generateMatch(path, matcher, delegate);
- Given a URL, formats it to be placed into the page as part
- of an element's `href` attribute.
+ if (delegate && delegate.contextEntered) {
+ delegate.contextEntered(target, match);
+ }
- This is used, for example, when using the {{action}} helper
- to generate a URL based on an event.
+ callback(match);
+ }
+ };
- @method formatURL
- @param url {String}
- */
- formatURL: function(url) {
- return '#'+url;
- },
+ function generateMatch(startingPath, matcher, delegate) {
+ return function(path, nestedCallback) {
+ var fullPath = startingPath + path;
- willDestroy: function() {
- var guid = Ember.guidFor(this);
+ if (nestedCallback) {
+ nestedCallback(generateMatch(fullPath, matcher, delegate));
+ } else {
+ return new Target(startingPath + path, matcher, delegate);
+ }
+ };
+ }
- Ember.$(window).unbind('hashchange.ember-location-'+guid);
- }
-});
+ function addRoute(routeArray, path, handler) {
+ var len = 0;
+ for (var i=0, l=routeArray.length; i<l; i++) {
+ len += routeArray[i].path.length;
+ }
-Ember.Location.registerImplementation('hash', Ember.HashLocation);
+ path = path.substr(len);
+ routeArray.push({ path: path, handler: handler });
+ }
-})();
+ function eachRoute(baseRoute, matcher, callback, binding) {
+ var routes = matcher.routes;
+ for (var path in routes) {
+ if (routes.hasOwnProperty(path)) {
+ var routeArray = baseRoute.slice();
+ addRoute(routeArray, path, routes[path]);
+ if (matcher.children[path]) {
+ eachRoute(routeArray, matcher.children[path], callback, binding);
+ } else {
+ callback.call(binding, routeArray);
+ }
+ }
+ }
+ }
-(function() {
-/**
-@module ember
-@submodule ember-routing
-*/
+ RouteRecognizer.prototype.map = function(callback, addRouteCallback) {
+ var matcher = new Matcher();
-var get = Ember.get, set = Ember.set;
+ callback(generateMatch("", matcher, this.delegate));
-/**
- Ember.HistoryLocation implements the location API using the browser's
- history.pushState API.
+ eachRoute([], matcher, function(route) {
+ if (addRouteCallback) { addRouteCallback(this, route); }
+ else { this.add(route); }
+ }, this);
+ };
+ return RouteRecognizer;
+ });
- @class HistoryLocation
- @namespace Ember
- @extends Ember.Object
-*/
-Ember.HistoryLocation = Ember.Object.extend({
+})();
- init: function() {
- set(this, 'location', get(this, 'location') || window.location);
- set(this, '_initialURL', get(this, 'location').pathname);
- },
- /**
- Will be pre-pended to path upon state change
- @property rootURL
- @default '/'
- */
- rootURL: '/',
+(function() {
+define("router",
+ ["route-recognizer"],
+ function(RouteRecognizer) {
+ "use strict";
+ /**
+ @private
- /**
- @private
+ This file references several internal structures:
- Used to give history a starting reference
+ ## `RecognizedHandler`
- @property _initialURL
- @default null
- */
- _initialURL: null,
+ * `{String} handler`: A handler name
+ * `{Object} params`: A hash of recognized parameters
- /**
- @private
+ ## `UnresolvedHandlerInfo`
- Returns the current `location.pathname`.
+ * `{Boolean} isDynamic`: whether a handler has any dynamic segments
+ * `{String} name`: the name of a handler
+ * `{Object} context`: the active context for the handler
- @method getURL
- */
- getURL: function() {
- return get(this, 'location').pathname;
- },
+ ## `HandlerInfo`
- /**
- @private
+ * `{Boolean} isDynamic`: whether a handler has any dynamic segments
+ * `{String} name`: the original unresolved handler name
+ * `{Object} handler`: a handler object
+ * `{Object} context`: the active context for the handler
+ */
- 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');
+ function Router() {
+ this.recognizer = new RouteRecognizer();
+ }
- path = this.formatURL(path);
- if ((initialURL !== path && !state) || (state && state.path !== path)) {
- window.history.pushState({ path: path }, null, path);
- }
- },
+ Router.prototype = {
+ /**
+ The main entry point into the router. The API is essentially
+ the same as the `map` method in `route-recognizer`.
- /**
- @private
+ This method extracts the String handler at the last `.to()`
+ call and uses it as the name of the whole route.
- Register a callback to be invoked whenever the browser
- history changes, including using forward and back buttons.
+ @param {Function} callback
+ */
+ map: function(callback) {
+ this.recognizer.delegate = this.delegate;
- @method onUpdateURL
- @param callback {Function}
- */
- onUpdateURL: function(callback) {
- var guid = Ember.guidFor(this);
+ this.recognizer.map(callback, function(recognizer, route) {
+ var lastHandler = route[route.length - 1].handler;
+ var args = [route, { as: lastHandler }];
+ recognizer.add.apply(recognizer, args);
+ });
+ },
- Ember.$(window).bind('popstate.ember-location-'+guid, function(e) {
- callback(location.pathname);
- });
- },
+ hasRoute: function(route) {
+ return this.recognizer.hasRoute(route);
+ },
- /**
- @private
+ /**
+ The entry point for handling a change to the URL (usually
+ via the back and forward button).
- Used when using `{{action}}` helper. The url is always appended to the rootURL.
+ Returns an Array of handlers and the parameters associated
+ with those parameters.
- @method formatURL
- @param url {String}
- */
- formatURL: function(url) {
- var rootURL = get(this, 'rootURL');
+ @param {String} url a URL to process
- if (url !== '') {
- rootURL = rootURL.replace(/\/$/, '');
- }
+ @return {Array} an Array of `[handler, parameter]` tuples
+ */
+ handleURL: function(url) {
+ var results = this.recognizer.recognize(url),
+ objects = [];
- return rootURL + url;
- },
+ if (!results) {
+ throw new Error("No route matched the URL '" + url + "'");
+ }
- willDestroy: function() {
- var guid = Ember.guidFor(this);
+ collectObjects(this, results, 0, []);
+ },
- Ember.$(window).unbind('popstate.ember-location-'+guid);
- }
-});
+ /**
+ Hook point for updating the URL.
-Ember.Location.registerImplementation('history', Ember.HistoryLocation);
+ @param {String} url a URL to update to
+ */
+ updateURL: function() {
+ throw "updateURL is not implemented";
+ },
-})();
+ /**
+ Hook point for replacing the current URL, i.e. with replaceState
+ By default this behaves the same as `updateURL`
+ @param {String} url a URL to update to
+ */
+ replaceURL: function(url) {
+ this.updateURL(url);
+ },
-(function() {
+ /**
+ Transition into the specified named route.
-})();
+ If necessary, trigger the exit callback on any handlers
+ that are no longer represented by the target route.
+ @param {String} name the name of the route
+ */
+ transitionTo: function(name) {
+ var args = Array.prototype.slice.call(arguments, 1);
+ doTransition(this, name, this.updateURL, args);
+ },
+ /**
+ Identical to `transitionTo` except that the current URL will be replaced
+ if possible.
-(function() {
-/**
-@module ember
-@submodule ember-routing
-*/
+ This method is intended primarily for use with `replaceState`.
-var get = Ember.get, set = Ember.set;
+ @param {String} name the name of the route
+ */
+ replaceWith: function(name) {
+ var args = Array.prototype.slice.call(arguments, 1);
+ doTransition(this, name, this.replaceURL, args);
+ },
-var merge = function(original, hash) {
- for (var prop in hash) {
- if (!hash.hasOwnProperty(prop)) { continue; }
- if (original.hasOwnProperty(prop)) { continue; }
+ /**
+ @private
- original[prop] = hash[prop];
- }
-};
+ This method takes a handler name and a list of contexts and returns
+ a serialized parameter hash suitable to pass to `recognizer.generate()`.
-/**
- `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
- the router will update the URL to reflect an application's state changes over time.
+ @param {String} handlerName
+ @param {Array[Object]} contexts
+ @return {Object} a serialized parameter hash
+ */
+ paramsForHandler: function(handlerName, callback) {
+ var output = this._paramsForHandler(handlerName, [].slice.call(arguments, 1));
+ return output.params;
+ },
- ## Adding a Router Instance to Your Application
- An instance of Ember.Router can be associated with an instance of Ember.Application in one of two ways:
+ /**
+ Take a named route and context objects and generate a
+ URL.
- You can provide a subclass of Ember.Router as the `Router` property of your application. An instance
- of this Router class will be instantiated and route detection will be enabled when the application's
- `initialize` method is called. The Router instance will be available as the `router` property
- of the application:
+ @param {String} name the name of the route to generate
+ a URL for
+ @param {...Object} objects a list of objects to serialize
- App = Ember.Application.create({
- Router: Ember.Router.extend({ ... })
- });
+ @return {String} a URL
+ */
+ generate: function(handlerName) {
+ var params = this.paramsForHandler.apply(this, arguments);
+ return this.recognizer.generate(handlerName, params);
+ },
- App.initialize();
- App.get('router') // an instance of App.Router
-
- If you want to define a Router instance elsewhere, you can pass the instance to the application's
- `initialize` method:
-
- App = Ember.Application.create();
- aRouter = Ember.Router.create({ ... });
-
- App.initialize(aRouter);
- App.get('router') // aRouter
-
- ## Adding Routes to a Router
- The `initialState` property of Ember.Router instances is named `root`. The state stored in this
- property must be a subclass of Ember.Route. The `root` route acts as the container for the
- set of routable states but is not routable itself. It should have states that are also subclasses
- of Ember.Route which each have a `route` property describing the URL pattern you would like to detect.
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- index: Ember.Route.extend({
- route: '/'
- }),
- ... additional Ember.Routes ...
- })
- })
- });
- App.initialize();
-
-
- When an application loads, Ember will parse the URL and attempt to find an Ember.Route within
- the application's states that matches. (The example URL-matching below will use the default
- 'hash syntax' provided by `Ember.HashLocation`.)
-
- In the following route structure:
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/'
- }),
- bRoute: Ember.Route.extend({
- route: '/alphabeta'
- })
- })
- })
- });
- App.initialize();
-
- Loading the page at the URL '#/' will detect the route property of 'root.aRoute' ('/') and
- transition the router first to the state named 'root' and then to the substate 'aRoute'.
-
- Respectively, loading the page at the URL '#/alphabeta' would detect the route property of
- 'root.bRoute' ('/alphabeta') and transition the router first to the state named 'root' and
- then to the substate 'bRoute'.
-
- ## Adding Nested Routes to a Router
- Routes can contain nested subroutes each with their own `route` property describing the nested
- portion of the URL they would like to detect and handle. Router, like all instances of StateManager,
- cannot call `transitonTo` with an intermediary state. To avoid transitioning the Router into an
- intermediary state when detecting URLs, a Route with nested routes must define both a base `route`
- property for itself and a child Route with a `route` property of `'/'` which will be transitioned
- to when the base route is detected in the URL:
-
- Given the following application code:
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/theBaseRouteForThisSet',
-
- indexSubRoute: Ember.Route.extend({
- route: '/'
- }),
-
- subRouteOne: Ember.Route.extend({
- route: '/subroute1'
- }),
-
- subRouteTwo: Ember.Route.extend({
- route: '/subRoute2'
- })
-
- })
- })
- })
- });
- App.initialize();
-
- When the application is loaded at '/theBaseRouteForThisSet' the Router will transition to the route
- at path 'root.aRoute' and then transition to state 'indexSubRoute'.
-
- When the application is loaded at '/theBaseRouteForThisSet/subRoute1' the Router will transition to
- the route at path 'root.aRoute' and then transition to state 'subRouteOne'.
-
- ## Route Transition Events
- Transitioning between Ember.Route instances (including the transition into the detected
- route when loading the application) triggers the same transition events as state transitions for
- base `Ember.State`s. However, the default `setup` transition event is named `connectOutlets` on
- Ember.Router instances (see 'Changing View Hierarchy in Response To State Change').
-
- The following route structure when loaded with the URL "#/"
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/',
- enter: function(router) {
- console.log("entering root.aRoute from", router.get('currentState.name'));
- },
- connectOutlets: function(router) {
- console.log("entered root.aRoute, fully transitioned to", router.get('currentState.path'));
- }
- })
- })
- })
- });
- App.initialize();
-
- Will result in console output of:
-
- 'entering root.aRoute from root'
- 'entered root.aRoute, fully transitioned to root.aRoute '
-
- Ember.Route has two additional callbacks for handling URL serialization and deserialization. See
- 'Serializing/Deserializing URLs'
-
- ## Routes With Dynamic Segments
- An Ember.Route's `route` property can reference dynamic sections of the URL by prefacing a URL segment
- with the ':' character. The values of these dynamic segments will be passed as a hash to the
- `deserialize` method of the matching Route (see 'Serializing/Deserializing URLs').
-
- ## Serializing/Deserializing URLs
- Ember.Route has two callbacks for associating a particular object context with a URL: `serialize`
- for converting an object into a parameters hash to fill dynamic segments of a URL and `deserialize`
- for converting a hash of dynamic segments from the URL into the appropriate object.
-
- ### Deserializing A URL's Dynamic Segments
- When an application is first loaded or the URL is changed manually (e.g. through the browser's
- back button) the `deserialize` method of the URL's matching Ember.Route will be called with
- the application's router as its first argument and a hash of the URL's dynamic segments and values
- as its second argument.
-
- The following route structure when loaded with the URL "#/fixed/thefirstvalue/anotherFixed/thesecondvalue":
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/fixed/:dynamicSectionA/anotherFixed/:dynamicSectionB',
- deserialize: function(router, params) {}
- })
- })
- })
- });
- App.initialize();
+ /**
+ @private
+
+ Used internally by `generate` and `transitionTo`.
+ */
+ _paramsForHandler: function(handlerName, objects, doUpdate) {
+ var handlers = this.recognizer.handlersFor(handlerName),
+ params = {},
+ toSetup = [],
+ startIdx = handlers.length,
+ objectsToMatch = objects.length,
+ object, objectChanged, handlerObj, handler, names, i, len;
+
+ // Find out which handler to start matching at
+ for (i=handlers.length-1; i>=0 && objectsToMatch>0; i--) {
+ if (handlers[i].names.length) {
+ objectsToMatch--;
+ startIdx = i;
+ }
+ }
- Will call the 'deserialize' method of the Route instance at the path 'root.aRoute' with the
- following hash as its second argument:
+ if (objectsToMatch > 0) {
+ throw "More objects were passed than dynamic segments";
+ }
- {
- dynamicSectionA: 'thefirstvalue',
- dynamicSectionB: 'thesecondvalue'
- }
+ // Connect the objects to the routes
+ for (i=0, len=handlers.length; i<len; i++) {
+ handlerObj = handlers[i];
+ handler = this.getHandler(handlerObj.handler);
+ names = handlerObj.names;
+ objectChanged = false;
+
+ // If it's a dynamic segment
+ if (names.length) {
+ // If we have objects, use them
+ if (i >= startIdx) {
+ object = objects.shift();
+ objectChanged = true;
+ // Otherwise use existing context
+ } else {
+ object = handler.context;
+ }
- Within `deserialize` you should use this information to retrieve or create an appropriate context
- object for the given URL (e.g. by loading from a remote API or accessing the browser's
- `localStorage`). This object must be the `return` value of `deserialize` and will be
- passed to the Route's `connectOutlets` and `serialize` methods.
-
- When an application's state is changed from within the application itself, the context provided for
- the transition will be passed and `deserialize` is not called (see 'Transitions Between States').
-
- ### Serializing An Object For URLs with Dynamic Segments
- When transitioning into a Route whose `route` property contains dynamic segments the Route's
- `serialize` method is called with the Route's router as the first argument and the Route's
- context as the second argument. The return value of `serialize` will be used to populate the
- dynamic segments and should be an object with keys that match the names of the dynamic sections.
-
- Given the following route structure:
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/'
- }),
- bRoute: Ember.Route.extend({
- route: '/staticSection/:someDynamicSegment',
- serialize: function(router, context) {
- return {
- someDynamicSegment: context.get('name')
- }
+ // Serialize to generate params
+ if (handler.serialize) {
+ merge(params, handler.serialize(object, names));
+ }
+ // If it's not a dynamic segment and we're updating
+ } else if (doUpdate) {
+ // If we've passed the match point we need to deserialize again
+ // or if we never had a context
+ if (i > startIdx || !handler.hasOwnProperty('context')) {
+ if (handler.deserialize) {
+ object = handler.deserialize({});
+ objectChanged = true;
}
- })
- })
- })
- });
- App.initialize();
-
-
- Transitioning to "root.bRoute" with a context of `Object.create({name: 'Yehuda'})` will call
- the Route's `serialize` method with the context as its second argument and update the URL to
- '#/staticSection/Yehuda'.
-
- ## Transitions Between States
- Once a routed application has initialized its state based on the entry URL, subsequent transitions to other
- states will update the URL if the entered Route has a `route` property. Given the following route structure
- loaded at the URL '#/':
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/',
- moveElsewhere: Ember.Route.transitionTo('bRoute')
- }),
- bRoute: Ember.Route.extend({
- route: '/someOtherLocation'
- })
- })
- })
- });
- App.initialize();
-
- And application code:
-
- App.get('router').send('moveElsewhere');
-
- Will transition the application's state to 'root.bRoute' and trigger an update of the URL to
- '#/someOtherLocation'.
-
- For URL patterns with dynamic segments a context can be supplied as the second argument to `send`.
- The router will match dynamic segments names to keys on this object and fill in the URL with the
- supplied values. Given the following state structure loaded at the URL '#/':
-
- App = Ember.Application.create({
- Router: Ember.Router.extend({
- root: Ember.Route.extend({
- aRoute: Ember.Route.extend({
- route: '/',
- moveElsewhere: Ember.Route.transitionTo('bRoute')
- }),
- bRoute: Ember.Route.extend({
- route: '/a/route/:dynamicSection/:anotherDynamicSection',
- connectOutlets: function(router, context) {},
- })
- })
- })
- });
- App.initialize();
+ // Otherwise use existing context
+ } else {
+ object = handler.context;
+ }
+ }
- And application code:
+ // Make sure that we update the context here so it's available to
+ // subsequent deserialize calls
+ if (doUpdate && objectChanged) {
+ // TODO: It's a bit awkward to set the context twice, see if we can DRY things up
+ setContext(handler, object);
+ }
- App.get('router').send('moveElsewhere', {
- dynamicSection: '42',
- anotherDynamicSection: 'Life'
- });
+ toSetup.push({
+ isDynamic: !!handlerObj.names.length,
+ handler: handlerObj.handler,
+ name: handlerObj.name,
+ context: object
+ });
+ }
- Will transition the application's state to 'root.bRoute' and trigger an update of the URL to
- '#/a/route/42/Life'.
+ return { params: params, toSetup: toSetup };
+ },
- The context argument will also be passed as the second argument to the `serialize` method call.
+ isActive: function(handlerName) {
+ var contexts = [].slice.call(arguments, 1);
- ## Injection of Controller Singletons
- During application initialization Ember will detect properties of the application ending in 'Controller',
- create singleton instances of each class, and assign them as properties on the router. The property name
- will be the UpperCamel name converted to lowerCamel format. These controller classes should be subclasses
- of Ember.ObjectController, Ember.ArrayController, Ember.Controller, or a custom Ember.Object that includes the
- Ember.ControllerMixin mixin.
+ var currentHandlerInfos = this.currentHandlerInfos,
+ found = false, names, object, handlerInfo, handlerObj;
- ``` javascript
- App = Ember.Application.create({
- FooController: Ember.Object.create(Ember.ControllerMixin),
- Router: Ember.Router.extend({ ... })
- });
+ for (var i=currentHandlerInfos.length-1; i>=0; i--) {
+ handlerInfo = currentHandlerInfos[i];
+ if (handlerInfo.name === handlerName) { found = true; }
- App.get('router.fooController'); // instance of App.FooController
- ```
+ if (found) {
+ if (contexts.length === 0) { break; }
+
+ if (handlerInfo.isDynamic) {
+ object = contexts.pop();
+ if (handlerInfo.context !== object) { return false; }
+ }
+ }
+ }
- The controller singletons will have their `namespace` property set to the application and their `target`
- property set to the application's router singleton for easy integration with Ember's user event system.
- See 'Changing View Hierarchy in Response To State Change' and 'Responding to User-initiated Events.'
+ return contexts.length === 0 && found;
+ },
- ## Responding to User-initiated Events
- Controller instances injected into the router at application initialization have their `target` property
- set to the application's router instance. These controllers will also be the default `context` for their
- associated views. Uses of the `{{action}}` helper will automatically target the application's router.
+ trigger: function(name) {
+ var args = [].slice.call(arguments);
+ trigger(this, args);
+ }
+ };
- Given the following application entered at the URL '#/':
+ function merge(hash, other) {
+ for (var prop in other) {
+ if (other.hasOwnProperty(prop)) { hash[prop] = other[prop]; }
+ }
+ }
- ``` 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) {
+ function isCurrent(currentHandlerInfos, handlerName) {
+ return currentHandlerInfos[currentHandlerInfos.length - 1].name === handlerName;
+ }
- }
- })
- })
- })
- });
- App.initialize();
- ```
+ /**
+ @private
+
+ This function is called the first time the `collectObjects`
+ function encounters a promise while converting URL parameters
+ into objects.
- The following template:
+ It triggers the `enter` and `setup` methods on the `loading`
+ handler.
- ``` handlebars
- <script type="text/x-handlebars" data-template-name="aView">
- <h1><a {{action anActionOnTheRouter}}>{{title}}</a></h1>
- </script>
- ```
+ @param {Router} router
+ */
+ function loading(router) {
+ if (!router.isLoading) {
+ router.isLoading = true;
+ var handler = router.getHandler('loading');
- 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
- as the context argument. This context will be passed to the `connectOutlets` as its second argument.
+ if (handler) {
+ if (handler.enter) { handler.enter(); }
+ if (handler.setup) { handler.setup(); }
+ }
+ }
+ }
- Different `context` can be supplied from within the `{{action}}` helper, allowing specific context passing
- between application states:
+ /**
+ @private
- ``` handlebars
- <script type="text/x-handlebars" data-template-name="photos">
- {{#each photo in controller}}
- <h1><a {{action showPhoto photo}}>{{title}}</a></h1>
- {{/each}}
- </script>
- ```
+ This function is called if a promise was previously
+ encountered once all promises are resolved.
- See `Handlebars.helpers.action` for additional usage examples.
+ It triggers the `exit` method on the `loading` handler.
+ @param {Router} router
+ */
+ function loaded(router) {
+ router.isLoading = false;
+ var handler = router.getHandler('loading');
+ if (handler && handler.exit) { handler.exit(); }
+ }
- ## Changing View Hierarchy in Response To State Change
+ /**
+ @private
- 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:
+ This function is called if any encountered promise
+ is rejected.
- ``` javascript
- App = Ember.Application.create({
- OneController: Ember.ObjectController.extend(),
- OneView: 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');
- },
- })
- })
- })
- });
- App.initialize();
- ```
+ It triggers the `exit` method on the `loading` handler,
+ the `enter` method on the `failure` handler, and the
+ `setup` method on the `failure` handler with the
+ `error`.
+ @param {Router} router
+ @param {Object} error the reason for the promise
+ rejection, to pass into the failure handler's
+ `setup` method.
+ */
+ function failure(router, error) {
+ loaded(router);
+ var handler = router.getHandler('failure');
+ if (handler && handler.setup) { handler.setup(error); }
+ }
- This will detect the '{{outlet}}' portion of `oneController`'s view (an instance of `App.OneView`) and
- fill it with a rendered instance of `App.AnotherView` whose `context` will be the single instance of
- `App.AnotherController` stored on the router in the `anotherController` property.
+ /**
+ @private
+ */
+ function doTransition(router, name, method, args) {
+ var output = router._paramsForHandler(name, args, true);
+ var params = output.params, toSetup = output.toSetup;
- For more information about Outlets, see `Ember.Handlebars.helpers.outlet`. For additional information on
- the `connectOutlet` method, see `Ember.Controller.connectOutlet`. For more information on
- controller injections, see `Ember.Application#initialize()`. For additional information about view context,
- see `Ember.View`.
+ var url = router.recognizer.generate(name, params);
+ method.call(router, url);
- @class Router
- @namespace Ember
- @extends Ember.StateManager
-*/
-Ember.Router = Ember.StateManager.extend(
-/** @scope Ember.Router.prototype */ {
+ setupContexts(router, toSetup);
+ }
- /**
- @property initialState
- @type String
- @default 'root'
- */
- initialState: 'root',
+ /**
+ @private
+
+ This function is called after a URL change has been handled
+ by `router.handleURL`.
+
+ Takes an Array of `RecognizedHandler`s, and converts the raw
+ params hashes into deserialized objects by calling deserialize
+ on the handlers. This process builds up an Array of
+ `HandlerInfo`s. It then calls `setupContexts` with the Array.
+
+ If the `deserialize` method on a handler returns a promise
+ (i.e. has a method called `then`), this function will pause
+ building up the `HandlerInfo` Array until the promise is
+ resolved. It will use the resolved value as the context of
+ `HandlerInfo`.
+ */
+ function collectObjects(router, results, index, objects) {
+ if (results.length === index) {
+ loaded(router);
+ setupContexts(router, objects);
+ return;
+ }
- /**
- The `Ember.Location` implementation to be used to manage the application
- URL state. The following values are supported:
+ var result = results[index];
+ var handler = router.getHandler(result.handler);
+ var object = handler.deserialize && handler.deserialize(result.params);
- * '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.
+ if (object && typeof object.then === 'function') {
+ loading(router);
- @property location
- @type String
- @default 'hash'
- */
- location: 'hash',
+ // The chained `then` means that we can also catch errors that happen in `proceed`
+ object.then(proceed).then(null, function(error) {
+ failure(router, error);
+ });
+ } else {
+ proceed(object);
+ }
- /**
- 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.
+ function proceed(value) {
+ if (handler.context !== object) {
+ setContext(handler, object);
+ }
- @property rootURL
- @type String
- @default '/'
- */
+ var updatedObjects = objects.concat([{
+ context: value,
+ handler: result.handler,
+ isDynamic: result.isDynamic
+ }]);
+ collectObjects(router, results, index + 1, updatedObjects);
+ }
+ }
- rootURL: '/',
+ /**
+ @private
+
+ Takes an Array of `UnresolvedHandlerInfo`s, resolves the handler names
+ into handlers, and then figures out what to do with each of the handlers.
+
+ For example, consider the following tree of handlers. Each handler is
+ followed by the URL segment it handles.
+
+ ```
+ |~index ("/")
+ | |~posts ("/posts")
+ | | |-showPost ("/:id")
+ | | |-newPost ("/new")
+ | | |-editPost ("/edit")
+ | |~about ("/about/:id")
+ ```
+
+ Consider the following transitions:
+
+ 1. A URL transition to `/posts/1`.
+ 1. Triggers the `deserialize` callback on the
+ `index`, `posts`, and `showPost` handlers
+ 2. Triggers the `enter` callback on the same
+ 3. Triggers the `setup` callback on the same
+ 2. A direct transition to `newPost`
+ 1. Triggers the `exit` callback on `showPost`
+ 2. Triggers the `enter` callback on `newPost`
+ 3. Triggers the `setup` callback on `newPost`
+ 3. A direct transition to `about` with a specified
+ context object
+ 1. Triggers the `exit` callback on `newPost`
+ and `posts`
+ 2. Triggers the `serialize` callback on `about`
+ 3. Triggers the `enter` callback on `about`
+ 4. Triggers the `setup` callback on `about`
+
+ @param {Router} router
+ @param {Array[UnresolvedHandlerInfo]} handlerInfos
+ */
+ function setupContexts(router, handlerInfos) {
+ resolveHandlers(router, handlerInfos);
+
+ var partition =
+ partitionHandlers(router.currentHandlerInfos || [], handlerInfos);
+
+ router.currentHandlerInfos = handlerInfos;
+
+ eachHandler(partition.exited, function(handler, context) {
+ delete handler.context;
+ if (handler.exit) { handler.exit(); }
+ });
- transitionTo: function() {
- this.abortRoutingPromises();
- this._super.apply(this, arguments);
- },
+ eachHandler(partition.updatedContext, function(handler, context) {
+ setContext(handler, context);
+ if (handler.setup) { handler.setup(context); }
+ });
- route: function(path) {
- this.abortRoutingPromises();
+ eachHandler(partition.entered, function(handler, context) {
+ if (handler.enter) { handler.enter(); }
+ setContext(handler, context);
+ if (handler.setup) { handler.setup(context); }
+ });
- set(this, 'isRouting', true);
+ if (router.didTransition) {
+ router.didTransition(handlerInfos);
+ }
+ }
- var routableState;
+ /**
+ @private
- try {
- path = path.replace(get(this, 'rootURL'), '');
- path = path.replace(/^(?=[^\/])/, "/");
+ Iterates over an array of `HandlerInfo`s, passing the handler
+ and context into the callback.
- this.send('navigateAway');
- this.send('unroutePath', path);
+ @param {Array[HandlerInfo]} handlerInfos
+ @param {Function(Object, Object)} callback
+ */
+ function eachHandler(handlerInfos, callback) {
+ for (var i=0, l=handlerInfos.length; i<l; i++) {
+ var handlerInfo = handlerInfos[i],
+ handler = handlerInfo.handler,
+ context = handlerInfo.context;
- routableState = get(this, 'currentState');
- while (routableState && !routableState.get('isRoutable')) {
- routableState = get(routableState, 'parentState');
+ callback(handler, context);
}
- var currentURL = routableState ? routableState.absoluteRoute(this) : '';
- var rest = path.substr(currentURL.length);
-
- this.send('routePath', rest);
- } finally {
- set(this, 'isRouting', false);
}
- routableState = get(this, 'currentState');
- while (routableState && !routableState.get('isRoutable')) {
- routableState = get(routableState, 'parentState');
- }
+ /**
+ @private
- if (routableState) {
- routableState.updateRoute(this, get(this, 'location'));
- }
- },
+ Updates the `handler` field in each element in an Array of
+ `UnresolvedHandlerInfo`s from a handler name to a resolved handler.
- urlFor: function(path, hash) {
- var currentState = get(this, 'currentState') || this,
- state = this.findStateByPath(currentState, path);
+ When done, the Array will contain `HandlerInfo` structures.
- Ember.assert(Ember.String.fmt("Could not find route with path '%@'", [path]), !!state);
- Ember.assert("To get a URL for a state, it must have a `route` property.", !!get(state, 'routeMatcher'));
+ @param {Router} router
+ @param {Array[UnresolvedHandlerInfo]} handlerInfos
+ */
+ function resolveHandlers(router, handlerInfos) {
+ var handlerInfo;
- var location = get(this, 'location'),
- absoluteRoute = state.absoluteRoute(this, hash);
+ for (var i=0, l=handlerInfos.length; i<l; i++) {
+ handlerInfo = handlerInfos[i];
- return location.formatURL(absoluteRoute);
- },
+ handlerInfo.name = handlerInfo.handler;
+ handlerInfo.handler = router.getHandler(handlerInfo.handler);
+ }
+ }
+
+ /**
+ @private
+
+ This function is called when transitioning from one URL to
+ another to determine which handlers are not longer active,
+ which handlers are newly active, and which handlers remain
+ active but have their context changed.
+
+ Take a list of old handlers and new handlers and partition
+ them into four buckets:
+
+ * unchanged: the handler was active in both the old and
+ new URL, and its context remains the same
+ * updated context: the handler was active in both the
+ old and new URL, but its context changed. The handler's
+ `setup` method, if any, will be called with the new
+ context.
+ * exited: the handler was active in the old URL, but is
+ no longer active.
+ * entered: the handler was not active in the old URL, but
+ is now active.
+
+ The PartitionedHandlers structure has three fields:
+
+ * `updatedContext`: a list of `HandlerInfo` objects that
+ represent handlers that remain active but have a changed
+ context
+ * `entered`: a list of `HandlerInfo` objects that represent
+ handlers that are newly active
+ * `exited`: a list of `HandlerInfo` objects that are no
+ longer active.
+
+ @param {Array[HandlerInfo]} oldHandlers a list of the handler
+ information for the previous URL (or `[]` if this is the
+ first handled transition)
+ @param {Array[HandlerInfo]} newHandlers a list of the handler
+ information for the new URL
+
+ @return {Partition}
+ */
+ function partitionHandlers(oldHandlers, newHandlers) {
+ var handlers = {
+ updatedContext: [],
+ exited: [],
+ entered: []
+ };
+
+ var handlerChanged, contextChanged, i, l;
+
+ for (i=0, l=newHandlers.length; i<l; i++) {
+ var oldHandler = oldHandlers[i], newHandler = newHandlers[i];
+
+ if (!oldHandler || oldHandler.handler !== newHandler.handler) {
+ handlerChanged = true;
+ }
+
+ if (handlerChanged) {
+ handlers.entered.push(newHandler);
+ if (oldHandler) { handlers.exited.unshift(oldHandler); }
+ } else if (contextChanged || oldHandler.context !== newHandler.context) {
+ contextChanged = true;
+ handlers.updatedContext.push(newHandler);
+ }
+ }
- urlForEvent: function(eventName) {
- var contexts = Array.prototype.slice.call(arguments, 1);
- var currentState = get(this, 'currentState');
- var targetStateName = currentState.lookupEventTransition(eventName);
+ for (i=newHandlers.length, l=oldHandlers.length; i<l; i++) {
+ handlers.exited.unshift(oldHandlers[i]);
+ }
- Ember.assert(Ember.String.fmt("You must specify a target state for event '%@' in order to link to it in the current state '%@'.", [eventName, get(currentState, 'path')]), !!targetStateName);
+ return handlers;
+ }
- var targetState = this.findStateByPath(currentState, targetStateName);
+ function trigger(router, args) {
+ var currentHandlerInfos = router.currentHandlerInfos;
- Ember.assert("Your target state name " + targetStateName + " for event " + eventName + " did not resolve to a state", !!targetState);
+ if (!currentHandlerInfos) {
+ throw new Error("Could not trigger event. There are no active handlers");
+ }
- var hash = this.serializeRecursively(targetState, contexts, {});
+ var name = args.shift();
- return this.urlFor(targetStateName, hash);
- },
+ for (var i=currentHandlerInfos.length-1; i>=0; i--) {
+ var handlerInfo = currentHandlerInfos[i],
+ handler = handlerInfo.handler;
- serializeRecursively: function(state, contexts, hash) {
- var parentState,
- context = get(state, 'hasContext') ? contexts.pop() : null;
- merge(hash, state.serialize(this, context));
- parentState = state.get("parentState");
- if (parentState && parentState instanceof Ember.Route) {
- return this.serializeRecursively(parentState, contexts, hash);
- } else {
- return hash;
+ if (handler.events && handler.events[name]) {
+ handler.events[name].apply(handler, args);
+ break;
+ }
+ }
}
- },
- abortRoutingPromises: function() {
- if (this._routingPromises) {
- this._routingPromises.abort();
- this._routingPromises = null;
+ function setContext(handler, context) {
+ handler.context = context;
+ if (handler.contextDidChange) { handler.contextDidChange(); }
}
- },
+ return Router;
+ });
- handleStatePromises: function(states, complete) {
- this.abortRoutingPromises();
+})();
- this.set('isLocked', true);
- var manager = this;
- this._routingPromises = Ember._PromiseChain.create({
- promises: states.slice(),
+(function() {
+/**
+@module ember
+@submodule ember-routing
+*/
- successCallback: function() {
- manager.set('isLocked', false);
- complete();
- },
+function DSL(name) {
+ this.parent = name;
+ this.matches = [];
+}
- failureCallback: function() {
- throw "Unable to load object";
- },
+DSL.prototype = {
+ resource: function(name, options, callback) {
+ if (arguments.length === 2 && typeof options === 'function') {
+ callback = options;
+ options = {};
+ }
- promiseSuccessCallback: function(item, args) {
- set(item, 'object', args[0]);
- },
+ if (arguments.length === 1) {
+ options = {};
+ }
- abortCallback: function() {
- manager.set('isLocked', false);
- }
- }).start();
+ if (typeof options.path !== 'string') {
+ options.path = "/" + name;
+ }
+
+ if (callback) {
+ var dsl = new DSL(name);
+ callback.call(dsl);
+ this.push(options.path, name, dsl.generate());
+ } else {
+ this.push(options.path, name);
+ }
},
- init: function() {
- this._super();
+ push: function(url, name, callback) {
+ if (url === "" || url === "/") { this.explicitIndex = true; }
+
+ this.matches.push([url, name, callback]);
+ },
+
+ route: function(name, options) {
+ Ember.assert("You must use `this.resource` to nest", typeof options !== 'function');
- var location = get(this, 'location'),
- rootURL = get(this, 'rootURL');
+ options = options || {};
- if ('string' === typeof location) {
- set(this, 'location', Ember.Location.create({
- implementation: location,
- rootURL: rootURL
- }));
+ if (typeof options.path !== 'string') {
+ options.path = "/" + name;
}
- this.assignRouter(this, this);
- },
+ if (this.parent && this.parent !== 'application') {
+ name = this.parent + "." + name;
+ }
- assignRouter: function(state, router) {
- state.router = router;
+ this.push(options.path, name);
+ },
- var childStates = state.states;
+ generate: function() {
+ var dslMatches = this.matches;
- if (childStates) {
- for (var stateName in childStates) {
- if (!childStates.hasOwnProperty(stateName)) { continue; }
- this.assignRouter(childStates[stateName], router);
- }
+ if (!this.explicitIndex) {
+ this.route("index", { path: "/" });
}
- },
- willDestroy: function() {
- get(this, 'location').destroy();
+ return function(match) {
+ for (var i=0, l=dslMatches.length; i<l; i++) {
+ var dslMatch = dslMatches[i];
+ match(dslMatch[0]).to(dslMatch[1], dslMatch[2]);
+ }
+ };
}
-});
+};
+
+DSL.map = function(callback) {
+ var dsl = new DSL();
+ callback.call(dsl);
+ return dsl;
+};
+
+Ember.RouterDSL = DSL;
})();
(function() {
/**
-Ember Routing
-
@module ember
@submodule ember-routing
-@requires ember-states
*/
-})();
+Ember.controllerFor = function(container, controllerName, context) {
+ return container.lookup('controller:' + controllerName) ||
+ Ember.generateController(container, controllerName, context);
+};
-(function() {
-// ==========================================================================
-// Project: metamorph
-// Copyright: ©2011 My Company Inc. All rights reserved.
-// ==========================================================================
-
-(function(window) {
-
- var K = function(){},
- guid = 0,
- document = window.document,
-
- // Feature-detect the W3C range API, the extended check is for IE9 which only partially supports ranges
- supportsRange = ('createRange' in document) && (typeof Range !== 'undefined') && Range.prototype.createContextualFragment,
-
- // Internet Explorer prior to 9 does not allow setting innerHTML if the first element
- // is a "zero-scope" element. This problem can be worked around by making
- // the first node an invisible text node. We, like Modernizr, use ­
- needsShy = (function(){
- var testEl = document.createElement('div');
- testEl.innerHTML = "<div></div>";
- testEl.firstChild.innerHTML = "<script></script>";
- return testEl.firstChild.innerHTML === '';
- })();
-
- // Constructor that supports either Metamorph('foo') or new
- // Metamorph('foo');
- //
- // Takes a string of HTML as the argument.
+Ember.generateController = function(container, controllerName, context) {
+ var controller;
- var Metamorph = function(html) {
- var self;
+ if (context && Ember.isArray(context)) {
+ controller = Ember.ArrayController.extend({
+ content: context
+ });
+ } else if (context) {
+ controller = Ember.ObjectController.extend({
+ content: context
+ });
+ } else {
+ controller = Ember.Controller.extend();
+ }
- if (this instanceof Metamorph) {
- self = this;
- } else {
- self = new K();
- }
+ controller.toString = function() {
+ return "(generated " + controllerName + " controller)";
+ };
- self.innerHTML = html;
- var myGuid = 'metamorph-'+(guid++);
- self.start = myGuid + '-start';
- self.end = myGuid + '-end';
+ container.register('controller', controllerName, controller);
+ return container.lookup('controller:' + controllerName);
+};
- return self;
- };
+})();
- K.prototype = Metamorph.prototype;
- var rangeFor, htmlFunc, removeFunc, outerHTMLFunc, appendToFunc, afterFunc, prependFunc, startTagFunc, endTagFunc;
- outerHTMLFunc = function() {
- return this.startTag() + this.innerHTML + this.endTag();
- };
+(function() {
+/**
+@module ember
+@submodule ember-routing
+*/
- startTagFunc = function() {
- return "<script id='" + this.start + "' type='text/x-placeholder'></script>";
- };
+var Router = requireModule("router");
+var get = Ember.get, set = Ember.set, classify = Ember.String.classify;
- endTagFunc = function() {
- return "<script id='" + this.end + "' type='text/x-placeholder'></script>";
- };
+var DefaultView = Ember.View.extend(Ember._Metamorph);
+function setupLocation(router) {
+ var location = get(router, 'location'),
+ rootURL = get(router, 'rootURL');
- // If we have the W3C range API, this process is relatively straight forward.
- if (supportsRange) {
+ if ('string' === typeof location) {
+ location = set(router, 'location', Ember.Location.create({
+ implementation: location
+ }));
- // Get a range for the current morph. Optionally include the starting and
- // ending placeholders.
- rangeFor = function(morph, outerToo) {
- var range = document.createRange();
- var before = document.getElementById(morph.start);
- var after = document.getElementById(morph.end);
+ if (typeof rootURL === 'string') {
+ set(location, 'rootURL', rootURL);
+ }
+ }
+}
- if (outerToo) {
- range.setStartBefore(before);
- range.setEndAfter(after);
- } else {
- range.setStartAfter(before);
- range.setEndBefore(after);
- }
+Ember.Router = Ember.Object.extend({
+ location: 'hash',
- return range;
- };
+ init: function() {
+ this.router = this.constructor.router;
+ this._activeViews = {};
+ setupLocation(this);
+ },
- htmlFunc = function(html, outerToo) {
- // get a range for the current metamorph object
- var range = rangeFor(this, outerToo);
+ startRouting: function() {
+ this.router = this.router || this.constructor.map(Ember.K);
- // delete the contents of the range, which will be the
- // nodes between the starting and ending placeholder.
- range.deleteContents();
+ var router = this.router,
+ location = get(this, 'location'),
+ container = this.container,
+ self = this;
- // create a new document fragment for the HTML
- var fragment = range.createContextualFragment(html);
+ setupRouter(this, router, location);
- // insert the fragment into the range
- range.insertNode(fragment);
- };
+ container.register('view', 'default', DefaultView);
+ container.register('view', 'toplevel', Ember.View.extend());
- removeFunc = function() {
- // get a range for the current metamorph object including
- // the starting and ending placeholders.
- var range = rangeFor(this, true);
+ router.handleURL(location.getURL());
+ location.onUpdateURL(function(url) {
+ router.handleURL(url);
+ });
+ },
- // delete the entire range.
- range.deleteContents();
- };
+ didTransition: function(infos) {
+ // Don't do any further action here if we redirected
+ if (infos[infos.length-1].handler.transitioned) { return; }
- appendToFunc = function(node) {
- var range = document.createRange();
- range.setStart(node);
- range.collapse(false);
- var frag = range.createContextualFragment(this.outerHTML());
- node.appendChild(frag);
- };
+ var appController = this.container.lookup('controller:application'),
+ path = routePath(infos);
- afterFunc = function(html) {
- var range = document.createRange();
- var after = document.getElementById(this.end);
+ set(appController, 'currentPath', path);
+ this.notifyPropertyChange('url');
- range.setStartAfter(after);
- range.setEndAfter(after);
+ if (get(this, 'namespace').LOG_TRANSITIONS) {
+ Ember.Logger.log("Transitioned into '" + path + "'");
+ }
+ },
- var fragment = range.createContextualFragment(html);
- range.insertNode(fragment);
- };
+ handleURL: function(url) {
+ this.router.handleURL(url);
+ this.notifyPropertyChange('url');
+ },
- prependFunc = function(html) {
- var range = document.createRange();
- var start = document.getElementById(this.start);
+ transitionTo: function(passedName) {
+ var args = [].slice.call(arguments), name;
- range.setStartAfter(start);
- range.setEndAfter(start);
+ if (!this.router.hasRoute(passedName)) {
+ name = args[0] = passedName + '.index';
+ } else {
+ name = passedName;
+ }
- var fragment = range.createContextualFragment(html);
- range.insertNode(fragment);
- };
+ Ember.assert("The route " + passedName + " was not found", this.router.hasRoute(name));
- } else {
- /**
- * This code is mostly taken from jQuery, with one exception. In jQuery's case, we
- * have some HTML and we need to figure out how to convert it into some nodes.
- *
- * In this case, jQuery needs to scan the HTML looking for an opening tag and use
- * that as the key for the wrap map. In our case, we know the parent node, and
- * can use its type as the key for the wrap map.
- **/
- var wrapMap = {
- select: [ 1, "<select multiple='multiple'>", "</select>" ],
- fieldset: [ 1, "<fieldset>", "</fieldset>" ],
- table: [ 1, "<table>", "</table>" ],
- tbody: [ 2, "<table><tbody>", "</tbody></table>" ],
- tr: [ 3, "<table><tbody><tr>", "</tr></tbody></table>" ],
- colgroup: [ 2, "<table><tbody></tbody><colgroup>", "</colgroup></table>" ],
- map: [ 1, "<map>", "</map>" ],
- _default: [ 0, "", "" ]
- };
+ this.router.transitionTo.apply(this.router, args);
+ this.notifyPropertyChange('url');
+ },
- /**
- * Given a parent node and some HTML, generate a set of nodes. Return the first
- * node, which will allow us to traverse the rest using nextSibling.
- *
- * We need to do this because innerHTML in IE does not really parse the nodes.
- **/
- var firstNodeFor = function(parentNode, html) {
- var arr = wrapMap[parentNode.tagName.toLowerCase()] || wrapMap._default;
- var depth = arr[0], start = arr[1], end = arr[2];
+ replaceWith: function() {
+ this.router.replaceWith.apply(this.router, arguments);
+ this.notifyPropertyChange('url');
+ },
- if (needsShy) { html = '­'+html; }
+ generate: function() {
+ var url = this.router.generate.apply(this.router, arguments);
+ return this.location.formatURL(url);
+ },
- var element = document.createElement('div');
- element.innerHTML = start + html + end;
+ isActive: function(routeName) {
+ var router = this.router;
+ return router.isActive.apply(router, arguments);
+ },
- for (var i=0; i<=depth; i++) {
- element = element.firstChild;
- }
+ send: function(name, context) {
+ if (Ember.$ && context instanceof Ember.$.Event) {
+ context = context.context;
+ }
- // Look for ­ to remove it.
- if (needsShy) {
- var shyElement = element;
+ this.router.trigger(name, context);
+ },
- // Sometimes we get nameless elements with the shy inside
- while (shyElement.nodeType === 1 && !shyElement.nodeName) {
- shyElement = shyElement.firstChild;
- }
+ hasRoute: function(route) {
+ return this.router.hasRoute(route);
+ },
- // At this point it's the actual unicode character.
- if (shyElement.nodeType === 3 && shyElement.nodeValue.charAt(0) === "\u00AD") {
- shyElement.nodeValue = shyElement.nodeValue.slice(1);
- }
- }
+ _lookupActiveView: function(templateName) {
+ var active = this._activeViews[templateName];
+ return active && active[0];
+ },
- return element;
- };
+ _connectActiveView: function(templateName, view) {
+ var existing = this._activeViews[templateName];
- /**
- * In some cases, Internet Explorer can create an anonymous node in
- * the hierarchy with no tagName. You can create this scenario via:
- *
- * div = document.createElement("div");
- * div.innerHTML = "<table>­<script></script><tr><td>hi</td></tr></table>";
- * div.firstChild.firstChild.tagName //=> ""
- *
- * If our script markers are inside such a node, we need to find that
- * node and use *it* as the marker.
- **/
- var realNode = function(start) {
- while (start.parentNode.tagName === "") {
- start = start.parentNode;
- }
+ if (existing) {
+ existing[0].off('willDestroyElement', this, existing[1]);
+ }
- return start;
+ var disconnect = function() {
+ delete this._activeViews[templateName];
};
- /**
- * When automatically adding a tbody, Internet Explorer inserts the
- * tbody immediately before the first <tr>. Other browsers create it
- * before the first node, no matter what.
- *
- * This means the the following code:
- *
- * div = document.createElement("div");
- * div.innerHTML = "<table><script id='first'></script><tr><td>hi</td></tr><script id='last'></script></table>
- *
- * Generates the following DOM in IE:
- *
- * + div
- * + table
- * - script id='first'
- * + tbody
- * + tr
- * + td
- * - "hi"
- * - script id='last'
- *
- * Which means that the two script tags, even though they were
- * inserted at the same point in the hierarchy in the original
- * HTML, now have different parents.
- *
- * This code reparents the first script tag by making it the tbody's
- * first child.
- **/
- var fixParentage = function(start, end) {
- if (start.parentNode !== end.parentNode) {
- end.parentNode.insertBefore(start, end.parentNode.firstChild);
- }
- };
+ this._activeViews[templateName] = [view, disconnect];
+ view.one('willDestroyElement', this, disconnect);
+ }
+});
- htmlFunc = function(html, outerToo) {
- // get the real starting node. see realNode for details.
- var start = realNode(document.getElementById(this.start));
- var end = document.getElementById(this.end);
- var parentNode = end.parentNode;
- var node, nextSibling, last;
-
- // make sure that the start and end nodes share the same
- // parent. If not, fix it.
- fixParentage(start, end);
-
- // remove all of the nodes after the starting placeholder and
- // before the ending placeholder.
- node = start.nextSibling;
- while (node) {
- nextSibling = node.nextSibling;
- last = node === end;
-
- // if this is the last node, and we want to remove it as well,
- // set the `end` node to the next sibling. This is because
- // for the rest of the function, we insert the new nodes
- // before the end (note that insertBefore(node, null) is
- // the same as appendChild(node)).
- //
- // if we do not want to remove it, just break.
- if (last) {
- if (outerToo) { end = node.nextSibling; } else { break; }
- }
+Ember.Router.reopenClass({
+ defaultFailureHandler: {
+ setup: function(error) {
+ Ember.Logger.error('Error while loading route:', error);
- node.parentNode.removeChild(node);
+ // Using setTimeout allows us to escape from the Promise's try/catch block
+ setTimeout(function() { throw error; });
+ }
+ }
+});
- // if this is the last node and we didn't break before
- // (because we wanted to remove the outer nodes), break
- // now.
- if (last) { break; }
+function getHandlerFunction(router) {
+ var seen = {}, container = router.container;
- node = nextSibling;
- }
+ return function(name) {
+ var handler = container.lookup('route:' + name);
+ if (seen[name]) { return handler; }
- // get the first node for the HTML string, even in cases like
- // tables and lists where a simple innerHTML on a div would
- // swallow some of the content.
- node = firstNodeFor(start.parentNode, html);
-
- // copy the nodes for the HTML between the starting and ending
- // placeholder.
- while (node) {
- nextSibling = node.nextSibling;
- parentNode.insertBefore(node, end);
- node = nextSibling;
- }
- };
+ seen[name] = true;
- // remove the nodes in the DOM representing this metamorph.
- //
- // this includes the starting and ending placeholders.
- removeFunc = function() {
- var start = realNode(document.getElementById(this.start));
- var end = document.getElementById(this.end);
-
- this.html('');
- start.parentNode.removeChild(start);
- end.parentNode.removeChild(end);
- };
+ if (!handler) {
+ if (name === 'loading') { return {}; }
+ if (name === 'failure') { return router.constructor.defaultFailureHandler; }
- appendToFunc = function(parentNode) {
- var node = firstNodeFor(parentNode, this.outerHTML());
+ container.register('route', name, Ember.Route.extend());
+ handler = container.lookup('route:' + name);
+ }
- while (node) {
- nextSibling = node.nextSibling;
- parentNode.appendChild(node);
- node = nextSibling;
- }
- };
+ handler.routeName = name;
+ return handler;
+ };
+}
- afterFunc = function(html) {
- // get the real starting node. see realNode for details.
- var end = document.getElementById(this.end);
- var insertBefore = end.nextSibling;
- var parentNode = end.parentNode;
- var nextSibling;
- var node;
-
- // get the first node for the HTML string, even in cases like
- // tables and lists where a simple innerHTML on a div would
- // swallow some of the content.
- node = firstNodeFor(parentNode, html);
-
- // copy the nodes for the HTML between the starting and ending
- // placeholder.
- while (node) {
- nextSibling = node.nextSibling;
- parentNode.insertBefore(node, insertBefore);
- node = nextSibling;
- }
- };
+function handlerIsActive(router, handlerName) {
+ var handler = router.container.lookup('route:' + handlerName),
+ currentHandlerInfos = router.router.currentHandlerInfos,
+ handlerInfo;
- prependFunc = function(html) {
- var start = document.getElementById(this.start);
- var parentNode = start.parentNode;
- var nextSibling;
- var node;
+ for (var i=0, l=currentHandlerInfos.length; i<l; i++) {
+ handlerInfo = currentHandlerInfos[i];
+ if (handlerInfo.handler === handler) { return true; }
+ }
- node = firstNodeFor(parentNode, html);
- var insertBefore = start.nextSibling;
+ return false;
+}
- while (node) {
- nextSibling = node.nextSibling;
- parentNode.insertBefore(node, insertBefore);
- node = nextSibling;
- }
- }
+function routePath(handlerInfos) {
+ var path = [];
+
+ for (var i=1, l=handlerInfos.length; i<l; i++) {
+ var name = handlerInfos[i].name,
+ nameParts = name.split(".");
+
+ path.push(nameParts[nameParts.length - 1]);
}
- Metamorph.prototype.html = function(html) {
- this.checkRemoved();
- if (html === undefined) { return this.innerHTML; }
+ return path.join(".");
+}
+
+function setupRouter(emberRouter, router, location) {
+ var lastURL;
- htmlFunc.call(this, html);
+ router.getHandler = getHandlerFunction(emberRouter);
- this.innerHTML = html;
+ var doUpdateURL = function() {
+ location.setURL(lastURL);
};
- Metamorph.prototype.replaceWith = function(html) {
- this.checkRemoved();
- htmlFunc.call(this, html, true);
+ router.updateURL = function(path) {
+ lastURL = path;
+ Ember.run.once(doUpdateURL);
};
- Metamorph.prototype.remove = removeFunc;
- Metamorph.prototype.outerHTML = outerHTMLFunc;
- Metamorph.prototype.appendTo = appendToFunc;
- Metamorph.prototype.after = afterFunc;
- Metamorph.prototype.prepend = prependFunc;
- Metamorph.prototype.startTag = startTagFunc;
- Metamorph.prototype.endTag = endTagFunc;
+ if (location.replaceURL) {
+ var doReplaceURL = function() {
+ location.replaceURL(lastURL);
+ };
- Metamorph.prototype.isRemoved = function() {
- var before = document.getElementById(this.start);
- var after = document.getElementById(this.end);
+ router.replaceURL = function(path) {
+ lastURL = path;
+ Ember.run.once(doReplaceURL);
+ };
+ }
- return !before || !after;
+ router.didTransition = function(infos) {
+ emberRouter.didTransition(infos);
};
+}
- Metamorph.prototype.checkRemoved = function() {
- if (this.isRemoved()) {
- throw new Error("Cannot perform operations on a Metamorph that is not in the DOM.");
- }
- };
+Ember.Router.reopenClass({
+ map: function(callback) {
+ var router = this.router = new Router();
- window.Metamorph = Metamorph;
-})(this);
+ var dsl = Ember.RouterDSL.map(function() {
+ this.resource('application', { path: "/" }, function() {
+ callback.call(this);
+ });
+ });
+ router.map(dsl.generate());
+ return router;
+ }
+});
})();
+
+
(function() {
-/*globals Handlebars */
/**
@module ember
-@submodule ember-handlebars
+@submodule ember-routing
*/
-var objectCreate = Ember.create;
+var get = Ember.get, set = Ember.set,
+ classify = Ember.String.classify,
+ decamelize = Ember.String.decamelize;
+
+
+Ember.Route = Ember.Object.extend({
+ exit: function() {
+ teardownView(this);
+ },
+
+ /**
+ Transition into another route. Optionally supply a model for the
+ route in question. The model will be serialized into the URL
+ using the `serialize` hook.
+
+ @method transitionTo
+ @param {String} name the name of the route
+ @param {...Object} models the
+ */
+ transitionTo: function() {
+ this.transitioned = true;
+ return this.router.transitionTo.apply(this.router, arguments);
+ },
+
+ /**
+ Transition into another route while replacing the current URL if
+ possible. Identical to `transitionTo` in all other respects.
+
+ @method replaceWith
+ @param {String} name the name of the route
+ @param {...Object} models the
+ */
+ replaceWith: function() {
+ this.transitioned = true;
+ return this.router.replaceWith.apply(this.router, arguments);
+ },
+ send: function() {
+ return this.router.send.apply(this.router, arguments);
+ },
-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]+/));
+ /**
+ @private
-/**
- Prepares the Handlebars templating library for use inside Ember's view
- system.
+ This hook is the entry point for router.js
- The Ember.Handlebars object is the standard Handlebars library, extended to use
- Ember's get() method instead of direct property access, which allows
- computed properties to be used inside templates.
+ @method setup
+ */
+ setup: function(context) {
+ this.transitioned = false;
+ this.redirect(context);
- To create an Ember.Handlebars template, call Ember.Handlebars.compile(). This will
- return a function that can be used by Ember.View for rendering.
+ if (this.transitioned) { return; }
- @class Handlebars
- @namespace Ember
-*/
-Ember.Handlebars = objectCreate(Handlebars);
+ var controller = this.controllerFor(this.routeName, context);
-/**
-@class helpers
-@namespace Ember.Handlebars
-*/
-Ember.Handlebars.helpers = objectCreate(Handlebars.helpers);
+ if (controller) {
+ set(controller, 'model', context);
+ }
-/**
- Override the the opcode compiler and JavaScript compiler for Handlebars.
+ if (this.setupControllers) {
+ Ember.deprecate("Ember.Route.setupControllers is deprecated. Please use Ember.Route.setupController(controller, model) instead.");
+ this.setupControllers(controller, context);
+ } else {
+ this.setupController(controller, context);
+ }
- @class Compiler
- @namespace Ember.Handlebars
- @private
- @constructor
-*/
-Ember.Handlebars.Compiler = function() {};
+ if (this.renderTemplates) {
+ Ember.deprecate("Ember.Route.renderTemplates is deprecated. Please use Ember.Route.renderTemplate(controller, model) instead.");
+ this.renderTemplates(context);
+ } else {
+ this.renderTemplate(controller, context);
+ }
+ },
-// Handlebars.Compiler doesn't exist in runtime-only
-if (Handlebars.Compiler) {
- Ember.Handlebars.Compiler.prototype = objectCreate(Handlebars.Compiler.prototype);
-}
+ /**
+ A hook you can implement to optionally redirect to another route.
-Ember.Handlebars.Compiler.prototype.compiler = Ember.Handlebars.Compiler;
+ If you call `this.transitionTo` from inside of this hook, this route
+ will not be entered in favor of the other hook.
-/**
- @class JavaScriptCompiler
- @namespace Ember.Handlebars
- @private
- @constructor
-*/
-Ember.Handlebars.JavaScriptCompiler = function() {};
+ @method redirect
+ @param {Object} model the model for this route
+ */
+ redirect: Ember.K,
-// Handlebars.JavaScriptCompiler doesn't exist in runtime-only
-if (Handlebars.JavaScriptCompiler) {
- Ember.Handlebars.JavaScriptCompiler.prototype = objectCreate(Handlebars.JavaScriptCompiler.prototype);
- Ember.Handlebars.JavaScriptCompiler.prototype.compiler = Ember.Handlebars.JavaScriptCompiler;
-}
+ /**
+ @private
+ The hook called by `router.js` to convert parameters into the context
+ for this handler. The public Ember hook is `model`.
-Ember.Handlebars.JavaScriptCompiler.prototype.namespace = "Ember.Handlebars";
+ @method deserialize
+ */
+ deserialize: function(params) {
+ var model = this.model(params);
+ return this.currentModel = model;
+ },
+ /**
+ @private
-Ember.Handlebars.JavaScriptCompiler.prototype.initializeBuffer = function() {
- return "''";
-};
+ Called when the context is changed by router.js.
+ */
+ contextDidChange: function() {
+ this.currentModel = this.context;
+ },
-/**
- @private
+ /**
+ A hook you can implement to convert the URL into the model for
+ this route.
- 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.
+ ```js
+ App.Route.map(function(match) {
+ match("/posts/:post_id").to("post");
+ });
+ ```
- @method appendToBuffer
- @param string {String}
-*/
-Ember.Handlebars.JavaScriptCompiler.prototype.appendToBuffer = function(string) {
- return "data.buffer.push("+string+");";
-};
+ The model for the `post` route is `App.Post.find(params.post_id)`.
-/**
- @private
+ By default, if your route has a dynamic segment ending in `_id`:
- 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.
+ * The model class is determined from the segment (`post_id`'s
+ class is `App.Post`)
+ * The find method is called on the model class with the value of
+ the dynamic segment.
- @method mustache
- @for Ember.Handlebars.Compiler
- @param mustache
-*/
-Ember.Handlebars.Compiler.prototype.mustache = function(mustache) {
- if (mustache.params.length || mustache.hash) {
- return Handlebars.Compiler.prototype.mustache.call(this, mustache);
- } else {
- var id = new Handlebars.AST.IdNode(['_triageMustache']);
+ @method model
+ @param {Object} params the parameters extracted from the URL
+ */
+ model: function(params) {
+ var match, name, value;
- // Update the mustache node to include a hash value indicating whether the original node
- // was escaped. This will allow us to properly escape values when the underlying value
- // changes and we need to re-render the value.
- if(!mustache.escaped) {
- mustache.hash = mustache.hash || new Handlebars.AST.HashNode([]);
- mustache.hash.pairs.push(["unescaped", new Handlebars.AST.StringNode("true")]);
+ for (var prop in params) {
+ if (match = prop.match(/^(.*)_id$/)) {
+ name = match[1];
+ value = params[prop];
+ }
}
- mustache = new Handlebars.AST.MustacheNode([id].concat([mustache.id]), mustache.hash, !mustache.escaped);
- return Handlebars.Compiler.prototype.mustache.call(this, 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) {
- var ast = Handlebars.parse(string);
+ if (!name) { return; }
- var options = {
- knownHelpers: {
- action: true,
- unbound: true,
- bindAttr: true,
- template: true,
- view: true,
- _triageMustache: true
- },
- data: true,
- stringParams: true
- };
+ var className = classify(name),
+ namespace = this.router.namespace,
+ modelClass = namespace[className];
- var environment = new Ember.Handlebars.Compiler().compile(ast, options);
- return new Ember.Handlebars.JavaScriptCompiler().compile(environment, options, undefined, true);
-};
+ Ember.assert("You used the dynamic segment " + name + "_id in your router, but " + namespace + "." + className + " did not exist and you did not override your state's `model` hook.", modelClass);
+ return modelClass.find(value);
+ },
-// We don't support this for Handlebars runtime-only
-if (Handlebars.compile) {
/**
- 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);
- var options = { data: true, stringParams: true };
- var environment = new Ember.Handlebars.Compiler().compile(ast, options);
- var templateSpec = new Ember.Handlebars.JavaScriptCompiler().compile(environment, options, undefined, true);
-
- return Handlebars.template(templateSpec);
- };
-}
+ A hook you can implement to convert the route's model into parameters
+ for the URL.
-/**
- @private
+ ```js
+ App.Route.map(function(match) {
+ match("/posts/:post_id").to("post");
+ });
- If a path starts with a reserved keyword, returns the root
- that should be used.
+ App.PostRoute = Ember.Route.extend({
+ model: function(params) {
+ // the server returns `{ id: 12 }`
+ return jQuery.getJSON("/posts/" + params.post_id);
+ },
- @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) || {},
- keyword, isKeyword;
+ serialize: function(model) {
+ // this will make the URL `/posts/12`
+ return { post_id: model.id };
+ }
+ });
+ ```
- // Get the first segment of the path. For example, if the
- // path is "foo.bar.baz", returns "foo".
- keyword = path.split('.', 1)[0];
+ The default `serialize` method inserts the model's `id` into the
+ route's dynamic segment (in this case, `:post_id`).
- // Test to see if the first path is a keyword that has been
- // passed along in the view's data hash. If so, we will treat
- // that object as the new root.
- if (keywords.hasOwnProperty(keyword)) {
- // Look up the value in the template's data hash.
- root = keywords[keyword];
- isKeyword = true;
+ This method is called when `transitionTo` is called with a context
+ in order to populate the URL.
- // Handle cases where the entire path is the reserved
- // word. In that case, return the object itself.
- if (path === keyword) {
- path = '';
- } else {
- // Strip the keyword from the path and look up
- // the remainder from the newly found root.
- path = path.substr(keyword.length+1);
- }
- }
+ @method serialize
+ @param {Object} model the route's model
+ @param {Array} params an Array of parameter names for the current
+ route (in the example, `['post_id']`.
+ @return {Object} the serialized parameters
+ */
+ serialize: function(model, params) {
+ if (params.length !== 1) { return; }
- return { root: root, path: path, isKeyword: isKeyword };
-};
+ var name = params[0], object = {};
+ object[name] = get(model, 'id');
+ return object;
+ },
-/**
- 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.
+ /**
+ A hook you can use to setup the controller for the current route.
- @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),
- value;
+ This method is called with the controller for the current route and the
+ model supplied by the `model` hook.
- // In cases where the path begins with a keyword, change the
- // root to the value represented by that keyword, and ensure
- // the path is relative to it.
- root = normalizedPath.root;
- path = normalizedPath.path;
+ ```js
+ App.Route.map(function(match) {
+ match("/posts/:post_id").to("post");
+ });
+ ```
- value = Ember.get(root, path);
+ For the `post` route, the controller is `App.PostController`.
- if (value === undefined && root !== window && Ember.isGlobalPath(path)) {
- value = Ember.get(window, path);
- }
- return value;
-};
+ By default, the `setupController` hook sets the `content` property of
+ the controller to the `model`.
-/**
- @private
+ If no explicit controller is defined, the route will automatically create
+ an appropriate controller for the model:
- 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.
+ * if the model is an `Ember.Array` (including record arrays from Ember
+ Data), the controller is an `Ember.ArrayController`.
+ * otherwise, the controller is an `Ember.ObjectController`.
- This throws an exception with a more helpful error message so the user can
- track down where the problem is happening.
+ This means that your template will get a proxy for the model as its
+ context, and you can act as though the model itself was the context.
- @method helperMissing
- @for Ember.Handlebars.helpers
- @param {String} path
- @param {Hash} options
-*/
-Ember.Handlebars.registerHelper('helperMissing', function(path, options) {
- var error, view = "";
+ @method setupController
+ */
+ setupController: Ember.K,
- error = "%@ Handlebars error: Could not find property '%@' on object %@.";
- if (options.data){
- view = options.data.view;
- }
- throw new Ember.Error(Ember.String.fmt(error, [view, path, this]));
-});
+ /**
+ Returns the controller for a particular route.
+ ```js
+ App.PostRoute = Ember.Route.extend({
+ setupController: function(controller, post) {
+ this._super(controller, post);
+ this.controllerFor('posts').set('currentPost', post);
+ }
+ });
+ ```
-})();
+ By default, the controller for `post` is the shared instance of
+ `App.PostController`.
+ @method controllerFor
+ @param {String} name the name of the route
+ @param {Object} model the model associated with the route (optional)
+ @return {Ember.Controller}
+ */
+ controllerFor: function(name, model) {
+ var container = this.router.container,
+ controller = container.lookup('controller:' + name);
+ if (!controller) {
+ model = model || this.modelFor(name);
-(function() {
-/**
- @method htmlSafe
- @for Ember.String
- @static
-*/
-Ember.String.htmlSafe = function(str) {
- return new Handlebars.SafeString(str);
-};
+ Ember.assert("You are trying to look up a controller that you did not define, and for which Ember does not know the model.\n\nThis is not a controller for a route, so you must explicitly define the controller ("+this.router.namespace.toString() + "." + Ember.String.capitalize(Ember.String.camelize(name))+"Controller) or pass a model as the second parameter to `controllerFor`, so that Ember knows which type of controller to create for you.", model || this.container.lookup('route:' + name));
-var htmlSafe = Ember.String.htmlSafe;
+ controller = Ember.generateController(container, name, model);
+ }
-if (Ember.EXTEND_PROTOTYPES) {
+ return controller;
+ },
/**
- See {{#crossLink "Ember.String/htmlSafe"}}{{/crossLink}}
+ Returns the current model for a given route.
- @method htmlSafe
- @for String
+ This is the object returned by the `model` hook of the route
+ in question.
+
+ @method modelFor
+ @param {String} name the name of the route
+ @return {Object} the model object
*/
- String.prototype.htmlSafe = function() {
- return htmlSafe(this);
- };
+ modelFor: function(name) {
+ var route = this.container.lookup('route:' + name);
+ return route && route.currentModel;
+ },
+
+ /**
+ A hook you can use to render the template for the current route.
-}
+ This method is called with the controller for the current route and the
+ model supplied by the `model` hook. By default, it renders the route's
+ template, configured with the controller for the route.
-})();
+ This method can be overridden to set up and render additional or
+ alternative templates.
+ @method renderTemplate
+ @param {Object} controller the route's controller
+ @param {Object} model the route's model
+ */
+ renderTemplate: function(controller, model) {
+ this.render();
+ },
+ /**
+ Renders a template into an outlet.
-(function() {
-/*jshint newcap:false*/
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ This method has a number of defaults, based on the name of the
+ route specified in the router.
-var set = Ember.set, get = Ember.get;
+ For example:
-// DOMManager should just abstract dom manipulation between jquery and metamorph
-var DOMManager = {
- remove: function(view) {
- view.morph.remove();
- },
+ ```js
+ App.Router.map(function(match) {
+ match("/").to("index");
+ match("/posts/:post_id").to("post");
+ });
- prepend: function(view, html) {
- view.morph.prepend(html);
- },
+ App.PostRoute = App.Route.extend({
+ renderTemplate: function() {
+ this.render();
+ }
+ });
+ ```
- after: function(view, html) {
- view.morph.after(html);
- },
+ The name of the `PostRoute`, as defined by the router, is `post`.
- html: function(view, html) {
- view.morph.html(html);
- },
+ By default, render will:
- // This is messed up.
- replace: function(view) {
- var morph = view.morph;
+ * render the `post` template
+ * with the `post` view (`PostView`) for event handling, if one exists
+ * and the `post` controller (`PostController`), if one exists
+ * into the `main` outlet of the `application` template
- view.transitionTo('preRender');
- view.clearRenderedChildren();
- var buffer = view.renderToBuffer();
+ You can override this behavior:
- Ember.run.schedule('render', this, function() {
- if (get(view, 'isDestroyed')) { return; }
- view.invalidateRecursively('element');
- view._notifyWillInsertElement();
- morph.replaceWith(buffer.string());
- view.transitionTo('inDOM');
- view._notifyDidInsertElement();
+ ```js
+ App.PostRoute = App.Route.extend({
+ renderTemplate: function() {
+ this.render('myPost', { // the template to render
+ into: 'index', // the template to render into
+ outlet: 'detail', // the name of the outlet in that template
+ controller: 'blogPost' // the controller to use for the template
+ });
+ }
});
- },
+ ```
- empty: function(view) {
- view.morph.html("");
- }
-};
+ Remember that the controller's `content` will be the route's model. In
+ this case, the default model will be `App.Post.find(params.post_id)`.
-// The `morph` and `outerHTML` properties are internal only
-// and not observable.
+ @method render
+ @param {String} name the name of the template to render
+ @param {Object} options the options
+ */
+ render: function(name, options) {
+ if (typeof name === 'object' && !options) {
+ options = name;
+ name = this.routeName;
+ }
-/**
- @class _Metamorph
- @namespace Ember
- @extends Ember.Mixin
- @private
-*/
-Ember._Metamorph = Ember.Mixin.create({
- isVirtual: true,
- tagName: '',
+ name = name ? name.replace(/\//g, '.') : this.routeName;
- init: function() {
- this._super();
- this.morph = Metamorph();
- },
+ var container = this.container,
+ view = container.lookup('view:' + name),
+ template = container.lookup('template:' + name);
- beforeRender: function(buffer) {
- buffer.push(this.morph.startTag());
- },
+ if (!view && !template) { return; }
- afterRender: function(buffer) {
- buffer.push(this.morph.endTag());
- },
+ this.lastRenderedTemplate = name;
- createElement: function() {
- var buffer = this.renderToBuffer();
- this.outerHTML = buffer.string();
- this.clearBuffer();
- },
+ options = normalizeOptions(this, name, template, options);
+ view = setupView(view, container, options);
- domManager: DOMManager
+ appendView(this, view, options);
+ }
});
-/**
- @class _MetamorphView
- @namespace Ember
- @extends Ember.View
- @uses Ember._Metamorph
- @private
-*/
-Ember._MetamorphView = Ember.View.extend(Ember._Metamorph);
+function parentRoute(route) {
+ var handlerInfos = route.router.router.currentHandlerInfos;
+ var parent, current;
-})();
+ for (var i=0, l=handlerInfos.length; i<l; i++) {
+ current = handlerInfos[i].handler;
+ if (current === route) { return parent; }
+ parent = current;
+ }
+}
+function parentTemplate(route) {
+ var parent = parentRoute(route), template;
+ if (!parent) { return; }
-(function() {
-/*globals Handlebars */
+ if (template = parent.lastRenderedTemplate) {
+ return template;
+ } else {
+ return parentTemplate(parent);
+ }
+}
-/**
-@module ember
-@submodule ember-handlebars
-*/
+function normalizeOptions(route, name, template, options) {
+ options = options || {};
+ options.into = options.into ? options.into.replace(/\//g, '.') : parentTemplate(route);
+ options.outlet = options.outlet || 'main';
+ options.name = name;
+ options.template = template;
-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.
+ var controller = options.controller, namedController;
- Every time a property is bound using a `{{mustache}}`, an anonymous subclass
- 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.
+ if (options.controller) {
+ controller = options.controller;
+ } else if (namedController = route.container.lookup('controller:' + name)) {
+ controller = namedController;
+ } else {
+ controller = route.routeName;
+ }
- @class _HandlebarsBoundView
- @namespace Ember
- @extends Ember._MetamorphView
- @private
-*/
-Ember._HandlebarsBoundView = Ember._MetamorphView.extend({
+ if (typeof controller === 'string') {
+ controller = route.container.lookup('controller:' + controller);
+ }
- /**
- 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.
+ options.controller = controller;
- @property shouldDisplayFunc
- @type Function
- @default null
- */
- shouldDisplayFunc: null,
+ return options;
+}
- /**
- Whether the template rendered by this view gets passed the context object
- of its parent template, or gets passed the value of retrieving `path`
- from the `pathRoot`.
+function setupView(view, container, options) {
+ var defaultView = options.into ? 'view:default' : 'view:toplevel';
- For example, this is true when using the `{{#if}}` helper, because the
- template inside the helper should look up properties relative to the same
- object as outside the block. This would be false when used with `{{#with
- foo}}` because the template should receive the object found by evaluating
- `foo`.
+ view = view || container.lookup(defaultView);
- @property preserveContext
- @type Boolean
- @default false
- */
- preserveContext: false,
+ if (!get(view, 'templateName')) {
+ set(view, 'template', options.template);
+ }
- /**
- If `preserveContext` is true, this is the object that will be used
- to render the template.
+ set(view, 'renderedName', options.name);
+ set(view, 'controller', options.controller);
- @property previousContext
- @type Object
- */
- previousContext: null,
+ return view;
+}
- /**
- The template to render when `shouldDisplayFunc` evaluates to true.
+function appendView(route, view, options) {
+ if (options.into) {
+ var parentView = route.router._lookupActiveView(options.into);
+ route.teardownView = teardownOutlet(parentView, options.outlet);
+ parentView.connectOutlet(options.outlet, view);
+ } else {
+ var rootElement = get(route, 'router.namespace.rootElement');
+ route.router._connectActiveView(options.name, view);
+ route.teardownView = teardownTopLevel(view);
+ view.appendTo(rootElement);
+ }
+}
- @property displayTemplate
- @type Function
- @default null
- */
- displayTemplate: null,
+function teardownTopLevel(view) {
+ return function() { view.remove(); };
+}
- /**
- The template to render when `shouldDisplayFunc` evaluates to false.
+function teardownOutlet(parentView, outlet) {
+ return function() { parentView.disconnectOutlet(outlet); };
+}
- @property inverseTemplate
- @type Function
- @default null
- */
- inverseTemplate: null,
+function teardownView(route) {
+ if (route.teardownView) { route.teardownView(); }
+ delete route.teardownView;
+ delete route.lastRenderedTemplate;
+}
- /**
- The path to look up on `pathRoot` that is passed to
- `shouldDisplayFunc` to determine which template to render.
+})();
- 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
- */
- path: null,
- /**
- The object from which the `path` will be looked up. Sometimes this is the
- same as the `previousContext`, but in cases where this view has been generated
- for paths that start with a keyword such as `view` or `controller`, the
- path root will be that resolved object.
+(function() {
- @property pathRoot
- @type Object
- */
- pathRoot: null,
+})();
- normalizedValue: Ember.computed(function() {
- var path = get(this, 'path'),
- pathRoot = get(this, 'pathRoot'),
- valueNormalizer = get(this, 'valueNormalizerFunc'),
- result, templateData;
- // Use the pathRoot as the result if no path is provided. This
- // happens if the path is `this`, which gets normalized into
- // a `pathRoot` of the current Handlebars context and a path
- // of `''`.
- if (path === '') {
- result = pathRoot;
- } else {
- templateData = get(this, 'templateData');
- result = getPath(pathRoot, path, { data: templateData });
- }
- return valueNormalizer ? valueNormalizer(result) : result;
- }).property('path', 'pathRoot', 'valueNormalizerFunc').volatile(),
+(function() {
+var get = Ember.get, set = Ember.set;
+Ember.onLoad('Ember.Handlebars', function(Handlebars) {
- rerenderIfNeeded: function() {
- if (!get(this, 'isDestroyed') && get(this, 'normalizedValue') !== this._lastNormalizedValue) {
- this.rerender();
+ var resolvePaths = Ember.Handlebars.resolvePaths,
+ isSimpleClick = Ember.ViewUtils.isSimpleClick;
+
+ function fullRouteName(router, name) {
+ if (!router.hasRoute(name)) {
+ name = name + '.index';
}
- },
- /**
- Determines which template to invoke, sets up the correct state based on
- that logic, then invokes the default Ember.View `render` implementation.
+ return name;
+ }
- This method will first look up the `path` key on `pathRoot`,
- then pass that value to the `shouldDisplayFunc` function. If that returns
- true, the `displayTemplate` function will be rendered to DOM. Otherwise,
- `inverseTemplate`, if specified, will be rendered.
+ function resolvedPaths(linkView) {
+ return resolvePaths(linkView.parameters);
+ }
- 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`.
+ function args(linkView, router, route) {
+ var passedRouteName = route || linkView.namedRoute, routeName;
- @method render
- @param {Ember.RenderBuffer} buffer
- */
- render: function(buffer) {
- // If not invoked via a triple-mustache ({{{foo}}}), escape
- // the content of the template.
- var escape = get(this, 'isEscaped');
+ routeName = fullRouteName(router, passedRouteName);
- var shouldDisplay = get(this, 'shouldDisplayFunc'),
- preserveContext = get(this, 'preserveContext'),
- context = get(this, 'previousContext');
+ Ember.assert("The route " + passedRouteName + " was not found", router.hasRoute(routeName));
- var inverseTemplate = get(this, 'inverseTemplate'),
- displayTemplate = get(this, 'displayTemplate');
+ var ret = [ routeName ];
+ return ret.concat(resolvePaths(linkView.parameters));
+ }
- var result = get(this, 'normalizedValue');
- this._lastNormalizedValue = result;
+ var LinkView = Ember.View.extend({
+ tagName: 'a',
+ namedRoute: null,
+ currentWhen: null,
+ title: null,
+ activeClass: 'active',
+ replace: false,
+ attributeBindings: ['href', 'title'],
+ classNameBindings: 'active',
+
+ active: Ember.computed(function() {
+ var router = this.get('router'),
+ params = resolvedPaths(this),
+ currentWithIndex = this.currentWhen + '.index',
+ isActive = router.isActive.apply(router, [this.currentWhen].concat(params)) ||
+ router.isActive.apply(router, [currentWithIndex].concat(params));
+
+ if (isActive) { return get(this, 'activeClass'); }
+ }).property('namedRoute', 'router.url'),
+
+ router: Ember.computed(function() {
+ return this.get('controller').container.lookup('router:main');
+ }),
- // First, test the conditional to see if we should
- // render the template or not.
- if (shouldDisplay(result)) {
- set(this, 'template', displayTemplate);
+ click: function(event) {
+ if (!isSimpleClick(event)) { return true; }
- // If we are preserving the context (for example, if this
- // is an #if block, call the template with the same object.
- if (preserveContext) {
- set(this, '_context', context);
- } else {
- // Otherwise, determine if this is a block bind or not.
- // If so, pass the specified object to the template
- if (displayTemplate) {
- set(this, '_context', result);
- } else {
- // This is not a bind block, just push the result of the
- // expression to the render context and return.
- if (result === null || result === undefined) {
- result = "";
- } else if (!(result instanceof Handlebars.SafeString)) {
- result = String(result);
- }
+ event.preventDefault();
+ if (this.bubbles === false) { event.stopPropagation(); }
- if (escape) { result = Handlebars.Utils.escapeExpression(result); }
- buffer.push(result);
- return;
- }
- }
- } else if (inverseTemplate) {
- set(this, 'template', inverseTemplate);
+ var router = this.get('router');
- if (preserveContext) {
- set(this, '_context', context);
+ if (this.get('replace')) {
+ router.replaceWith.apply(router, args(this, router));
} else {
- set(this, '_context', result);
+ router.transitionTo.apply(router, args(this, router));
}
- } else {
- set(this, 'template', function() { return ''; });
- }
+ },
+
+ href: Ember.computed(function() {
+ var router = this.get('router');
+ return router.generate.apply(router, args(this, router));
+ })
+ });
+
+ LinkView.toString = function() { return "LinkView"; };
+
+ Ember.Handlebars.registerHelper('linkTo', function(name) {
+ var options = [].slice.call(arguments, -1)[0];
+ var contexts = [].slice.call(arguments, 1, -1);
+
+ var hash = options.hash;
+
+ hash.namedRoute = name;
+ hash.currentWhen = hash.currentWhen || name;
+
+ hash.parameters = {
+ data: options.data,
+ contexts: contexts,
+ roots: options.contexts
+ };
+
+ return Ember.Handlebars.helpers.view.call(this, LinkView, options);
+ });
- return this._super(buffer);
- }
});
+
})();
(function() {
/**
@module ember
-@submodule ember-handlebars
+@submodule ember-routing
*/
-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;
+var get = Ember.get, set = Ember.set;
+Ember.onLoad('Ember.Handlebars', function(Handlebars) {
+ /**
+ @module ember
+ @submodule ember-handlebars
+ */
-var EmberHandlebars = Ember.Handlebars, helpers = EmberHandlebars.helpers;
+ Handlebars.OutletView = Ember.ContainerView.extend(Ember._Metamorph);
-// 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.
-function bind(property, options, preserveContext, shouldDisplay, valueNormalizer) {
- var data = options.data,
- fn = options.fn,
- inverse = options.inverse,
- view = data.view,
- currentContext = this,
- pathRoot, path, normalized;
+ /**
+ The `outlet` helper allows you to specify that the current
+ view's controller will fill in the view for a given area.
- normalized = normalizePath(currentContext, property, data);
+ ``` handlebars
+ {{outlet}}
+ ```
- pathRoot = normalized.root;
- path = normalized.path;
+ By default, when the the current controller's `view` property changes, the
+ outlet will replace its current view with the new view. You can set the
+ `view` property directly, but it's normally best to use `connectOutlet`.
- // Set up observers for observable objects
- if ('object' === typeof this) {
- // Create the view that will wrap the output of this template/property
- // and add it to the nearest view's childViews array.
- // See the documentation of Ember._HandlebarsBoundView for more.
- var bindView = view.createChildView(Ember._HandlebarsBoundView, {
- preserveContext: preserveContext,
- shouldDisplayFunc: shouldDisplay,
- valueNormalizerFunc: valueNormalizer,
- displayTemplate: fn,
- inverseTemplate: inverse,
- path: path,
- pathRoot: pathRoot,
- previousContext: currentContext,
- isEscaped: !options.hash.unescaped,
- templateData: options.data
- });
+ ``` javascript
+ # Instantiate App.PostsView and assign to `view`, so as to render into outlet.
+ controller.connectOutlet('posts');
+ ```
- view.appendChild(bindView);
+ You can also specify a particular name other than `view`:
- var observer = function() {
- Ember.run.scheduleOnce('render', bindView, 'rerenderIfNeeded');
- };
+ ``` handlebars
+ {{outlet masterView}}
+ {{outlet detailView}}
+ ```
- // Observes the given property on the context and
- // tells the Ember._HandlebarsBoundView to re-render. If property
- // is an empty string, we are printing the current context
- // object ({{this}}) so updating it is not our responsibility.
- if (path !== '') {
- Ember.addObserver(pathRoot, path, observer);
- }
- } else {
- // The object is not observable, so just render it out and
- // be done with it.
- data.buffer.push(getPath(pathRoot, path, options));
- }
-}
+ Then, you can control several outlets from a single controller.
-/**
- @private
+ ``` javascript
+ # Instantiate App.PostsView and assign to controller.masterView.
+ controller.connectOutlet('masterView', 'posts');
+ # Also, instantiate App.PostInfoView and assign to controller.detailView.
+ controller.connectOutlet('detailView', 'postInfo');
+ ```
- '_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
- helper resolves that.
+ @method outlet
+ @for Ember.Handlebars.helpers
+ @param {String} property the property on the controller
+ that holds the view for this outlet
+ */
+ Handlebars.registerHelper('outlet', function(property, options) {
+ var outletSource;
- This would not be typically invoked by directly.
+ if (property && property.data && property.data.isRenderData) {
+ options = property;
+ property = 'main';
+ }
- @method _triageMustache
- @for Ember.Handlebars.helpers
- @param {String} property Property/helperID to triage
- @param {Function} fn Context to provide for rendering
- @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);
- if (helpers[property]) {
- return helpers[property].call(this, fn);
- }
- else {
- return helpers.bind.apply(this, arguments);
- }
-});
+ outletSource = options.data.view;
+ while (!(outletSource.get('template.isTop'))){
+ outletSource = outletSource.get('_parentView');
+ }
-/**
- @private
+ options.data.view.set('outletSource', outletSource);
+ options.hash.currentViewBinding = '_view.outletSource._outlets.' + property;
- `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`:
+ return Handlebars.helpers.view.call(this, Handlebars.OutletView, options);
+ });
- ``` handlebars
- {{bind "content.title"}}
- ```
+ Ember.View.reopen({
+ init: function() {
+ set(this, '_outlets', {});
+ this._super();
+ },
- 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
- DOM. Note that if you need to support IE7 and IE8 you must modify the
- model objects properties using Ember.get() and Ember.set() for this to work as
- it relies on Ember's KVO system. For all other browsers this will be handled
- for you automatically.
+ connectOutlet: function(outletName, view) {
+ var outlets = get(this, '_outlets'),
+ container = get(this, 'container'),
+ router = container && container.lookup('router:main'),
+ oldView = get(outlets, outletName),
+ renderedName = get(view, 'renderedName');
- @method bind
- @for Ember.Handlebars.helpers
- @param {String} property Property to bind
- @param {Function} fn Context to provide for rendering
- @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);
+ set(outlets, outletName, view);
- var context = (fn.contexts && fn.contexts[0]) || this;
+ if (router) {
+ if (oldView) {
+ router._disconnectActiveView(oldView);
+ }
+ if (renderedName) {
+ router._connectActiveView(renderedName, view);
+ }
+ }
+ },
+
+ disconnectOutlet: function(outletName) {
+ var outlets = get(this, '_outlets'),
+ container = get(this, 'container'),
+ router = container && container.lookup('router:main'),
+ view = get(outlets, outletName);
+
+ set(outlets, outletName, null);
- return bind.call(context, property, fn, false, function(result) {
- return !Ember.none(result);
+ if (router && view) {
+ router._disconnectActiveView(view);
+ }
+ }
});
});
-/**
- @private
+})();
- Use the `boundIf` helper to create a conditional that re-evaluates
- whenever the bound value changes.
- ``` handlebars
- {{#boundIf "content.shouldDisplayTitle"}}
- {{content.title}}
- {{/boundIf}}
- ```
- @method boundIf
- @for Ember.Handlebars.helpers
- @param {String} property Property to bind
- @param {Function} fn Context to provide for rendering
- @return {String} HTML string
+(function() {
+/**
+@module ember
+@submodule ember-routing
*/
-EmberHandlebars.registerHelper('boundIf', function(property, fn) {
- var context = (fn.contexts && fn.contexts[0]) || this;
- var func = function(result) {
- if (Ember.typeOf(result) === 'array') {
- return get(result, 'length') !== 0;
- } else {
- return !!result;
+
+var get = Ember.get, set = Ember.set;
+Ember.onLoad('Ember.Handlebars', function(Handlebars) {
+
+ Ember.Handlebars.registerHelper('render', function(name, context, options) {
+ Ember.assert("You must pass a template to render", arguments.length >= 2);
+ var container, router, controller, view;
+
+ if (arguments.length === 2) {
+ options = context;
+ context = undefined;
}
- };
- return bind.call(context, property, fn, true, func, func);
-});
+ if (typeof context === 'string') {
+ context = Ember.Handlebars.get(options.contexts[1], context, options);
+ }
-/**
- @method with
- @for Ember.Handlebars.helpers
- @param {Function} context
- @param {Hash} options
- @return {String} HTML string
-*/
-EmberHandlebars.registerHelper('with', function(context, options) {
- if (arguments.length === 4) {
- var keywordName, path, rootPath, normalized;
+ name = name.replace(/\//g, '.');
+ container = options.data.keywords.controller.container;
+ router = container.lookup('router:main');
- Ember.assert("If you pass more than one argument to the with helper, it must be in the form #with foo as bar", arguments[1] === "as");
- options = arguments[3];
- keywordName = arguments[2];
- path = arguments[0];
+ Ember.assert("This view is already rendered", !router || !router._lookupActiveView(name));
- Ember.assert("You must pass a block to the with helper", options.fn && options.fn !== Handlebars.VM.noop);
+ view = container.lookup('view:' + name) || container.lookup('view:default');
- if (Ember.isGlobalPath(path)) {
- Ember.bind(options.data.keywords, keywordName, path);
+ if (controller = options.hash.controller) {
+ controller = container.lookup('controller:' + controller);
} else {
- normalized = normalizePath(this, path, options.data);
- path = normalized.path;
- rootPath = normalized.root;
+ controller = Ember.controllerFor(container, name, context);
+ }
- // This is a workaround for the fact that you cannot bind separate objects
- // together. When we implement that functionality, we should use it here.
- var contextKey = Ember.$.expando + Ember.guidFor(rootPath);
- options.data.keywords[contextKey] = rootPath;
+ if (controller && context) {
+ controller.set('model', context);
+ }
- // if the path is '' ("this"), just bind directly to the current context
- var contextPath = path ? contextKey + '.' + path : contextKey;
- Ember.bind(options.data.keywords, keywordName, contextPath);
+ controller.set('target', options.data.keywords.controller);
+
+ options.hash.viewName = Ember.String.camelize(name);
+ options.hash.template = container.lookup('template:' + name);
+ options.hash.controller = controller;
+
+ if (router) {
+ router._connectActiveView(name, view);
}
- return bind.call(this, path, options, true, function(result) {
- return !Ember.none(result);
- });
- } else {
- Ember.assert("You must pass exactly one argument to the with helper", arguments.length === 2);
- Ember.assert("You must pass a block to the with helper", options.fn && options.fn !== Handlebars.VM.noop);
- return helpers.bind.call(options.contexts[0], context, options);
- }
+ Ember.Handlebars.helpers.view.call(this, view, options);
+ });
+
});
+})();
-/**
- @method if
- @for Ember.Handlebars.helpers
- @param {Function} context
- @param {Hash} options
- @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);
- Ember.assert("You must pass a block to the if helper", options.fn && options.fn !== Handlebars.VM.noop);
- return helpers.boundIf.call(options.contexts[0], context, options);
-});
+(function() {
/**
- @method unless
- @for Ember.Handlebars.helpers
- @param {Function} context
- @param {Hash} options
- @return {String} HTML string
+@module ember
+@submodule ember-routing
*/
-EmberHandlebars.registerHelper('unless', function(context, options) {
- Ember.assert("You must pass exactly one argument to the unless helper", arguments.length === 2);
- Ember.assert("You must pass a block to the unless helper", options.fn && options.fn !== Handlebars.VM.noop);
-
- var fn = options.fn, inverse = options.inverse;
-
- options.fn = inverse;
- options.inverse = fn;
+Ember.onLoad('Ember.Handlebars', function(Handlebars) {
- return helpers.boundIf.call(options.contexts[0], context, options);
-});
+ var resolvePaths = Ember.Handlebars.resolvePaths,
+ isSimpleClick = Ember.ViewUtils.isSimpleClick;
-/**
- `bindAttr` allows you to create a binding between DOM element attributes and
- Ember objects. For example:
+ var EmberHandlebars = Ember.Handlebars,
+ handlebarsGet = EmberHandlebars.get,
+ SafeString = EmberHandlebars.SafeString,
+ get = Ember.get,
+ a_slice = Array.prototype.slice;
- ``` handlebars
- <img {{bindAttr src="imageUrl" alt="imageTitle"}}>
- ```
+ function args(options, actionName) {
+ var ret = [];
+ if (actionName) { ret.push(actionName); }
+ return ret.concat(resolvePaths(options.parameters));
+ }
- @method bindAttr
- @for Ember.Handlebars.helpers
- @param {Hash} options
- @return {String} HTML string
-*/
-EmberHandlebars.registerHelper('bindAttr', function(options) {
+ var ActionHelper = EmberHandlebars.ActionHelper = {
+ registeredActions: {}
+ };
- var attrs = options.hash;
+ ActionHelper.registerAction = function(actionName, options) {
+ var actionId = (++Ember.uuid).toString();
- Ember.assert("You must specify at least one hash argument to bindAttr", !!Ember.keys(attrs).length);
+ ActionHelper.registeredActions[actionId] = {
+ eventName: options.eventName,
+ handler: function(event) {
+ if (!isSimpleClick(event)) { return true; }
+ event.preventDefault();
- var view = options.data.view;
- var ret = [];
- var ctx = this;
+ if (options.bubbles === false) {
+ event.stopPropagation();
+ }
- // Generate a unique id for this element. This will be added as a
- // data attribute to the element so it can be looked up when
- // the bound property changes.
- var dataId = ++Ember.$.uuid;
+ var view = options.view,
+ contexts = options.contexts,
+ target = options.target;
- // Handle classes differently, as we can bind multiple classes
- var classBindings = attrs['class'];
- if (classBindings !== null && classBindings !== undefined) {
- var classResults = EmberHandlebars.bindClasses(this, classBindings, view, dataId, options);
- ret.push('class="' + Handlebars.Utils.escapeExpression(classResults.join(' ')) + '"');
- delete attrs['class'];
- }
+ if (target.send) {
+ return target.send.apply(target, args(options, actionName));
+ } else {
+ Ember.assert("The action '" + actionName + "' did not exist on " + target, typeof target[actionName] === 'function');
+ return target[actionName].apply(target, args(options));
+ }
+ }
+ };
- var attrKeys = Ember.keys(attrs);
+ options.view.on('willClearRender', function() {
+ delete ActionHelper.registeredActions[actionId];
+ });
- // For each attribute passed, create an observer and emit the
- // current value of the property as an attribute.
- forEach.call(attrKeys, function(attr) {
- var path = attrs[attr],
- pathRoot, normalized;
+ return actionId;
+ };
- Ember.assert(fmt("You must provide a String for a bound attribute, not %@", [path]), typeof path === 'string');
+ /**
+ The `{{action}}` helper registers an HTML element within a template for DOM
+ event handling and forwards that interaction to the view's controller
+ or supplied `target` option (see 'Specifying a Target').
- normalized = normalizePath(ctx, path, options.data);
+ If the view's controller does not implement the event, the event is sent
+ to the current route, and it bubbles up the route hierarchy from there.
- pathRoot = normalized.root;
- path = normalized.path;
+ User interaction with that element will invoke the supplied action name on
+ the appropriate target.
- var value = (path === 'this') ? pathRoot : getPath(pathRoot, path, options),
- type = Ember.typeOf(value);
+ Given the following Handlebars template on the page
- Ember.assert(fmt("Attributes must be numbers, strings or booleans, not %@", [value]), value === null || value === undefined || type === 'number' || type === 'string' || type === 'boolean');
+ ```handlebars
+ <script type="text/x-handlebars" data-template-name='a-template'>
+ <div {{action anActionName}}>
+ click me
+ </div>
+ </script>
+ ```
- var observer, invoker;
+ And application code
- observer = function observer() {
- var result = getPath(pathRoot, path, options);
+ ```javascript
+ AController = Ember.Controller.extend({
+ anActionName: function() {}
+ });
- Ember.assert(fmt("Attributes must be numbers, strings or booleans, not %@", [result]), result === null || result === undefined || typeof result === 'number' || typeof result === 'string' || typeof result === 'boolean');
+ AView = Ember.View.extend({
+ controller: AController.create(),
+ templateName: 'a-template'
+ });
- var elem = view.$("[data-bindattr-" + dataId + "='" + dataId + "']");
+ aView = AView.create();
+ aView.appendTo('body');
+ ```
- // If we aren't able to find the element, it means the element
- // to which we were bound has been removed from the view.
- // In that case, we can assume the template has been re-rendered
- // and we need to clean up the observer.
- if (!elem || elem.length === 0) {
- Ember.removeObserver(pathRoot, path, invoker);
- return;
- }
+ Will results in the following rendered HTML
- Ember.View.applyAttributeBindings(elem, attr, result);
- };
+ ```html
+ <div class="ember-view">
+ <div data-ember-action="1">
+ click me
+ </div>
+ </div>
+ ```
- invoker = function() {
- Ember.run.scheduleOnce('render', observer);
- };
+ Clicking "click me" will trigger the `anActionName` method of the
+ `AController`. In this case, no additional parameters will be passed.
- // Add an observer to the view for when the property changes.
- // When the observer fires, find the element using the
- // unique data id and update the attribute to the new value.
- if (path !== 'this') {
- Ember.addObserver(pathRoot, path, invoker);
- }
+ If you provide additional parameters to the helper:
- // if this changes, also change the logic in ember-views/lib/views/view.js
- if ((type === 'string' || (type === 'number' && !isNaN(value)))) {
- ret.push(attr + '="' + Handlebars.Utils.escapeExpression(value) + '"');
- } else if (value && type === 'boolean') {
- // The developer controls the attr name, so it should always be safe
- ret.push(attr + '="' + attr + '"');
- }
- }, this);
+ ```handlebars
+ <button {{action 'edit' post}}>Edit</button>
+ ```
- // Add the unique identifier
- // NOTE: We use all lower-case since Firefox has problems with mixed case in SVG
- ret.push('data-bindattr-' + dataId + '="' + dataId + '"');
- return new EmberHandlebars.SafeString(ret.join(' '));
-});
+ Those parameters will be passed along as arguments to the JavaScript
+ function implementing the action.
-/**
- @private
+ ### Event Propagation
- 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
- change, the correct class name will be reapplied to the DOM element.
+ Events triggered through the action helper will automatically have
+ `.preventDefault()` called on them. You do not need to do so in your event
+ handlers.
- For example, if you pass the string "fooBar", it will first look up the
- "fooBar" value of the context. If that value is true, it will add the
- "foo-bar" class to the current element (i.e., the dasherized form of
- "fooBar"). If the value is a string, it will add that string as the class.
- Otherwise, it will not add any new class name.
+ To also disable bubbling, pass `bubbles=false` to the helper:
- @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;
+ ```handlebars
+ <button {{action 'edit' post bubbles=false}}>Edit</button>
+ ```
- // Helper method to retrieve the property from the context and
- // determine which class string to return, based on whether it is
- // a Boolean or not.
- var classStringForPath = function(root, parsedPath, options) {
- var val,
- path = parsedPath.path;
+ If you need the default handler to trigger you should either register your
+ own event handler, or use event methods on your view class. See `Ember.View`
+ 'Responding to Browser Events' for more information.
- if (path === 'this') {
- val = root;
- } else if (path === '') {
- val = true;
- } else {
- val = getPath(root, path, options);
- }
+ ### Specifying DOM event type
- return Ember.View._classStringForValue(path, val, parsedPath.className, parsedPath.falsyClassName);
- };
+ 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:
- // For each property passed, loop through and setup
- // an observer.
- forEach.call(classBindings.split(' '), function(binding) {
+ ```handlebars
+ <script type="text/x-handlebars" data-template-name='a-template'>
+ <div {{action anActionName on="doubleClick"}}>
+ click me
+ </div>
+ </script>
+ ```
- // Variable in which the old class value is saved. The observer function
- // closes over this variable, so it knows which string to remove when
- // the property changes.
- var oldClass;
+ See `Ember.View` 'Responding to Browser Events' for a list of
+ acceptable DOM event names.
- var observer, invoker;
+ NOTE: Because `{{action}}` depends on Ember's event dispatch system it will
+ only function if an `Ember.EventDispatcher` instance is available. An
+ `Ember.EventDispatcher` instance will be created when a new `Ember.Application`
+ is created. Having an instance of `Ember.Application` will satisfy this
+ requirement.
- var parsedPath = Ember.View._parsePropertyPath(binding),
- path = parsedPath.path,
- pathRoot = context,
- normalized;
+ ### Specifying a Target
- if (path !== '' && path !== 'this') {
- normalized = normalizePath(context, path, options.data);
+ There are several possible target objects for `{{action}}` helpers:
- pathRoot = normalized.root;
- path = normalized.path;
- }
+ In a typical Ember application, where views are managed through use of the
+ `{{outlet}}` helper, actions will bubble to the current controller, then
+ to the current route, and then up the route hierarchy.
- // Set up an observer on the context. If the property changes, toggle the
- // class name.
- observer = function() {
- // Get the current value of the property
- newClass = classStringForPath(pathRoot, parsedPath, options);
- elem = bindAttrId ? view.$("[data-bindattr-" + bindAttrId + "='" + bindAttrId + "']") : view.$();
+ Alternatively, a `target` option can be provided to the helper to change
+ which object will receive the method call. This option must be a path
+ path to an object, accessible in the current context:
- // If we can't find the element anymore, a parent template has been
- // re-rendered and we've been nuked. Remove the observer.
- if (!elem || elem.length === 0) {
- Ember.removeObserver(pathRoot, path, invoker);
- } else {
- // If we had previously added a class to the element, remove it.
- if (oldClass) {
- elem.removeClass(oldClass);
- }
+ ```handlebars
+ <script type="text/x-handlebars" data-template-name='a-template'>
+ <div {{action anActionName target="MyApplication.someObject"}}>
+ click me
+ </div>
+ </script>
+ ```
- // If necessary, add a new class. Make sure we keep track of it so
- // it can be removed in the future.
- if (newClass) {
- elem.addClass(newClass);
- oldClass = newClass;
- } else {
- oldClass = null;
- }
- }
- };
+ Clicking "click me" in the rendered HTML of the above template will trigger
+ the `anActionName` method of the object at `MyApplication.someObject`.
- invoker = function() {
- Ember.run.scheduleOnce('render', observer);
- };
+ If an action's target does not implement a method that matches the supplied
+ action name an error will be thrown.
- if (path !== '' && path !== 'this') {
- Ember.addObserver(pathRoot, path, invoker);
- }
+ ```handlebars
+ <script type="text/x-handlebars" data-template-name='a-template'>
+ <div {{action aMethodNameThatIsMissing}}>
+ click me
+ </div>
+ </script>
+ ```
- // We've already setup the observer; now we just need to figure out the
- // correct behavior right now on the first pass through.
- value = classStringForPath(pathRoot, parsedPath, options);
+ With the following application code
- if (value) {
- ret.push(value);
+ ```javascript
+ AView = Ember.View.extend({
+ templateName; 'a-template',
+ // note: no method 'aMethodNameThatIsMissing'
+ anActionName: function(event) {}
+ });
- // Make sure we save the current value so that it can be removed if the
- // observer fires.
- oldClass = value;
- }
- });
+ aView = AView.create();
+ aView.appendTo('body');
+ ```
- return ret;
-};
+ Will throw `Uncaught TypeError: Cannot call method 'call' of undefined` when
+ "click me" is clicked.
+ ### Additional Parameters
-})();
+ You may specify additional parameters to the `{{action}}` helper. These
+ parameters are passed along as the arguments to the JavaScript function
+ implementing the action.
+ ```handlebars
+ <script type="text/x-handlebars" data-template-name='a-template'>
+ {{#each person in people}}
+ <div {{action edit person}}>
+ click me
+ </div>
+ {{/each}}
+ </script>
+ ```
+ Clicking "click me" will trigger the `edit` method on the current view's
+ controller with the current person as a parameter.
-(function() {
-/*globals Handlebars */
+ @method action
+ @for Ember.Handlebars.helpers
+ @param {String} actionName
+ @param {Object...} contexts
+ @param {Hash} options
+ */
+ EmberHandlebars.registerHelper('action', function(actionName) {
+ var options = arguments[arguments.length - 1],
+ contexts = a_slice.call(arguments, 1, -1);
-// TODO: Don't require the entire module
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ var hash = options.hash,
+ view = options.data.view,
+ target, controller, link;
-var get = Ember.get, set = Ember.set;
-var PARENT_VIEW_PATH = /^parentView\./;
-var EmberHandlebars = Ember.Handlebars;
-var VIEW_PRESERVES_CONTEXT = Ember.VIEW_PRESERVES_CONTEXT;
+ // create a hash to pass along to registerAction
+ var action = {
+ eventName: hash.on || "click"
+ };
-EmberHandlebars.ViewHelper = Ember.Object.create({
+ action.parameters = {
+ data: options.data,
+ contexts: contexts,
+ roots: options.contexts
+ };
- propertiesFromHTMLOptions: function(options, thisContext) {
- var hash = options.hash, data = options.data;
- var extensions = {},
- classes = hash['class'],
- dup = false;
+ action.view = view = get(view, 'concreteView');
- if (hash.id) {
- extensions.elementId = hash.id;
- dup = true;
+ if (hash.target) {
+ target = handlebarsGet(this, hash.target, options);
+ } else if (controller = options.data.keywords.controller) {
+ target = controller;
}
- if (classes) {
- classes = classes.split(' ');
- extensions.classNames = classes;
- dup = true;
- }
+ action.target = target;
+ action.bubbles = hash.bubbles;
- if (hash.classBinding) {
- extensions.classNameBindings = hash.classBinding.split(' ');
- dup = true;
- }
+ var actionId = ActionHelper.registerAction(actionName, action);
+ return new SafeString('data-ember-action="' + actionId + '"');
+ });
- if (hash.classNameBindings) {
- if (extensions.classNameBindings === undefined) extensions.classNameBindings = [];
- extensions.classNameBindings = extensions.classNameBindings.concat(hash.classNameBindings.split(' '));
- dup = true;
- }
+});
- if (hash.attributeBindings) {
- Ember.assert("Setting 'attributeBindings' via Handlebars is not allowed. Please subclass Ember.View and set it there instead.");
- extensions.attributeBindings = null;
- dup = true;
- }
+})();
- if (dup) {
- hash = Ember.$.extend({}, hash);
- delete hash.id;
- delete hash['class'];
- delete hash.classBinding;
- }
- // Set the proper context for all bindings passed to the helper. This applies to regular attribute bindings
- // as well as class name bindings. If the bindings are local, make them relative to the current context
- // instead of the view.
- var path;
- // Evaluate the context of regular attribute bindings:
- for (var prop in hash) {
- if (!hash.hasOwnProperty(prop)) { continue; }
+(function() {
- // Test if the property ends in "Binding"
- if (Ember.IS_BINDING.test(prop) && typeof hash[prop] === 'string') {
- path = this.contextualizeBindingPath(hash[prop], data);
- if (path) { hash[prop] = path; }
- }
- }
+})();
- // Evaluate the context of class name bindings:
- if (extensions.classNameBindings) {
- for (var b in extensions.classNameBindings) {
- var full = extensions.classNameBindings[b];
- if (typeof full === 'string') {
- // Contextualize the path of classNameBinding so this:
- //
- // classNameBinding="isGreen:green"
- //
- // is converted to this:
- //
- // classNameBinding="bindingContext.isGreen:green"
- var parsedPath = Ember.View._parsePropertyPath(full);
- path = this.contextualizeBindingPath(parsedPath.path, data);
- if (path) { extensions.classNameBindings[b] = path + parsedPath.classNames; }
- }
+
+
+(function() {
+/**
+@module ember
+@submodule ember-routing
+*/
+
+var get = Ember.get, set = Ember.set;
+var ControllersProxy = Ember.Object.extend({
+ controller: null,
+
+ unknownProperty: function(controllerName) {
+ var controller = get(this, 'controller'),
+ needs = get(controller, 'needs'),
+ dependency;
+
+ for (var i=0, l=needs.length; i<l; i++) {
+ dependency = needs[i];
+ if (dependency === controllerName) {
+ return controller.controllerFor(controllerName);
}
}
+ }
+});
- // Make the current template context available to the view
- // for the bindings set up above.
- extensions.bindingContext = thisContext;
+Ember.ControllerMixin.reopen({
+ concatenatedProperties: ['needs'],
+ needs: [],
- return Ember.$.extend(hash, extensions);
- },
+ init: function() {
+ this._super.apply(this, arguments);
- // Transform bindings from the current context to a context that can be evaluated within the view.
- // Returns null if the path shouldn't be changed.
- //
- // TODO: consider the addition of a prefix that would allow this method to return `path`.
- contextualizeBindingPath: function(path, data) {
- var normalized = Ember.Handlebars.normalizePath(null, path, data);
- if (normalized.isKeyword) {
- return 'templateData.keywords.' + path;
- } else if (Ember.isGlobalPath(path)) {
- return null;
- } else if (path === 'this') {
- return 'bindingContext';
- } else {
- return 'bindingContext.' + path;
+ // Structure asserts to still do verification but not string concat in production
+ if(!verifyDependencies(this)) {
+ Ember.assert("Missing dependencies", false);
}
},
- helper: function(thisContext, path, options) {
- var inverse = options.inverse,
- data = options.data,
- view = data.view,
- fn = options.fn,
- hash = options.hash,
- newView;
+ transitionToRoute: function() {
+ var target = get(this, 'target');
- if ('string' === typeof path) {
- newView = EmberHandlebars.getPath(thisContext, path, options);
- Ember.assert("Unable to find view at path '" + path + "'", !!newView);
+ return target.transitionTo.apply(target, arguments);
+ },
+
+ // TODO: Deprecate this, see https://github.com/emberjs/ember.js/issues/1785
+ transitionTo: function() {
+ return this.transitionToRoute.apply(this, arguments);
+ },
+
+ replaceRoute: function() {
+ var target = get(this, 'target');
+
+ return target.replaceWith.apply(target, arguments);
+ },
+
+ // TODO: Deprecate this, see https://github.com/emberjs/ember.js/issues/1785
+ replaceWith: function() {
+ return this.replaceRoute.apply(this, arguments);
+ },
+
+ controllerFor: function(controllerName) {
+ var container = get(this, 'container');
+ return container.lookup('controller:' + controllerName);
+ },
+
+ model: Ember.computed(function(key, value) {
+ if (arguments.length > 1) {
+ return set(this, 'content', value);
} else {
- newView = path;
+ return get(this, 'content');
}
+ }).property('content'),
- Ember.assert(Ember.String.fmt('You must pass a view class to the #view helper, not %@ (%@)', [path, newView]), Ember.View.detect(newView));
+ controllers: Ember.computed(function() {
+ return ControllersProxy.create({ controller: this });
+ })
+});
- var viewOptions = this.propertiesFromHTMLOptions(options, thisContext);
- var currentView = data.view;
- viewOptions.templateData = options.data;
+function verifyDependencies(controller) {
+ var needs = get(controller, 'needs'),
+ container = get(controller, 'container'),
+ dependency, satisfied = true;
- if (fn) {
- Ember.assert("You cannot provide a template block if you also specified a templateName", !get(viewOptions, 'templateName') && !get(newView.proto(), 'templateName'));
- viewOptions.template = fn;
+ for (var i=0, l=needs.length; i<l; i++) {
+ dependency = needs[i];
+ if (dependency.indexOf(':') === -1) {
+ dependency = "controller:" + dependency;
}
- // We only want to override the `_context` computed property if there is
- // no specified controller. See View#_context for more information.
- if (VIEW_PRESERVES_CONTEXT && !newView.proto().controller && !newView.proto().controllerBinding && !viewOptions.controller && !viewOptions.controllerBinding) {
- viewOptions._context = thisContext;
+ if (!container.has(dependency)) {
+ satisfied = false;
+ Ember.assert(controller + " needs " + dependency + " but it does not exist", false);
}
-
- currentView.appendChild(newView, viewOptions);
}
-});
+ return satisfied;
+}
+
+})();
+
+
+
+(function() {
/**
- `{{view}}` inserts a new instance of `Ember.View` into a template passing its options
- to the `Ember.View`'s `create` method and using the supplied block as the view's own template.
+@module ember
+@submodule ember-routing
+*/
- An empty `<body>` and the following template:
+var get = Ember.get, set = Ember.set;
- ``` handlebars
- <script type="text/x-handlebars">
- A span:
- {{#view tagName="span"}}
- hello.
- {{/view}}
- </script>
- ```
+Ember.View.reopen({
+ init: function() {
+ set(this, '_outlets', {});
+ this._super();
+ },
- Will result in HTML structure:
+ connectOutlet: function(outletName, view) {
+ var outlets = get(this, '_outlets'),
+ container = get(this, 'container'),
+ router = container && container.lookup('router:main'),
+ renderedName = get(view, 'renderedName');
- ``` html
- <body>
- <!-- Note: the handlebars template script
- also results in a rendered Ember.View
- which is the outer <div> here -->
+ set(outlets, outletName, view);
- <div class="ember-view">
- A span:
- <span id="ember1" class="ember-view">
- Hello.
- </span>
- </div>
- </body>
- ```
+ if (router && renderedName) {
+ router._connectActiveView(renderedName, view);
+ }
+ },
- ### parentView setting
+ disconnectOutlet: function(outletName) {
+ var outlets = get(this, '_outlets');
- 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.
+ set(outlets, outletName, null);
+ }
+});
- ``` javascript
- aView = Ember.View.create({
- template: Ember.Handlebars.compile("{{#view}} my parent: {{parentView.elementId}} {{/view}}")
- });
+})();
- aView.appendTo('body');
- ```
-
- Will result in HTML structure:
- ``` html
- <div id="ember1" class="ember-view">
- <div id="ember2" class="ember-view">
- my parent: ember1
- </div>
- </div>
- ```
- ### Setting CSS id and class attributes
+(function() {
- The HTML `id` attribute can be set on the `{{view}}`'s resulting element with the `id` option.
- This option will _not_ be passed to `Ember.View.create`.
+})();
- ``` handlebars
- <script type="text/x-handlebars">
- {{#view tagName="span" id="a-custom-id"}}
- hello.
- {{/view}}
- </script>
- ```
- Results in the following HTML structure:
- ``` html
- <div class="ember-view">
- <span id="a-custom-id" class="ember-view">
- hello.
- </span>
- </div>
- ```
+(function() {
+/**
+@module ember
+@submodule ember-routing
+*/
- The HTML `class` attribute can be set on the `{{view}}`'s resulting element with
- the `class` or `classNameBindings` options. The `class` option
- will directly set the CSS `class` attribute and will not be passed to
- `Ember.View.create`. `classNameBindings` will be passed to `create` and use
- `Ember.View`'s class name binding functionality:
+var get = Ember.get, set = Ember.set;
- ``` handlebars
- <script type="text/x-handlebars">
- {{#view tagName="span" class="a-custom-class"}}
- hello.
- {{/view}}
- </script>
- ```
+/*
+ This file implements the `location` API used by Ember's router.
- Results in the following HTML structure:
+ That API is:
- ``` html
- <div class="ember-view">
- <span id="ember2" class="ember-view a-custom-class">
- hello.
- </span>
- </div>
- ```
+ getURL: returns the current URL
+ setURL(path): sets the current URL
+ replaceURL(path): replace the current URL (optional)
+ onUpdateURL(callback): triggers the callback when the URL changes
+ formatURL(url): formats `url` to be placed into `href` attribute
- ### Supplying a different view class
+ Calling setURL or replaceURL will not trigger onUpdateURL callbacks.
- `{{view}}` can take an optional first argument before its supplied options to specify a
- path to a custom view class.
+ TODO: This should perhaps be moved so that it's visible in the doc output.
+*/
- ``` handlebars
- <script type="text/x-handlebars">
- {{#view "MyApp.CustomView"}}
- hello.
- {{/view}}
- </script>
- ```
+/**
+ Ember.Location returns an instance of the correct implementation of
+ the `location` API.
- 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:
+ You can pass it a `implementation` ('hash', 'history', 'none') to force a
+ particular implementation.
- ``` 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}}')
- });
+ @class Location
+ @namespace Ember
+ @static
+*/
+Ember.Location = {
+ create: function(options) {
+ var implementation = options && options.implementation;
+ Ember.assert("Ember.Location.create: you must specify a 'implementation' option", !!implementation);
- MyApp.OuterView.create().appendTo('body');
- ```
+ var implementationClass = this.implementations[implementation];
+ Ember.assert("Ember.Location.create: " + implementation + " is not a valid implementation", !!implementationClass);
- Will result in the following HTML:
+ return implementationClass.create.apply(implementationClass, arguments);
+ },
- ``` html
- <div id="ember1" class="ember-view">
- <div id="ember2" class="ember-view a-custom-view-class-as-property">
- hi
- </div>
- </div>
- ```
+ registerImplementation: function(name, implementation) {
+ this.implementations[name] = implementation;
+ },
- ### Blockless use
+ implementations: {}
+};
- If you supply a custom `Ember.View` subclass that specifies its own template
- or provide a `templateName` option to `{{view}}` it can be used without supplying a block.
- Attempts to use both a `templateName` option and supply a block will throw an error.
+})();
- ``` handlebars
- <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.
+(function() {
+/**
+@module ember
+@submodule ember-routing
+*/
- ``` javascript
- aView = Ember.View.create({
- template: Ember.Handlebars.compile('{{#view viewName="aChildByName"}} hi {{/view}}')
- });
+var get = Ember.get, set = Ember.set;
- aView.appendTo('body');
- aView.get('aChildByName') // the instance of Ember.View created by {{view}} helper
- ```
+/**
+ 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).
- @method view
- @for Ember.Handlebars.helpers
- @param {String} path
- @param {Hash} options
- @return {String} HTML string
+ @class NoneLocation
+ @namespace Ember
+ @extends Ember.Object
*/
-EmberHandlebars.registerHelper('view', function(path, options) {
- Ember.assert("The view helper only takes a single argument", arguments.length <= 2);
+Ember.NoneLocation = Ember.Object.extend({
+ path: '',
- // If no path is provided, treat path param as options.
- if (path && path.data && path.data.isRenderData) {
- options = path;
- path = "Ember.View";
- }
+ getURL: function() {
+ return get(this, 'path');
+ },
- return EmberHandlebars.ViewHelper.helper(this, path, options);
+ setURL: function(path) {
+ set(this, 'path', path);
+ },
+
+ onUpdateURL: function(callback) {
+ // We are not wired up to the browser, so we'll never trigger the callback.
+ },
+
+ formatURL: function(url) {
+ // The return value is not overly meaningful, but we do not want to throw
+ // errors when test code renders templates containing {{action href=true}}
+ // helpers.
+ return url;
+ }
});
+Ember.Location.registerImplementation('none', Ember.NoneLocation);
})();
(function() {
-/*globals Handlebars */
-
-// TODO: Don't require all of this module
/**
@module ember
-@submodule ember-handlebars
+@submodule ember-routing
*/
-var get = Ember.get, getPath = Ember.Handlebars.getPath, fmt = Ember.String.fmt;
+var get = Ember.get, set = Ember.set;
/**
- `{{collection}}` is a `Ember.Handlebars` helper for adding instances of
- `Ember.CollectionView` to a template. See `Ember.CollectionView` for additional
- information on how a `CollectionView` functions.
-
- `{{collection}}`'s primary use is as a block helper with a `contentBinding` option
- pointing towards an `Ember.Array`-compatible object. An `Ember.View` instance will
- be created for each item in its `content` property. Each view will have its own
- `content` property set to the appropriate item in the collection.
-
- The provided block will be applied as the template for each item's view.
-
- Given an empty `<body>` the following template:
-
- ``` handlebars
- <script type="text/x-handlebars">
- {{#collection contentBinding="App.items"}}
- Hi {{view.content.name}}
- {{/collection}}
- </script>
- ```
-
- And the following application code
-
- ``` 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
-
- ``` 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
- the block.
-
- The following template:
-
- ``` handlebars
- <script type="text/x-handlebars">
- {{collection contentBinding="App.items" itemViewClass="App.AnItemView"}}
- </script>
- ```
-
- And application code
-
- ``` 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 {{view.content.name}}")
- });
- ```
-
- 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>
- ```
+ Ember.HashLocation implements the location API using the browser's
+ hash. At present, it relies on a hashchange event existing in the
+ browser.
- ### Specifying a CollectionView subclass
+ @class HashLocation
+ @namespace Ember
+ @extends Ember.Object
+*/
+Ember.HashLocation = Ember.Object.extend({
- 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:
+ init: function() {
+ set(this, 'location', get(this, 'location') || window.location);
+ },
- ``` handlebars
- <script type="text/x-handlebars">
- {{#collection App.MyCustomCollectionClass contentBinding="App.items"}}
- Hi {{view.content.name}}
- {{/collection}}
- </script>
- ```
+ /**
+ @private
+ Returns the current `location.hash`, minus the '#' at the front.
- ### Forwarded `item.*`-named Options
+ @method getURL
+ */
+ getURL: function() {
+ return get(this, 'location').hash.substr(1);
+ },
- 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):
+ /**
+ @private
- ``` handlebars
- <script type="text/x-handlebars">
- {{#collection contentBinding="App.items"
- itemTagName="p"
- itemClassNames="greeting"}}
- Howdy {{view.content.name}}
- {{/collection}}
- </script>
- ```
+ Set the `location.hash` and remembers what was set. This prevents
+ `onUpdateURL` callbacks from triggering when the hash was set by
+ `HashLocation`.
- Will result in the following HTML structure:
+ @method setURL
+ @param path {String}
+ */
+ setURL: function(path) {
+ get(this, 'location').hash = path;
+ set(this, 'lastSetURL', path);
+ },
- ``` 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>
- ```
+ /**
+ @private
- @method collection
- @for Ember.Handlebars.helpers
- @param {String} path
- @param {Hash} options
- @return {String} HTML string
-*/
-Ember.Handlebars.registerHelper('collection', function(path, options) {
- // If no path is provided, treat path param as options.
- if (path && path.data && path.data.isRenderData) {
- options = path;
- path = undefined;
- Ember.assert("You cannot pass more than one argument to the collection helper", arguments.length === 1);
- } else {
- Ember.assert("You cannot pass more than one argument to the collection helper", arguments.length === 2);
- }
+ 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.
- var fn = options.fn;
- var data = options.data;
- var inverse = options.inverse;
+ @method onUpdateURL
+ @param callback {Function}
+ */
+ onUpdateURL: function(callback) {
+ var self = this;
+ var guid = Ember.guidFor(this);
- // If passed a path string, convert that into an object.
- // Otherwise, just default to the standard class.
- var collectionClass;
- collectionClass = path ? getPath(this, path, options) : Ember.CollectionView;
- Ember.assert(fmt("%@ #collection: Could not find collection class %@", [data.view, path]), !!collectionClass);
+ Ember.$(window).bind('hashchange.ember-location-'+guid, function() {
+ var path = location.hash.substr(1);
+ if (get(self, 'lastSetURL') === path) { return; }
- var hash = options.hash, itemHash = {}, match;
+ set(self, 'lastSetURL', null);
- // Extract item view class if provided else default to the standard class
- var itemViewClass, itemViewPath = hash.itemViewClass;
- var collectionPrototype = collectionClass.proto();
- delete hash.itemViewClass;
- itemViewClass = itemViewPath ? getPath(collectionPrototype, itemViewPath, options) : collectionPrototype.itemViewClass;
- Ember.assert(fmt("%@ #collection: Could not find itemViewClass %@", [data.view, itemViewPath]), !!itemViewClass);
+ callback(location.hash.substr(1));
+ });
+ },
- // Go through options passed to the {{collection}} helper and extract options
- // that configure item views instead of the collection itself.
- for (var prop in hash) {
- if (hash.hasOwnProperty(prop)) {
- match = prop.match(/^item(.)(.*)$/);
+ /**
+ @private
- if(match) {
- // Convert itemShouldFoo -> shouldFoo
- itemHash[match[1].toLowerCase() + match[2]] = hash[prop];
- // Delete from hash as this will end up getting passed to the
- // {{view}} helper method.
- delete hash[prop];
- }
- }
- }
+ Given a URL, formats it to be placed into the page as part
+ of an element's `href` attribute.
- var tagName = hash.tagName || collectionPrototype.tagName;
+ This is used, for example, when using the {{action}} helper
+ to generate a URL based on an event.
- if (fn) {
- itemHash.template = fn;
- delete options.fn;
- }
+ @method formatURL
+ @param url {String}
+ */
+ formatURL: function(url) {
+ return '#'+url;
+ },
- var emptyViewClass;
- if (inverse && inverse !== Handlebars.VM.noop) {
- emptyViewClass = get(collectionPrototype, 'emptyViewClass');
- emptyViewClass = emptyViewClass.extend({
- template: inverse,
- tagName: itemHash.tagName
- });
- } else if (hash.emptyViewClass) {
- emptyViewClass = getPath(this, hash.emptyViewClass, options);
- }
- hash.emptyView = emptyViewClass;
+ willDestroy: function() {
+ var guid = Ember.guidFor(this);
- if (hash.eachHelper === 'each') {
- itemHash._context = Ember.computed(function() {
- return get(this, 'content');
- }).property('content');
- delete hash.eachHelper;
+ Ember.$(window).unbind('hashchange.ember-location-'+guid);
}
-
- var viewOptions = Ember.Handlebars.ViewHelper.propertiesFromHTMLOptions({ data: data, hash: itemHash }, this);
- hash.itemViewClass = itemViewClass.extend(viewOptions);
-
- return Ember.Handlebars.helpers.view.call(this, collectionClass, options);
});
+Ember.Location.registerImplementation('hash', Ember.HashLocation);
})();
(function() {
-/*globals Handlebars */
/**
@module ember
-@submodule ember-handlebars
+@submodule ember-routing
*/
-var getPath = Ember.Handlebars.getPath;
+var get = Ember.get, set = Ember.set;
+var popstateReady = false;
/**
- `unbound` allows you to output a property without binding. *Important:* The
- output will not be updated if the property changes. Use with caution.
-
- ``` handlebars
- <div>{{unbound somePropertyThatDoesntChange}}</div>
- ```
+ Ember.HistoryLocation implements the location API using the browser's
+ history.pushState API.
- @method unbound
- @for Ember.Handlebars.helpers
- @param {String} property
- @return {String} HTML string
+ @class HistoryLocation
+ @namespace Ember
+ @extends Ember.Object
*/
-Ember.Handlebars.registerHelper('unbound', function(property, fn) {
- var context = (fn.contexts && fn.contexts[0]) || this;
- return getPath(context, property, fn);
-});
+Ember.HistoryLocation = Ember.Object.extend({
-})();
+ init: function() {
+ set(this, 'location', get(this, 'location') || window.location);
+ this.initState();
+ },
+
+ /**
+ @private
+
+ Used to set state on first call to setURL
+
+ @method initState
+ */
+ initState: function() {
+ this.replaceState(get(this, 'location').pathname);
+ set(this, 'history', window.history);
+ },
+
+ /**
+ Will be pre-pended to path upon state change
+
+ @property rootURL
+ @default '/'
+ */
+ rootURL: '/',
+ /**
+ @private
+ Returns the current `location.pathname`.
-(function() {
-/*jshint debug:true*/
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ @method getURL
+ */
+ getURL: function() {
+ return get(this, 'location').pathname;
+ },
-var getPath = Ember.Handlebars.getPath, normalizePath = Ember.Handlebars.normalizePath;
+ /**
+ @private
-/**
- `log` allows you to output the value of a value in the current rendering
- context.
+ Uses `history.pushState` to update the url without a page reload.
- ``` handlebars
- {{log myVariable}}
- ```
+ @method setURL
+ @param path {String}
+ */
+ setURL: function(path) {
+ path = this.formatURL(path);
- @method log
- @for Ember.Handlebars.helpers
- @param {String} property
-*/
-Ember.Handlebars.registerHelper('log', function(property, options) {
- var context = (options.contexts && options.contexts[0]) || this,
- normalized = normalizePath(context, property, options.data),
- pathRoot = normalized.root,
- path = normalized.path,
- value = (path === 'this') ? pathRoot : getPath(pathRoot, path, options);
- Ember.Logger.log(value);
-});
+ if (this.getState() && this.getState().path !== path) {
+ popstateReady = true;
+ this.pushState(path);
+ }
+ },
-/**
- The `debugger` helper executes the `debugger` statement in the current
- context.
+ /**
+ @private
- ``` handlebars
- {{debugger}}
- ```
+ Uses `history.replaceState` to update the url without a page reload
+ or history modification.
- @method debugger
- @for Ember.Handlebars.helpers
- @param {String} property
-*/
-Ember.Handlebars.registerHelper('debugger', function() {
- debugger;
-});
+ @method replaceURL
+ @param path {String}
+ */
+ replaceURL: function(path) {
+ path = this.formatURL(path);
-})();
+ if (this.getState() && this.getState().path !== path) {
+ popstateReady = true;
+ this.replaceState(path);
+ }
+ },
+ /**
+ @private
+ Get the current `history.state`
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ @method getState
+ */
+ getState: function() {
+ return get(this, 'history').state;
+ },
-var get = Ember.get, set = Ember.set;
+ /**
+ @private
-Ember.Handlebars.EachView = Ember.CollectionView.extend(Ember._Metamorph, {
- itemViewClass: Ember._MetamorphView,
- emptyViewClass: Ember._MetamorphView,
+ Pushes a new state
- createChildView: function(view, attrs) {
- view = this._super(view, attrs);
+ @method pushState
+ @param path {String}
+ */
+ pushState: function(path) {
+ window.history.pushState({ path: path }, null, path);
+ },
- // At the moment, if a container view subclass wants
- // to insert keywords, it is responsible for cloning
- // the keywords hash. This will be fixed momentarily.
- var keyword = get(this, 'keyword');
+ /**
+ @private
- if (keyword) {
- var data = get(view, 'templateData');
+ Replaces the current state
- data = Ember.copy(data);
- data.keywords = view.cloneKeywords();
- set(view, 'templateData', data);
+ @method replaceState
+ @param path {String}
+ */
+ replaceState: function(path) {
+ window.history.replaceState({ path: path }, null, path);
+ },
- var content = get(view, 'content');
+ /**
+ @private
- // In this case, we do not bind, because the `content` of
- // a #each item cannot change.
- data.keywords[keyword] = content;
- }
+ Register a callback to be invoked whenever the browser
+ history changes, including using forward and back buttons.
- return view;
- }
-});
+ @method onUpdateURL
+ @param callback {Function}
+ */
+ onUpdateURL: function(callback) {
+ var guid = Ember.guidFor(this);
-/**
- The `{{#each}}` helper loops over elements in a collection, rendering its block once for each item:
+ Ember.$(window).bind('popstate.ember-location-'+guid, function(e) {
+ if(!popstateReady) {
+ return;
+ }
+ callback(location.pathname);
+ });
+ },
- ``` javascript
- Developers = [{name: 'Yehuda'},{name: 'Tom'}, {name: 'Paul'}];
- ```
+ /**
+ @private
- ``` handlebars
- {{#each Developers}}
- {{name}}
- {{/each}}
- ```
+ Used when using `{{action}}` helper. The url is always appended to the rootURL.
- `{{each}}` supports an alternative syntax with element naming:
+ @method formatURL
+ @param url {String}
+ */
+ formatURL: function(url) {
+ var rootURL = get(this, 'rootURL');
- ``` handlebars
- {{#each person in Developers}}
- {{person.name}}
- {{/each}}
- ```
+ if (url !== '') {
+ rootURL = rootURL.replace(/\/$/, '');
+ }
- When looping over objects that do not have properties, `{{this}}` can be used to render the object:
+ return rootURL + url;
+ },
- ``` javascript
- DeveloperNames = ['Yehuda', 'Tom', 'Paul']
- ```
+ willDestroy: function() {
+ var guid = Ember.guidFor(this);
- ``` handlebars
- {{#each DeveloperNames}}
- {{this}}
- {{/each}}
- ```
+ Ember.$(window).unbind('popstate.ember-location-'+guid);
+ }
+});
- ### Blockless Use
+Ember.Location.registerImplementation('history', Ember.HistoryLocation);
- 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
+(function() {
- ``` 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>
- ```
+(function() {
+/**
+Ember Routing
- @method each
- @for Ember.Handlebars.helpers
- @param [name] {String} name for item (used with `in`)
- @param path {String} path
+@module ember
+@submodule ember-routing
+@requires ember-states
+@requires ember-views
*/
-Ember.Handlebars.registerHelper('each', function(path, options) {
- if (arguments.length === 4) {
- Ember.assert("If you pass more than one argument to the each helper, it must be in the form #each foo in bar", arguments[1] === "in");
- var keywordName = arguments[0];
+})();
- options = arguments[3];
- path = arguments[2];
- if (path === '') { path = "this"; }
+(function() {
+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);
+};
- options.hash.keyword = keywordName;
- } else {
- options.hash.eachHelper = 'each';
+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);
+ }
}
+};
- options.hash.contentBinding = path;
- // Set up emptyView as a metamorph with no tag
- //options.hash.emptyViewClass = Ember._MetamorphView;
+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);
+ }
+ }
+ }
+};
- return Ember.Handlebars.helpers.collection.call(this, 'Ember.Handlebars.EachView', options);
-});
+Ember.DAG = DAG;
})();
(function() {
/**
@module ember
-@submodule ember-handlebars
+@submodule ember-application
*/
+var get = Ember.get, set = Ember.set,
+ classify = Ember.String.classify,
+ decamelize = Ember.String.decamelize;
+
/**
- `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:
+ An instance of `Ember.Application` is the starting point for every Ember
+ application. It helps to instantiate, initialize and coordinate the many
+ objects that make up your app.
- ``` handlebars
- <script type="text/x-handlebars">
- {{#with loggedInUser}}
- Last Login: {{lastLogin}}
- User Info: {{template "user_info"}}
- {{/with}}
- </script>
+ Each Ember 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:
- <script type="text/x-handlebars" data-template-name="user_info">
- Name: <em>{{name}}</em>
- Karma: <em>{{karma}}</em>
- </script>
+ ```javascript
+ window.App = Ember.Application.create();
```
- 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,
- they will be compiled and placed in this hash automatically.
+ 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.
- You can also manually register templates by adding them to the hash:
+ For example, if you define a view class, it might look like this:
- ``` javascript
- Ember.TEMPLATES["my_cool_template"] = Ember.Handlebars.compile('<b>{{user}}</b>');
+ ```javascript
+ App.MyView = Ember.View.extend();
```
- @method template
- @for Ember.Handlebars.helpers
- @param {String} templateName the template to render
-*/
-
-Ember.Handlebars.registerHelper('template', function(name, options) {
- var template = Ember.TEMPLATES[name];
-
- Ember.assert("Unable to find template with name '"+name+"'.", !!template);
+ By default, calling `Ember.Application.create()` will automatically initialize
+ your application by calling the `Ember.Application.initialize()` method. If
+ you need to delay initialization, you can call your app's `deferReadiness()`
+ method. When you are ready for your app to be initialized, call its
+ `advanceReadiness()` method.
- Ember.TEMPLATES[name](this, { data: options.data });
-});
+ 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.
-})();
+ 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.
+ ### Event Delegation
+ Ember 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 sets up a `mousedown`
+ listener on the `body`.
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ If a `mousedown` event occurs, Ember 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.
-var EmberHandlebars = Ember.Handlebars,
- getPath = EmberHandlebars.getPath,
- get = Ember.get,
- a_slice = Array.prototype.slice;
+ `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.
-var ActionHelper = EmberHandlebars.ActionHelper = {
- registeredActions: {}
-};
+ If there is a browser event that Ember does not listen for by default, you
+ can specify custom events and their corresponding view method names by
+ setting the application's `customEvents` property:
-ActionHelper.registerAction = function(actionName, options) {
- var actionId = (++Ember.$.uuid).toString();
+ ```javascript
+ App = Ember.Application.create({
+ customEvents: {
+ // add support for the loadedmetadata media
+ // player event
+ 'loadedmetadata': "loadedMetadata"
+ }
+ });
+ ```
- ActionHelper.registeredActions[actionId] = {
- eventName: options.eventName,
- handler: function(event) {
- var modifier = event.shiftKey || event.metaKey || event.altKey || event.ctrlKey,
- secondaryClick = event.which > 1, // IE9 may return undefined
- nonStandard = modifier || secondaryClick;
+ By default, the application sets up these event listeners on the document
+ body. However, in cases where you are embedding an Ember application inside
+ an existing page, you may want it to set up the listeners on an element
+ inside the body.
- if (options.link && nonStandard) {
- // Allow the browser to handle special link clicks normally
- return;
- }
+ For example, if only events inside a DOM element with the ID of `ember-app`
+ should be delegated, set your application's `rootElement` property:
- event.preventDefault();
+ ```javascript
+ window.App = Ember.Application.create({
+ rootElement: '#ember-app'
+ });
+ ```
- event.view = options.view;
+ 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!
- if (options.hasOwnProperty('context')) {
- event.context = options.context;
- }
+ To learn more about the advantages of event delegation and the Ember view
+ layer, and a list of the event listeners that are setup by default, visit the
+ [Ember View Layer guide](http://emberjs.com/guides/view_layer#toc_event-delegation).
- if (options.hasOwnProperty('contexts')) {
- event.contexts = options.contexts;
- }
+ ### Dependency Injection
- var target = options.target;
+ One thing you may have noticed while using Ember 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`.
- // Check for StateManager (or compatible object)
- if (target.isState && typeof target.send === 'function') {
- return target.send(actionName, event);
- } else {
- Ember.assert(Ember.String.fmt('Target %@ does not have action %@', [target, actionName]), target[actionName]);
- return target[actionName].call(target, event);
- }
- }
- };
+ When the `Ember.Application` initializes, it will look for an `Ember.Router`
+ class defined on the applications's `Router` property, like this:
- options.view.on('willRerender', function() {
- delete ActionHelper.registeredActions[actionId];
+ ```javascript
+ App.Router = Ember.Router.extend({
+ // ...
});
+ ```
- return actionId;
-};
-
-/**
- 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 'Specifying a Target').
-
- User interaction with that element will invoke the supplied action name on
- the appropriate target.
+ 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.
- Given the following Handlebars template on the page
+ 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.
- ``` handlebars
- <script type="text/x-handlebars" data-template-name='a-template'>
- <div {{action anActionName}}>
- click me
- </div>
- </script>
- ```
+ 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.
- And application code
+ For example, if you define a controller class:
- ``` javascript
- AView = Ember.View.extend({
- templateName; 'a-template',
- anActionName: function(event){}
+ ```javascript
+ App.MyController = Ember.Controller.extend({
+ // ...
});
-
- aView = AView.create();
- aView.appendTo('body');
```
- Will results in the following rendered HTML
+ Your router will receive an instance of `App.MyController` saved on its
+ `myController` property.
- ``` html
- <div class="ember-view">
- <div data-ember-action="1">
- click me
- </div>
- </div>
+ Libraries on top of Ember 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());
+ }
+ }
+ });
```
- Clicking "click me" will trigger the `anActionName` method of the `aView`
- object with a `jQuery.Event` object as its argument. The `jQuery.Event`
- object will be extended to include a `view` property that is set to the
- original view interacted with (in this case the `aView` object).
+ ### Routing
+
+ In addition to creating your application's router, `Ember.Application` is
+ also responsible for telling the router when to start routing.
- ### Event Propagation
+ 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.
- Events triggered through the action helper will automatically have
- `.preventDefault()` called on them. You do not need to do so in your event
- handlers. To stop propagation of the event, simply return `false` from your
- handler.
+ 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:
- If you need the default handler to trigger you should either register your
- own event handler, or use event methods on your view class. See Ember.View
- 'Responding to Browser Events' for more information.
-
- ### Specifying DOM event type
+ ```javascript
+ window.App = Ember.Application.create({
+ ready: function() {
+ this.set('router.enableLogging', true);
+ }
+ });
- 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:
+ 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:
- ``` handlebars
- <script type="text/x-handlebars" data-template-name='a-template'>
- <div {{action anActionName on="doubleClick"}}>
- click me
- </div>
- </script>
+ ```javascript
+ App.ApplicationView = Ember.View.extend({
+ templateName: 'application'
+ });
+ App.ApplicationController = Ember.Controller.extend();
```
- See Ember.View 'Responding to Browser Events' for a list of
- acceptable DOM event names.
+ @class Application
+ @namespace Ember
+ @extends Ember.Namespace
+*/
+var Application = Ember.Application = Ember.Namespace.extend(
+/** @scope Ember.Application.prototype */{
- Because `{{action}}` depends on Ember's event dispatch system it will only
- function if an `Ember.EventDispatcher` instance is available. An
- `Ember.EventDispatcher` instance will be created when a new
- `Ember.Application` is created. Having an instance of `Ember.Application`
- will satisfy this requirement.
-
-
- ### Specifying a Target
- There are several possible target objects for `{{action}}` helpers:
-
- In a typical `Ember.Router`-backed Application where views are managed
- through use of the `{{outlet}}` helper, actions will be forwarded to the
- current state of the Applications's Router. See Ember.Router 'Responding
- to User-initiated Events' for more information.
-
- If you manually set the `target` property on the controller of a template's
- `Ember.View` instance, the specifed `controller.target` will become the target
- for any actions. Likely custom values for a controller's `target` are the
- controller itself or a StateManager other than the Application's Router.
-
- If the templates's view lacks a controller property the view itself is the target.
-
- Finally, a `target` option can be provided to the helper to change which object
- will receive the method call. This option must be a string representing a
- path to an object:
+ /**
+ 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/).
- ``` handlebars
- <script type="text/x-handlebars" data-template-name='a-template'>
- <div {{action anActionName target="MyApplication.someObject"}}>
- click me
- </div>
- </script>
- ```
+ 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.
- Clicking "click me" in the rendered HTML of the above template will trigger
- the `anActionName` method of the object at `MyApplication.someObject`.
- The first argument to this method will be a `jQuery.Event` extended to
- include a `view` property that is set to the original view interacted with.
+ @property rootElement
+ @type DOMElement
+ @default 'body'
+ */
+ rootElement: 'body',
- A path relative to the template's `Ember.View` instance can also be used as
- a target:
+ /**
+ The `Ember.EventDispatcher` responsible for delegating events to this
+ application's views.
- ``` handlebars
- <script type="text/x-handlebars" data-template-name='a-template'>
- <div {{action anActionName target="parentView"}}>
- click me
- </div>
- </script>
- ```
+ 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.
- Clicking "click me" in the rendered HTML of the above template will trigger
- the `anActionName` method of the view's parent view.
+ See the documentation for `Ember.EventDispatcher` for more information.
- The `{{action}}` helper is `Ember.StateManager` aware. If the target of the
- action is an `Ember.StateManager` instance `{{action}}` will use the `send`
- functionality of StateManagers. The documentation for `Ember.StateManager`
- has additional information about this use.
+ @property eventDispatcher
+ @type Ember.EventDispatcher
+ @default null
+ */
+ eventDispatcher: null,
- If an action's target does not implement a method that matches the supplied
- action name an error will be thrown.
+ /**
+ The DOM events for which the event dispatcher should listen.
- ``` handlebars
- <script type="text/x-handlebars" data-template-name='a-template'>
- <div {{action aMethodNameThatIsMissing}}>
- click me
- </div>
- </script>
- ```
+ 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.
- With the following application code
+ 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:
- ``` javascript
- AView = Ember.View.extend({
- templateName; 'a-template',
- // note: no method 'aMethodNameThatIsMissing'
- anActionName: function(event){}
- });
+ ```javascript
+ App = Ember.Application.create({
+ customEvents: {
+ // add support for the loadedmetadata media
+ // player event
+ 'loadedmetadata': "loadedMetadata"
+ }
+ });
+ ```
- aView = AView.create();
- aView.appendTo('body');
- ```
+ @property customEvents
+ @type Object
+ @default null
+ */
+ customEvents: null,
- Will throw `Uncaught TypeError: Cannot call method 'call' of undefined` when
- "click me" is clicked.
-
- ### Specifying a context
+ isInitialized: false,
- By default the `{{action}}` helper passes the current Handlebars context
- along in the `jQuery.Event` object. You may specify an alternate object to
- pass as the context by providing a property path:
+ // Start off the number of deferrals at 1. This will be
+ // decremented by the Application's own `initialize` method.
+ _readinessDeferrals: 1,
- ``` handlebars
- <script type="text/x-handlebars" data-template-name='a-template'>
- {{#each person in people}}
- <div {{action edit person}}>
- click me
- </div>
- {{/each}}
- </script>
- ```
+ init: function() {
+ if (!this.$) { this.$ = Ember.$; }
+ this.__container__ = this.buildContainer();
- @method action
- @for Ember.Handlebars.helpers
- @param {String} actionName
- @param {Object...} contexts
- @param {Hash} options
-*/
-EmberHandlebars.registerHelper('action', function(actionName) {
- var options = arguments[arguments.length - 1],
- contexts = a_slice.call(arguments, 1, -1);
+ this.Router = this.Router || this.defaultRouter();
+ if (this.Router) { this.Router.namespace = this; }
- var hash = options.hash,
- view = options.data.view,
- target, controller, link;
+ this._super();
- // create a hash to pass along to registerAction
- var action = {
- eventName: hash.on || "click"
- };
+ this.deferUntilDOMReady();
+ this.scheduleInitialize();
+ },
- action.view = view = get(view, 'concreteView');
+ /**
+ @private
- if (hash.target) {
- target = getPath(this, hash.target, options);
- } else if (controller = options.data.keywords.controller) {
- target = get(controller, 'target');
- }
+ Build the container for the current application.
- action.target = target = target || view;
+ Also register a default application view in case the application
+ itself does not.
- if (contexts.length) {
- action.contexts = contexts = Ember.EnumerableUtils.map(contexts, function(context) {
- return getPath(this, context, options);
- }, this);
- action.context = contexts[0];
- }
+ @method buildContainer
+ @return {Ember.Container} the configured container
+ */
+ buildContainer: function() {
+ var container = this.__container__ = Application.buildContainer(this);
- var output = [], url;
+ return container;
+ },
- if (hash.href && target.urlForEvent) {
- url = target.urlForEvent.apply(target, [actionName].concat(contexts));
- output.push('href="' + url + '"');
- action.link = true;
- }
+ /**
+ @private
- var actionId = ActionHelper.registerAction(actionName, action);
- output.push('data-ember-action="' + actionId + '"');
+ If the application has not opted out of routing and has not explicitly
+ defined a router, supply a default router for the application author
+ to configure.
- return new EmberHandlebars.SafeString(output.join(" "));
-});
+ This allows application developers to do:
-})();
+ ```javascript
+ App = Ember.Application.create();
+ App.Router.map(function(match) {
+ match("/").to("index");
+ });
+ ```
+ @method defaultRouter
+ @return {Ember.Router} the default router
+ */
+ defaultRouter: function() {
+ // Create a default App.Router if one was not supplied to make
+ // it possible to do App.Router.map(...) without explicitly
+ // creating a router first.
+ if (this.router === undefined) {
+ return Ember.Router.extend();
+ }
+ },
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ /**
+ @private
-var get = Ember.get, set = Ember.set;
+ Defer Ember readiness until DOM readiness. By default, Ember
+ will wait for both DOM readiness and application initialization,
+ as well as any deferrals registered by initializers.
-/**
+ @method deferUntilDOMReady
+ */
+ deferUntilDOMReady: function() {
+ this.deferReadiness();
- When used in a Handlebars template that is assigned to an `Ember.View` instance's
- `layout` property Ember will render the layout template first, inserting the view's
- own rendered output at the `{{ yield }}` location.
+ var self = this;
+ this.$().ready(function() {
+ self.advanceReadiness();
+ });
+ },
- An empty `<body>` and the following application code:
+ /**
+ @private
- ``` 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>')
- });
+ Automatically initialize the application once the DOM has
+ become ready.
- aView = AView.create();
- aView.appendTo('body');
- ```
+ The initialization itself is deferred using Ember.run.once,
+ which ensures that application loading finishes before
+ booting.
- Will result in the following HTML output:
+ If you are asynchronously loading code, you should call
+ `deferReadiness()` to defer booting, and then call
+ `advanceReadiness()` once all of your code has finished
+ loading.
- ``` html
- <body>
- <div class='ember-view a-view-with-layout'>
- <div class="wrapper">
- <span>I am wrapped</span>
- </div>
- </div>
- </body>
- ```
+ @method scheduleInitialize
+ */
+ scheduleInitialize: function() {
+ var self = this;
+ this.$().ready(function() {
+ if (self.isDestroyed || self.isInitialized) return;
+ Ember.run.once(self, 'initialize');
+ });
+ },
- 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.
+ /**
+ Use this to defer readiness until some condition is true.
- ``` javascript
- BView = Ember.View.extend({
- classNames: ['a-view-with-layout'],
- template: Ember.Handlebars.compile('{{yield}}')
- });
+ Example:
- bView = BView.create();
- bView.appendTo('body');
+ ```javascript
+ App = Ember.Application.create();
+ App.deferReadiness();
- // throws
- // Uncaught Error: assertion failed: You called yield in a template that was not a layout
- ```
+ jQuery.getJSON("/auth-token", function(token) {
+ App.token = token;
+ App.advanceReadiness();
+ });
+ ```
- @method yield
- @for Ember.Handlebars.helpers
- @param {Hash} options
- @return {String} HTML string
-*/
-Ember.Handlebars.registerHelper('yield', function(options) {
- var view = options.data.view, template;
+ This allows you to perform asynchronous setup logic and defer
+ booting your application until the setup has finished.
- while (view && !get(view, 'layout')) {
- view = get(view, 'parentView');
- }
+ However, if the setup requires a loading UI, it might be better
+ to use the router for this purpose.
- Ember.assert("You called yield in a template that was not a layout", !!view);
+ @method deferReadiness
+ */
+ deferReadiness: function() {
+ Ember.assert("You cannot defer readiness since the `ready()` hook has already been called.", this._readinessDeferrals > 0);
+ this._readinessDeferrals++;
+ },
- template = get(view, 'template');
+ /**
+ @method advanceReadiness
+ @see {Ember.Application#deferReadiness}
+ */
+ advanceReadiness: function() {
+ this._readinessDeferrals--;
- if (template) { template(this, options); }
-});
+ if (this._readinessDeferrals === 0) {
+ Ember.run.once(this, this.didBecomeReady);
+ }
+ },
-})();
+ register: function() {
+ var container = this.__container__;
+ return container.register.apply(container, arguments);
+ },
+ /**
+ @private
+ Initialize the application. This happens automatically.
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ Run any injections and run the application load hook. These hooks may
+ choose to defer readiness. For example, an authentication hook might want
+ to defer readiness until the auth token has been retrieved.
-Ember.Handlebars.OutletView = Ember.ContainerView.extend(Ember._Metamorph);
+ @method initialize
+ */
+ initialize: function() {
+ Ember.assert("Application initialize may only be called once", !this.isInitialized);
+ Ember.assert("Cannot initialize a destroyed application", !this.isDestroyed);
+ this.isInitialized = true;
-/**
- The `outlet` helper allows you to specify that the current
- view's controller will fill in the view for a given area.
+ // At this point, the App.Router must already be assigned
+ this.__container__.register('router', 'main', this.Router);
- ``` handlebars
- {{outlet}}
- ```
+ // Run any injections and run the application load hook. These hooks may
+ // choose to defer readiness. For example, an authentication hook might want
+ // to defer readiness until the auth token has been retrieved.
+ this.runInitializers();
+ Ember.runLoadHooks('application', this);
- By default, when the the current controller's `view`
- property changes, the outlet will replace its current
- view with the new view.
+ // At this point, any injections or load hooks that would have wanted
+ // to defer readiness have fired. In general, advancing readiness here
+ // will proceed to didBecomeReady.
+ this.advanceReadiness();
- ``` javascript
- controller.set('view', someView);
- ```
+ return this;
+ },
- You can also specify a particular name, other than view:
+ /**
+ @private
+ @method runInitializers
+ */
+ runInitializers: function() {
+ var initializers = get(this.constructor, 'initializers'),
+ container = this.__container__,
+ graph = new Ember.DAG(),
+ namespace = this,
+ properties, i, initializer;
- ``` handlebars
- {{outlet masterView}}
- {{outlet detailView}}
- ```
+ for (i=0; i<initializers.length; i++) {
+ initializer = initializers[i];
+ graph.addEdges(initializer.name, initializer.initialize, initializer.before, initializer.after);
+ }
- Then, you can control several outlets from a single
- controller:
+ graph.topsort(function (vertex) {
+ var initializer = vertex.value;
+ initializer(container, namespace);
+ });
+ },
- ``` javascript
- controller.set('masterView', postsView);
- controller.set('detailView', postView);
- ```
+ /**
+ @private
+ @method didBecomeReady
+ */
+ didBecomeReady: function() {
+ this.setupEventDispatcher();
+ this.ready(); // user hook
+ this.startRouting();
- @method outlet
- @for Ember.Handlebars.helpers
- @param {String} property the property on the controller
- that holds the view for this outlet
-*/
-Ember.Handlebars.registerHelper('outlet', function(property, options) {
- if (property && property.data && property.data.isRenderData) {
- options = property;
- property = 'view';
- }
+ if (!Ember.testing) {
+ // Eagerly name all classes that are already loaded
+ Ember.Namespace.processAll();
+ Ember.BOOTED = true;
+ }
+ },
+
+ /**
+ @private
- options.hash.currentViewBinding = "controller." + property;
+ Setup up the event dispatcher to receive events on the
+ application's `rootElement` with any registered
+ `customEvents`.
- return Ember.Handlebars.helpers.view.call(this, Ember.Handlebars.OutletView, options);
-});
+ @method setupEventDispatcher
+ */
+ setupEventDispatcher: function() {
+ var eventDispatcher = this.createEventDispatcher(),
+ customEvents = get(this, 'customEvents');
-})();
+ eventDispatcher.setup(customEvents);
+ },
+ /**
+ @private
+ Create an event dispatcher for the application's `rootElement`.
-(function() {
+ @method createEventDispatcher
+ */
+ createEventDispatcher: function() {
+ var rootElement = get(this, 'rootElement'),
+ eventDispatcher = Ember.EventDispatcher.create({
+ rootElement: rootElement
+ });
-})();
+ set(this, 'eventDispatcher', eventDispatcher);
+ return eventDispatcher;
+ },
+ /**
+ @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.
-(function() {
+ @method startRouting
+ @property router {Ember.Router}
+ */
+ startRouting: function() {
+ var router = this.__container__.lookup('router:main');
+ if (!router) { return; }
-})();
+ router.startRouting();
+ },
+ /**
+ Called when the Application has become ready.
+ The call will be delayed until the DOM has become ready.
+ @event ready
+ */
+ ready: Ember.K,
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ willDestroy: function() {
+ Ember.BOOTED = false;
-var set = Ember.set, get = Ember.get;
+ var eventDispatcher = get(this, 'eventDispatcher');
+ if (eventDispatcher) { eventDispatcher.destroy(); }
-/**
- 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.
+ this.__container__.destroy();
+ },
- Example:
+ initializer: function(options) {
+ this.constructor.initializer(options);
+ }
+});
- ``` handlebars
- {{view Ember.Checkbox checkedBinding="receiveEmail"}}
- ```
+Ember.Application.reopenClass({
+ concatenatedProperties: ['initializers'],
+ initializers: Ember.A(),
+ initializer: function(initializer) {
+ var initializers = get(this, 'initializers');
- You can add a `label` tag yourself in the template where the Ember.Checkbox is being used.
+ Ember.assert("The initializer '" + initializer.name + "' has already been registered", !initializers.findProperty('name', initializers.name));
+ Ember.assert("An injection cannot be registered with both a before and an after", !(initializer.before && initializer.after));
+ Ember.assert("An injection cannot be registered without an injection function", Ember.canInvoke(initializer, 'initialize'));
- ``` html
- <label>
- {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}}
- Some Title
- </label>
- ```
+ initializers.push(initializer);
+ },
+ /**
+ @private
- The `checked` attribute of an Ember.Checkbox object should always be set
- through the Ember object or by interacting with its rendered element representation
- via the mouse, keyboard, or touch. Updating the value of the checkbox via jQuery will
- result in the checked value of the object and its element losing synchronization.
+ This creates a container with the default Ember naming conventions.
- ## 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.
+ It also configures the container:
- @class Checkbox
- @namespace Ember
- @extends Ember.View
-*/
-Ember.Checkbox = Ember.View.extend({
- classNames: ['ember-checkbox'],
+ * registered views are created every time they are looked up (they are
+ not singletons)
+ * registered templates are not factories; the registered value is
+ returned directly.
+ * the router receives the application as its `namespace` property
+ * all controllers receive the router as their `target` and `controllers`
+ properties
+ * all controllers receive the application as their `namespace` property
+ * the application view receives the application controller as its
+ `controller` property
+ * the application view receives the application template as its
+ `defaultTemplate` property
- tagName: 'input',
+ @method buildContainer
+ @static
+ @param {Ember.Application} namespace the application to build the
+ container for.
+ @return {Ember.Container} the built container
+ */
+ buildContainer: function(namespace) {
+ var container = new Ember.Container();
+ Ember.Container.defaultContainer = container;
- attributeBindings: ['type', 'checked', 'disabled', 'tabindex'],
+ container.set = Ember.set;
+ container.resolver = resolverFor(namespace);
+ container.optionsForType('view', { singleton: false });
+ container.optionsForType('template', { instantiate: false });
+ container.register('application', 'main', namespace, { instantiate: false });
+ container.injection('router:main', 'namespace', 'application:main');
- type: "checkbox",
- checked: false,
- disabled: false,
+ container.typeInjection('controller', 'target', 'router:main');
+ container.typeInjection('controller', 'namespace', 'application:main');
- init: function() {
- this._super();
- this.on("change", this, this._updateElementValue);
- },
+ container.typeInjection('route', 'router', 'router:main');
- _updateElementValue: function() {
- set(this, 'checked', this.$().prop('checked'));
+ return container;
}
});
-})();
+/**
+ @private
+
+ This function defines the default lookup rules for container lookups:
+ * templates are looked up on `Ember.TEMPLATES`
+ * other names are looked up on the application after classifying the name.
+ For example, `controller:post` looks up `App.PostController` by default.
+ * if the default lookup fails, look for registered classes on the container
+ This allows the application to register default injections in the container
+ that could be overridden by the normal naming convention.
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
+ @param {Ember.Namespace} namespace the namespace to look for classes
+ @return {any} the resolved value for a given lookup
*/
+function resolverFor(namespace) {
+ return function(fullName) {
+ var nameParts = fullName.split(":"),
+ type = nameParts[0], name = nameParts[1];
-var get = Ember.get, set = Ember.set;
+ if (type === 'template') {
+ var templateName = name.replace(/\./g, '/');
+ if (Ember.TEMPLATES[templateName]) {
+ return Ember.TEMPLATES[templateName];
+ }
-/**
- Shared mixin used by Ember.TextField and Ember.TextArea.
+ templateName = decamelize(templateName);
+ if (Ember.TEMPLATES[templateName]) {
+ return Ember.TEMPLATES[templateName];
+ }
+ }
- @class TextSupport
- @namespace Ember
- @extends Ember.Mixin
- @private
-*/
-Ember.TextSupport = Ember.Mixin.create({
- value: "",
+ if (type === 'controller' || type === 'route' || type === 'view') {
+ name = name.replace(/\./g, '_');
+ }
- attributeBindings: ['placeholder', 'disabled', 'maxlength', 'tabindex'],
- placeholder: null,
- disabled: false,
- maxlength: null,
+ var className = classify(name) + classify(type);
+ var factory = get(namespace, className);
- insertNewline: Ember.K,
- cancel: Ember.K,
+ if (factory) { return factory; }
+ };
+}
- init: function() {
- this._super();
- this.on("focusOut", this, this._elementValueDidChange);
- this.on("change", this, this._elementValueDidChange);
- this.on("keyUp", this, this.interpretKeyEvents);
- },
+Ember.runLoadHooks('Ember.Application', Ember.Application);
- interpretKeyEvents: function(event) {
- var map = Ember.TextSupport.KEY_EVENTS;
- var method = map[event.keyCode];
- this._elementValueDidChange();
- if (method) { return this[method](event); }
- },
+})();
- _elementValueDidChange: function() {
- set(this, 'value', this.$().val());
- }
-});
-Ember.TextSupport.KEY_EVENTS = {
- 13: 'insertNewline',
- 27: 'cancel'
-};
+(function() {
})();
(function() {
/**
+Ember Application
+
@module ember
-@submodule ember-handlebars
+@submodule ember-application
+@requires ember-views, ember-states, ember-routing
*/
+})();
+
+(function() {
var get = Ember.get, set = Ember.set;
/**
- 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`),
- live-updating as the user inputs text.
-
- Example:
-
- ``` 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.
+@module ember
+@submodule ember-states
+*/
- @class TextField
+/**
+ @class State
@namespace Ember
- @extends Ember.View
- @uses Ember.TextSupport
+ @extends Ember.Object
+ @uses Ember.Evented
*/
-Ember.TextField = Ember.View.extend(Ember.TextSupport,
- /** @scope Ember.TextField.prototype */ {
-
- classNames: ['ember-text-field'],
- tagName: "input",
- attributeBindings: ['type', 'value', 'size'],
+Ember.State = Ember.Object.extend(Ember.Evented,
+/** @scope Ember.State.prototype */{
+ isState: true,
/**
- The value attribute of the input element. As the user inputs text, this
- property is updated live.
+ A reference to the parent state.
- @property value
- @type String
- @default ""
+ @property parentState
+ @type Ember.State
*/
- value: "",
+ parentState: null,
+ start: null,
/**
- The type attribute of the input element.
+ The name of this state.
- @property type
+ @property name
@type String
- @default "text"
*/
- type: "text",
+ name: null,
/**
- The size of the text field in characters.
+ The full path to this state.
- @property size
+ @property path
@type String
- @default null
*/
- size: null
-});
-
-})();
-
-
-
-(function() {
-/**
-@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'],
-
- tagName: 'button',
+ path: Ember.computed(function() {
+ var parentPath = get(this, 'parentState.path'),
+ path = get(this, 'name');
- propagateEvents: false,
+ if (parentPath) {
+ path = parentPath + '.' + path;
+ }
- attributeBindings: ['type', 'disabled', 'href', 'tabindex'],
+ return path;
+ }),
/**
@private
- Overrides TargetActionSupport's targetObject computed
- property to use Handlebars-specific path resolution.
+ Override the default event firing from `Ember.Evented` to
+ also call methods with the given name.
- @property targetObject
+ @method trigger
+ @param name
*/
- targetObject: Ember.computed(function() {
- var target = get(this, 'target'),
- root = get(this, 'context'),
- data = get(this, 'templateData');
+ trigger: function(name) {
+ if (this[name]) {
+ this[name].apply(this, [].slice.call(arguments, 1));
+ }
+ this._super.apply(this, arguments);
+ },
- if (typeof target !== 'string') { return target; }
+ init: function() {
+ var states = get(this, 'states'), foundStates;
+ set(this, 'childStates', Ember.A());
+ set(this, 'eventTransitions', get(this, 'eventTransitions') || {});
- return Ember.Handlebars.getPath(root, target, { data: data });
- }).property('target').cacheable(),
+ var name, value, transitionTarget;
- // Defaults to 'button' if tagName is 'input' or 'button'
- type: Ember.computed(function(key, value) {
- var tagName = this.get('tagName');
- if (value !== undefined) { this._type = value; }
- if (this._type !== undefined) { return this._type; }
- if (tagName === 'input' || tagName === 'button') { return 'button'; }
- }).property('tagName').cacheable(),
+ // As a convenience, loop over the properties
+ // of this state and look for any that are other
+ // Ember.State instances or classes, and move them
+ // to the `states` hash. This avoids having to
+ // create an explicit separate hash.
- disabled: false,
+ if (!states) {
+ states = {};
- // Allow 'a' tags to act like buttons
- href: Ember.computed(function() {
- return this.get('tagName') === 'a' ? '#' : null;
- }).property('tagName').cacheable(),
+ for (name in this) {
+ if (name === "constructor") { continue; }
- mouseDown: function() {
- if (!get(this, 'disabled')) {
- set(this, 'isActive', true);
- this._mouseDown = true;
- this._mouseEntered = true;
+ if (value = this[name]) {
+ if (transitionTarget = value.transitionTarget) {
+ this.eventTransitions[name] = transitionTarget;
+ }
+
+ this.setupChild(states, name, value);
+ }
+ }
+
+ set(this, 'states', states);
+ } else {
+ for (name in states) {
+ this.setupChild(states, name, states[name]);
+ }
}
- return get(this, 'propagateEvents');
+
+ set(this, 'pathsCache', {});
+ set(this, 'pathsCacheNoContext', {});
},
- mouseLeave: function() {
- if (this._mouseDown) {
- set(this, 'isActive', false);
- this._mouseEntered = false;
+ setupChild: function(states, name, value) {
+ if (!value) { return false; }
+
+ if (value.isState) {
+ set(value, 'name', name);
+ } else if (Ember.State.detect(value)) {
+ value = value.create({
+ name: name
+ });
}
- },
- mouseEnter: function() {
- if (this._mouseDown) {
- set(this, 'isActive', true);
- this._mouseEntered = true;
+ if (value.isState) {
+ set(value, 'parentState', this);
+ get(this, 'childStates').pushObject(value);
+ states[name] = value;
+ return value;
}
},
- mouseUp: function(event) {
- if (get(this, 'isActive')) {
- // Actually invoke the button's target and action.
- // This method comes from the Ember.TargetActionSupport mixin.
- this.triggerAction();
- set(this, 'isActive', false);
+ lookupEventTransition: function(name) {
+ var path, state = this;
+
+ while(state && !path) {
+ path = state.eventTransitions[name];
+ state = state.get('parentState');
}
- this._mouseDown = false;
- this._mouseEntered = false;
- return get(this, 'propagateEvents');
+ return path;
},
- keyDown: function(event) {
- // Handle space or enter
- if (event.keyCode === 13 || event.keyCode === 32) {
- this.mouseDown();
- }
- },
+ /**
+ A Boolean value indicating whether the state is a leaf state
+ 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() {
+ return !get(this, 'childStates').length;
+ }),
+
+ /**
+ A boolean value indicating whether the state takes a context.
+ By default we assume all states take contexts.
+
+ @property hasContext
+ @default true
+ */
+ hasContext: true,
- keyUp: function(event) {
- // Handle space or enter
- if (event.keyCode === 13 || event.keyCode === 32) {
- this.mouseUp();
- }
- },
+ /**
+ This is the default transition event.
- // TODO: Handle proper touch behavior. Including should make inactive when
- // finger moves more than 20x outside of the edge of the button (vs mouse
- // which goes inactive as soon as mouse goes out of edges.)
+ @event setup
+ @param {Ember.StateManager} manager
+ @param context
+ @see Ember.StateManager#transitionEvent
+ */
+ setup: Ember.K,
- touchStart: function(touch) {
- return this.mouseDown(touch);
- },
+ /**
+ This event fires when the state is entered.
- touchEnd: function(touch) {
- return this.mouseUp(touch);
- },
+ @event enter
+ @param {Ember.StateManager} manager
+ */
+ enter: Ember.K,
- init: function() {
- Ember.deprecate("Ember.Button is deprecated and will be removed from future releases. Consider using the `{{action}}` helper.");
- this._super();
- }
+ /**
+ This event fires when the state is exited.
+
+ @event exit
+ @param {Ember.StateManager} manager
+ */
+ exit: Ember.K
});
-})();
+Ember.State.reopenClass({
+ /**
+ Creates an action function for transitioning to the named state while
+ preserving context.
+ The following example StateManagers are equivalent:
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ ```javascript
+ aManager = Ember.StateManager.create({
+ stateOne: Ember.State.create({
+ changeToStateTwo: Ember.State.transitionTo('stateTwo')
+ }),
+ stateTwo: Ember.State.create({})
+ })
-var get = Ember.get, set = Ember.set;
+ bManager = Ember.StateManager.create({
+ stateOne: Ember.State.create({
+ changeToStateTwo: function(manager, context){
+ manager.transitionTo('stateTwo', context)
+ }
+ }),
+ stateTwo: Ember.State.create({})
+ })
+ ```
-/**
- 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`),
- live-updating as the user inputs text.
+ @method transitionTo
+ @static
+ @param {String} target
+ */
- ## Layout and LayoutName properties
+ transitionTo: function(target) {
- 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.
+ var transitionFunction = function(stateManager, contextOrEvent) {
+ var contexts = [], transitionArgs,
+ Event = Ember.$ && Ember.$.Event;
- @class TextArea
- @namespace Ember
- @extends Ember.View
- @uses Ember.TextSupport
-*/
-Ember.TextArea = Ember.View.extend(Ember.TextSupport, {
- classNames: ['ember-text-area'],
+ if (contextOrEvent && (Event && contextOrEvent instanceof Event)) {
+ if (contextOrEvent.hasOwnProperty('contexts')) {
+ contexts = contextOrEvent.contexts.slice();
+ }
+ }
+ else {
+ contexts = [].slice.call(arguments, 1);
+ }
- tagName: "textarea",
- attributeBindings: ['rows', 'cols'],
- rows: null,
- cols: null,
+ contexts.unshift(target);
+ stateManager.transitionTo.apply(stateManager, contexts);
+ };
- _updateElementValue: Ember.observer(function() {
- // We do this check so cursor position doesn't get affected in IE
- var value = get(this, 'value'),
- $el = this.$();
- if ($el && value !== $el.val()) {
- $el.val(value);
- }
- }, 'value'),
+ transitionFunction.transitionTarget = target;
- init: function() {
- this._super();
- this.on("didInsertElement", this, this._updateElementValue);
+ return transitionFunction;
}
});
(function() {
/**
@module ember
-@submodule ember-handlebars
+@submodule ember-states
*/
+var get = Ember.get, set = Ember.set, fmt = Ember.String.fmt;
+var arrayForEach = Ember.ArrayPolyfills.forEach;
/**
-@class TabContainerView
-@namespace Ember
-@deprecated
-@extends Ember.View
+ 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
*/
-Ember.TabContainerView = Ember.View.extend({
- init: function() {
- Ember.deprecate("Ember.TabContainerView is deprecated and will be removed from future releases.");
- this._super();
- }
-});
+var Transition = function(raw) {
+ this.enterStates = raw.enterStates.slice();
+ this.exitStates = raw.exitStates.slice();
+ this.resolveState = raw.resolveState;
-})();
+ this.finalState = raw.enterStates[raw.enterStates.length - 1] || raw.resolveState;
+};
+Transition.prototype = {
+ /**
+ Normalize the passed in enter, exit and resolve states.
+ This process also adds `finalState` and `contexts` to the Transition object.
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ @method normalize
+ @param {Ember.StateManager} manager the state manager running the transition
+ @param {Array} contexts a list of contexts passed into `transitionTo`
+ */
+ normalize: function(manager, contexts) {
+ this.matchContextsToStates(contexts);
+ this.addInitialStates();
+ this.removeUnchangedContexts(manager);
+ return this;
+ },
-var get = Ember.get;
+ /**
+ 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.
-/**
- @class TabPaneView
- @namespace Ember
- @extends Ember.View
- @deprecated
-*/
-Ember.TabPaneView = Ember.View.extend({
- tabsContainer: Ember.computed(function() {
- return this.nearestInstanceOf(Ember.TabContainerView);
- }).property().volatile(),
+ @method matchContextsToStates
+ @param {Array} contexts a list of contexts passed into `transitionTo`
+ */
+ matchContextsToStates: function(contexts) {
+ var stateIdx = this.enterStates.length - 1,
+ matchedContexts = [],
+ state,
+ context;
- isVisible: Ember.computed(function() {
- return get(this, 'viewName') === get(this, 'tabsContainer.currentView');
- }).property('tabsContainer.currentView').volatile(),
+ // Next, we will match the passed in contexts to the states they
+ // represent.
+ //
+ // First, assign a context to each enter state in reverse order. If
+ // any contexts are left, add a parent state to the list of states
+ // to enter and exit, and assign a context to the parent state.
+ //
+ // If there are still contexts left when the state manager is
+ // reached, raise an exception.
+ //
+ // This allows the following:
+ //
+ // |- root
+ // | |- post
+ // | | |- comments
+ // | |- about (* current state)
+ //
+ // For `transitionTo('post.comments', post, post.get('comments')`,
+ // the first context (`post`) will be assigned to `root.post`, and
+ // the second context (`post.get('comments')`) will be assigned
+ // to `root.post.comments`.
+ //
+ // For the following:
+ //
+ // |- root
+ // | |- post
+ // | | |- index (* current state)
+ // | | |- comments
+ //
+ // For `transitionTo('post.comments', otherPost, otherPost.get('comments')`,
+ // the `<root.post>` state will be added to the list of enter and exit
+ // states because its context has changed.
- init: function() {
- Ember.deprecate("Ember.TabPaneView is deprecated and will be removed from future releases.");
- this._super();
- }
-});
+ while (contexts.length > 0) {
+ if (stateIdx >= 0) {
+ state = this.enterStates[stateIdx--];
+ } else {
+ if (this.enterStates.length) {
+ state = get(this.enterStates[0], 'parentState');
+ if (!state) { throw "Cannot match all contexts to states"; }
+ } else {
+ // If re-entering the current state with a context, the resolve
+ // state will be the current state.
+ state = this.resolveState;
+ }
-})();
+ this.enterStates.unshift(state);
+ this.exitStates.unshift(state);
+ }
+ // in routers, only states with dynamic segments have a context
+ if (get(state, 'hasContext')) {
+ context = contexts.pop();
+ } else {
+ context = null;
+ }
+ matchedContexts.unshift(context);
+ }
-(function() {
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ this.contexts = matchedContexts;
+ },
-var get = Ember.get, setPath = Ember.setPath;
+ /**
+ Add any `initialState`s to the list of enter states.
-/**
-@class TabView
-@namespace Ember
-@extends Ember.View
-@deprecated
-*/
-Ember.TabView = Ember.View.extend({
- tabsContainer: Ember.computed(function() {
- return this.nearestInstanceOf(Ember.TabContainerView);
- }).property().volatile(),
+ @method addInitialStates
+ */
+ addInitialStates: function() {
+ var finalState = this.finalState, initialState;
+
+ while(true) {
+ initialState = get(finalState, 'initialState') || 'start';
+ finalState = get(finalState, 'states.' + initialState);
+
+ if (!finalState) { break; }
+
+ this.finalState = finalState;
+ this.enterStates.push(finalState);
+ this.contexts.push(undefined);
+ }
+ },
+
+ /**
+ 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
+ */
+ removeUnchangedContexts: function(manager) {
+ // Start from the beginning of the enter states. If the state was added
+ // to the list during the context matching phase, make sure the context
+ // has actually changed since the last time the state was entered.
+ while (this.enterStates.length > 0) {
+ if (this.enterStates[0] !== this.exitStates[0]) { break; }
- mouseUp: function() {
- setPath(this, 'tabsContainer.currentView', get(this, 'value'));
- },
+ if (this.enterStates.length === this.contexts.length) {
+ if (manager.getStateMeta(this.enterStates[0], 'context') !== this.contexts[0]) { break; }
+ this.contexts.shift();
+ }
- init: function() {
- Ember.deprecate("Ember.TabView is deprecated and will be removed from future releases.");
- this._super();
+ this.resolveState = this.enterStates.shift();
+ this.exitStates.shift();
+ }
}
-});
-
-})();
-
+};
+var sendRecursively = function(event, currentState, isUnhandledPass) {
+ var log = this.enableLogging,
+ eventName = isUnhandledPass ? 'unhandledEvent' : event,
+ action = currentState[eventName],
+ contexts, sendRecursiveArguments, actionArguments;
+
+ contexts = [].slice.call(arguments, 3);
+
+ // Test to see if the action is a method that
+ // can be invoked. Don't blindly check just for
+ // existence, because it is possible the state
+ // manager has a child state of the given name,
+ // and we should still raise an exception in that
+ // case.
+ if (typeof action === 'function') {
+ if (log) {
+ if (isUnhandledPass) {
+ Ember.Logger.log(fmt("STATEMANAGER: Unhandled event '%@' being sent to state %@.", [event, get(currentState, 'path')]));
+ } else {
+ Ember.Logger.log(fmt("STATEMANAGER: Sending event '%@' to state %@.", [event, get(currentState, 'path')]));
+ }
+ }
-(function() {
+ actionArguments = contexts;
+ if (isUnhandledPass) {
+ actionArguments.unshift(event);
+ }
+ actionArguments.unshift(this);
-})();
+ return action.apply(currentState, actionArguments);
+ } else {
+ var parentState = get(currentState, 'parentState');
+ if (parentState) {
+ sendRecursiveArguments = contexts;
+ sendRecursiveArguments.unshift(event, parentState, isUnhandledPass);
+ return sendRecursively.apply(this, sendRecursiveArguments);
+ } else if (!isUnhandledPass) {
+ return sendEvent.call(this, event, contexts, true);
+ }
+ }
+};
-(function() {
-/*jshint eqeqeq:false */
+var sendEvent = function(eventName, sendRecursiveArguments, isUnhandledPass) {
+ sendRecursiveArguments.unshift(eventName, get(this, 'currentState'), isUnhandledPass);
+ return sendRecursively.apply(this, sendRecursiveArguments);
+};
/**
-@module ember
-@submodule ember-handlebars
-*/
+ 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.
-var set = Ember.set, get = Ember.get;
-var indexOf = Ember.EnumerableUtils.indexOf, indexesOf = Ember.EnumerableUtils.indexesOf;
+ ## Defining States
-/**
- The Ember.Select view class renders a
- [select](https://developer.mozilla.org/en/HTML/Element/select) HTML element,
- allowing the user to choose from a list of options.
+ The states of StateManager can be declared in one of two ways. First, you can
+ define a `states` property that contains all the states:
- The text and `value` property of each `<option>` element within the `<select>` element
- are populated from the objects in the Element.Select's `content` property. The
- underlying data object of the selected `<option>` is stored in the
- Element.Select's `value` property.
+ ```javascript
+ managerA = Ember.StateManager.create({
+ states: {
+ stateOne: Ember.State.create(),
+ stateTwo: Ember.State.create()
+ }
+ })
- ### `content` as an array of Strings
- The simplest version of an Ember.Select takes an array of strings as its `content` property.
- The string will be used as both the `value` property and the inner text of each `<option>`
- element inside the rendered `<select>`.
+ managerA.get('states')
+ // {
+ // stateOne: Ember.State.create(),
+ // stateTwo: Ember.State.create()
+ // }
+ ```
- Example:
+ You can also add instances of `Ember.State` (or an `Ember.State` subclass)
+ directly as properties of a StateManager. These states will be collected into
+ the `states` property for you.
- ``` javascript
- App.Names = ["Yehuda", "Tom"];
- ```
+ ```javascript
+ managerA = Ember.StateManager.create({
+ stateOne: Ember.State.create(),
+ stateTwo: Ember.State.create()
+ })
- ``` handlebars
- {{view Ember.Select contentBinding="App.Names"}}
+ managerA.get('states')
+ // {
+ // stateOne: Ember.State.create(),
+ // stateTwo: Ember.State.create()
+ // }
```
- Would result in the following HTML:
+ ## The Initial State
- ``` html
- <select class="ember-select">
- <option value="Yehuda">Yehuda</option>
- <option value="Tom">Tom</option>
- </select>
- ```
+ When created a StateManager instance will immediately enter into the state
+ defined as its `start` property or the state referenced by name in its
+ `initialState` property:
- You can control which `<option>` is selected through the Ember.Select's
- `value` property directly or as a binding:
+ ```javascript
+ managerA = Ember.StateManager.create({
+ start: Ember.State.create({})
+ })
- ``` javascript
- App.Names = Ember.Object.create({
- selected: 'Tom',
- content: ["Yehuda", "Tom"]
- });
- ```
+ managerA.get('currentState.name') // 'start'
- ``` handlebars
- {{view Ember.Select
- contentBinding="App.controller.content"
- valueBinding="App.controller.selected"
- }}
+ managerB = Ember.StateManager.create({
+ initialState: 'beginHere',
+ beginHere: Ember.State.create({})
+ })
+
+ managerB.get('currentState.name') // 'beginHere'
```
- Would result in the following HTML with the `<option>` for 'Tom' selected:
+ Because it is a property you may also provide a computed function if you wish
+ to derive an `initialState` programmatically:
- ``` html
- <select class="ember-select">
- <option value="Yehuda">Yehuda</option>
- <option value="Tom" selected="selected">Tom</option>
- </select>
+ ```javascript
+ managerC = Ember.StateManager.create({
+ initialState: function(){
+ if (someLogic) {
+ return 'active';
+ } else {
+ return 'passive';
+ }
+ }.property(),
+ active: Ember.State.create({}),
+ passive: Ember.State.create({})
+ })
```
- A user interacting with the rendered `<select>` to choose "Yehuda" would update
- the value of `App.controller.selected` to "Yehuda".
-
- ### `content` as an Array of Objects
- An Ember.Select can also take an array of JavaScript or Ember objects
- as its `content` property.
+ ## Moving Between States
- When using objects you need to tell the Ember.Select which property should be
- accessed on each object to supply the `value` attribute of the `<option>`
- and which property should be used to supply the element text.
+ A StateManager can have any number of `Ember.State` objects as properties
+ and can have a single one of these states as its current state.
- The `optionValuePath` option is used to specify the path on each object to
- the desired property for the `value` attribute. The `optionLabelPath`
- specifies the path on each object to the desired property for the
- element's text. Both paths must reference each object itself as 'content':
+ Calling `transitionTo` transitions between states:
- ``` javascript
- App.Programmers = [
- Ember.Object.create({firstName: "Yehuda", id: 1}),
- Ember.Object.create({firstName: "Tom", id: 2})
- ];
- ```
+ ```javascript
+ robotManager = Ember.StateManager.create({
+ initialState: 'poweredDown',
+ poweredDown: Ember.State.create({}),
+ poweredUp: Ember.State.create({})
+ })
- ``` handlebars
- {{view Ember.Select
- contentBinding="App.Programmers"
- optionValuePath="content.id"
- optionLabelPath="content.firstName"}}
+ robotManager.get('currentState.name') // 'poweredDown'
+ robotManager.transitionTo('poweredUp')
+ robotManager.get('currentState.name') // 'poweredUp'
```
- Would result in the following HTML:
-
- ``` html
- <select class="ember-select">
- <option value>Please Select</option>
- <option value="1">Yehuda</option>
- <option value="2">Tom</option>
- </select>
- ```
+ Before transitioning into a new state the existing `currentState` will have
+ its `exit` method called with the StateManager instance as its first argument
+ and an object representing the transition as its second argument.
+ After transitioning into a new state the new `currentState` will have its
+ `enter` method called with the StateManager instance as its first argument
+ and an object representing the transition as its second argument.
- 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
+ robotManager = Ember.StateManager.create({
+ initialState: 'poweredDown',
+ poweredDown: Ember.State.create({
+ exit: function(stateManager){
+ console.log("exiting the poweredDown state")
+ }
+ }),
+ poweredUp: Ember.State.create({
+ enter: function(stateManager){
+ console.log("entering the poweredUp state. Destroy all humans.")
+ }
+ })
+ })
- ``` javascript
- App.Programmers = [
- Ember.Object.create({firstName: "Yehuda", id: 1}),
- Ember.Object.create({firstName: "Tom", id: 2})
- ];
+ robotManager.get('currentState.name') // 'poweredDown'
+ robotManager.transitionTo('poweredUp')
- App.currentProgrammer = Ember.Object.create({
- id: 2
- });
+ // will log
+ // 'exiting the poweredDown state'
+ // 'entering the poweredUp state. Destroy all humans.'
```
- ``` handlebars
- {{view Ember.Select
- contentBinding="App.controller.content"
- optionValuePath="content.id"
- optionLabelPath="content.firstName"
- valueBinding="App.currentProgrammer.id"}}
- ```
+ Once a StateManager is already in a state, subsequent attempts to enter that
+ state will not trigger enter or exit method calls. Attempts to transition
+ into a state that the manager does not have will result in no changes in the
+ StateManager's current state:
- Would result in the following HTML with a selected option:
+ ```javascript
+ robotManager = Ember.StateManager.create({
+ initialState: 'poweredDown',
+ poweredDown: Ember.State.create({
+ exit: function(stateManager){
+ console.log("exiting the poweredDown state")
+ }
+ }),
+ poweredUp: Ember.State.create({
+ enter: function(stateManager){
+ console.log("entering the poweredUp state. Destroy all humans.")
+ }
+ })
+ })
- ``` html
- <select class="ember-select">
- <option value>Please Select</option>
- <option value="1">Yehuda</option>
- <option value="2" selected="selected">Tom</option>
- </select>
- ```
+ robotManager.get('currentState.name') // 'poweredDown'
+ robotManager.transitionTo('poweredUp')
+ // will log
+ // 'exiting the poweredDown state'
+ // 'entering the poweredUp state. Destroy all humans.'
+ robotManager.transitionTo('poweredUp') // no logging, no state change
- Interacting with the rendered element by selecting the first option
- ('Yehuda') will update the `id` value of `App.currentProgrammer`
- to match the `value` property of the newly selected `<option>`.
+ robotManager.transitionTo('someUnknownState') // silently fails
+ robotManager.get('currentState.name') // 'poweredUp'
+ ```
- Alternatively, you can control selection through the underlying objects
- used to render each object providing a `selectionBinding`. When the selected
- `<option>` is changed, the property path provided to `selectionBinding`
- will be updated to match the content object of the rendered `<option>`
- element:
+ Each state property may itself contain properties that are instances of
+ `Ember.State`. The StateManager can transition to specific sub-states in a
+ series of transitionTo method calls or via a single transitionTo with the
+ full path to the specific state. The StateManager will also keep track of the
+ full path to its currentState
- ``` javascript
- App.controller = Ember.Object.create({
- selectedPerson: null,
- content: [
- Ember.Object.create({firstName: "Yehuda", id: 1}),
- Ember.Object.create({firstName: "Tom", id: 2})
- ]
- });
- ```
+ ```javascript
+ robotManager = Ember.StateManager.create({
+ initialState: 'poweredDown',
+ poweredDown: Ember.State.create({
+ charging: Ember.State.create(),
+ charged: Ember.State.create()
+ }),
+ poweredUp: Ember.State.create({
+ mobile: Ember.State.create(),
+ stationary: Ember.State.create()
+ })
+ })
- ``` handlebars
- {{view Ember.Select
- contentBinding="App.controller.content"
- optionValuePath="content.id"
- optionLabelPath="content.firstName"
- selectionBinding="App.controller.selectedPerson"}}
- ```
+ robotManager.get('currentState.name') // 'poweredDown'
- Would result in the following HTML with a selected option:
+ robotManager.transitionTo('poweredUp')
+ robotManager.get('currentState.name') // 'poweredUp'
- ``` html
- <select class="ember-select">
- <option value>Please Select</option>
- <option value="1">Yehuda</option>
- <option value="2" selected="selected">Tom</option>
- </select>
- ```
+ robotManager.transitionTo('mobile')
+ robotManager.get('currentState.name') // 'mobile'
+ // transition via a state path
+ robotManager.transitionTo('poweredDown.charging')
+ robotManager.get('currentState.name') // 'charging'
- Interacting with the rendered element by selecting the first option
- ('Yehuda') will update the `selectedPerson` value of `App.controller`
- to match the content object of the newly selected `<option>`. In this
- case it is the first object in the `App.content.content`
+ robotManager.get('currentState.path') // 'poweredDown.charging'
+ ```
- ### Supplying a Prompt
+ Enter transition methods will be called for each state and nested child state
+ in their hierarchical order. Exit methods will be called for each state and
+ its nested states in reverse hierarchical order.
- A `null` value for the Ember.Select's `value` or `selection` property
- results in there being no `<option>` with a `selected` attribute:
+ Exit transitions for a parent state are not called when entering into one of
+ its child states, only when transitioning to a new section of possible states
+ in the hierarchy.
- ``` javascript
- App.controller = Ember.Object.create({
- selected: null,
- content: [
- "Yehuda",
- "Tom"
- ]
- });
- ```
+ ```javascript
+ robotManager = Ember.StateManager.create({
+ initialState: 'poweredDown',
+ poweredDown: Ember.State.create({
+ enter: function(){},
+ exit: function(){
+ console.log("exited poweredDown state")
+ },
+ charging: Ember.State.create({
+ enter: function(){},
+ exit: function(){}
+ }),
+ charged: Ember.State.create({
+ enter: function(){
+ console.log("entered charged state")
+ },
+ exit: function(){
+ console.log("exited charged state")
+ }
+ })
+ }),
+ poweredUp: Ember.State.create({
+ enter: function(){
+ console.log("entered poweredUp state")
+ },
+ exit: function(){},
+ mobile: Ember.State.create({
+ enter: function(){
+ console.log("entered mobile state")
+ },
+ exit: function(){}
+ }),
+ stationary: Ember.State.create({
+ enter: function(){},
+ exit: function(){}
+ })
+ })
+ })
- ``` handlebars
- {{view Ember.Select
- contentBinding="App.controller.content"
- valueBinding="App.controller.selected"
- }}
- ```
- Would result in the following HTML:
+ robotManager.get('currentState.path') // 'poweredDown'
+ robotManager.transitionTo('charged')
+ // logs 'entered charged state'
+ // but does *not* log 'exited poweredDown state'
+ robotManager.get('currentState.name') // 'charged
- ``` html
- <select class="ember-select">
- <option value="Yehuda">Yehuda</option>
- <option value="Tom">Tom</option>
- </select>
+ robotManager.transitionTo('poweredUp.mobile')
+ // logs
+ // 'exited charged state'
+ // 'exited poweredDown state'
+ // 'entered poweredUp state'
+ // 'entered mobile state'
```
- Although `App.controller.selected` is `null` and no `<option>`
- has a `selected` attribute the rendered HTML will display the
- first item as though it were selected. You can supply a string
- value for the Ember.Select to display when there is no selection
- with the `prompt` option:
+ During development you can set a StateManager's `enableLogging` property to
+ `true` to receive console messages of state transitions.
- ``` javascript
- App.controller = Ember.Object.create({
- selected: null,
- content: [
- "Yehuda",
- "Tom"
- ]
- });
+ ```javascript
+ robotManager = Ember.StateManager.create({
+ enableLogging: true
+ })
```
- ``` handlebars
- {{view Ember.Select
- contentBinding="App.controller.content"
- valueBinding="App.controller.selected"
- prompt="Please select a name"
- }}
- ```
+ ## Managing currentState with Actions
- Would result in the following HTML:
+ To control which transitions are possible for a given state, and
+ appropriately handle external events, the StateManager can receive and
+ route action messages to its states via the `send` method. Calling to
+ `send` with an action name will begin searching for a method with the same
+ name starting at the current state and moving up through the parent states
+ in a state hierarchy until an appropriate method is found or the StateManager
+ instance itself is reached.
- ``` html
- <select class="ember-select">
- <option>Please select a name</option>
- <option value="Yehuda">Yehuda</option>
- <option value="Tom">Tom</option>
- </select>
- ```
+ If an appropriately named method is found it will be called with the state
+ manager as the first argument and an optional `context` object as the second
+ argument.
- @class Select
- @namespace Ember
- @extends Ember.View
-*/
-Ember.Select = Ember.View.extend(
- /** @scope Ember.Select.prototype */ {
+ ```javascript
+ managerA = Ember.StateManager.create({
+ initialState: 'stateOne.substateOne.subsubstateOne',
+ stateOne: Ember.State.create({
+ substateOne: Ember.State.create({
+ anAction: function(manager, context){
+ console.log("an action was called")
+ },
+ subsubstateOne: Ember.State.create({})
+ })
+ })
+ })
- tagName: 'select',
- classNames: ['ember-select'],
- defaultTemplate: Ember.Handlebars.compile('{{#if view.prompt}}<option value>{{view.prompt}}</option>{{/if}}{{#each view.content}}{{view Ember.SelectOption contentBinding="this"}}{{/each}}'),
- attributeBindings: ['multiple', 'tabindex'],
+ managerA.get('currentState.name') // 'subsubstateOne'
+ managerA.send('anAction')
+ // 'stateOne.substateOne.subsubstateOne' has no anAction method
+ // so the 'anAction' method of 'stateOne.substateOne' is called
+ // and logs "an action was called"
+ // with managerA as the first argument
+ // and no second argument
+
+ someObject = {}
+ managerA.send('anAction', someObject)
+ // the 'anAction' method of 'stateOne.substateOne' is called again
+ // with managerA as the first argument and
+ // someObject as the second argument.
+ ```
- /**
- The `multiple` attribute of the select element. Indicates whether multiple
- options can be selected.
+ If the StateManager attempts to send an action but does not find an appropriately named
+ method in the current state or while moving upwards through the state hierarchy, it will
+ repeat the process looking for a `unhandledEvent` method. If an `unhandledEvent` method is
+ found, it will be called with the original event name as the second argument. If an
+ `unhandledEvent` method is not found, the StateManager will throw a new Ember.Error.
- @property multiple
- @type Boolean
- @default false
- */
- multiple: false,
+ ```javascript
+ managerB = Ember.StateManager.create({
+ initialState: 'stateOne.substateOne.subsubstateOne',
+ stateOne: Ember.State.create({
+ substateOne: Ember.State.create({
+ subsubstateOne: Ember.State.create({}),
+ unhandledEvent: function(manager, eventName, context) {
+ console.log("got an unhandledEvent with name " + eventName);
+ }
+ })
+ })
+ })
- /**
- The list of options.
+ managerB.get('currentState.name') // 'subsubstateOne'
+ managerB.send('anAction')
+ // neither `stateOne.substateOne.subsubstateOne` nor any of it's
+ // parent states have a handler for `anAction`. `subsubstateOne`
+ // also does not have a `unhandledEvent` method, but its parent
+ // state, `substateOne`, does, and it gets fired. It will log
+ // "got an unhandledEvent with name anAction"
+ ```
- If `optionLabelPath` and `optionValuePath` are not overridden, this should
- be a list of strings, which will serve simultaneously as labels and values.
+ Action detection only moves upwards through the state hierarchy from the current state.
+ It does not search in other portions of the hierarchy.
- Otherwise, this should be a list of objects. For instance:
+ ```javascript
+ managerC = Ember.StateManager.create({
+ initialState: 'stateOne.substateOne.subsubstateOne',
+ stateOne: Ember.State.create({
+ substateOne: Ember.State.create({
+ subsubstateOne: Ember.State.create({})
+ })
+ }),
+ stateTwo: Ember.State.create({
+ anAction: function(manager, context){
+ // will not be called below because it is
+ // not a parent of the current state
+ }
+ })
+ })
- content: Ember.A([
- { id: 1, firstName: 'Yehuda' },
- { id: 2, firstName: 'Tom' }
- ]),
- optionLabelPath: 'content.firstName',
- optionValuePath: 'content.id'
+ managerC.get('currentState.name') // 'subsubstateOne'
+ managerC.send('anAction')
+ // Error: <Ember.StateManager:ember132> could not
+ // respond to event anAction in state stateOne.substateOne.subsubstateOne.
+ ```
- @property content
- @type Array
- @default null
- */
- content: null,
+ Inside of an action method the given state should delegate `transitionTo` calls on its
+ StateManager.
- /**
- When `multiple` is false, the element of `content` that is currently
- selected, if any.
+ ```javascript
+ robotManager = Ember.StateManager.create({
+ initialState: 'poweredDown.charging',
+ poweredDown: Ember.State.create({
+ charging: Ember.State.create({
+ chargeComplete: function(manager, context){
+ manager.transitionTo('charged')
+ }
+ }),
+ charged: Ember.State.create({
+ boot: function(manager, context){
+ manager.transitionTo('poweredUp')
+ }
+ })
+ }),
+ poweredUp: Ember.State.create({
+ beginExtermination: function(manager, context){
+ manager.transitionTo('rampaging')
+ },
+ rampaging: Ember.State.create()
+ })
+ })
- When `multiple` is true, an array of such elements.
+ robotManager.get('currentState.name') // 'charging'
+ robotManager.send('boot') // throws error, no boot action
+ // in current hierarchy
+ robotManager.get('currentState.name') // remains 'charging'
- @property selection
- @type Object or Array
- @default null
- */
- selection: null,
+ robotManager.send('beginExtermination') // throws error, no beginExtermination
+ // action in current hierarchy
+ robotManager.get('currentState.name') // remains 'charging'
- /**
- In single selection mode (when `multiple` is false), value can be used to get
- the current selection's value or set the selection by it's value.
+ robotManager.send('chargeComplete')
+ robotManager.get('currentState.name') // 'charged'
- It is not currently supported in multiple selection mode.
+ robotManager.send('boot')
+ robotManager.get('currentState.name') // 'poweredUp'
- @property value
- @type String
- @default null
- */
- value: Ember.computed(function(key, value) {
- if (arguments.length === 2) { return value; }
+ robotManager.send('beginExtermination', allHumans)
+ robotManager.get('currentState.name') // 'rampaging'
+ ```
- var valuePath = get(this, 'optionValuePath').replace(/^content\.?/, '');
- return valuePath ? get(this, 'selection.' + valuePath) : get(this, 'selection');
- }).property('selection').cacheable(),
+ Transition actions can also be created using the `transitionTo` method of the `Ember.State` class. The
+ following example StateManagers are equivalent:
- /**
- If given, a top-most dummy option will be rendered to serve as a user
- prompt.
+ ```javascript
+ aManager = Ember.StateManager.create({
+ stateOne: Ember.State.create({
+ changeToStateTwo: Ember.State.transitionTo('stateTwo')
+ }),
+ stateTwo: Ember.State.create({})
+ })
- @property prompt
- @type String
- @default null
- */
- prompt: null,
+ bManager = Ember.StateManager.create({
+ stateOne: Ember.State.create({
+ changeToStateTwo: function(manager, context){
+ manager.transitionTo('stateTwo', context)
+ }
+ }),
+ stateTwo: Ember.State.create({})
+ })
+ ```
+ @class StateManager
+ @namespace Ember
+ @extends Ember.State
+**/
+Ember.StateManager = Ember.State.extend({
/**
- The path of the option labels. See `content`.
+ @private
- @property optionLabelPath
- @type String
- @default 'content'
+ 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
*/
- optionLabelPath: 'content',
+ init: function() {
+ this._super();
- /**
- The path of the option values. See `content`.
+ set(this, 'stateMeta', Ember.Map.create());
- @property optionValuePath
- @type String
- @default 'content'
- */
- optionValuePath: 'content',
+ var initialState = get(this, 'initialState');
- _change: function() {
- if (get(this, 'multiple')) {
- this._changeMultiple();
- } else {
- this._changeSingle();
+ if (!initialState && get(this, 'states.start')) {
+ initialState = 'start';
}
- },
- selectionDidChange: Ember.observer(function() {
- var selection = get(this, 'selection'),
- isArray = Ember.isArray(selection);
- if (get(this, 'multiple')) {
- if (!isArray) {
- set(this, 'selection', Ember.A([selection]));
- return;
- }
- this._selectionDidChangeMultiple();
- } else {
- this._selectionDidChangeSingle();
+ if (initialState) {
+ this.transitionTo(initialState);
+ Ember.assert('Failed to transition to initial state "' + initialState + '"', !!get(this, 'currentState'));
}
- }, 'selection'),
-
- valueDidChange: Ember.observer(function() {
- var content = get(this, 'content'),
- value = get(this, 'value'),
- valuePath = get(this, 'optionValuePath').replace(/^content\.?/, ''),
- selectedValue = (valuePath ? get(this, 'selection.' + valuePath) : get(this, 'selection')),
- selection;
+ },
- if (value !== selectedValue) {
- selection = content.find(function(obj) {
- return value === (valuePath ? get(obj, valuePath) : obj);
- });
+ stateMetaFor: function(state) {
+ var meta = get(this, 'stateMeta'),
+ stateMeta = meta.get(state);
- this.set('selection', selection);
+ if (!stateMeta) {
+ stateMeta = {};
+ meta.set(state, stateMeta);
}
- }, 'value'),
-
-
- _triggerChange: function() {
- var selection = get(this, 'selection');
- var value = get(this, 'value');
- if (selection) { this.selectionDidChange(); }
- if (value) { this.valueDidChange(); }
+ return stateMeta;
+ },
- this._change();
+ setStateMeta: function(state, key, value) {
+ return set(this.stateMetaFor(state), key, value);
},
- _changeSingle: function() {
- var selectedIndex = this.$()[0].selectedIndex,
- content = get(this, 'content'),
- prompt = get(this, 'prompt');
+ getStateMeta: function(state, key) {
+ return get(this.stateMetaFor(state), key);
+ },
- if (!content) { return; }
- if (prompt && selectedIndex === 0) { set(this, 'selection', null); return; }
+ /**
+ 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.
- if (prompt) { selectedIndex -= 1; }
- set(this, 'selection', content.objectAt(selectedIndex));
- },
+ @property currentState
+ @type Ember.State
+ */
+ currentState: null,
- _changeMultiple: function() {
- var options = this.$('option:selected'),
- prompt = get(this, 'prompt'),
- offset = prompt ? 1 : 0,
- content = get(this, 'content');
+ /**
+ The path of the current state. Returns a string representation of the current
+ state.
- if (!content){ return; }
- if (options) {
- var selectedIndexes = options.map(function(){
- return this.index - offset;
- }).toArray();
- set(this, 'selection', content.objectsAt(selectedIndexes));
- }
- },
+ @property currentPath
+ @type String
+ */
+ currentPath: Ember.computed('currentState', function() {
+ return get(this, 'currentState.path');
+ }),
- _selectionDidChangeSingle: function() {
- var el = this.get('element');
- if (!el) { return; }
+ /**
+ The name of transitionEvent that this stateManager will dispatch
- var content = get(this, 'content'),
- selection = get(this, 'selection'),
- selectionIndex = content ? indexOf(content, selection) : -1,
- prompt = get(this, 'prompt');
+ @property transitionEvent
+ @type String
+ @default 'setup'
+ */
+ transitionEvent: 'setup',
- if (prompt) { selectionIndex += 1; }
- if (el) { el.selectedIndex = selectionIndex; }
- },
+ /**
+ If set to true, `errorOnUnhandledEvents` will cause an exception to be
+ 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.
- _selectionDidChangeMultiple: function() {
- var content = get(this, 'content'),
- selection = get(this, 'selection'),
- selectedIndexes = content ? indexesOf(content, selection) : [-1],
- prompt = get(this, 'prompt'),
- offset = prompt ? 1 : 0,
- options = this.$('option'),
- adjusted;
+ @property errorOnUnhandledEvents
+ @type Boolean
+ @default true
+ */
+ errorOnUnhandledEvent: true,
- if (options) {
- options.each(function() {
- adjusted = this.index > -1 ? this.index - offset : -1;
- this.selected = indexOf(selectedIndexes, adjusted) > -1;
- });
+ send: function(event) {
+ var contexts = [].slice.call(arguments, 1);
+ Ember.assert('Cannot send event "' + event + '" while currentState is ' + get(this, 'currentState'), get(this, 'currentState'));
+ return sendEvent.call(this, event, contexts, false);
+ },
+ unhandledEvent: function(manager, event) {
+ if (get(this, 'errorOnUnhandledEvent')) {
+ throw new Ember.Error(this.toString() + " could not respond to event " + event + " in state " + get(this, 'currentState.path') + ".");
}
},
- init: function() {
- this._super();
- this.on("didInsertElement", this, this._triggerChange);
- this.on("change", this, this._change);
- }
-});
+ /**
+ Finds a state by its state path.
-Ember.SelectOption = Ember.View.extend({
- tagName: 'option',
- attributeBindings: ['value', 'selected'],
+ Example:
- defaultTemplate: function(context, options) {
- options = { data: options.data, hash: {} };
- Ember.Handlebars.helpers.bind.call(context, "view.label", options);
- },
+ ```javascript
+ manager = Ember.StateManager.create({
+ root: Ember.State.create({
+ dashboard: Ember.State.create()
+ })
+ });
+
+ manager.getStateByPath(manager, "root.dashboard")
+
+ // returns the dashboard state
+ ```
+
+ @method getStateByPath
+ @param {Ember.State} root the state to start searching from
+ @param {String} path the state path to follow
+ @return {Ember.State} the state at the end of the path
+ */
+ getStateByPath: function(root, path) {
+ var parts = path.split('.'),
+ state = root;
- init: function() {
- this.labelPathDidChange();
- this.valuePathDidChange();
+ for (var i=0, len=parts.length; i<len; i++) {
+ state = get(get(state, 'states'), parts[i]);
+ if (!state) { break; }
+ }
- this._super();
+ return state;
},
- selected: Ember.computed(function() {
- var content = get(this, 'content'),
- selection = get(this, 'parentView.selection');
- if (get(this, 'parentView.multiple')) {
- return selection && indexOf(selection, content.valueOf()) > -1;
- } else {
- // Primitives get passed through bindings as objects... since
- // `new Number(4) !== 4`, we use `==` below
- return content == selection;
+ findStateByPath: function(state, path) {
+ var possible;
+
+ while (!possible && state) {
+ possible = this.getStateByPath(state, path);
+ state = get(state, 'parentState');
}
- }).property('content', 'parentView.selection').volatile(),
- labelPathDidChange: Ember.observer(function() {
- var labelPath = get(this, 'parentView.optionLabelPath');
+ return possible;
+ },
- if (!labelPath) { return; }
+ /**
+ A state stores its child states in its `states` hash.
+ This code takes a path like `posts.show` and looks
+ up `root.states.posts.states.show`.
- Ember.defineProperty(this, 'label', Ember.computed(function() {
- return get(this, labelPath);
- }).property(labelPath).cacheable());
- }, 'parentView.optionLabelPath'),
+ It returns a list of all of the states from the
+ root, which is the list of states to call `enter`
+ on.
- valuePathDidChange: Ember.observer(function() {
- var valuePath = get(this, 'parentView.optionValuePath');
+ @method getStatesInPath
+ @param root
+ @param path
+ */
+ getStatesInPath: function(root, path) {
+ if (!path || path === "") { return undefined; }
+ var parts = path.split('.'),
+ result = [],
+ states,
+ state;
- if (!valuePath) { return; }
+ for (var i=0, len=parts.length; i<len; i++) {
+ states = get(root, 'states');
+ if (!states) { return undefined; }
+ state = get(states, parts[i]);
+ if (state) { root = state; result.push(state); }
+ else { return undefined; }
+ }
- Ember.defineProperty(this, 'value', Ember.computed(function() {
- return get(this, valuePath);
- }).property(valuePath).cacheable());
- }, 'parentView.optionValuePath')
-});
+ return result;
+ },
-})();
+ goToState: function() {
+ // not deprecating this yet so people don't constantly need to
+ // make trivial changes for little reason.
+ return this.transitionTo.apply(this, arguments);
+ },
+ transitionTo: function(path, context) {
+ // XXX When is transitionTo called with no path
+ if (Ember.isEmpty(path)) { return; }
+ // The ES6 signature of this function is `path, ...contexts`
+ var contexts = context ? Array.prototype.slice.call(arguments, 1) : [],
+ currentState = get(this, 'currentState') || this;
-(function() {
+ // First, get the enter, exit and resolve states for the current state
+ // and specified path. If possible, use an existing cache.
+ var hash = this.contextFreeTransition(currentState, path);
-})();
+ // Next, process the raw state information for the contexts passed in.
+ var transition = new Transition(hash).normalize(this, contexts);
+ this.enterState(transition);
+ this.triggerSetupContext(transition);
+ },
+ contextFreeTransition: function(currentState, path) {
+ var cache = currentState.pathsCache[path];
+ if (cache) { return cache; }
-(function() {
-/*globals Handlebars */
-/**
-@module ember
-@submodule ember-handlebars
-*/
+ var enterStates = this.getStatesInPath(currentState, path),
+ exitStates = [],
+ resolveState = currentState;
-/**
- @private
+ // Walk up the states. For each state, check whether a state matching
+ // the `path` is nested underneath. This will find the closest
+ // parent state containing `path`.
+ //
+ // This allows the user to pass in a relative path. For example, for
+ // the following state hierarchy:
+ //
+ // | |root
+ // | |- posts
+ // | | |- show (* current)
+ // | |- comments
+ // | | |- show
+ //
+ // If the current state is `<root.posts.show>`, an attempt to
+ // transition to `comments.show` will match `<root.comments.show>`.
+ //
+ // First, this code will look for root.posts.show.comments.show.
+ // Next, it will look for root.posts.comments.show. Finally,
+ // it will look for `root.comments.show`, and find the state.
+ //
+ // After this process, the following variables will exist:
+ //
+ // * resolveState: a common parent state between the current
+ // and target state. In the above example, `<root>` is the
+ // `resolveState`.
+ // * enterStates: a list of all of the states represented
+ // by the path from the `resolveState`. For example, for
+ // the path `root.comments.show`, `enterStates` would have
+ // `[<root.comments>, <root.comments.show>]`
+ // * exitStates: a list of all of the states from the
+ // `resolveState` to the `currentState`. In the above
+ // example, `exitStates` would have
+ // `[<root.posts>`, `<root.posts.show>]`.
+ while (resolveState && !enterStates) {
+ exitStates.unshift(resolveState);
- 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.
+ resolveState = get(resolveState, 'parentState');
+ if (!resolveState) {
+ enterStates = this.getStatesInPath(this, path);
+ if (!enterStates) {
+ Ember.assert('Could not find state for path: "'+path+'"');
+ return;
+ }
+ }
+ enterStates = this.getStatesInPath(resolveState, path);
+ }
- 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.
+ // If the path contains some states that are parents of both the
+ // current state and the target state, remove them.
+ //
+ // For example, in the following hierarchy:
+ //
+ // |- root
+ // | |- post
+ // | | |- index (* current)
+ // | | |- show
+ //
+ // If the `path` is `root.post.show`, the three variables will
+ // be:
+ //
+ // * resolveState: `<state manager>`
+ // * enterStates: `[<root>, <root.post>, <root.post.show>]`
+ // * exitStates: `[<root>, <root.post>, <root.post.index>]`
+ //
+ // The goal of this code is to remove the common states, so we
+ // have:
+ //
+ // * resolveState: `<root.post>`
+ // * enterStates: `[<root.post.show>]`
+ // * exitStates: `[<root.post.index>]`
+ //
+ // This avoid unnecessary calls to the enter and exit transitions.
+ while (enterStates.length > 0 && enterStates[0] === exitStates[0]) {
+ resolveState = enterStates.shift();
+ exitStates.shift();
+ }
- @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"]';
+ // Cache the enterStates, exitStates, and resolveState for the
+ // current state and the `path`.
+ var transitions = currentState.pathsCache[path] = {
+ exitStates: exitStates,
+ enterStates: enterStates,
+ resolveState: resolveState
+ };
- Ember.$(selectors, ctx)
- .each(function() {
- // Get a reference to the script tag
- var script = Ember.$(this),
- type = script.attr('type');
+ return transitions;
+ },
- var compile = (script.attr('type') === 'text/x-raw-handlebars') ?
- Ember.$.proxy(Handlebars.compile, Handlebars) :
- Ember.$.proxy(Ember.Handlebars.compile, Ember.Handlebars),
- // 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') || 'application',
- template = compile(script.html());
+ triggerSetupContext: function(transitions) {
+ var contexts = transitions.contexts,
+ offset = transitions.enterStates.length - contexts.length,
+ enterStates = transitions.enterStates,
+ transitionEvent = get(this, 'transitionEvent');
- // For templates which have a name, we save them and then remove them from the DOM
- Ember.TEMPLATES[templateName] = template;
+ Ember.assert("More contexts provided than states", offset >= 0);
- // Remove script tag from DOM
- script.remove();
- });
-};
+ arrayForEach.call(enterStates, function(state, idx) {
+ state.trigger(transitionEvent, this, contexts[idx-offset]);
+ }, this);
+ },
-function bootstrap() {
- Ember.Handlebars.bootstrap( Ember.$(document) );
-}
+ getState: function(name) {
+ var state = get(this, name),
+ parentState = get(this, 'parentState');
-/*
- We tie this to application.load to ensure that we've at least
- attempted to bootstrap at the point that the application is loaded.
+ if (state) {
+ return state;
+ } else if (parentState) {
+ return parentState.getState(name);
+ }
+ },
- We also tie this to document ready since we're guaranteed that all
- the inline templates are present at this point.
+ enterState: function(transition) {
+ var log = this.enableLogging;
- There's no harm to running this twice, since we remove the templates
- from the DOM after processing.
-*/
+ var exitStates = transition.exitStates.slice(0).reverse();
+ arrayForEach.call(exitStates, function(state) {
+ state.trigger('exit', this);
+ }, this);
-Ember.onLoad('application', bootstrap);
+ arrayForEach.call(transition.enterStates, function(state) {
+ if (log) { Ember.Logger.log("STATEMANAGER: Entering " + get(state, 'path')); }
+ state.trigger('enter', this);
+ }, this);
+
+ set(this, 'currentState', transition.finalState);
+ }
+});
})();
(function() {
/**
-Ember Handlebars
+Ember States
@module ember
-@submodule ember-handlebars
-@requires ember-views
+@submodule ember-states
+@requires ember-runtime
*/
})();
-// Version: v1.0.pre-160-g7d62790
-// Last commit: 7d62790 (2012-09-26 15:59:36 -0700)
+
+})();
+// Version: v1.0.0-pre.3-19-g015138e
+// Last commit: 015138e (2013-01-17 23:02:17 -0800)
(function() {
projects / profile / ivi / cowhide.git / commitdiff