app-base.js revision 2ef8442ba77d2cc7c049bcedf368f1fbde01effc
0N/AThe App Framework provides simple MVC-like building blocks (models, model lists, 0N/Aviews, and URL-based routing) for writing single-page JavaScript applications. 0N/AProvides a top-level application component which manages navigation and views. 0N/A// TODO: Better handling of lifecycle for registered views: 1054N/A// * Seems like any view created via `createView` should listen for the view's 0N/A// `destroy` event and use that to remove it from the `_viewsInfoMap`. I 0N/A// should look at what ModelList does for Models as a reference. 125N/A// * Should we have a companion `destroyView()` method? Maybe this wouldn't be 125N/A// needed if we have a `getView(name, create)` method, and already doing the 58N/A// above? We could do `app.getView('foo').destroy()` and it would be removed 77N/A// from the `_viewsInfoMap` as well. 312N/AProvides a top-level application component which manages navigation and views. 428N/AThis gives you a foundation and structure on which to build your application; it 126N/Acombines robust URL navigation with powerful routing and flexible view 8N/A@param {Object} [config] The following are configuration properties that can be 77N/A specified _in addition_ to default attribute values and the non-attribute 0N/A properties provided by `Y.Base`: 0N/A @param {Object} [config.views] Hash of view-name to metadata used to 0N/A declaratively describe an application's views and their relationship with 0N/A the app and other views. The views specified here will override any defaults 0N/A provided by the `views` object on the `prototype`. 491N/A // -- Public Properties ---------------------------------------------------- 886N/A Hash of view-name to metadata used to declaratively describe an 886N/A application's views and their relationship with the app and its other views. 886N/A The view metadata is composed of Objects keyed to a view-name that can have 491N/A any or all of the following properties: 491N/A * `type`: Function or a string representing the view constructor to use to 491N/A create view instances. If a string is used, the constructor function is 65N/A assumed to be on the `Y` object; e.g. `"SomeView"` -> `Y.SomeView`. 65N/A * `preserve`: Boolean for whether the view instance should be retained. By 65N/A default, the view instance will be destroyed when it is no longer the 464N/A `activeView`. If `true` the view instance will simply be `removed()` 0N/A from the DOM when it is no longer active. This is useful when the view 58N/A is frequently used and may be expensive to re-create. 312N/A * `parent`: String to another named view in this hash that represents the 260N/A parent view within the application's view hierarchy; e.g. a `"photo"` 428N/A relationship is a useful cue for things like transitions. 376N/A * `instance`: Used internally to manage the current instance of this named 0N/A view. This can be used if your view instance is created up-front, or if 11N/A you would rather manage the View lifecycle, but you probably should just 0N/A let this be handled for you. 1016N/A If `views` are specified at instantiation time, the metadata in the `views` 58N/A Object here will be used as defaults when creating the instance's `views`. 58N/A Every `Y.App` instance gets its own copy of a `views` object so this Object 58N/A on the prototype will not be polluted. 207N/A // Imagine that `Y.UsersView` and `Y.UserView` have been defined. 111N/A // -- Protected Properties ------------------------------------------------- 111N/A Map of view instance id (via `Y.stamp()`) to view-info object in `views`. 491N/A This mapping is used to tie a specific view instance back to its metadata by 1088N/A adding a reference to the the related view info on the `views` object. 491N/A // -- Lifecycle Methods ---------------------------------------------------- 491N/A // Merges-in specified view metadata into local `views` object. 491N/A // First, each view in the `views` prototype object gets its metadata 491N/A // merged-in, providing the defaults. 491N/A // Then, each view in the specified `config.views` object gets its 491N/A // The resulting hodgepodge of metadata is then stored as the instance's 491N/A // `views` object, and no one's objects were harmed in the making. 491N/A // PjaxBase will bind click events when `html5` is `true`, so this just 491N/A // forces the binding when `serverRouting` and `html5` are both falsy. 491N/A // TODO: `destructor` to destory the `activeView`? 491N/A // -- Public Methods ------------------------------------------------------- 491N/A Creates and returns this apps's container node from the specified selector 491N/A string, DOM element, or existing `Y.Node` instance. This method is called 491N/A internally when the app is initialized. 491N/A This node is also stamped with the CSS class specified by 491N/A `Y.App.Base.CSS_CLASS`. 1016N/A By default, the created node is _not_ added to the DOM automatically. 491N/A @param {String|Node|HTMLElement} container Selector string, `Y.Node` 491N/A instance, or DOM element to use as the container node. 491N/A @return {Node} Node instance of the created container node. 1088N/A Creates and returns a new view instance using the provided `name` to look up 799N/A the view info metadata defined in the `views` object. The passed-in `config` 886N/A object is passed to the view constructor function. 886N/A This function also maps a view instance back to its view info metadata. 891N/A @param {String} name The name of a view defined on the `views` object. 886N/A @param {Object} [config] The configuration object passed to the view 891N/A constructor function when creating the new view instance. 886N/A @return {View} The new view instance. 491N/A // Create the view instance and map it with its metadata. 491N/A Creates and returns this app's view-container node from the specified 491N/A selector string, DOM element, or existing `Y.Node` instance. This method is 491N/A called internally when the app is initialized. 491N/A This node is also stamped with the CSS class specified by 1088N/A `Y.App.Base.VIEWS_CSS_CLASS`. 1088N/A By default, the created node will appended to the `container` node by the 491N/A @method createViewContainer 491N/A @param {String|Node|HTMLElement} viewContainer Selector string, `Y.Node` 491N/A instance, or DOM element to use as the view-container node. 491N/A @return {Node} Node instance of the created view-container node. 1088N/A Returns the metadata associated with a view instance or view name defined on 1115N/A @param {View|String} view View instance, or name of a view defined on the 77N/A @return {Object} The metadata for the view, or `undefined` if the view is 1106N/A Navigates to the specified URL if there is a route handler that matches. In 1106N/A browsers capable of using HTML5 history or when `serverRouting` is falsy, 1106N/A the navigation will be enhanced by firing the `navigate` event and having 1106N/A the app handle the "request". When `serverRouting` is `true`, non-HTML5 1106N/A browsers will navigate to the new URL via a full page reload. 1106N/A When there is a route handler for the specified URL and it is being 1106N/A navigated to, this method will return `true`, otherwise it will return 1106N/A **Note:** The specified URL _must_ be of the same origin as the current URL, 490N/A otherwise an error will be logged and navigation will not occur. This is 1106N/A intended as both a security constraint and a purposely imposed limitation as 491N/A it does not make sense to tell the app to navigate to a URL on a 1088N/A different scheme, host, or port. 1088N/A @param {String} url The fully-resolved URL that the app should dispatch to 1026N/A its route handlers to fulfill the enhanced navigation "request", or use to 491N/A update `window.location` in non-HTML5 history capable browsers when 491N/A `serverRouting` is `true`. 491N/A @param {Object} [options] Additional options to configure the navigation. 491N/A These are mixed into the `navigate` event facade. 491N/A @param {Boolean} [options.replace] Whether or not the current history 1088N/A entry will be replaced, or a new entry will be created. Will default 491N/A to `true` if the specified `url` is the same as the current URL. 1088N/A @param {Boolean} [options.force] Whether the enhanced navigation 491N/A should occur even in browsers without HTML5 history. Will default to 491N/A `true` when `serverRouting` is falsy. 491N/A @see PjaxBase.navigate() 491N/A Renders this application by appending the `viewContainer` node to the 491N/A `container` node if it isn't already a child of the container, and the 1088N/A `activeView` will be appended the view container, if it isn't already. 491N/A You should call this method at least once, usually after the initialization 491N/A of your app instance so the proper DOM structure is setup and optionally 491N/A append the container to the DOM if it's not there already. 99N/A You may override this method to customize the app's rendering, but you 491N/A should expect that the `viewContainer`'s contents will be modified by the 491N/A app for the purpose of rendering the `activeView` when it changes. 491N/A app's `activeView` attribute to the specified `view`. 491N/A When a string-name is provided for a view which has been registered on this 491N/A app's `views` object, the referenced metadata will be used and the 491N/A `activeView` will be set to either a preserved view instance, or a new 491N/A instance of the registered view will be created using the specified `config` 491N/A object passed-into this method. 491N/A A callback function can be specified as either the third or fourth argument, 491N/A and this function will be called after the new `view` becomes the 491N/A `activeView`, is rendered to the `viewContainer`, and is ready to use. 491N/A // Imagine that `Y.UsersView` has been defined. 491N/A app.route('/users/', function () { 491N/A this.showView('users'); 491N/A app.navigate('/uses/'); // => Creates a new `Y.UsersView` and shows it. 1088N/A @param {String|View} view The name of a view defined in the `views` object, 994N/A @param {Object} [config] Optional configuration to use when creating a new 994N/A @param {Object} [options] Optional object containing any of the following 491N/A @param {Boolean} [options.prepend] Whether the new view should be 491N/A prepended instead of appended to the `viewContainer`. 1088N/A @param {Function} [callback] Optional callback Function to call after the 491N/A new `activeView` is ready to use, the function will be passed: 1088N/A @param {View} callback.view A reference to the new `activeView`. 1100N/A // Use the preserved view instance, or create a new view. 1100N/A // TODO: Maybe we can remove the strict check for `preserve` and 1100N/A // assume we'll use a View instance if it is there, and just check 1100N/A // `preserve` when detaching? 491N/A // Make sure there's a mapping back to the view metadata. 491N/A // TODO: Add `options.update` to update to view with the `config`, if 491N/A // needed. This could also call `setAttrs()` when the specified `view` 261N/A // already a View instance. Is this be too much overloading of the API? 0N/A // TODO: Add `options.render` to provide a way to control whether a view 77N/A // is rendered or not; by default, `render()` will only be called if 77N/A // this method created the View. 1062N/A // TODO: Should the `callback` _always_ be called, even when the 1064N/A // `activeView` does not change? 886N/A // -- Protected Methods ---------------------------------------------------- 886N/A Helper method to attach the view instance to the application by making the 886N/A app a bubble target of the view, append the view to the `viewContainer`, and 886N/A assign it to the `instance` property of the associated view info metadata. 886N/A @param {View} view View to attach. 1088N/A @param {Boolean} prepend Whether the view should be prepended instead of 886N/A appended to the `viewContainer`. 1090N/A // TODO: Attach events here for persevered Views? 1090N/A // See related TODO in `_detachView`. 1017N/A // Insert view into the DOM. 1017N/A Overrides View's container destruction to deal with the `viewContainer` and 1017N/A checks to make sure not to remove and purge the `<body>`. 312N/A // We do not want to remove or destroy the `<body>`. 491N/A // Just clean-up our events listeners. 491N/A // Clean-up `yui3-app` CSS class on the `container`. 491N/A // Clean-up `yui3-app-views` CSS class on the `container`. 491N/A // Destroy and purge the `viewContainer`. 491N/A // Remove and purge events from both containers. 491N/A Helper method to detach the view instance from the application by removing 491N/A the application as a bubble target of the view, and either just removing the 491N/A view if it is intended to be preserved, or destroying the instance 491N/A @param {View} view View to detach. 491N/A // TODO: Detach events here for preserved Views? It is possible that 491N/A // some event subscriptions are made on elements other than the 1054N/A // TODO: The following should probably happen automagically from 491N/A // `destroy()` being called! Possibly `removeTarget()` as well. 1054N/A // Remove from view to view-info map. 491N/A // Remove from view-info instance property. 1092N/A Provides the default value for the `html5` attribute. 491N/A The value returned is dependent on the value of the `serverRouting` 1092N/A attribute. When `serverRouting` is explicit set to `false` (not just falsy), 1092N/A the default value for `html5` will be set to `false` for *all* browsers. 1092N/A When `serverRouting` is `true` or `undefined` the returned value will be 1092N/A dependent on the browser's capability of using HTML5 history. 1092N/A @return {Boolean} Whether or not HTML5 history should be used. 1092N/A // When `serverRouting` is explicitly set to `false` (not just falsy), 1092N/A // forcing hash-based URLs in all browsers. 491N/A if (
this.
get(
'serverRouting') ===
false) {
491N/A Determines if the specified `view` is configured as a child of the specified 491N/A `parent` view. This requires both views to be either named-views, or view 1054N/A instances created using configuration data that exists in the `views` 491N/A object, e.g. created by the `createView()` or `showView()` method. 312N/A @param {View|String} view The name of a view defined in the `views` object, 491N/A @param {View|String} parent The name of a view defined in the `views` 491N/A object, or a view instance. 491N/A @return {Boolean} Whether the view is configured as a child of the parent. 491N/A Determines if the specified `view` is configured as the parent of the 77N/A specified `child` view. This requires both views to be either named-views, 1054N/A or view instances created using configuration data that exists in the 1054N/A `views` object, e.g. created by the `createView()` or `showView()` method. 491N/A @param {View|String} view The name of a view defined in the `views` object, 491N/A @param {View|String} parent The name of a view defined in the `views` 1062N/A object, or a view instance. 491N/A @return {Boolean} Whether the view is configured as the parent of the child. 491N/A Underlying implementation for `navigate()`. 491N/A @param {String} url The fully-resolved URL that the app should dispatch to 491N/A its route handlers to fulfill the enhanced navigation "request", or use to 491N/A update `window.location` in non-HTML5 history capable browsers when 491N/A `serverRouting` is `true`. 1062N/A @param {Object} [options] Additional options to configure the navigation. 491N/A These are mixed into the `navigate` event facade. 491N/A @param {Boolean} [options.replace] Whether or not the current history 491N/A entry will be replaced, or a new entry will be created. Will default 491N/A to `true` if the specified `url` is the same as the current URL. 491N/A @param {Boolean} [options.force] Whether the enhanced navigation 491N/A should occur even in browsers without HTML5 history. Will default to 491N/A `true` when `serverRouting` is falsy. 491N/A @see PjaxBase._navigate() 491N/A // Force navigation to be enhanced and handled by the app when 491N/A // `serverRouting` is falsy because the server might not be able to 491N/A // properly handle the request. 491N/A // Determine if the current history entry should be replaced. Since 99N/A // we've upgraded a hash-based URL to a full-path URL, we'll do the 491N/A // same for the current URL before comparing the two. 1054N/A Will either save a history entry using `pushState()` or the location hash, 99N/A or gracefully-degrade to sending a request to the server causing a full-page 58N/A Overrides Router's `_save()` method to preform graceful-degradation when the 491N/A app's `serverRouting` is `true` and `html5` is `false` by updating the full 491N/A URL via standard assignment to `window.location` or by calling 491N/A `window.location.replace()`; both of which will cause a request to the 491N/A server resulting in a full-page reload. 1054N/A Otherwise this will just delegate off to Router's `_save()` method allowing 491N/A the client-side enhanced routing to occur. 491N/A @param {String} [url] URL for the history entry. 491N/A @param {Boolean} [replace=false] If `true`, the current history entry will 491N/A be replaced instead of a new one being added. 508N/A // Forces full-path URLs to always be used by modifying 508N/A // `window.location` in non-HTML5 history capable browsers. 274N/A // Perform same-origin check on the specified URL. 491N/A Y.
error(
'Security error: The new URL must be of the same origin as the current URL.');
491N/A // Results in the URL's full path starting with '/'. 930N/A // Either replace the current history entry or create a new one 930N/A // while navigating to the `url`. 491N/A Performs the actual change of the app's `activeView` by attaching the 491N/A `newView` to this app, and detaching the `oldView` from this app using any 491N/A The `newView` is attached to the app by rendering it to the `viewContainer`, 1054N/A and making this app a bubble target of its events. 1054N/A The `oldView` is detached from the app by removing it from the 1054N/A `viewContainer`, and removing this app as a bubble target for its events. 491N/A The `oldView` will either be preserved or properly destroyed. 491N/A The `activeView` attribute is read-only and can be changed by calling the 0N/A `showView()` method. 260N/A @method _uiSetActiveView 260N/A @param {View} newView The View which is now this app's `activeView`. 0N/A @param {View} [oldView] The View which was this app's `activeView`. @param {Object} [options] Optional object containing any of the following @param {Boolean} [options.prepend] Whether the new view should be prepended instead of appended to the `viewContainer`. @param {Function} [callback] Optional callback Function to call after the `newView` is ready to use, the function will be passed: @param {View} options.callback.view A reference to the `newView`. // Prevent detaching (thus removing) the view we want to show. // Also hard to animate out and in, the same view. Upgrades a hash-based URL to a full-path URL, if necessary. The specified `url` will be upgraded if its of the same origin as the current URL and has a path-like hash. URLs that don't need upgrading will be @param {String} url The URL to upgrade from hash-based to full-path. @return {String} The upgraded URL, or the specified URL untouched. // We should not try to upgrade paths for external URLs. // TODO: Should the `root` be removed first, and the hash only // considered if in the form of '/#/'? // Strip any hash prefix, like hash-bangs. // If the hash looks like a URL path, assume it is, and upgrade it! // Re-join with configured `root` before resolving. // -- Protected Event Handlers --------------------------------------------- Handles the application's `activeViewChange` event (which is fired when the `activeView` attribute changes) by detaching the old view, attaching the new The `activeView` attribute is read-only, so the public API to change its value is through the `showView()` method. @method _afterActiveViewChange This attribute is read-only, to set the `activeView` use the Container node which represents the application's bounding-box, into which this app's content will be rendered. The container node serves as the host for all DOM events attached by the app. Delegation is used to handle events on children of the container, allowing the container's contents to be re-rendered at any time without losing event subscriptions. The default container is the `<body>` Node, but you can override this in a subclass, or by passing in a custom `container` config value at When `container` is overridden by a subclass or passed as a config option at instantiation time, it may be provided as a selector string, a DOM element, or a `Y.Node` instance. During initialization, this app's `create()` method will be called to convert the container into a `Y.Node` instance if it isn't one already and stamp it with the CSS The container is not added to the page automatically. This allows you to have full control over how and when your app is actually rendered to @type HTMLElement|Node|String Whether or not this browser is capable of using HTML5 history. This value is dependent on the value of `serverRouting` and will default Setting this to `false` will force the use of hash-based history even on HTML5 browsers, but please don't do this unless you understand the CSS selector string used to filter link click events so that only the links which match it will have the enhanced-navigation behavior of pjax When a link is clicked and that link matches this selector, navigating to the link's `href` URL using the enhanced, pjax, behavior will be attempted; and the browser's default way to navigate to new pages will By default this selector will match _all_ links on the page. Whether or not this application's server is capable of properly routing all requests and rendering the initial state in the HTML responses. This can have three different values, each having particular implications on how the app will handle routing and navigation: * `undefined`: The best form of URLs will be chosen based on the capabilities of the browser. Given no information about the server environmentm a balanced approach to routing and navigation is The server should be capable of handling full-path requests, since full-URLs will be generated by browsers using HTML5 history. If this is a client-side-only app the server could handle full-URL requests by sending a redirect back to the root with a hash-based URL, e.g: * `true`: The server is *fully* capable of properly handling requests to all full-path URLs the app can produce. This is the best option for progressive-enhancement because it will cause **all URLs to always have full-paths**, which means the server will be able to accurately handle all URLs this app produces. e.g. To meet this strict full-URL requirement, browsers which are not capable of using HTML5 history will make requests to the server resulting in full-page reloads. * `false`: The server is *not* capable of properly handling requests to all full-path URLs the app can produce, therefore all routing will be handled by this App instance. Be aware that this will cause **all URLs to always be hash-based**, even in browsers that are capable of using HTML5 history. e.g. A single-page or client-side-only app where the server sends a "shell" page with JavaScript to the client might have this restriction. If you're setting this to `false`, read the following: **Note:** When this is set to `false`, the server will *never* receive the full URL because browsers do not send the fragment-part to the server, that is everything after and including the '#'. Consider the following example: You should feel bad about hurting our precious web if you forcefully set either `serverRouting` or `html5` to `false`, because you're basically punching the web in the face here with your lossy URLs! Please make sure you know what you're doing and that you understand the implications. Ideally you should always prefer full-path URLs (not /#/foo/), and want full-page reloads when the client's browser is not capable of enhancing the experience using the HTML5 history APIs. Setting this to `true` is the best option for progressive-enhancement (and graceful-degradation). The node into which this app's `views` will be rendered when they become The view container node serves as the container to hold the app's `activeView`. Each time the `activeView` is set via `showView()`, the previous view will be removed from this node, and the new active view's `container` node will be appended. The default view container is `<div>` Node, but you can override this in a subclass, or by passing in a custom `viewContainer` config value at When `viewContainer` is overridden by a subclass or passed as a config option at instantiation time, it may be provided as a selector string, DOM element, or a `Y.Node` instance (having the `viewContainer` and the `container` be the same node is also supported). During initialization, the app's `createViewContainer()` method will be called to convert the view container into a `Y.Node` instance if it isn't one already and stamp it with the CSS class: `"yui3-app-views"`. The app's `render()` method will append the view container to the app's `container` node if it isn't already, and any `activeView` will be appended to this node if it isn't already. @type HTMLElement|Node|String @default `Y.Node.create("<div/>")` setter :
'createViewContainer',
// -- Namespace ---------------------------------------------------------------- Provides a top-level application component which manages navigation and views. This gives you a foundation and structure on which to build your application; it combines robust URL navigation with powerful routing and flexible view `Y.App` is both a namespace and constructor function. The `Y.App` class is special in that any `Y.App` class extensions that are included in the YUI instance will be **auto-mixed** on to the `Y.App` class. Consider this example: YUI().use('app-base', 'app-transitions', function (Y) { // This will create two YUI Apps, `basicApp` will not have transitions, // but `fancyApp` will have transitions support included and turn it on. var basicApp = new Y.App.Base(), fancyApp = new Y.App({transitions: true}); @param {Object} [config] The following are configuration properties that can be specified _in addition_ to default attribute values and the non-attribute properties provided by `Y.Base`: @param {Object} [config.views] Hash of view-name to metadata used to declaratively describe an application's views and their relationship with the app and other views. The views specified here will override any defaults provided by the `views` object on the `prototype`. },
'@VERSION@' ,{
requires:[
'classnamemanager',
'pjax-base',
'router',
'view']});