[Summary view] [Print] [Text view]

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