lib/yuilib/3.13.0/view/view.js

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