App.Content Class
Y.App extension that provides pjax-style content fetching and handling.
This makes it easy to fetch server rendered content for URLs using Ajax. The HTML content returned from the server will be view-ified and set as the app's main content, making it seamless to use a mixture of server and client rendered views.
When the "app-content" module is used, it will automatically mix itself into
Y.App, and it provides three main features:
Y.App.Content.route: A stack of middleware which forms a pjax-style content route.loadContent(): Route middleware which load content from a server. This makes an Ajax request for the requested URL, parses the returned content and puts it on the route's response object.showContent(): Method which provides an easy way to view-ify HTML content which should be shown as an app's active/visible view.
The following is an example of how these features can be used:
// Creates a new app and registers the "post" view.
var app = new Y.App({
views: {
post: {type: Y.PostView}
}
});
// Uses a simple server rendered content route for the About page.
app.route('/about/', Y.App.Content.route);
// Uses the loadContent() middleware to fetch the contents of the post
// from the server and shows that content in a "post" view.
app.route('/posts/:id/', 'loadContent', function (req, res, next) {
this.showContent(res.content.node, {view: 'post'});
});
Methods
_contentRoute
-
req -
res -
next
Provides a default content route which will show a server rendered view.
Note: This route callback assumes that it's called after the
loadContent() middleware.
_onPjaxIOComplete
-
id -
ioResponse -
details
Handles IO complete events.
This parses the content from the Y.io() response and puts it on the
route's response object.
_onPjaxIOEnd
-
id -
details
Handles IO end events.
getContent
-
responseText
Extracts and returns the relevant HTML content from an Ajax response. The
content is extracted using the contentSelector attribute as a CSS
selector. If contentSelector is null, the entire response will be
returned.
The return value is an object containing two properties:
node: AY.Nodeinstance for a document fragment containing the extracted HTML content.title: The title of the HTML page, if any, extracted using thetitleSelectorattribute (which defaults to looking for a<title>element). IftitleSelectoris not set or if a title could not be found, this property will beundefined.
Parameters:
-
responseTextStringRaw Ajax response text.
Returns:
loadContent
-
req -
res -
next
Pjax route middleware to load content from a server. This makes an Ajax request for the requested URL, parses the returned content and puts it on the route's response object.
This is route middleware and not intended to be the final callback for a route. This will add the following information to the route's request and response objects:
req.ioURL: The full URL that was used to make theY.io()XHR. This may contain"pjax=1"if theaddPjaxParamoption is set.res.content: An object containingnodeandtitleproperties for the content extracted from the server's response. SeegetContent()for more details.res.ioResponse: The fullY.io()response object. This is useful if you need access to the XHR's responsestatusor HTTP headers.
Parameters:
Example:
router.route('/foo/', 'loadContent', function (req, res, next) {
Y.one('container').setHTML(res.content.node);
Y.config.doc.title = res.content.title;
});
showContent
-
content -
[options] -
[callback]
Sets this app's activeView attribute using the specified content.
This provides an easy way to view-ify HTML content which should be shown as
this app's active/visible view. This method will determine the appropriate
view container node based on the specified content. By default, a new
Y.View instance will be created unless options.view is specified.
Under the hood, this method calls the showView() method, so refer to its
docs for more information.
Parameters:
-
contentHTMLElement | Node | StringThe content to show, it may be provided as a selector string, a DOM element, or a
Y.Nodeinstance. -
[options]Object optionalOptional objects containing any of the following properties in addition to any
showView()options:-
[view]Object | String optionalThe name of a view defined in this app's
views, or an object with the following properties:-
nameStringThe name of a view defined in this app'sviews. -
[config]Object optionalOptional configuration to use when creating the new view instance. This config object can also be used to update an existing or preserved view's attributes whenoptions.updateistrue. **Note:** If acontaineris specified, it will be overridden by thecontentspecified in the first argument.
-
-
-
[callback]Function optionalOptional callback function to call after the new
activeViewis ready to use. Note: this will overrideoptions.callbackand it can be specified as either the second or third argument. The function will be passed the following:-
viewViewA reference to the new
activeView.
-
Properties
route
Array
static
A stack of middleware which forms a pjax-style content route.
This route will load the rendered HTML content from the server, then create and show a new view using those contents.
Attributes
addPjaxParam
Boolean
If true, a "pjax=1" query parameter will be appended to all URLs
requested via Pjax.
Browsers ignore HTTP request headers when caching content, so if the same URL is used to request a partial Pjax page and a full page, the browser will cache them under the same key and may later load the cached partial page when the user actually requests a full page (or vice versa).
To prevent this, we can add a bogus query parameter to the URL so that Pjax URLs will always be cached separately from non-Pjax URLs.
Default: true
Fires event addPjaxParamChange
Fires when the value for the configuration attribute addPjaxParam is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
contentSelector
String
CSS selector used to extract a specific portion of the content of a page loaded via Pjax.
For example, if you wanted to load the page example.html but only use
the content within an element with the id "pjax-content", you'd set
contentSelector to "#pjax-content".
If not set, the entire page will be used.
Default: null
Fires event contentSelectorChange
Fires when the value for the configuration attribute contentSelector is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
timeout
Number
Time in milliseconds after which an Ajax request should time out.
Default: 30000
Fires event timeoutChange
Fires when the value for the configuration attribute timeout is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
titleSelector
String
CSS selector used to extract a page title from the content of a page loaded via Pjax.
By default this is set to extract the title from the <title> element,
but you could customize it to extract the title from an <h1>, or from
any other element, if that's more appropriate for the content you're
loading.
Default: "title"
Fires event titleSelectorChange
Fires when the value for the configuration attribute titleSelector is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added: