lib/yuilib/3.7.2/build/view/view.js

   1 /*
   2 YUI 3.7.2 (build 5639)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('view', function (Y, NAME) {
   8
   9 /**
  10 Represents a logical piece of an application's user interface, and provides a
  11 lightweight, overridable API for rendering content and handling delegated DOM
  12 events on a container element.
  13
  14 @module app
  15 @submodule view
  16 @since 3.4.0
  17 **/
  18
  19 /**
  20 Represents a logical piece of an application's user interface, and provides a
  21 lightweight, overridable API for rendering content and handling delegated DOM
  22 events on a container element.
  23
  24 The View class imposes little structure and provides only minimal functionality
  25 of its own: it's basically just an overridable API interface that helps you
  26 implement custom views.
  27
  28 As of YUI 3.5.0, View allows ad-hoc attributes to be specified at instantiation
  29 time, so you don't need to subclass `Y.View` to add custom attributes. Just pass
  30 them to the constructor:
  31
  32     var view = new Y.View({foo: 'bar'});
  33     view.get('foo'); // => "bar"
  34
  35 @class View
  36 @constructor
  37 @extends Base
  38 @since 3.4.0
  39 **/
  40
  41 function View() {
  42     View.superclass.constructor.apply(this, arguments);
  43 }
  44
  45 Y.View = Y.extend(View, Y.Base, {
  46     // -- Public Properties ----------------------------------------------------
  47
  48     /**
  49     Template for this view's container.
  50
  51     @property containerTemplate
  52     @type String
  53     @default "<div/>"
  54     @since 3.5.0
  55     **/
  56     containerTemplate: '<div/>',
  57
  58     /**
  59     Hash of CSS selectors mapped to events to delegate to elements matching
  60     those selectors.
  61
  62     CSS selectors are relative to the `container` element. Events are attached
  63     to the container, and delegation is used so that subscribers are only
  64     notified of events that occur on elements inside the container that match
  65     the specified selectors. This allows the container's contents to be re-
  66     rendered as needed without losing event subscriptions.
  67
  68     Event handlers can be specified either as functions or as strings that map
  69     to function names on this view instance or its prototype.
  70
  71     The `this` object in event handlers will refer to this view instance. If
  72     you'd prefer `this` to be something else, use `Y.bind()` to bind a custom
  73     `this` object.
  74
  75     @example
  76
  77         var view = new Y.View({
  78             events: {
  79                 // Call `this.toggle()` whenever the element with the id
  80                 // "toggle-button" is clicked.
  81                 '#toggle-button': {click: 'toggle'},
  82
  83                 // Call `this.hoverOn()` when the mouse moves over any element
  84                 // with the "hoverable" class, and `this.hoverOff()` when the
  85                 // mouse moves out of any element with the "hoverable" class.
  86                 '.hoverable': {
  87                     mouseover: 'hoverOn',
  88                     mouseout : 'hoverOff'
  89                 }
  90             }
  91         });
  92
  93     @property events
  94     @type Object
  95     @default {}
  96     **/
  97     events: {},
  98
  99     /**
 100     Template for this view's contents.
 101
 102     This is a convenience property that has no default behavior of its own.
 103     It's only provided as a convention to allow you to store whatever you
 104     consider to be a template, whether that's an HTML string, a `Y.Node`
 105     instance, a Mustache template, or anything else your little heart
 106     desires.
 107
 108     How this template gets used is entirely up to you and your custom
 109     `render()` method.
 110
 111     @property template
 112     @type mixed
 113     @default ''
 114     **/
 115     template: '',
 116
 117     // -- Protected Properties -------------------------------------------------
 118
 119     /**
 120     This tells `Y.Base` that it should create ad-hoc attributes for config
 121     properties passed to View's constructor. This makes it possible to
 122     instantiate a view and set a bunch of attributes without having to subclass
 123     `Y.View` and declare all those attributes first.
 124
 125     @property _allowAdHocAttrs
 126     @type Boolean
 127     @default true
 128     @protected
 129     @since 3.5.0
 130     **/
 131     _allowAdHocAttrs: true,
 132
 133     // -- Lifecycle Methods ----------------------------------------------------
 134     initializer: function (config) {
 135         config || (config = {});
 136
 137         // Set instance properties specified in the config.
 138         config.containerTemplate &&
 139             (this.containerTemplate = config.containerTemplate);
 140
 141         config.template && (this.template = config.template);
 142
 143         // Merge events from the config into events in `this.events`.
 144         this.events = config.events ? Y.merge(this.events, config.events) :
 145             this.events;
 146
 147         // When the container node changes (or when it's set for the first
 148         // time), we'll attach events to it, but not until then. This allows the
 149         // container to be created lazily the first time it's accessed rather
 150         // than always on init.
 151         this.after('containerChange', this._afterContainerChange);
 152     },
 153
 154     /**
 155     Destroys this View, detaching any DOM events and optionally also destroying
 156     its container node.
 157
 158     By default, the container node will not be destroyed. Pass an _options_
 159     object with a truthy `remove` property to destroy the container as well.
 160
 161     @method destroy
 162     @param {Object} [options] Options.
 163         @param {Boolean} [options.remove=false] If `true`, this View's container
 164             will be removed from the DOM and destroyed as well.
 165     @chainable
 166     */
 167     destroy: function (options) {
 168         // We also accept `delete` as a synonym for `remove`.
 169         if (options && (options.remove || options['delete'])) {
 170             // Attaching an event handler here because the `destroy` event is
 171             // preventable. If we destroyed the container before calling the
 172             // superclass's `destroy()` method and the event was prevented, the
 173             // class would end up in a broken state.
 174             this.onceAfter('destroy', function () {
 175                 this._destroyContainer();
 176             });
 177         }
 178
 179         return View.superclass.destroy.call(this);
 180     },
 181
 182     destructor: function () {
 183         this.detachEvents();
 184         delete this._container;
 185     },
 186
 187     // -- Public Methods -------------------------------------------------------
 188
 189     /**
 190     Attaches delegated event handlers to this view's container element. This
 191     method is called internally to subscribe to events configured in the
 192     `events` attribute when the view is initialized.
 193
 194     You may override this method to customize the event attaching logic.
 195
 196     @method attachEvents
 197     @param {Object} [events] Hash of events to attach. See the docs for the
 198         `events` attribute for details on the format. If not specified, this
 199         view's `events` property will be used.
 200     @chainable
 201     @see detachEvents
 202     **/
 203     attachEvents: function (events) {
 204         var container = this.get('container'),
 205             owns      = Y.Object.owns,
 206             handler, handlers, name, selector;
 207
 208         this.detachEvents();
 209
 210         events || (events = this.events);
 211
 212         for (selector in events) {
 213             if (!owns(events, selector)) { continue; }
 214
 215             handlers = events[selector];
 216
 217             for (name in handlers) {
 218                 if (!owns(handlers, name)) { continue; }
 219
 220                 handler = handlers[name];
 221
 222                 // TODO: Make this more robust by using lazy-binding:
 223                 // `handler = Y.bind(handler, this);`
 224                 if (typeof handler === 'string') {
 225                     handler = this[handler];
 226                 }
 227
 228                 if (!handler) {
 229                     continue;
 230                 }
 231
 232                 this._attachedViewEvents.push(
 233                     container.delegate(name, handler, selector, this));
 234             }
 235         }
 236
 237         return this;
 238     },
 239
 240     /**
 241     Creates and returns a container node for this view.
 242
 243     By default, the container is created from the HTML template specified in the
 244     `containerTemplate` property, and is _not_ added to the DOM automatically.
 245
 246     You may override this method to customize how the container node is created
 247     (such as by rendering it from a custom template format). Your method must
 248     return a `Y.Node` instance.
 249
 250     @method create
 251     @param {HTMLElement|Node|String} [container] Selector string, `Y.Node`
 252         instance, or DOM element to use at the container node.
 253     @return {Node} Node instance of the created container node.
 254     **/
 255     create: function (container) {
 256         return container ? Y.one(container) :
 257                 Y.Node.create(this.containerTemplate);
 258     },
 259
 260     /**
 261     Detaches DOM events that have previously been attached to the container by
 262     `attachEvents()`.
 263
 264     @method detachEvents
 265     @chainable
 266     @see attachEvents
 267     **/
 268     detachEvents: function () {
 269         Y.Array.each(this._attachedViewEvents, function (handle) {
 270             if (handle) {
 271                 handle.detach();
 272             }
 273         });
 274
 275         this._attachedViewEvents = [];
 276         return this;
 277     },
 278
 279     /**
 280     Removes this view's container element from the DOM (if it's in the DOM),
 281     but doesn't destroy it or any event listeners attached to it.
 282
 283     @method remove
 284     @chainable
 285     **/
 286     remove: function () {
 287         var container = this.get('container');
 288         container && container.remove();
 289         return this;
 290     },
 291
 292     /**
 293     Renders this view.
 294
 295     This method is a noop by default. Override it to provide a custom
 296     implementation that renders this view's content and appends it to the
 297     container element. Ideally your `render` method should also return `this` as
 298     the end to allow chaining, but that's up to you.
 299
 300     Since there's no default renderer, you're free to render your view however
 301     you see fit, whether that means manipulating the DOM directly, dumping
 302     strings into `innerHTML`, or using a template language of some kind.
 303
 304     For basic templating needs, `Y.Node.create()` and `Y.Lang.sub()` may
 305     suffice, but there are no restrictions on what tools or techniques you can
 306     use to render your view. All you need to do is append something to the
 307     container element at some point, and optionally append the container
 308     to the DOM if it's not there already.
 309
 310     @method render
 311     @chainable
 312     **/
 313     render: function () {
 314         return this;
 315     },
 316
 317     // -- Protected Methods ----------------------------------------------------
 318
 319     /**
 320     Removes the `container` from the DOM and purges all its event listeners.
 321
 322     @method _destroyContainer
 323     @protected
 324     **/
 325     _destroyContainer: function () {
 326         var container = this.get('container');
 327         container && container.remove(true);
 328     },
 329
 330     /**
 331     Getter for the `container` attribute.
 332
 333     @method _getContainer
 334     @param {Node|null} value Current attribute value.
 335     @return {Node} Container node.
 336     @protected
 337     @since 3.5.0
 338     **/
 339     _getContainer: function (value) {
 340         // This wackiness is necessary to enable fully lazy creation of the
 341         // container node both when no container is specified and when one is
 342         // specified via a valueFn.
 343
 344         if (!this._container) {
 345             if (value) {
 346                 // Attach events to the container when it's specified via a
 347                 // valueFn, which won't fire the containerChange event.
 348                 this._container = value;
 349                 this.attachEvents();
 350             } else {
 351                 // Create a default container and set that as the new attribute
 352                 // value. The `this._container` property prevents infinite
 353                 // recursion.
 354                 value = this._container = this.create();
 355                 this._set('container', value);
 356             }
 357         }
 358
 359         return value;
 360     },
 361
 362     // -- Protected Event Handlers ---------------------------------------------
 363
 364     /**
 365     Handles `containerChange` events. Detaches event handlers from the old
 366     container (if any) and attaches them to the new container.
 367
 368     Right now the `container` attr is initOnly so this event should only ever
 369     fire the first time the container is created, but in the future (once Y.App
 370     can handle it) we may allow runtime container changes.
 371
 372     @method _afterContainerChange
 373     @protected
 374     @since 3.5.0
 375     **/
 376     _afterContainerChange: function () {
 377         this.attachEvents(this.events);
 378     }
 379 }, {
 380     NAME: 'view',
 381
 382     ATTRS: {
 383         /**
 384         Container node into which this view's content will be rendered.
 385
 386         The container node serves as the host for all DOM events attached by the
 387         view. Delegation is used to handle events on children of the container,
 388         allowing the container's contents to be re-rendered at any time without
 389         losing event subscriptions.
 390
 391         The default container is a `<div>` Node, but you can override this in
 392         a subclass, or by passing in a custom `container` config value at
 393         instantiation time. If you override the default container in a subclass
 394         using `ATTRS`, you must use the `valueFn` property. The view's constructor
 395         will ignore any assignments using `value`.
 396
 397         When `container` is overridden by a subclass or passed as a config
 398         option at instantiation time, you can provide it as a selector string, a
 399         DOM element, a `Y.Node` instance, or (if you are subclassing and modifying
 400         the attribute), a `valueFn` function that returns a `Y.Node` instance.
 401         The value will be converted into a `Y.Node` instance if it isn't one
 402         already.
 403
 404         The container is not added to the page automatically. This allows you to
 405         have full control over how and when your view is actually rendered to
 406         the page.
 407
 408         @attribute container
 409         @type HTMLElement|Node|String
 410         @default Y.Node.create(this.containerTemplate)
 411         @writeOnce
 412         **/
 413         container: {
 414             getter   : '_getContainer',
 415             setter   : Y.one,
 416             writeOnce: true
 417         }
 418     },
 419
 420     /**
 421     Properties that shouldn't be turned into ad-hoc attributes when passed to
 422     View's constructor.
 423
 424     @property _NON_ATTRS_CFG
 425     @type Array
 426     @static
 427     @protected
 428     @since 3.5.0
 429     **/
 430     _NON_ATTRS_CFG: [
 431         'containerTemplate',
 432         'events',
 433         'template'
 434     ]
 435 });
 436
 437
 438
 439 }, '3.7.2', {"requires": ["base-build", "node-event-delegate"]});