lib/yuilib/3.7.2/build/app-content/app-content.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('app-content', function (Y, NAME) {
   8
   9 /**
  10 `Y.App` extension that provides pjax-style content fetching and handling.
  11
  12 @module app
  13 @submodule app-content
  14 @since 3.7.0
  15 **/
  16
  17 var PjaxContent = Y.PjaxContent;
  18
  19 /**
  20 `Y.App` extension that provides pjax-style content fetching and handling.
  21
  22 This makes it easy to fetch server rendered content for URLs using Ajax. The
  23 HTML content returned from the server will be view-ified and set as the app's
  24 main content, making it seamless to use a mixture of server and client rendered
  25 views.
  26
  27 When the `"app-content"` module is used, it will automatically mix itself into
  28 `Y.App`, and it provides three main features:
  29
  30   - **`Y.App.Content.route`**: A stack of middleware which forms a pjax-style
  31     content route.
  32
  33   - **`loadContent()`**: Route middleware which load content from a server. This
  34     makes an Ajax request for the requested URL, parses the returned content and
  35     puts it on the route's response object.
  36
  37   - **`showContent()`**: Method which provides an easy way to view-ify HTML
  38     content which should be shown as an app's active/visible view.
  39
  40 The following is an example of how these features can be used:
  41
  42     // Creates a new app and registers the `"post"` view.
  43     var app = new Y.App({
  44         views: {
  45             post: {type: Y.PostView}
  46         }
  47     });
  48
  49     // Uses a simple server rendered content route for the About page.
  50     app.route('/about/', Y.App.Content.route);
  51
  52     // Uses the `loadContent()` middleware to fetch the contents of the post
  53     // from the server and shows that content in a `"post"` view.
  54     app.route('/posts/:id/', 'loadContent', function (req, res, next) {
  55         this.showContent(res.content.node, {view: 'post'});
  56     });
  57
  58 @class App.Content
  59 @uses PjaxContent
  60 @extensionfor App
  61 @since 3.7.0
  62 **/
  63 function AppContent() {
  64     PjaxContent.apply(this, arguments);
  65 }
  66
  67 /**
  68 A stack of middleware which forms a pjax-style content route.
  69
  70 This route will load the rendered HTML content from the server, then create and
  71 show a new view using those contents.
  72
  73 @property route
  74 @type Array
  75 @static
  76 @since 3.7.0
  77 **/
  78 AppContent.route = ['loadContent', '_contentRoute'];
  79
  80 AppContent.prototype = {
  81     // -- Public Methods -------------------------------------------------------
  82
  83     /**
  84     Sets this app's `activeView` attribute using the specified `content`.
  85
  86     This provides an easy way to view-ify HTML content which should be shown as
  87     this app's active/visible view. This method will determine the appropriate
  88     view `container` node based on the specified `content`. By default, a new
  89     `Y.View` instance will be created unless `options.view` is specified.
  90
  91     Under the hood, this method calls the `showView()` method, so refer to its
  92     docs for more information.
  93
  94     @method showContent
  95     @param {HTMLElement|Node|String} content The content to show, it may be
  96         provided as a selector string, a DOM element, or a `Y.Node` instance.
  97     @param {Object} [options] Optional objects containing any of the following
  98         properties in addition to any `showView()` options:
  99
 100       @param {Object|String} [options.view] The name of a view defined in this
 101           app's `views`, or an object with the following properties:
 102
 103         @param {String} options.view.name The name of a view defined in this
 104             app's `views`.
 105         @param {Object} [options.view.config] Optional configuration to use when
 106             creating the new view instance. This config object can also be used
 107             to update an existing or preserved view's attributes when
 108             `options.update` is `true`. **Note:** If a `container` is specified,
 109             it will be overridden by the `content` specified in the first
 110             argument.
 111
 112     @param {Function} [callback] Optional callback function to call after the
 113         new `activeView` is ready to use. **Note:** this will override
 114         `options.callback` and it can be specified as either the second or third
 115         argument. The function will be passed the following:
 116
 117       @param {View} callback.view A reference to the new `activeView`.
 118
 119     @since 3.7.0
 120     @see App.showView()
 121     **/
 122     showContent: function (content, options, callback) {
 123         // Makes sure we have a node instance, and will query selector strings.
 124         content = Y.one(content);
 125
 126         // Support the callback function being either the second or third arg.
 127         if (typeof options === 'function') {
 128             options  = {callback: options};
 129             callback = null;
 130         }
 131
 132         // Mix in default option to *not* render the view because presumably we
 133         // have pre-rendered content here. This also creates a copy so we can
 134         // modify the object.
 135         options = Y.merge({render: false}, options);
 136
 137         var view       = options.view || '',
 138             viewName   = typeof view === 'string' ? view : view.name,
 139             viewConfig = typeof view !== 'string' ? view.config : {},
 140             viewInfo   = this.getViewInfo(viewName),
 141             container, template, type, ViewConstructor;
 142
 143         // Remove `view` from the `options` which will be passed along to the
 144         // `showView()` method.
 145         delete options.view;
 146
 147         // When the specified `content` is a document fragment, we want to see
 148         // if it only contains a single node, and use that as the content. This
 149         // checks `childNodes` which will include text nodes.
 150         if (content && content.isFragment() &&
 151                 content.get('childNodes').size() === 1) {
 152
 153             content = content.get('firstChild');
 154         }
 155
 156         // When the `content` is an element node (`nodeType` 1), we can use it
 157         // as-is for the `container`. Otherwise, we'll construct a new container
 158         // based on the `options.view`'s `containerTemplate`.
 159         if (content && content.get('nodeType') === 1) {
 160             container = content;
 161         } else {
 162             type = (viewInfo && viewInfo.type) || Y.View;
 163
 164             // Looks for a namespaced constructor function on `Y`.
 165             ViewConstructor = typeof type === 'string' ?
 166                     Y.Object.getValue(Y, type.split('.')) : type;
 167
 168             // Find the correct node template for the view.
 169             template  = ViewConstructor.prototype.containerTemplate;
 170             container = Y.Node.create(template);
 171
 172             // Append the document fragment to the newly created `container`
 173             // node. This is the worst case where we have to create a wrapper
 174             // node around the `content`.
 175             container.append(content);
 176         }
 177
 178         // Makes sure the view is created using _our_ `container` node.
 179         viewConfig = Y.merge(viewConfig, {container: container});
 180
 181         // Finally switch to the new `activeView`. We want to make sure `view`
 182         // is a string if it's falsy, that way a new view will be created.
 183         return this.showView(viewName, viewConfig, options, callback);
 184     },
 185
 186     // -- Protected Methods ----------------------------------------------------
 187
 188     /**
 189     Provides a default content route which will show a server rendered view.
 190
 191     **Note:** This route callback assumes that it's called after the
 192     `loadContent()` middleware.
 193
 194     @method _contentRoute
 195     @param {Object} req Request object.
 196     @param {Object} res Response Object.
 197     @param {Function} next Function to pass control to the next route callback.
 198     @protected
 199     @since 3.7.0
 200     @see Y.App.Content.route
 201     **/
 202     _contentRoute: function (req, res, next) {
 203         var content = res.content,
 204             doc     = Y.config.doc,
 205             activeViewHandle;
 206
 207         // We must have some content to work with.
 208         if (!(content && content.node)) { return next(); }
 209
 210         if (content.title && doc) {
 211             // Make sure the `activeView` does actually change before we go
 212             // messing with the page title.
 213             activeViewHandle = this.onceAfter('activeViewChange', function () {
 214                 doc.title = content.title;
 215             });
 216         }
 217
 218         this.showContent(content.node);
 219
 220         // Detach the handle just in case.
 221         if (activeViewHandle) {
 222             activeViewHandle.detach();
 223         }
 224
 225         next();
 226     }
 227 };
 228
 229 // Mix statics.
 230 Y.mix(AppContent, PjaxContent);
 231 // Mix prototype.
 232 Y.mix(AppContent, PjaxContent, false, null, 1);
 233
 234 // -- Namespace ----------------------------------------------------------------
 235 Y.App.Content = AppContent;
 236 Y.Base.mix(Y.App, [AppContent]);
 237
 238
 239 }, '3.7.2', {"requires": ["app-base", "pjax-content"]});