/*

YUI 3.10.3 (build 2fb5187)

Copyright 2013 Yahoo! Inc. All rights reserved.

Licensed under the BSD License.

http://yuilibrary.com/license/

*/

YUI.add('app-base', function (Y, NAME) {

/**

The App Framework provides simple MVC-like building blocks (models, model lists,

views, and URL-based routing) for writing single-page JavaScript applications.

@main app

@module app

@since 3.4.0

**/

/**

Provides a top-level application component which manages navigation and views.

@module app

@submodule app-base

@since 3.5.0

**/

// TODO: Better handling of lifecycle for registered views:

//

//   * [!] Just redo basically everything with view management so there are no

//     pre-`activeViewChange` side effects and handle the rest of these things:

//

//   * Seems like any view created via `createView` should listen for the view's

//     `destroy` event and use that to remove it from the `_viewsInfoMap`. I

//     should look at what ModelList does for Models as a reference.

//

//   * Should we have a companion `destroyView()` method? Maybe this wouldn't be

//     needed if we have a `getView(name, create)` method, and already doing the

//     above? We could do `app.getView('foo').destroy()` and it would be removed

//     from the `_viewsInfoMap` as well.

//

//   * Should we wait to call a view's `render()` method inside of the

//     `_attachView()` method?

//

//   * Should named views support a collection of instances instead of just one?

//

var Lang    = Y.Lang,

    YObject = Y.Object,

    PjaxBase = Y.PjaxBase,

    Router   = Y.Router,

    View     = Y.View,

    getClassName = Y.ClassNameManager.getClassName,

    win = Y.config.win,

    AppBase;

/**

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

management.

@class App.Base

@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`.

@constructor

@extends Base

@uses View

@uses Router

@uses PjaxBase

@since 3.5.0

**/

AppBase = Y.Base.create('app', Y.Base, [View, Router, PjaxBase], {

    // -- Public Properties ----------------------------------------------------

    /**

    Hash of view-name to metadata used to declaratively describe an

    application's views and their relationship with the app and its other views.

    The view metadata is composed of Objects keyed to a view-name that can have

    any or all of the following properties:

      * `type`: Function or a string representing the view constructor to use to

        create view instances. If a string is used, the constructor function is

        assumed to be on the `Y` object; e.g. `"SomeView"` -> `Y.SomeView`.

      * `preserve`: Boolean for whether the view instance should be retained. By

        default, the view instance will be destroyed when it is no longer the

        `activeView`. If `true` the view instance will simply be `removed()`

        from the DOM when it is no longer active. This is useful when the view

        is frequently used and may be expensive to re-create.

      * `parent`: String to another named view in this hash that represents the

        parent view within the application's view hierarchy; e.g. a `"photo"`

        view could have `"album"` has its `parent` view. This parent/child

        relationship is a useful cue for things like transitions.

      * `instance`: Used internally to manage the current instance of this named

        view. This can be used if your view instance is created up-front, or if

        you would rather manage the View lifecycle, but you probably should just

        let this be handled for you.

    If `views` are specified at instantiation time, the metadata in the `views`

    Object here will be used as defaults when creating the instance's `views`.

    Every `Y.App` instance gets its own copy of a `views` object so this Object

    on the prototype will not be polluted.

    @example

        // Imagine that `Y.UsersView` and `Y.UserView` have been defined.

        var app = new Y.App({

            views: {

                users: {

                    type    : Y.UsersView,

                    preserve: true

                },

                user: {

                    type  : Y.UserView,

                    parent: 'users'

                }

            }

        });

    @property views

    @type Object

    @default {}

    @since 3.5.0

    **/

    views: {},

    // -- Protected Properties -------------------------------------------------

    /**

    Map of view instance id (via `Y.stamp()`) to view-info object in `views`.

    This mapping is used to tie a specific view instance back to its metadata by

    adding a reference to the the related view info on the `views` object.

    @property _viewInfoMap

    @type Object

    @default {}

    @protected

    @since 3.5.0

    **/

    // -- Lifecycle Methods ----------------------------------------------------

    initializer: function (config) {

        config || (config = {});

        var views = {};

        // Merges-in specified view metadata into local `views` object.

        function mergeViewConfig(view, name) {

            views[name] = Y.merge(views[name], view);

        }

        // First, each view in the `views` prototype object gets its metadata

        // merged-in, providing the defaults.

        YObject.each(this.views, mergeViewConfig);

        // Then, each view in the specified `config.views` object gets its

        // metadata merged-in.

        YObject.each(config.views, mergeViewConfig);

        // The resulting hodgepodge of metadata is then stored as the instance's

        // `views` object, and no one's objects were harmed in the making.

        this.views        = views;

        this._viewInfoMap = {};

        // Using `bind()` to aid extensibility.

        this.after('activeViewChange', Y.bind('_afterActiveViewChange', this));

        // PjaxBase will bind click events when `html5` is `true`, so this just

        // forces the binding when `serverRouting` and `html5` are both falsy.

        if (!this.get('serverRouting')) {

            this._pjaxBindUI();

        }

    },

    // TODO: `destructor` to destroy the `activeView`?

    // -- Public Methods -------------------------------------------------------

    /**

    Creates and returns a new view instance using the provided `name` to look up

    the view info metadata defined in the `views` object. The passed-in `config`

    object is passed to the view constructor function.

    This function also maps a view instance back to its view info metadata.

    @method createView

    @param {String} name The name of a view defined on the `views` object.

    @param {Object} [config] The configuration object passed to the view

      constructor function when creating the new view instance.

    @return {View} The new view instance.

    @since 3.5.0

    **/

    createView: function (name, config) {

        var viewInfo = this.getViewInfo(name),

            type     = (viewInfo && viewInfo.type) || View,

            ViewConstructor, view;

        // Looks for a namespaced constructor function on `Y`.

        ViewConstructor = Lang.isString(type) ?

                YObject.getValue(Y, type.split('.')) : type;

        // Create the view instance and map it with its metadata.

        view = new ViewConstructor(config);

        this._viewInfoMap[Y.stamp(view, true)] = viewInfo;

        return view;

    },

    /**

    Returns the metadata associated with a view instance or view name defined on

    the `views` object.

    @method getViewInfo

    @param {View|String} view View instance, or name of a view defined on the

      `views` object.

    @return {Object} The metadata for the view, or `undefined` if the view is

      not registered.

    @since 3.5.0

    **/

    getViewInfo: function (view) {

        if (Lang.isString(view)) {

            return this.views[view];

        }

        return view && this._viewInfoMap[Y.stamp(view, true)];

    },

    /**

    Navigates to the specified URL if there is a route handler that matches. In

    browsers capable of using HTML5 history or when `serverRouting` is falsy,

    the navigation will be enhanced by firing the `navigate` event and having

    the app handle the "request". When `serverRouting` is `true`, non-HTML5

    browsers will navigate to the new URL via a full page reload.

    When there is a route handler for the specified URL and it is being

    navigated to, this method will return `true`, otherwise it will return

    `false`.

    **Note:** The specified URL _must_ be of the same origin as the current URL,

    otherwise an error will be logged and navigation will not occur. This is

    intended as both a security constraint and a purposely imposed limitation as

    it does not make sense to tell the app to navigate to a URL on a

    different scheme, host, or port.

    @method navigate

    @param {String} url The URL to navigate to. This must be of the same origin

      as the current URL.

    @param {Object} [options] Additional options to configure the navigation.

      These are mixed into the `navigate` event facade.

        @param {Boolean} [options.replace] Whether or not the current history

          entry will be replaced, or a new entry will be created. Will default

          to `true` if the specified `url` is the same as the current URL.

        @param {Boolean} [options.force] Whether the enhanced navigation

          should occur even in browsers without HTML5 history. Will default to

          `true` when `serverRouting` is falsy.

    @see PjaxBase.navigate()

    **/

    // Does not override `navigate()` but does use extra `options`.

    /**

    Renders this application by appending the `viewContainer` node to the

    `container` node if it isn't already a child of the container, and the

    `activeView` will be appended the view container, if it isn't already.

    You should call this method at least once, usually after the initialization

    of your app instance so the proper DOM structure is setup and optionally

    append the container to the DOM if it's not there already.

    You may override this method to customize the app's rendering, but you

    should expect that the `viewContainer`'s contents will be modified by the

    app for the purpose of rendering the `activeView` when it changes.

    @method render

    @chainable

    @see View.render()

    **/

    render: function () {

        var CLASS_NAMES         = Y.App.CLASS_NAMES,

            container           = this.get('container'),

            viewContainer       = this.get('viewContainer'),

            activeView          = this.get('activeView'),

            activeViewContainer = activeView && activeView.get('container'),

            areSame             = container.compareTo(viewContainer);

        container.addClass(CLASS_NAMES.app);

        viewContainer.addClass(CLASS_NAMES.views);

        // Prevents needless shuffling around of nodes and maintains DOM order.

        if (activeView && !viewContainer.contains(activeViewContainer)) {

            viewContainer.appendChild(activeViewContainer);

        }

        // Prevents needless shuffling around of nodes and maintains DOM order.

        if (!container.contains(viewContainer) && !areSame) {

            container.appendChild(viewContainer);

        }

        return this;

    },

    /**

    Sets which view is active/visible for the application. This will set the

    app's `activeView` attribute to the specified `view`.

    The `view` will be "attached" to this app, meaning it will be both rendered

    into this app's `viewContainer` node and all of its events will bubble to

    the app. The previous `activeView` will be "detached" from this app.

    When a string-name is provided for a view which has been registered on this

    app's `views` object, the referenced metadata will be used and the

    `activeView` will be set to either a preserved view instance, or a new

    instance of the registered view will be created using the specified `config`

    object passed-into this method.

    A callback function can be specified as either the third or fourth argument,

    and this function will be called after the new `view` becomes the

    `activeView`, is rendered to the `viewContainer`, and is ready to use.

    @example

        var app = new Y.App({

            views: {

                usersView: {

                    // Imagine that `Y.UsersView` has been defined.

                    type: Y.UsersView

                }

            },

            users: new Y.ModelList()

        });

        app.route('/users/', function () {

            this.showView('usersView', {users: this.get('users')});

        });

        app.render();

        app.navigate('/uses/'); // => Creates a new `Y.UsersView` and shows it.

    @method showView

    @param {String|View} view The name of a view defined in the `views` object,

        or a view instance which should become this app's `activeView`.

    @param {Object} [config] Optional configuration to use when creating a new

        view instance. This config object can also be used to update an existing

        or preserved view's attributes when `options.update` is `true`.

    @param {Object} [options] Optional object containing any of the following

        properties:

      @param {Function} [options.callback] Optional callback function to call

        after new `activeView` is ready to use, the function will be passed:

          @param {View} options.callback.view A reference to the new

            `activeView`.

      @param {Boolean} [options.prepend=false] Whether the `view` should be

        prepended instead of appended to the `viewContainer`.

      @param {Boolean} [options.render] Whether the `view` should be rendered.

        **Note:** If no value is specified, a view instance will only be

        rendered if it's newly created by this method.

      @param {Boolean} [options.update=false] Whether an existing view should

        have its attributes updated by passing the `config` object to its

        `setAttrs()` method. **Note:** This option does not have an effect if

        the `view` instance is created as a result of calling this method.

    @param {Function} [callback] Optional callback Function to call after the

        new `activeView` is ready to use. **Note:** this will override

        `options.callback` and it can be specified as either the third or fourth

        argument. The function will be passed the following:

      @param {View} callback.view A reference to the new `activeView`.

    @chainable

    @since 3.5.0

    **/

    showView: function (view, config, options, callback) {

        var viewInfo, created;

        options || (options = {});

        // Support the callback function being either the third or fourth arg.

        if (callback) {

            options = Y.merge(options, {callback: callback});

        } else if (Lang.isFunction(options)) {

            options = {callback: options};

        }

        if (Lang.isString(view)) {

            viewInfo = this.getViewInfo(view);

            // Use the preserved view instance, or create a new view.

            // TODO: Maybe we can remove the strict check for `preserve` and

            // assume we'll use a View instance if it is there, and just check

            // `preserve` when detaching?

            if (viewInfo && viewInfo.preserve && viewInfo.instance) {

                view = viewInfo.instance;

                // Make sure there's a mapping back to the view metadata.

                this._viewInfoMap[Y.stamp(view, true)] = viewInfo;

            } else {

                // TODO: Add the app as a bubble target during construction, but

                // make sure to check that it isn't already in `bubbleTargets`!

                // This will allow the app to be notified for about _all_ of the

                // view's events. **Note:** This should _only_ happen if the

                // view is created _after_ `activeViewChange`.

                view    = this.createView(view, config);

                created = true;

            }

        }

        // Update the specified or preserved `view` when signaled to do so.

        // There's no need to updated a view if it was _just_ created.

        if (options.update && !created) {

            view.setAttrs(config);

        }

        // TODO: Hold off on rendering the view until after it has been

        // "attached", and move the call to render into `_attachView()`.

        // When a value is specified for `options.render`, prefer it because it

        // represents the developer's intent. When no value is specified, the

        // `view` will only be rendered if it was just created.

        if ('render' in options) {

            if (options.render) {

                view.render();

            }

        } else if (created) {

            view.render();

        }

        return this._set('activeView', view, {options: options});

    },

    // -- Protected Methods ----------------------------------------------------

    /**

    Helper method to attach the view instance to the application by making the

    app a bubble target of the view, append the view to the `viewContainer`, and

    assign it to the `instance` property of the associated view info metadata.

    @method _attachView