Debian Codegraph @

closure-library/closure/goog/ui/zippy.js

raw
1 // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Zippy widget implementation.
17 *
18 * @author [email protected] (Emil A Eklund)
19 * @see ../demos/zippy.html
20 */
21
22 goog.provide('goog.ui.Zippy');
23 goog.provide('goog.ui.Zippy.Events');
24 goog.provide('goog.ui.ZippyEvent');
25
26 goog.require('goog.a11y.aria');
27 goog.require('goog.a11y.aria.Role');
28 goog.require('goog.a11y.aria.State');
29 goog.require('goog.dom');
30 goog.require('goog.dom.classlist');
31 goog.require('goog.events.Event');
32 goog.require('goog.events.EventHandler');
33 goog.require('goog.events.EventTarget');
34 goog.require('goog.events.EventType');
35 goog.require('goog.events.KeyCodes');
36 goog.require('goog.events.KeyHandler');
37 goog.require('goog.style');
38
39
40
41 /**
42 * Zippy widget. Expandable/collapsible container, clicking the header toggles
43 * the visibility of the content.
44 *
45 * @extends {goog.events.EventTarget}
46 * @param {Element|string|null} header Header element, either element
47 * reference, string id or null if no header exists.
48 * @param {Element|string|function():Element=} opt_content Content element
49 * (if any), either element reference or string id. If skipped, the caller
50 * should handle the TOGGLE event in its own way. If a function is passed,
51 * then if will be called to create the content element the first time the
52 * zippy is expanded.
53 * @param {boolean=} opt_expanded Initial expanded/visibility state. If
54 * undefined, attempts to infer the state from the DOM. Setting visibility
55 * using one of the standard Soy templates guarantees correct inference.
56 * @param {Element|string=} opt_expandedHeader Element to use as the header when
57 * the zippy is expanded.
58 * @param {goog.dom.DomHelper=} opt_domHelper An optional DOM helper.
59 * @param {goog.a11y.aria.Role<string>=} opt_role ARIA role, default TAB.
60 * @constructor
61 */
62 goog.ui.Zippy = function(
63 header, opt_content, opt_expanded, opt_expandedHeader, opt_domHelper,
64 opt_role) {
65 goog.ui.Zippy.base(this, 'constructor');
66
67 /**
68 * DomHelper used to interact with the document, allowing components to be
69 * created in a different window.
70 * @type {!goog.dom.DomHelper}
71 * @private
72 */
73 this.dom_ = opt_domHelper || goog.dom.getDomHelper();
74
75 /**
76 * Header element or null if no header exists.
77 * @type {Element}
78 * @private
79 */
80 this.elHeader_ = this.dom_.getElement(header) || null;
81
82 /**
83 * When present, the header to use when the zippy is expanded.
84 * @type {Element}
85 * @private
86 */
87 this.elExpandedHeader_ = this.dom_.getElement(opt_expandedHeader || null);
88
89 /**
90 * Function that will create the content element, or false if there is no such
91 * function.
92 * @type {?function():Element}
93 * @private
94 */
95 this.lazyCreateFunc_ = goog.isFunction(opt_content) ? opt_content : null;
96
97 /**
98 * ARIA role.
99 * @type {goog.a11y.aria.Role<string>}
100 * @private
101 */
102 this.role_ = opt_role || goog.a11y.aria.Role.TAB;
103
104 /**
105 * Content element.
106 * @type {Element}
107 * @private
108 */
109 this.elContent_ = this.lazyCreateFunc_ || !opt_content ?
110 null :
111 this.dom_.getElement(/** @type {!Element} */ (opt_content));
112
113 /**
114 * Expanded state.
115 * @type {boolean}
116 * @private
117 */
118 this.expanded_ = opt_expanded == true;
119 if (!goog.isDef(opt_expanded) && !this.lazyCreateFunc_) {
120 // For the dual caption case, we can get expanded_ from the visibility of
121 // the expandedHeader. For the single-caption case, we use the
122 // presence/absence of the relevant class. Using one of the standard Soy
123 // templates guarantees that this will work.
124 if (this.elExpandedHeader_) {
125 this.expanded_ = goog.style.isElementShown(this.elExpandedHeader_);
126 } else if (this.elHeader_) {
127 this.expanded_ = goog.dom.classlist.contains(
128 this.elHeader_, goog.getCssName('goog-zippy-expanded'));
129 }
130 }
131
132
133 /**
134 * A keyboard events handler. If there are two headers it is shared for both.
135 * @type {goog.events.EventHandler<!goog.ui.Zippy>}
136 * @private
137 */
138 this.keyboardEventHandler_ = new goog.events.EventHandler(this);
139
140 /**
141 * The keyhandler used for listening on most key events. This takes care of
142 * abstracting away some of the browser differences.
143 * @private {!goog.events.KeyHandler}
144 */
145 this.keyHandler_ = new goog.events.KeyHandler();
146
147 /**
148 * A mouse events handler. If there are two headers it is shared for both.
149 * @type {goog.events.EventHandler<!goog.ui.Zippy>}
150 * @private
151 */
152 this.mouseEventHandler_ = new goog.events.EventHandler(this);
153
154 var self = this;
155 function addHeaderEvents(el) {
156 if (el) {
157 el.tabIndex = 0;
158 goog.a11y.aria.setRole(el, self.getAriaRole());
159 goog.dom.classlist.add(el, goog.getCssName('goog-zippy-header'));
160 self.enableMouseEventsHandling_(el);
161 self.enableKeyboardEventsHandling_(el);
162 }
163 }
164 addHeaderEvents(this.elHeader_);
165 addHeaderEvents(this.elExpandedHeader_);
166
167 // initialize based on expanded state
168 this.setExpanded(this.expanded_);
169 };
170 goog.inherits(goog.ui.Zippy, goog.events.EventTarget);
171 goog.tagUnsealableClass(goog.ui.Zippy);
172
173
174 /**
175 * Constants for event names
176 *
177 * @const
178 */
179 goog.ui.Zippy.Events = {
180 // Zippy will dispatch an ACTION event for user interaction. Mimics
181 // {@code goog.ui.Controls#performActionInternal} by first changing
182 // the toggle state and then dispatching an ACTION event.
183 ACTION: 'action',
184 // Zippy state is toggled from collapsed to expanded or vice versa.
185 TOGGLE: 'toggle'
186 };
187
188
189 /**
190 * Whether to listen for and handle mouse events; defaults to true.
191 * @type {boolean}
192 * @private
193 */
194 goog.ui.Zippy.prototype.handleMouseEvents_ = true;
195
196
197 /**
198 * Whether to listen for and handle key events; defaults to true.
199 * @type {boolean}
200 * @private
201 */
202 goog.ui.Zippy.prototype.handleKeyEvents_ = true;
203
204
205 /** @override */
206 goog.ui.Zippy.prototype.disposeInternal = function() {
207 goog.ui.Zippy.base(this, 'disposeInternal');
208 goog.dispose(this.keyboardEventHandler_);
209 goog.dispose(this.keyHandler_);
210 goog.dispose(this.mouseEventHandler_);
211 };
212
213
214 /**
215 * @return {goog.a11y.aria.Role} The ARIA role to be applied to Zippy element.
216 */
217 goog.ui.Zippy.prototype.getAriaRole = function() {
218 return this.role_;
219 };
220
221
222 /**
223 * @return {HTMLElement} The content element.
224 */
225 goog.ui.Zippy.prototype.getContentElement = function() {
226 return /** @type {!HTMLElement} */ (this.elContent_);
227 };
228
229
230 /**
231 * @return {Element} The visible header element.
232 */
233 goog.ui.Zippy.prototype.getVisibleHeaderElement = function() {
234 var expandedHeader = this.elExpandedHeader_;
235 return expandedHeader && goog.style.isElementShown(expandedHeader) ?
236 expandedHeader :
237 this.elHeader_;
238 };
239
240
241 /**
242 * Expands content pane.
243 */
244 goog.ui.Zippy.prototype.expand = function() {
245 this.setExpanded(true);
246 };
247
248
249 /**
250 * Collapses content pane.
251 */
252 goog.ui.Zippy.prototype.collapse = function() {
253 this.setExpanded(false);
254 };
255
256
257 /**
258 * Toggles expanded state.
259 */
260 goog.ui.Zippy.prototype.toggle = function() {
261 this.setExpanded(!this.expanded_);
262 };
263
264
265 /**
266 * Sets expanded state.
267 *
268 * @param {boolean} expanded Expanded/visibility state.
269 */
270 goog.ui.Zippy.prototype.setExpanded = function(expanded) {
271 if (this.elContent_) {
272 // Hide the element, if one is provided.
273 goog.style.setElementShown(this.elContent_, expanded);
274 } else if (expanded && this.lazyCreateFunc_) {
275 // Assume that when the element is not hidden upon creation.
276 this.elContent_ = this.lazyCreateFunc_();
277 }
278 if (this.elContent_) {
279 goog.dom.classlist.add(
280 this.elContent_, goog.getCssName('goog-zippy-content'));
281 }
282
283 if (this.elExpandedHeader_) {
284 // Hide the show header and show the hide one.
285 goog.style.setElementShown(this.elHeader_, !expanded);
286 goog.style.setElementShown(this.elExpandedHeader_, expanded);
287 } else {
288 // Update header image, if any.
289 this.updateHeaderClassName(expanded);
290 }
291
292 this.setExpandedInternal(expanded);
293
294 // Fire toggle event
295 this.dispatchEvent(
296 new goog.ui.ZippyEvent(
297 goog.ui.Zippy.Events.TOGGLE, this, this.expanded_));
298 };
299
300
301 /**
302 * Sets expanded internal state.
303 *
304 * @param {boolean} expanded Expanded/visibility state.
305 * @protected
306 */
307 goog.ui.Zippy.prototype.setExpandedInternal = function(expanded) {
308 this.expanded_ = expanded;
309 };
310
311
312 /**
313 * @return {boolean} Whether the zippy is expanded.
314 */
315 goog.ui.Zippy.prototype.isExpanded = function() {
316 return this.expanded_;
317 };
318
319
320 /**
321 * Updates the header element's className and ARIA (accessibility) EXPANDED
322 * state.
323 *
324 * @param {boolean} expanded Expanded/visibility state.
325 * @protected
326 */
327 goog.ui.Zippy.prototype.updateHeaderClassName = function(expanded) {
328 if (this.elHeader_) {
329 goog.dom.classlist.enable(
330 this.elHeader_, goog.getCssName('goog-zippy-expanded'), expanded);
331 goog.dom.classlist.enable(
332 this.elHeader_, goog.getCssName('goog-zippy-collapsed'), !expanded);
333 goog.a11y.aria.setState(
334 this.elHeader_, goog.a11y.aria.State.EXPANDED, expanded);
335 }
336 };
337
338
339 /**
340 * @return {boolean} Whether the Zippy handles its own key events.
341 */
342 goog.ui.Zippy.prototype.isHandleKeyEvents = function() {
343 return this.handleKeyEvents_;
344 };
345
346
347 /**
348 * @return {boolean} Whether the Zippy handles its own mouse events.
349 */
350 goog.ui.Zippy.prototype.isHandleMouseEvents = function() {
351 return this.handleMouseEvents_;
352 };
353
354
355 /**
356 * Sets whether the Zippy handles it's own keyboard events.
357 * @param {boolean} enable Whether the Zippy handles keyboard events.
358 */
359 goog.ui.Zippy.prototype.setHandleKeyboardEvents = function(enable) {
360 if (this.handleKeyEvents_ != enable) {
361 this.handleKeyEvents_ = enable;
362 if (enable) {
363 this.enableKeyboardEventsHandling_(this.elHeader_);
364 this.enableKeyboardEventsHandling_(this.elExpandedHeader_);
365 } else {
366 this.keyboardEventHandler_.removeAll();
367 this.keyHandler_.detach();
368 }
369 }
370 };
371
372
373 /**
374 * Sets whether the Zippy handles it's own mouse events.
375 * @param {boolean} enable Whether the Zippy handles mouse events.
376 */
377 goog.ui.Zippy.prototype.setHandleMouseEvents = function(enable) {
378 if (this.handleMouseEvents_ != enable) {
379 this.handleMouseEvents_ = enable;
380 if (enable) {
381 this.enableMouseEventsHandling_(this.elHeader_);
382 this.enableMouseEventsHandling_(this.elExpandedHeader_);
383 } else {
384 this.mouseEventHandler_.removeAll();
385 }
386 }
387 };
388
389
390 /**
391 * Enables keyboard events handling for the passed header element.
392 * @param {Element} header The header element.
393 * @private
394 */
395 goog.ui.Zippy.prototype.enableKeyboardEventsHandling_ = function(header) {
396 if (header) {
397 this.keyHandler_.attach(header);
398 this.keyboardEventHandler_.listen(
399 this.keyHandler_, goog.events.KeyHandler.EventType.KEY,
400 this.onHeaderKeyDown_);
401 }
402 };
403
404
405 /**
406 * Enables mouse events handling for the passed header element.
407 * @param {Element} header The header element.
408 * @private
409 */
410 goog.ui.Zippy.prototype.enableMouseEventsHandling_ = function(header) {
411 if (header) {
412 this.mouseEventHandler_.listen(
413 header, goog.events.EventType.CLICK, this.onHeaderClick_);
414 }
415 };
416
417
418 /**
419 * KeyDown event handler for header element. Enter and space toggles expanded
420 * state.
421 *
422 * @param {!goog.events.BrowserEvent} event KeyDown event.
423 * @private
424 */
425 goog.ui.Zippy.prototype.onHeaderKeyDown_ = function(event) {
426 if (event.keyCode == goog.events.KeyCodes.ENTER ||
427 event.keyCode == goog.events.KeyCodes.SPACE) {
428 this.toggle();
429 this.dispatchActionEvent_(event);
430
431 // Prevent enter key from submitting form.
432 event.preventDefault();
433
434 event.stopPropagation();
435 }
436 };
437
438
439 /**
440 * Click event handler for header element.
441 *
442 * @param {!goog.events.BrowserEvent} event Click event.
443 * @private
444 */
445 goog.ui.Zippy.prototype.onHeaderClick_ = function(event) {
446 this.toggle();
447 this.dispatchActionEvent_(event);
448 };
449
450
451 /**
452 * Dispatch an ACTION event whenever there is user interaction with the header.
453 * Please note that after the zippy state change is completed a TOGGLE event
454 * will be dispatched. However, the TOGGLE event is dispatch on every toggle,
455 * including programmatic call to {@code #toggle}.
456 * @param {!goog.events.BrowserEvent} triggeringEvent
457 * @private
458 */
459 goog.ui.Zippy.prototype.dispatchActionEvent_ = function(triggeringEvent) {
460 this.dispatchEvent(new goog.ui.ZippyEvent(
461 goog.ui.Zippy.Events.ACTION, this, this.expanded_, triggeringEvent));
462 };
463
464
465
466 /**
467 * Object representing a zippy toggle event.
468 *
469 * @param {string} type Event type.
470 * @param {goog.ui.Zippy} target Zippy widget initiating event.
471 * @param {boolean} expanded Expanded state.
472 * @param {!goog.events.BrowserEvent=} opt_triggeringEvent
473 * @extends {goog.events.Event}
474 * @constructor
475 * @final
476 */
477 goog.ui.ZippyEvent = function(type, target, expanded, opt_triggeringEvent) {
478 goog.ui.ZippyEvent.base(this, 'constructor', type, target);
479
480 /**
481 * The expanded state.
482 * @type {boolean}
483 */
484 this.expanded = expanded;
485
486 /**
487 * For ACTION events, the key or mouse event that triggered this event, if
488 * there was one.
489 * @type {?goog.events.BrowserEvent}
490 */
491 this.triggeringEvent = opt_triggeringEvent || null;
492 };
493 goog.inherits(goog.ui.ZippyEvent, goog.events.Event);