← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/lp/app/javascript/expander.js

  • Committer: Curtis Hovey
  • Date: 2011-05-27 21:53:34 UTC
  • mto: This revision was merged to the branch mainline in revision 13136.
  • Revision ID: curtis.hovey@canonical.com-20110527215334-jqlkmt52nnl4bpeh
Moved launchpad.event into registry interfaces.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/lp/app/javascript/expander.js
1
 
/* Copyright 2011 Canonical Ltd.  This software is licensed under the
2
 
 * GNU Affero General Public License version 3 (see the file LICENSE).
3
 
 *
4
 
 * Expander widget.  Can be used to let the user toggle the visibility of
5
 
 * existing elements on the page, or to make the page load elements on demand
6
 
 * as the user expands them.
7
 
 *
8
 
 * Synonyms: collapsible, foldable.
9
 
 *
10
 
 * Each expander needs two tags as "connection points":
11
 
 *  * Icon tag, to be marked up with the expander icon.
12
 
 *  * Content tag, to be exposed by the expander.
13
 
 *
14
 
 * Either may have initial contents.  The initial contents of the icon tag
15
 
 * stays in place, so it could say something like "Details..." that explains
16
 
 * what the icon means.  You'll want to hide it using the "unseen" class if
17
 
 * these contents should only be shown once the expander has been set up.
18
 
 *
19
 
 * Any initial contents of the content tag will be revealed when the expander
20
 
 * is opened; hide them using the "unseen" class if they should not be shown
21
 
 * when the expander has not been enabled.  An optional loader function may
22
 
 * produce new contents for this tag when the user first opens the expander.
23
 
 *
24
 
 * If you provide a loader function, the expander runs it when the user first
25
 
 * opens it.  The loader should produce a DOM node or node list(it may do this
26
 
 * asynchronously) and feed that back to the expander by passing it to the
27
 
 * expander's "receive" method.  The loader gets a reference to the expander
28
 
 * as its first argument.
29
 
 *
30
 
 * The expander is set up in its collapsed state by default.  If you want it
31
 
 * created in its expanded state instead, mark your content tag with the
32
 
 * "expanded" class.
33
 
 *
34
 
 * @module lp.app.widgets.expander
35
 
 * @requires node, event
36
 
 */
37
 
 
38
 
