view-debug.js revision b3c0000ee2acad3759af025d5cece6468634da07
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassRepresents a logical piece of an application's user interface, and provides a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glasslightweight, overridable API for rendering content and handling delegated DOM
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassevents on a container element.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove@submodule view
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan GroveRepresents a logical piece of an application's user interface, and provides a
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grovelightweight, overridable API for rendering content and handling delegated DOM
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Groveevents on a container element.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassThe View class imposes little structure and provides only minimal functionality
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassof its own: it's basically just an overridable API interface that helps you
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassimplement custom views.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove@extends Base
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass View.superclass.constructor.apply(this, arguments);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Public Properties ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Hash of CSS selectors mapped to events to delegate to elements matching
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass those selectors.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass CSS selectors are relative to the `container` element. Events are attached
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass to the container, and delegation is used so that subscribers are only
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass notified of events that occur on elements inside the container that match
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove the specified selectors. This allows the container's contents to be re-
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove rendered as needed without losing event subscriptions.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Event handlers can be specified either as functions or as strings that map
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass to function names on this view instance or its prototype.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass The `this` object in event handlers will refer to this view instance. If
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass you'd prefer `this` to be something else, use `Y.bind()` to bind a custom
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `this` object.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var view = new Y.View({
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Call `this.toggle()` whenever the element with the id
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // "toggle-button" is clicked.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass '#toggle-button': {click: 'toggle'},
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Call `this.hoverOn()` when the mouse moves over any element
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // with the "hoverable" class, and `this.hoverOff()` when the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // mouse moves out of any element with the "hoverable" class.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass '.hoverable': {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass mouseover: 'hoverOn',
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass mouseout : 'hoverOff'
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @property events
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @type Object
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Lifecycle Methods ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Merge events from the config into events in `this.events`, then
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // attach the events to the container node.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Y.merge(this.events, config.events) : this.events;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass destructor: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Remove the container from the DOM and purge all event listeners.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Public Methods -------------------------------------------------------
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Attaches delegated event handlers to this view's container element. This
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass method is called internally to subscribe to events configured in the
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `events` attribute when the view is initialized.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass You may override this method to customize the event attaching logic.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method attachEvents
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @param {Object} [events] Hash of events to attach. See the docs for the
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `events` attribute for details on the format. If not specified, this
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove view's `events` property will be used.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @see detachEvents
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove container.delegate(name, handler, selector, this));
b3c0000ee2acad3759af025d5cece6468634da07Ryan Grove Creates and returns this view's container node from the specified selector
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass string, DOM element, or existing `Y.Node` instance. This method is called
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass internally when the view is initialized.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass By default, the created node is _not_ added to the DOM automatically.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass You may override this method to customize how the container node is created
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass (such as by rendering it from a template). Your method should return a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `Y.Node` instance.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method create
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {HTMLElement|Node|String} container HTML string, DOM element, or
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `Y.Node` instance to use as the container node.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Node} Node instance of the created container node.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Detaches DOM events that have previously been attached to the container by
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `attachEvents()`.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @method detachEvents
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @see attachEvents
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove detachEvents: function () {
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Y.Array.each(this._attachedViewEvents, function (handle) {
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Removes this view's container element from the DOM (if it's in the DOM),
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass but doesn't destroy it or any event listeners attached to it.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method remove
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass remove: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return this;
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Renders this view.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove This method is a noop by default. Override it to provide a custom
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove implementation that renders this view's content and appends it to the
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove container element. Ideally your `render` method should also return `this` as
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove the end to allow chaining, but that's up to you.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Since there's no default renderer, you're free to render your view however
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass you see fit, whether that means manipulating the DOM directly, dumping
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass strings into `innerHTML`, or using a template language of some kind.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass For basic templating needs, `Y.Node.create()` and `Y.Lang.sub()` may
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass suffice, but there are no restrictions on what tools or techniques you can
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass use to render your view. All you need to do is append something to the
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove container element at some point, and optionally append the container
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass to the DOM if it's not there already.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method render
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass render: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return this;
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Container node into which this view's content will be rendered.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove The container node serves as the host for all DOM events attached by the
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove view. Delegation is used to handle events on children of the container,
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove allowing the container's contents to be re-rendered at any time without
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove losing event subscriptions.
b3c0000ee2acad3759af025d5cece6468634da07Ryan Grove The default container is a `<div>` Node, but you can override this in
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove a subclass, or by passing in a custom `container` config value at
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove instantiation time.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove When `container` is overridden by a subclass or passed as a config
b3c0000ee2acad3759af025d5cece6468634da07Ryan Grove option at instantiation time, it may be provided as a selector string, a
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove DOM element, or a `Y.Node` instance. During initialization, this view's
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `create()` method will be called to convert the container into a
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `Y.Node` instance if it isn't one already.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove The container is not added to the page automatically. This allows you to
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove have full control over how and when your view is actually rendered to
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @attribute container
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @type HTMLElement|Node|String
b3c0000ee2acad3759af025d5cece6468634da07Ryan Grove @default Y.Node.create('<div/>')
b3c0000ee2acad3759af025d5cece6468634da07Ryan Grove valueFn: function () {
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Model instance associated with this view instance.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove This is entirely optional. There's no requirement that views be
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove associated with models, but if you do intend to associate your view with
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove a model, then specifying that model instance at instantiation time will
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove cause a reference to be stored here for convenience.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @attribute model
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @default null
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove ModelList instance associated with this view instance.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove This is entirely optional. There's no requirement that views be
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove associated with model lists, but if you do intend to associate your view
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove with a model list, then specifying that list instance at instantiation
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove time will cause a reference to be stored here for convenience.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @attribute modelList
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @type ModelList
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @default null
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove Template for this view.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove This is a convenience attribute that has no default behavior of its own.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove It's only provided as a convention to allow you to store whatever you
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove consider to be a template, whether that's an HTML string, a `Y.Node`
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove instance, a Mustache template, or anything else your little heart
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove How this template gets used is entirely up to you and your custom
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove `render()` method.
3d972ae925dd55609d50660e1479c256bce1840cRyan Grove @attribute template
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass}, '@VERSION@' ,{requires:['base-build', 'node-event-delegate']});