~launchpad-pqm/launchpad/devel

/* Copyright 2011 Canonical Ltd.  This software is licensed under the

 * GNU Affero General Public License version 3 (see the file LICENSE).

 *

 * Expander widget.  Can be used to let the user toggle the visibility of

 * existing elements on the page, or to make the page load elements on demand

 * as the user expands them.

 *

 * Synonyms: collapsible, foldable.

 *

 * Each expander needs two tags as "connection points":

 *  * Icon tag, to be marked up with the expander icon.

 *  * Content tag, to be exposed by the expander.

 *

 * Either may have initial contents.  The initial contents of the icon tag

 * stays in place, so it could say something like "Details..." that explains

 * what the icon means.  You'll want to hide it using the "unseen" class if

 * these contents should only be shown once the expander has been set up.

 *

 * Any initial contents of the content tag will be revealed when the expander

 * is opened; hide them using the "unseen" class if they should not be shown

 * when the expander has not been enabled.  An optional loader function may

 * produce new contents for this tag when the user first opens the expander.

 *

 * If you provide a loader function, the expander runs it when the user first

 * opens it.  The loader should produce a DOM node or node list(it may do this

 * asynchronously) and feed that back to the expander by passing it to the

 * expander's "receive" method.  The loader gets a reference to the expander

 * as its first argument.

 *

 * The expander is set up in its collapsed state by default.  If you want it

 * created in its expanded state instead, mark your content tag with the

 * "expanded" class.

 *

 * An expander may be created with a group_id. Expanders which belong to the

 * same group can only have one instance in the expanded state at any time. If

 * a collapsed expander is opened, any other open expander within the same

 * group will be closed.

 *

 * @module lp.app.widgets.expander

 * @requires node, event

 */