YUI.add('lp.app.widgets.expander', function(Y) {
39
 
 
40
 
var namespace = Y.namespace('lp.app.widgets.expander');
41
 
 
42
 
/*
43
 
 * Create an expander.
44
 
 *
45
 
 * @param icon_node Node to serve as connection point for the expander icon.
46
 
 * @param content_node Node to serve as connection point for expander content.
47
 
 * @param config Object with additional parameters.
48
 
 *     loader: A function that will produce a Node or NodeList to replace the
49
 
 *         contents of the content tag.  Receives the Expander object
50
 
 *         "expander" as its argument.  Once the loader has constructed the
51
 
 *         output Node or NodeList it wants to display ("output"), it calls
52
 
 *         expander.receive(output) to update the content node.
53
 
 *     animate_node: A node to perform an animation on.  Mostly useful for
54
 
 *         animating table rows/cells when you want to animate the inner
55
 
 *         content (eg. a <div>).
56
 
 *     no_animation: Set to true if no animation should be used.  Useful for
57
 
 *         when you can't rearrange the nodes so animations apply to them
58
 
 *         (eg. we want to show a bunch of rows in the same table).
59
 
 */
60
 
function Expander(icon_node, content_node, config) {
61
 
    if (!Y.Lang.isObject(icon_node)) {
62
 
        throw new Error("No icon node given.");
63
 
    }
64
 
    if (!Y.Lang.isObject(content_node)) {
65
 
        throw new Error("No content node given.");
66
 
    }
67
 
    this.icon_node = icon_node;
68
 
    this.content_node = content_node;
69
 
    if (Y.Lang.isValue(config)) {
70
 
        this.config = config;
71
 
    } else {
72
 
        this.config = {};
73
 
    }
74
 
    this.loaded = !Y.Lang.isValue(this.config.loader);
75
 
 
76
 
    if (Y.Lang.isValue(this.config.animate_node)) {
77
 
        this._animate_node = Y.one(this.config.animate_node);
78
 
    } else {
79
 
        this._animate_node = this.content_node;
80
 
    }
81
 
 
82
 
    if (this.config.no_animation !== true) {
83
 
        this._animation = Y.lazr.effects.reversible_slide_out(
84
 
            this._animate_node);
85
 
    } else {
86
 
        this._animation = undefined;
87
 
    }
88
 
 
89
 
    // Is setup complete?  Skip any animations until it is.
90
 
    this.fully_set_up = false;
91
 
}
92
 
namespace.Expander = Expander;
93
 
 
94
 
namespace.Expander.prototype = {
95
 
    /*
96
 
     * CSS classes.
97
 
     */
98
 
    css_classes: {
99
 
        expanded: 'expanded',
100
 
        unseen: 'unseen'
101
 
    },
102
 
 
103
 
    /*
104
 
     * Return sprite name for given expander state.
105
 
     */
106
 
    nameSprite: function(expanded) {
107
 
        if (expanded) {
108
 
            return 'treeExpanded';
109
 
        } else {
110
 
            return 'treeCollapsed';
111
 
        }
112
 
    },
113
 
 
114
 
    /*
115
 
     * Is the content node currently expanded?
116
 
     */
117
 
    isExpanded: function() {
118
 
        return this.content_node.hasClass(this.css_classes.expanded);
119
 
    },
120
 
 
121
 
    /*
122
 
     * Either add or remove given CSS class from the content tag.
123
 
     *
124
 
     * @param want_class Whether this class is desired for the content tag.
125
 
     *     If it is, then the function may need to add it; if it isn't, then
126
 
     *     the function may need to remove it.
127
 
     * @param class_name CSS class name.
128
 
     */
129
 
    setContentClassIf: function(want_class, class_name) {
130
 
        if (want_class) {
131
 
            this.content_node.addClass(class_name);
132
 
        } else {
133
 
            this.content_node.removeClass(class_name);
134
 
        }
135
 
    },
136
 
 
137
 
    /*
138
 
     * Record the expanded/collapsed state of the content tag.
139
 
     */
140
 
    setExpanded: function(is_expanded) {
141
 
        this.setContentClassIf(is_expanded, this.css_classes.expanded);
142
 
    },
143
 
 
144
 
    /*
145
 
     * Hide or reveal the content node (by adding the "unseen" class to it).
146
 
     *
147
 
     * @param expand Are we expanding?  If not, we must be collapsing.
148
 
     * @param no_animation {Boolean} Whether to short-circuit the animation?
149
 
     */
150
 
    foldContentNode: function(expand, no_animation) {
151
 
        var expander = this;
152
 
        var has_paused = false;
153
 
        if (no_animation === true || Y.Lang.isUndefined(this._animation)) {
154
 
            // Make the animation have the proper direction set from
155
 
            // the start.
156
 
            if (!Y.Lang.isUndefined(this._animation)) {
157
 
                this._animation.set('reverse', expand);
158
 
            }
159
 
            expander.setContentClassIf(
160
 
                !expand, expander.css_classes.unseen);
161
 
        } else {
162
 
            this._animation.set('reverse', !expand);
163
 
 
164
 
            if (expand) {
165
 
                // Show when expanding.
166
 
                expander.setContentClassIf(
167
 
                    false, expander.css_classes.unseen);
168
 
            } else {
169
 
                // Hide when collapsing but only after
170
 
                // animation is complete.
171
 
                this._animation.once('end', function() {
172
 
                    // Only hide if the direction has not been
173
 
                    // changed in the meantime.
174
 
                    if (this.get('reverse')) {
175
 
                        expander.setContentClassIf(
176
 
                            true, expander.css_classes.unseen);
177
 
                    }
178
 
                });
179
 
            }
180
 
 
181
 
            expander._animation.run();
182
 
        }
183
 
    },
184
 
 
185
 
    revealIcon: function() {
186
 
        this.icon_node
187
 
            .addClass('sprite')
188
 
            .removeClass('unseen');
189
 
    },
190
 
 
191
 
    /*
192
 
     * Set icon to either the "expanded" or the "collapsed" state.
193
 
     *
194
 
     * @param expand Are we expanding?  If not, we must be collapsing.
195
 
     */
196
 
    setIcon: function(expand) {
197
 
        this.icon_node
198
 
            .removeClass(this.nameSprite(!expand))
199
 
            .addClass(this.nameSprite(expand))
200
 
            .setStyle('cursor', 'pointer');
201
 
    },
202
 
 
203
 
    /*
204
 
     * Process the output node being produced by the loader.  To be invoked
205
 
     * by a custom loader when it's done.
206
 
     *
207
 
     * @param output A Node or NodeList to replace the contents of the content
208
 
     *     tag with.
209
 
     * @param failed Whether loading has failed and should be retried.
210
 
     */
211
 
    receive: function(output, failed) {
212
 
        if (failed === true) {
213
 
            this.loaded = false;
214
 
        }
215
 
        var from_height = this._animate_node.getStyle('height');
216
 
        this._animate_node.setContent(output);
217
 
        if (Y.Lang.isUndefined(this._animation)) {
218
 
            return;
219
 
        }
220
 
        var to_height = this._animate_node.get('scrollHeight');
221
 
        if (this._animation.get('running')) {
222
 
            this._animation.stop();
223
 
        }
224
 
        this._animation.set('to', { height: to_height });
225
 
        this._animation.set('from', { height: from_height });
226
 
        this._animation.run();
227
 
    },
228
 
 
229
 
    /*
230
 
     * Invoke the loader, and record the fact that the loader has been
231
 
     * started.
232
 
     */
233
 
    load: function() {
234
 
        this.loaded = true;
235
 
        this.config.loader(this);
236
 
    },
237
 
 
238
 
    /*
239
 
     * Set the expander's DOM elements to a consistent, operational state.
240
 
     *
241
 
     * @param expanded Whether the expander is to be rendered in its expanded
242
 
     *     state.  If not, it must be in the collapsed state.
243
 
     */
244
 
    render: function(expanded, no_animation) {
245
 
        this.foldContentNode(expanded, no_animation);
246
 
        this.setIcon(expanded);
247
 
        if (expanded && !this.loaded) {
248
 
            this.load();
249
 
        }
250
 
        this.setExpanded(expanded);
251
 
    },
252
 
 
253
 
    /**
254
 
     * Wrap node content in an <a> tag and mark it as js-action.
255
 
     *
256
 
     * @param node Y.Node object to modify: its content is modified
257
 
     *     in-place so node events won't be lost, but anything set on
258
 
     *     the inner content nodes might be.
259
 
     */
260
 
    wrapNodeWithLink: function(node) {
261
 
        var link_node = Y.Node.create('<a></a>')
262
 
            .addClass('js-action')
263
 
            .set('href', '#')
264
 
            .setContent(node.getContent());
265
 
        node.setContent(link_node);
266
 
    },
267
 
 
268
 
    /*
269
 
     * Set up an expander's DOM and event handler.
270
 
     *
271
 
     * @param linkify {Boolean} Wrap the icon node into an <A> tag with
272
 
     *     proper CSS classes and content from the icon node.
273
 
     */
274
 
    setUp: function(linkify) {
275
 
        var expander = this;
276
 
        function click_handler(e) {
277
 
            e.halt();
278
 
            expander.render(!expander.isExpanded());
279
 
        }
280
 
 
281
 
        this.render(this.isExpanded(), true);
282
 
        if (linkify === true) {
283
 
            this.wrapNodeWithLink(this.icon_node);
284
 
        }
285
 
        this.icon_node.on('click', click_handler);
286
 
        this.revealIcon();
287
 
        this.fully_set_up = true;
288
 
        return this;
289
 
    }
290
 
};
291
 
 
292
 
/*
293
 
 * Initialize expanders based on CSS selectors.
294
 
 *
295
 
 * @param widget_select CSS selector to specify each tag that will have an
296
 
 *     expander created inside it.
297
 
 * @param icon_select CSS selector for the icon tag inside each tag matched
298
 
 *     by widget_select.
299
 
 * @param content_select CSS selector for the content tag inside each tag
300
 
 *     matched by widget_select.
301
 
 * @param linkify Whether to linkify the content in the icon_select node.
302
 
 * @param loader Optional loader function for each expander that is set up.
303
 
 *     Must take an Expander as its argument, create a Node or NodeList with
304
 
 *     the output to be displayed, and feed the output to the expander's
305
 
 *     "receive" method.
306
 
 */
307
 
function createByCSS(widget_select, icon_select, content_select, linkify,
308
 
                     loader) {
309
 
    var config = {
310
 
        loader: loader
311
 
    };
312
 
    var expander_factory = function(widget) {
313
 
        var expander = new Expander(
314
 
            widget.one(icon_select), widget.one(content_select), config);
315
 
        expander.setUp(linkify);
316
 
    };
317
 
    Y.all(widget_select).each(expander_factory);
318
 
}
319
 
namespace.createByCSS = createByCSS;
320
 
 
321
 
}, "0.1", {"requires": ["node", "lazr.effects"]});