` 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

+ 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

+ 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 -

My Blog

- {{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 -

My Blog

- {{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 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 - - ``` - - ## 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 -

- ``` +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 -

- ``` +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 -

- ``` +(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 -

- ``` + 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 -

- ``` +})(); - 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 -

- ``` +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 -

- ``` - When isEnabled is `false`, the resulting HTML reprensentation looks like this: - ``` html -

- ``` +(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 -

- ``` + // 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 -

- ``` + 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 - - ``` + 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 - - ``` - `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 -

I am the template

- ``` + 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 -

Hello Barry!!!

- ``` + 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 - - ``` + 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 -

I was the default

- ``` +(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 -

I was the template, not default

- ``` + 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. ``) 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("

") - 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 -

- I got wrapped -

- ``` + 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 `` 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 +

+ ``` - /** - @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 +

+ ``` - @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 `` 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 +

+ ``` - /** - 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, ] + ``` - 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 +

Another view

+ ``` - /** - 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 +

+ ``` - 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 +

+ ``` - 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` 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 +

the letter: A

the letter: B

the letter: C

+ ``` - 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 `` 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 +

the letter: A
the letter: B
the letter: C

+ ``` - 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 +

+ The collection is empty +

+ ``` - // 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 = "

"; + testEl.firstChild.innerHTML = ""; + 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: 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 "hi"; + * 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 . Other browsers create it + * before the first node, no matter what. + * + * This means the the following code: + * + * div = document.createElement("div"); + * div.innerHTML = "

+ * + * 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 `

` 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

- 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

- 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 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); + } }); })(); @@ -14648,1330 +18142,1532 @@ Ember.View.reopen({ (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 +

+ ``` -Ember.View.states.destroyed = { - parentState: Ember.View.states._default, + The above handlebars template will fill the ``'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 + 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 + 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 + + ``` -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 + ``` - 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 + ``` - 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 + ``` - 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 + + ``` - 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 `` the following code + ```html + + ``` - ``` 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 + + ``` - Results in the HTML + @method bindAttr + @for Ember.Handlebars.helpers + @param {Hash} options + @return {String} HTML string +*/ +EmberHandlebars.registerHelper('bindAttr', function(options) { - ``` html -

- ``` + 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 -

- ``` + // 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 `` 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 -

- ``` + 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, ] - ``` + 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 -

Another view

- ``` + 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 -

- ``` + 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 -

- ``` + // 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` and the following template: - hasElement: { - childViewsWillChange: function(view, views, start, removed) { - for (var i=start; i + -Ember.ContainerView.states.inDOM = { - parentState: Ember.ContainerView.states.hasElement -}; +

+ A span: + + Hello. + +

+ + ``` -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 +

+ my parent: ember1 +

+ ``` -/** - `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 `` and the following code: + ```html +

+ + hello. + +

+ ``` - ``` 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 -

the letter: A

the letter: B

the letter: C

+ ```html +

+ + hello. +

``` - ## 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 `` 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 -

the letter: A
the letter: B
the letter: C

+ ```html +

+ hi +

``` - 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 -

- The collection is empty -

+ // 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 `` 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 +

Hi Dave

Hi Mary

Hi Sara

``` - ## 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 +

Greetings Dave

Greetings Mary

Greetings Sara

+ ``` - _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 +

Howdy Dave

Howdy Mary

Howdy Sara

+ ``` - 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 +

+ ``` + + @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 +

Greetings Dave

Greetings Mary

Greetings Sara

+ ``` - 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); } }); @@ -15982,887 +19678,527 @@ Ember.State.reopenClass( (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 + + ``` - @class Transition - @private -*/ -var Transition = function(raw) { - this.enterStates = raw.enterStates.slice(); - this.exitStates = raw.exitStates.slice(); - this.resolveState = raw.resolveState; + ```html + + ``` - this.finalState = raw.enterStates[raw.enterStates.length - 1] || raw.resolveState; -}; + This helper looks for templates in the global `Ember.TEMPLATES` hash. If you + add ` - ``` + @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 - - ``` + 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=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"; - }; +var Router = requireModule("router"); +var get = Ember.get, set = Ember.set, classify = Ember.String.classify; - endTagFunc = function() { - return ""; - }; +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, "" ], - fieldset: [ 1, "

", "

" ], - table: [ 1, "", "

" ], - tbody: [ 2, "", "

" ], - tr: [ 3, "", "

" ], - colgroup: [ 2, "", "

" ], - map: [ 1, "", "" ], - _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 = "

"; - * 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 . Other browsers create it - * before the first node, no matter what. - * - * This means the the following code: - * - * div = document.createElement("div"); - * div.innerHTML = "

- * - * 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= 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 - 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 + + ``` - 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 +

+ click me +

+ ``` - 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 + + ``` - // 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 + + ``` - // 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 + + ``` - // 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 + + ``` - // 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 + + ``` - // 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 + + ``` + 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 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` and the following template: +var get = Ember.get, set = Ember.set; - ``` handlebars - - ``` +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 - - + set(outlets, outletName, view); -

- A span: - - Hello. - -

- - ``` + 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 -

- my parent: ember1 -

- ``` - ### 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 - - ``` - Results in the following HTML structure: - ``` html -

- - hello. - -

- ``` +(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 - - ``` +/* + This file implements the `location` API used by Ember's router. - Results in the following HTML structure: + That API is: - ``` html -

- - hello. - -

- ``` + 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 - - ``` +/** + 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 -

- hi -

- ``` + 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 - - ``` - ### 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 `` the following template: - - ``` handlebars - - ``` - - 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 -

Hi Dave

Hi Mary

Hi Sara

- ``` - - ### Blockless Use - If you provide an `itemViewClass` option that has its own `template` you can omit - the block. - - The following template: - - ``` handlebars - - ``` - - 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 -

Greetings Dave

Greetings Mary

Greetings Sara

- ``` + 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 - - ``` + /** + @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 - - ``` + 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 -

Howdy Dave

Howdy Mary

Howdy Sara

- ``` + /** + @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 -

- ``` + 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 - - ``` - 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 -

Greetings Dave

Greetings Mary

Greetings Sara

- ``` +(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; })(); @@ -20775,609 +24111,666 @@ Ember.Handlebars.registerHelper('each', function(path, options) { (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 - + 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: - + ```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('{{user}}'); + ```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 - - ``` + 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 -

- click me -

+ 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 - + ```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 - - ``` + 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 - - ``` + 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 - - ``` + 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 - - ``` + 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 `` and the following application code: + /** + @private - ``` javascript - AView = Ember.View.extend({ - classNames: ['a-view-with-layout'], - layout: Ember.Handlebars.compile('

'), - template: Ember.Handlebars.compile('I am wrapped') - }); + 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 - -

- I am wrapped -

- - ``` + @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 - {{view Ember.Checkbox classNames="applicaton-specific-checkbox"}} - Some Title - - ``` + 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() { })(); @@ -21385,247 +24778,253 @@ Ember.TextSupport.KEY_EVENTS = { (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; } }); @@ -21637,690 +25036,986 @@ Ember.TextArea = Ember.View.extend(Ember.TextSupport, { (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 `` 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 ` - - - - ``` + 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 `{{/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: 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 -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`, an attempt to + // transition to `comments.show` will match ``. + // + // 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, `` 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 + // `[, ]` + // * exitStates: a list of all of the states from the + // `resolveState` to the `currentState`. In the above + // example, `exitStates` would have + // `[`, `]`. + 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: `` + // * enterStates: `[, , ]` + // * exitStates: `[, , ]` + // + // The goal of this code is to remove the common states, so we + // have: + // + // * resolveState: `` + // * enterStates: `[]` + // * exitStates: `[]` + // + // 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); + } +}); })(); @@ -22328,17 +26023,19 @@ Ember.onLoad('application', bootstrap); (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() { diff --git a/lib/handlebars-1.0.rc.1.js b/lib/handlebars-1.0.rc.2.js similarity index 79% rename from lib/handlebars-1.0.rc.1.js rename to lib/handlebars-1.0.rc.2.js index 0534637..247a3fd 100644 --- a/lib/handlebars-1.0.rc.1.js +++ b/lib/handlebars-1.0.rc.2.js @@ -5,7 +5,7 @@ this.Handlebars = {}; (function(Handlebars) { -Handlebars.VERSION = "1.0.rc.1"; +Handlebars.VERSION = "1.0.rc.2"; Handlebars.helpers = {}; Handlebars.partials = {}; @@ -62,22 +62,53 @@ Handlebars.createFrame = Object.create || function(object) { return obj; }; +Handlebars.logger = { + DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3, level: 3, + + methodMap: {0: 'debug', 1: 'info', 2: 'warn', 3: 'error'}, + + // can be overridden in the host environment + log: function(level, obj) { + if (Handlebars.logger.level <= level) { + var method = Handlebars.logger.methodMap[level]; + if (typeof console !== 'undefined' && console[method]) { + console[method].call(console, obj); + } + } + } +}; + +Handlebars.log = function(level, obj) { Handlebars.logger.log(level, obj); }; + Handlebars.registerHelper('each', function(context, options) { var fn = options.fn, inverse = options.inverse; - var ret = "", data; + var i = 0, ret = "", data; if (options.data) { data = Handlebars.createFrame(options.data); } - if(context && context.length > 0) { - for(var i=0, j=context.length; i)/,/^(?:\{\{#)/,/^(?:\{\{\/)/,/^(?:\{\{\^)/,/^(?:\{\{\s*else\b)/,/^(?:\{\{\{)/,/^(?:\{\{&)/,/^(?:\{\{![\s\S]*?\}\})/,/^(?:\{\{)/,/^(?:=)/,/^(?:\.(?=[} ]))/,/^(?:\.\.)/,/^(?:[\/.])/,/^(?:\s+)/,/^(?:\}\}\})/,/^(?:\}\})/,/^(?:"(\\["]|[^"])*")/,/^(?:'(\\[']|[^'])*')/,/^(?:@[a-zA-Z]+)/,/^(?:true(?=[}\s]))/,/^(?:false(?=[}\s]))/,/^(?:[0-9]+(?=[}\s]))/,/^(?:[a-zA-Z0-9_$-]+(?=[=}\s\/.]))/,/^(?:\[[^\]]*\])/,/^(?:.)/,/^(?:$)/]; -lexer.conditions = {"mu":{"rules":[3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28],"inclusive":false},"emu":{"rules":[2],"inclusive":false},"INITIAL":{"rules":[0,1,28],"inclusive":true}}; +lexer.rules = [/^(?:[^\x00]*?(?=(\{\{)))/,/^(?:[^\x00]+)/,/^(?:[^\x00]{2,}?(?=(\{\{|$)))/,/^(?:[\s\S]*?--\}\})/,/^(?:\{\{>)/,/^(?:\{\{#)/,/^(?:\{\{\/)/,/^(?:\{\{\^)/,/^(?:\{\{\s*else\b)/,/^(?:\{\{\{)/,/^(?:\{\{&)/,/^(?:\{\{!--)/,/^(?:\{\{![\s\S]*?\}\})/,/^(?:\{\{)/,/^(?:=)/,/^(?:\.(?=[} ]))/,/^(?:\.\.)/,/^(?:[\/.])/,/^(?:\s+)/,/^(?:\}\}\})/,/^(?:\}\})/,/^(?:"(\\["]|[^"])*")/,/^(?:'(\\[']|[^'])*')/,/^(?:@[a-zA-Z]+)/,/^(?:true(?=[}\s]))/,/^(?:false(?=[}\s]))/,/^(?:[0-9]+(?=[}\s]))/,/^(?:[a-zA-Z0-9_$-]+(?=[=}\s\/.]))/,/^(?:\[[^\]]*\])/,/^(?:.)/,/^(?:\s+)/,/^(?:[a-zA-Z0-9_$-/]+)/,/^(?:$)/]; +lexer.conditions = {"mu":{"rules":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,32],"inclusive":false},"emu":{"rules":[2],"inclusive":false},"com":{"rules":[3],"inclusive":false},"par":{"rules":[30,31],"inclusive":false},"INITIAL":{"rules":[0,1,32],"inclusive":true}}; return lexer;})() parser.lexer = lexer; function Parser () { this.yy = {}; }Parser.prototype = parser;parser.Parser = Parser; return new Parser; -})(); -if (typeof require !== 'undefined' && typeof exports !== 'undefined') { -exports.parser = handlebars; -exports.Parser = handlebars.Parser; -exports.parse = function () { return handlebars.parse.apply(handlebars, arguments); } -exports.main = function commonjsMain(args) { - if (!args[1]) - throw new Error('Usage: '+args[0]+' FILE'); - var source, cwd; - if (typeof process !== 'undefined') { - source = require('fs').readFileSync(require('path').resolve(args[1]), "utf8"); - } else { - source = require("file").path(require("file").cwd()).join(args[1]).read({charset: "utf-8"}); - } - return exports.parser.parse(source); -} -if (typeof module !== 'undefined' && require.main === module) { - exports.main(typeof process !== 'undefined' ? process.argv.slice(1) : require("system").args); -} -}; -; +})();; // lib/handlebars/compiler/base.js Handlebars.Parser = handlebars; @@ -597,17 +625,7 @@ Handlebars.parse = function(string) { Handlebars.print = function(ast) { return new Handlebars.PrintVisitor().accept(ast); -}; - -Handlebars.logger = { - DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3, level: 3, - - // override in the host environment - log: function(level, str) {} -}; - -Handlebars.log = function(level, str) { Handlebars.logger.log(level, str); }; -; +};; // lib/handlebars/compiler/ast.js (function() { @@ -641,13 +659,10 @@ Handlebars.log = function(level, str) { Handlebars.logger.log(level, str); }; // pass or at runtime. }; - Handlebars.AST.PartialNode = function(id, context) { - this.type = "partial"; - - // TODO: disallow complex IDs - - this.id = id; - this.context = context; + Handlebars.AST.PartialNode = function(partialName, context) { + this.type = "partial"; + this.partialName = partialName; + this.context = context; }; var verifyMatch = function(open, close) { @@ -699,6 +714,13 @@ Handlebars.log = function(level, str) { Handlebars.logger.log(level, str); }; // an ID is simple if it only has one part, and that part is not // `..` or `this`. this.isSimple = parts.length === 1 && !this.isScoped && depth === 0; + + this.stringModeValue = this.string; + }; + + Handlebars.AST.PartialNameNode = function(name) { + this.type = "PARTIAL_NAME"; + this.name = name; }; Handlebars.AST.DataNode = function(id) { @@ -709,16 +731,19 @@ Handlebars.log = function(level, str) { Handlebars.logger.log(level, str); }; Handlebars.AST.StringNode = function(string) { this.type = "STRING"; this.string = string; + this.stringModeValue = string; }; Handlebars.AST.IntegerNode = function(integer) { this.type = "INTEGER"; this.integer = integer; + this.stringModeValue = Number(integer); }; Handlebars.AST.BooleanNode = function(bool) { this.type = "BOOLEAN"; this.bool = bool; + this.stringModeValue = bool === "true"; }; Handlebars.AST.CommentNode = function(comment) { @@ -728,14 +753,16 @@ Handlebars.log = function(level, str) { Handlebars.logger.log(level, str); }; })();; // lib/handlebars/utils.js + +var errorProps = ['description', 'fileName', 'lineNumber', 'message', 'name', 'number', 'stack']; + Handlebars.Exception = function(message) { var tmp = Error.prototype.constructor.apply(this, arguments); - for (var p in tmp) { - if (tmp.hasOwnProperty(p)) { this[p] = tmp[p]; } + // Unfortunately errors are not enumerable in Chrome (at least), so `for prop in tmp` doesn't work. + for (var idx = 0; idx < errorProps.length; idx++) { + this[errorProps[idx]] = tmp[errorProps[idx]]; } - - this.message = tmp.message; }; Handlebars.Exception.prototype = new Error(); @@ -778,11 +805,7 @@ Handlebars.SafeString.prototype.toString = function() { }, isEmpty: function(value) { - if (typeof value === "undefined") { - return true; - } else if (value === null) { - return true; - } else if (value === false) { + if (!value && value !== 0) { return true; } else if(Object.prototype.toString.call(value) === "[object Array]" && value.length === 0) { return true; @@ -921,7 +944,7 @@ Handlebars.JavaScriptCompiler = function() {}; // evaluate it by executing `blockHelperMissing` this.opcode('pushProgram', program); this.opcode('pushProgram', inverse); - this.opcode('pushLiteral', '{}'); + this.opcode('pushHash'); this.opcode('blockValue'); } else { this.ambiguousMustache(mustache, program, inverse); @@ -930,7 +953,7 @@ Handlebars.JavaScriptCompiler = function() {}; // evaluate it by executing `blockHelperMissing` this.opcode('pushProgram', program); this.opcode('pushProgram', inverse); - this.opcode('pushLiteral', '{}'); + this.opcode('pushHash'); this.opcode('ambiguousBlockValue'); } @@ -940,19 +963,24 @@ Handlebars.JavaScriptCompiler = function() {}; hash: function(hash) { var pairs = hash.pairs, pair, val; - this.opcode('push', '{}'); + this.opcode('pushHash'); for(var i=0, l=pairs.length; i