view-debug.js revision 76ca635d61eb3f9fb7c9d788a44fa8b1690aa138
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.
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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass@submodule view
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass View.superclass.constructor.apply(this, arguments);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Public Properties ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Container node into which this view's content will be rendered.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass The container node serves as the host for all DOM events attached by the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass view. Delegation is used to handle events on children of the container,
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass allowing the container's contents to be re-rendered at any time without
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass losing event subscriptions.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass The default container is a simple `<div>`, but you can override this in a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass subclass, or by passing in a custom `container` config value at
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass instantiation time.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass When `container` is overridden by a subclass or passed as a config option at
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass instantiation time, it may be provided as an HTML string, a DOM element, or
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass a `Y.Node` instance. During initialization, this view's `create()` method
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass will be called to convert the container into a `Y.Node` instance if it isn't
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass one already.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass The container is not added to the page automatically. This allows you to
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass have full control over how and when your view is actually rendered to the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @property container
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @type HTMLElement|Node|String
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @default `"<div/>"`
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
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass the specified selectors. This allows the container's contents to be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass re-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 @default `{}`
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `Y.Model` instance associated with this view instance.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This is entirely optional. There's no requirement that views be associated
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass with models, but if you do intend to associate your view with a model, then
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass specifying that model instance at instantiation time will cause a reference
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass to be stored here for convenience.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @property model
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Template for this view.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This is a convenience property that has no default behavior of its own. It's
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass only provided as a convention to allow you to store whatever you consider to
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass be a template, whether that's an HTML string, a `Y.Node` instance, a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Mustache template, or anything else your little heart desires.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass How this template gets used is entirely up to you and your custom `render()`
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @property template
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @default `''`
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Lifecycle Methods ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass this.container = this.create(config.container || this.container);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Use config properties if present; otherwise default to prototype
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // properties.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass config.template && (this.template = config.template);
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 -------------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Attaches delegated event handlers to this view's `container` element. This
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass method is called internally to subscribe to events configured in the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `events` property or config attribute when the view is initialized.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass You may override this method to customize the event attaching logic.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method attachEvents
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} events Hash of events to attach. See the docs for the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `events` property for details on the format.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass container.delegate(name, handler, selector, this);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Creates and returns this view's `container` node from the specified HTML
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
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `Y.Node` instance to use as the container node.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Node} Node instance of the created container node.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass 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;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Renders the view.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This method is a noop by default. Override it in your subclass to provide a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass custom implementation that renders this view's content and appends it to the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `container` element. Ideally your `render` method should also return `this`
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass as 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
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `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;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass}, '@VERSION@' ,{requires:['base-build', 'node-event-delegate']});