YUI.add('lp.app.widgets.expander', function(Y) {

var namespace = Y.namespace('lp.app.widgets.expander');

// Define some constants.

var EXPANDER_CREATED = 'expander:created',

    EXPANDER_DESTROYED = 'expander:destroyed',

    EXPANDER_STATE_CHANGED = 'expander:state_changed',

    EXPANDED = 'expander:expanded',

    COLLAPSED = 'expander:collapsed';

namespace.EXPANDER_CREATED = EXPANDER_CREATED;

namespace.EXPANDER_DESTORYED = EXPANDER_DESTROYED;

namespace.EXPANDER_STATE_CHANGED = EXPANDER_STATE_CHANGED;

namespace.EXPANDED = EXPANDED;

namespace.COLLAPSED = COLLAPSED;

/**

 * A single ExpanderRadioController instance is created for this namespace.

 * Each expander instance which is created with a group id is registered with

 * this controller. The controller ensures that only one expander from each

 * group is open at any time.

 */

function ExpanderRadioController() {

    ExpanderRadioController.superclass.constructor.apply(this, arguments);

}

ExpanderRadioController.NAME = "ExpanderRadioController";

Y.extend(ExpanderRadioController, Y.Base, {

    initializer: function() {

        this.expanders = {};

        var controller = this;

        Y.on(EXPANDER_CREATED, function(group_id, expander) {

            controller._registerExpander(group_id, expander);

        });

        Y.on(EXPANDER_DESTROYED, function(group_id, expander) {

            controller._deregisterExpander(group_id, expander);

        });

        Y.on(EXPANDER_STATE_CHANGED,

            function(group_id, new_state, active_expander) {

                controller._stateChangeProcessor(

                    group_id, new_state, active_expander);

            });

    },

    _stateChangeProcessor: function(group_id, new_state, active_expander) {

        this.expanders[group_id].forEach(function(expander) {

            if (new_state === EXPANDED && expander !== active_expander) {

                if (expander.isExpanded()) {

                    expander.render(false);

                }

            }

        }, this);

    },

    _registerExpander: function(group_id, expander) {

        if (!this.expanders.hasOwnProperty(group_id)) {

            this.expanders[group_id] = [];

        }

        this.expanders[group_id].push(expander);

    },

    _deregisterExpander: function(group_id, expander) {

        if (this.expanders.hasOwnProperty(group_id)) {

            var idx = this.expanders[group_id].indexOf(expander);

            if (idx !== -1) {

                this.expanders[group_id].splice(idx, 1);

            }

        }

    }

});

// Create the controller instance

if (namespace.expanderRadioController === undefined) {

    namespace.expanderRadioController = new ExpanderRadioController();

}

/*

 * Create an expander.

 *

 * @param icon_node Node to serve as connection point for the expander icon.

 * @param content_node Node to serve as connection point for expander content.

 * @param config Object with additional parameters.

 *     loader: A function that will produce a Node or NodeList to replace the

 *         contents of the content tag.  Receives the Expander object

 *         "expander" as its argument.  Once the loader has constructed the

 *         output Node or NodeList it wants to display ("output"), it calls

 *         expander.receive(output) to update the content node.

 *     animate_node: A node to perform an animation on.  Mostly useful for

 *         animating table rows/cells when you want to animate the inner

 *         content (eg. a <div>).

 *     no_animation: Set to true if no animation should be used.  Useful for

 *         when you can't rearrange the nodes so animations apply to them

 *         (eg. we want to show a bunch of rows in the same table).

 */

function Expander(icon_node, content_node, config) {

    Expander.superclass.constructor.apply(this);

    if (!Y.Lang.isObject(icon_node)) {

        throw new Error("No icon node given.");

    }

    if (!Y.Lang.isObject(content_node)) {

        throw new Error("No content node given.");

    }

    this.icon_node = icon_node;

    this.content_node = content_node;

    if (Y.Lang.isValue(config)) {

        this.config = config;

    } else {

        this.config = {};

    }

    this.loaded = !Y.Lang.isValue(this.config.loader);

    if (Y.Lang.isValue(this.config.animate_node)) {

        this._animate_node = Y.one(this.config.animate_node);

    } else {

        this._animate_node = this.content_node;

    }

    if (this.config.no_animation !== true) {

        this._animation = Y.lazr.effects.reversible_slide_out(

            this._animate_node);

    } else {

        this._animation = undefined;

    }

    if (Y.Lang.isValue(this.config.group_id)) {

        Y.fire(EXPANDER_CREATED, this.config.group_id, this);

    }

    // Is setup complete?  Skip any animations until it is.

    this.fully_set_up = false;

}

Expander.NAME = "Expander";

namespace.Expander = Expander;

Y.extend(Expander, Y.Base, {

    /*

     * CSS classes.

     */

    css_classes: {

        expanded: 'expanded',

        unseen: 'unseen'

    },

    destructor: function() {

        if (Y.Lang.isValue(this.config.group_id)) {

            Y.fire(EXPANDER_DESTROYED, this.config.group_id, this);

        }

    },

    /*

     * Return sprite name for given expander state.

     */

    nameSprite: function(expanded) {

        if (expanded) {

            return 'treeExpanded';

        } else {

            return 'treeCollapsed';

        }

    },

    /*

     * Is the content node currently expanded?

     */

    isExpanded: function() {

        return this.content_node.hasClass(this.css_classes.expanded);

    },

    /*

     * Either add or remove given CSS class from the content tag.

     *

     * @param want_class Whether this class is desired for the content tag.

     *     If it is, then the function may need to add it; if it isn't, then

     *     the function may need to remove it.

     * @param class_name CSS class name.

     */

    setContentClassIf: function(want_class, class_name) {

        if (want_class) {

            this.content_node.addClass(class_name);

        } else {

            this.content_node.removeClass(class_name);

        }

    },

    /*

     * Record the expanded/collapsed state of the content tag and fire the

     * state_changed event.

     */

    setExpanded: function(is_expanded) {

        var state_changed = this.isExpanded() !== is_expanded;

        this.setContentClassIf(is_expanded, this.css_classes.expanded);

        if (state_changed && Y.Lang.isValue(this.config.group_id)) {

            Y.fire(

                EXPANDER_STATE_CHANGED,

                this.config.group_id,

                is_expanded?EXPANDED:COLLAPSED, this);

        }

    },

    /*

     * Hide or reveal the content node (by adding the "unseen" class to it).

     *

     * @param expand Are we expanding?  If not, we must be collapsing.

     * @param no_animation {Boolean} Whether to short-circuit the animation?

     */

    foldContentNode: function(expand, no_animation) {

        var expander = this;

        var has_paused = false;

        if (no_animation === true || Y.Lang.isUndefined(this._animation)) {

            // Make the animation have the proper direction set from

            // the start.

            if (!Y.Lang.isUndefined(this._animation)) {

                this._animation.set('reverse', expand);

            }

            expander.setContentClassIf(

                !expand, expander.css_classes.unseen);

        } else {

            this._animation.set('reverse', !expand);

            if (expand) {

                // Show when expanding.

                expander.setContentClassIf(

                    false, expander.css_classes.unseen);

            } else {

                // Hide when collapsing but only after

                // animation is complete.

                this._animation.once('end', function() {

                    // Only hide if the direction has not been

                    // changed in the meantime.

                    if (this.get('reverse')) {

                        expander.setContentClassIf(

                            true, expander.css_classes.unseen);

                    }

                });

            }

            expander._animation.run();

        }

    },

    revealIcon: function() {

        this.icon_node

            .addClass('sprite')

            .removeClass('unseen');

    },

    /*

     * Set icon to either the "expanded" or the "collapsed" state.

     *

     * @param expand Are we expanding?  If not, we must be collapsing.

     */

    setIcon: function(expand) {

        this.icon_node

            .removeClass(this.nameSprite(!expand))

            .addClass(this.nameSprite(expand))

            .setStyle('cursor', 'pointer');

    },

    /*

     * Process the output node being produced by the loader.  To be invoked

     * by a custom loader when it's done.

     *

     * @param output A Node or NodeList to replace the contents of the content

     *     tag with.

     * @param failed Whether loading has failed and should be retried.

     */

    receive: function(output, failed) {

        if (failed === true) {

            this.loaded = false;

        }

        var from_height = this._animate_node.getStyle('height');

        this._animate_node.setContent(output);

        if (Y.Lang.isUndefined(this._animation)) {

            return;

        }

        var to_height = this._animate_node.get('scrollHeight');

        if (this._animation.get('running')) {

            this._animation.stop();

        }

        this._animation.set('to', { height: to_height });

        this._animation.set('from', { height: from_height });

        this._animation.run();

    },

    /*

     * Invoke the loader, and record the fact that the loader has been

     * started.

     */

    load: function() {

        this.loaded = true;

        this.config.loader(this);

    },

    /*

     * Set the expander's DOM elements to a consistent, operational state.

     *

     * @param expanded Whether the expander is to be rendered in its expanded

     *     state.  If not, it must be in the collapsed state.

     */

    render: function(expanded, no_animation) {

        this.foldContentNode(expanded, no_animation);

        this.setIcon(expanded);

        if (expanded && !this.loaded) {

            this.load();

        }

        this.setExpanded(expanded);

    },

    /**

     * Wrap node content in an <a> tag and mark it as js-action.

     *

     * @param node Y.Node object to modify: its content is modified

     *     in-place so node events won't be lost, but anything set on

     *     the inner content nodes might be.

     */

    wrapNodeWithLink: function(node) {

        var link_node = Y.Node.create('<a></a>')

            .addClass('js-action')

            .set('href', '#')

            .setContent(node.getContent());

        node.setContent(link_node);

    },

    /*

     * Set up an expander's DOM and event handler.

     *

     * @param linkify {Boolean} Wrap the icon node into an <A> tag with

     *     proper CSS classes and content from the icon node.

     */

    setUp: function(linkify) {

        var expander = this;

        function click_handler(e) {

            e.halt();

            expander.render(!expander.isExpanded());

        }

        this.render(this.isExpanded(), true);

        if (linkify === true) {

            this.wrapNodeWithLink(this.icon_node);

        }

        this.icon_node.on('click', click_handler);

        this.revealIcon();

        this.fully_set_up = true;

        return this;

    }

});

/*

 * Initialize expanders based on CSS selectors.

 *

 * @param widget_select CSS selector to specify each tag that will have an

 *     expander created inside it.

 * @param icon_select CSS selector for the icon tag inside each tag matched

 *     by widget_select.

 * @param content_select CSS selector for the content tag inside each tag

 *     matched by widget_select.

 * @param linkify Whether to linkify the content in the icon_select node.

 * @param loader Optional loader function for each expander that is set up.

 *     Must take an Expander as its argument, create a Node or NodeList with

 *     the output to be displayed, and feed the output to the expander's

 *     "receive" method.

 */

function createByCSS(widget_select, icon_select, content_select, linkify,

                     loader) {

    var config = {

        loader: loader

    };

    var expander_factory = function(widget) {

        var expander = new Expander(

            widget.one(icon_select), widget.one(content_select), config);

        expander.setUp(linkify);

    };

    Y.all(widget_select).each(expander_factory);

}

namespace.createByCSS = createByCSS;

}, "0.1", {"requires": ["base", "event", "node", "lazr.effects"]});