Debian Codegraph @

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

raw
1 // Copyright 2007 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 Menu where items can be filtered based on user keyboard input.
17 * If a filter is specified only the items matching it will be displayed.
18 *
19 * @author [email protected] (Emil A Eklund)
20 * @see ../demos/filteredmenu.html
21 */
22
23
24 goog.provide('goog.ui.FilteredMenu');
25
26 goog.require('goog.a11y.aria');
27 goog.require('goog.a11y.aria.AutoCompleteValues');
28 goog.require('goog.a11y.aria.State');
29 goog.require('goog.dom');
30 goog.require('goog.dom.InputType');
31 goog.require('goog.dom.TagName');
32 goog.require('goog.events');
33 goog.require('goog.events.EventType');
34 goog.require('goog.events.InputHandler');
35 goog.require('goog.events.KeyCodes');
36 goog.require('goog.string');
37 goog.require('goog.style');
38 goog.require('goog.ui.Component');
39 goog.require('goog.ui.FilterObservingMenuItem');
40 goog.require('goog.ui.Menu');
41 goog.require('goog.ui.MenuItem');
42 goog.require('goog.userAgent');
43
44
45
46 /**
47 * Filtered menu class.
48 * @param {goog.ui.MenuRenderer=} opt_renderer Renderer used to render filtered
49 * menu; defaults to {@link goog.ui.MenuRenderer}.
50 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
51 * @constructor
52 * @extends {goog.ui.Menu}
53 */
54 goog.ui.FilteredMenu = function(opt_renderer, opt_domHelper) {
55 goog.ui.Menu.call(this, opt_domHelper, opt_renderer);
56 };
57 goog.inherits(goog.ui.FilteredMenu, goog.ui.Menu);
58 goog.tagUnsealableClass(goog.ui.FilteredMenu);
59
60
61 /**
62 * Events fired by component.
63 * @enum {string}
64 */
65 goog.ui.FilteredMenu.EventType = {
66 /** Dispatched after the component filter criteria has been changed. */
67 FILTER_CHANGED: 'filterchange'
68 };
69
70
71 /**
72 * Filter menu element ids.
73 * @enum {string}
74 * @private
75 */
76 goog.ui.FilteredMenu.Id_ = {
77 CONTENT_ELEMENT: 'content-el'
78 };
79
80
81 /**
82 * Filter input element.
83 * @type {Element|undefined}
84 * @private
85 */
86 goog.ui.FilteredMenu.prototype.filterInput_;
87
88
89 /**
90 * The input handler that provides the input event.
91 * @type {goog.events.InputHandler|undefined}
92 * @private
93 */
94 goog.ui.FilteredMenu.prototype.inputHandler_;
95
96
97 /**
98 * Maximum number of characters for filter input.
99 * @type {number}
100 * @private
101 */
102 goog.ui.FilteredMenu.prototype.maxLength_ = 0;
103
104
105 /**
106 * Label displayed in the filter input when no text has been entered.
107 * @type {string}
108 * @private
109 */
110 goog.ui.FilteredMenu.prototype.label_ = '';
111
112
113 /**
114 * Label element.
115 * @type {Element|undefined}
116 * @private
117 */
118 goog.ui.FilteredMenu.prototype.labelEl_;
119
120
121 /**
122 * Whether multiple items can be entered comma separated.
123 * @type {boolean}
124 * @private
125 */
126 goog.ui.FilteredMenu.prototype.allowMultiple_ = false;
127
128
129 /**
130 * List of items entered in the search box if multiple entries are allowed.
131 * @type {Array<string>|undefined}
132 * @private
133 */
134 goog.ui.FilteredMenu.prototype.enteredItems_;
135
136
137 /**
138 * Index of first item that should be affected by the filter. Menu items with
139 * a lower index will not be affected by the filter.
140 * @type {number}
141 * @private
142 */
143 goog.ui.FilteredMenu.prototype.filterFromIndex_ = 0;
144
145
146 /**
147 * Filter applied to the menu.
148 * @type {string|undefined|null}
149 * @private
150 */
151 goog.ui.FilteredMenu.prototype.filterStr_;
152
153
154 /**
155 * @private {Element}
156 */
157 goog.ui.FilteredMenu.prototype.contentElement_;
158
159
160 /**
161 * Map of child nodes that shouldn't be affected by filtering.
162 * @type {Object|undefined}
163 * @private
164 */
165 goog.ui.FilteredMenu.prototype.persistentChildren_;
166
167
168 /** @override */
169 goog.ui.FilteredMenu.prototype.createDom = function() {
170 goog.ui.FilteredMenu.superClass_.createDom.call(this);
171
172 var dom = this.getDomHelper();
173 var el = dom.createDom(
174 goog.dom.TagName.DIV,
175 goog.getCssName(this.getRenderer().getCssClass(), 'filter'),
176 this.labelEl_ = dom.createDom(goog.dom.TagName.DIV, null, this.label_),
177 this.filterInput_ = dom.createDom(
178 goog.dom.TagName.INPUT, {'type': goog.dom.InputType.TEXT}));
179 var element = this.getElement();
180 dom.appendChild(element, el);
181 var contentElementId = this.makeId(goog.ui.FilteredMenu.Id_.CONTENT_ELEMENT);
182 this.contentElement_ = dom.createDom(goog.dom.TagName.DIV, {
183 'class': goog.getCssName(this.getRenderer().getCssClass(), 'content'),
184 'id': contentElementId
185 });
186 dom.appendChild(element, this.contentElement_);
187
188 this.initFilterInput_();
189
190 goog.a11y.aria.setState(
191 this.filterInput_, goog.a11y.aria.State.AUTOCOMPLETE,
192 goog.a11y.aria.AutoCompleteValues.LIST);
193 goog.a11y.aria.setState(
194 this.filterInput_, goog.a11y.aria.State.OWNS, contentElementId);
195 goog.a11y.aria.setState(
196 this.filterInput_, goog.a11y.aria.State.EXPANDED, true);
197 };
198
199
200 /**
201 * Helper method that initializes the filter input element.
202 * @private
203 */
204 goog.ui.FilteredMenu.prototype.initFilterInput_ = function() {
205 this.setFocusable(true);
206 this.setKeyEventTarget(this.filterInput_);
207
208 // Workaround for mozilla bug #236791.
209 if (goog.userAgent.GECKO) {
210 this.filterInput_.setAttribute('autocomplete', 'off');
211 }
212
213 if (this.maxLength_) {
214 this.filterInput_.maxLength = this.maxLength_;
215 }
216 };
217
218
219 /**
220 * Sets up listeners and prepares the filter functionality.
221 * @private
222 */
223 goog.ui.FilteredMenu.prototype.setUpFilterListeners_ = function() {
224 if (!this.inputHandler_ && this.filterInput_) {
225 this.inputHandler_ = new goog.events.InputHandler(
226 /** @type {Element} */ (this.filterInput_));
227 goog.style.setUnselectable(this.filterInput_, false);
228 goog.events.listen(
229 this.inputHandler_, goog.events.InputHandler.EventType.INPUT,
230 this.handleFilterEvent, false, this);
231 goog.events.listen(
232 this.filterInput_.parentNode, goog.events.EventType.CLICK,
233 this.onFilterLabelClick_, false, this);
234 if (this.allowMultiple_) {
235 this.enteredItems_ = [];
236 }
237 }
238 };
239
240
241 /**
242 * Tears down listeners and resets the filter functionality.
243 * @private
244 */
245 goog.ui.FilteredMenu.prototype.tearDownFilterListeners_ = function() {
246 if (this.inputHandler_) {
247 goog.events.unlisten(
248 this.inputHandler_, goog.events.InputHandler.EventType.INPUT,
249 this.handleFilterEvent, false, this);
250 goog.events.unlisten(
251 this.filterInput_.parentNode, goog.events.EventType.CLICK,
252 this.onFilterLabelClick_, false, this);
253
254 this.inputHandler_.dispose();
255 this.inputHandler_ = undefined;
256 this.enteredItems_ = undefined;
257 }
258 };
259
260
261 /** @override */
262 goog.ui.FilteredMenu.prototype.setVisible = function(show, opt_force, opt_e) {
263 var visibilityChanged = goog.ui.FilteredMenu.superClass_.setVisible.call(
264 this, show, opt_force, opt_e);
265 if (visibilityChanged && show && this.isInDocument()) {
266 this.setFilter('');
267 this.setUpFilterListeners_();
268 } else if (visibilityChanged && !show) {
269 this.tearDownFilterListeners_();
270 }
271
272 return visibilityChanged;
273 };
274
275
276 /** @override */
277 goog.ui.FilteredMenu.prototype.disposeInternal = function() {
278 this.tearDownFilterListeners_();
279 this.filterInput_ = undefined;
280 this.labelEl_ = undefined;
281 goog.ui.FilteredMenu.superClass_.disposeInternal.call(this);
282 };
283
284
285 /**
286 * Sets the filter label (the label displayed in the filter input element if no
287 * text has been entered).
288 * @param {?string} label Label text.
289 */
290 goog.ui.FilteredMenu.prototype.setFilterLabel = function(label) {
291 this.label_ = label || '';
292 if (this.labelEl_) {
293 goog.dom.setTextContent(this.labelEl_, this.label_);
294 }
295 };
296
297
298 /**
299 * @return {string} The filter label.
300 */
301 goog.ui.FilteredMenu.prototype.getFilterLabel = function() {
302 return this.label_;
303 };
304
305
306 /**
307 * Sets the filter string.
308 * @param {?string} str Filter string.
309 */
310 goog.ui.FilteredMenu.prototype.setFilter = function(str) {
311 if (this.filterInput_) {
312 this.filterInput_.value = str;
313 this.filterItems_(str);
314 }
315 };
316
317
318 /**
319 * Returns the filter string.
320 * @return {string} Current filter or an an empty string.
321 */
322 goog.ui.FilteredMenu.prototype.getFilter = function() {
323 return this.filterInput_ && goog.isString(this.filterInput_.value) ?
324 this.filterInput_.value :
325 '';
326 };
327
328
329 /**
330 * Sets the index of first item that should be affected by the filter. Menu
331 * items with a lower index will not be affected by the filter.
332 * @param {number} index Index of first item that should be affected by filter.
333 */
334 goog.ui.FilteredMenu.prototype.setFilterFromIndex = function(index) {
335 this.filterFromIndex_ = index;
336 };
337
338
339 /**
340 * Returns the index of first item that is affected by the filter.
341 * @return {number} Index of first item that is affected by filter.
342 */
343 goog.ui.FilteredMenu.prototype.getFilterFromIndex = function() {
344 return this.filterFromIndex_;
345 };
346
347
348 /**
349 * Gets a list of items entered in the search box.
350 * @return {!Array<string>} The entered items.
351 */
352 goog.ui.FilteredMenu.prototype.getEnteredItems = function() {
353 return this.enteredItems_ || [];
354 };
355
356
357 /**
358 * Sets whether multiple items can be entered comma separated.
359 * @param {boolean} b Whether multiple items can be entered.
360 */
361 goog.ui.FilteredMenu.prototype.setAllowMultiple = function(b) {
362 this.allowMultiple_ = b;
363 };
364
365
366 /**
367 * @return {boolean} Whether multiple items can be entered comma separated.
368 */
369 goog.ui.FilteredMenu.prototype.getAllowMultiple = function() {
370 return this.allowMultiple_;
371 };
372
373
374 /**
375 * Sets whether the specified child should be affected (shown/hidden) by the
376 * filter criteria.
377 * @param {goog.ui.Component} child Child to change.
378 * @param {boolean} persistent Whether the child should be persistent.
379 */
380 goog.ui.FilteredMenu.prototype.setPersistentVisibility = function(
381 child, persistent) {
382 if (!this.persistentChildren_) {
383 this.persistentChildren_ = {};
384 }
385 this.persistentChildren_[child.getId()] = persistent;
386 };
387
388
389 /**
390 * Returns whether the specified child should be affected (shown/hidden) by the
391 * filter criteria.
392 * @param {goog.ui.Component} child Menu item to check.
393 * @return {boolean} Whether the menu item is persistent.
394 */
395 goog.ui.FilteredMenu.prototype.hasPersistentVisibility = function(child) {
396 return !!(
397 this.persistentChildren_ && this.persistentChildren_[child.getId()]);
398 };
399
400
401 /**
402 * Handles filter input events.
403 * @param {goog.events.BrowserEvent} e The event object.
404 */
405 goog.ui.FilteredMenu.prototype.handleFilterEvent = function(e) {
406 this.filterItems_(this.filterInput_.value);
407
408 // Highlight the first visible item unless there's already a highlighted item.
409 var highlighted = this.getHighlighted();
410 if (!highlighted || !highlighted.isVisible()) {
411 this.highlightFirst();
412 }
413 this.dispatchEvent(goog.ui.FilteredMenu.EventType.FILTER_CHANGED);
414 };
415
416
417 /**
418 * Shows/hides elements based on the supplied filter.
419 * @param {?string} str Filter string.
420 * @private
421 */
422 goog.ui.FilteredMenu.prototype.filterItems_ = function(str) {
423 // Do nothing unless the filter string has changed.
424 if (this.filterStr_ == str) {
425 return;
426 }
427
428 if (this.labelEl_) {
429 this.labelEl_.style.visibility = str == '' ? 'visible' : 'hidden';
430 }
431
432 if (this.allowMultiple_ && this.enteredItems_) {
433 // Matches all non space characters after the last comma.
434 var lastWordRegExp = /^(.+),[ ]*([^,]*)$/;
435 var matches = str.match(lastWordRegExp);
436 // matches[1] is the string up to, but not including, the last comma and
437 // matches[2] the part after the last comma. If there are no non-space
438 // characters after the last comma matches[2] is undefined.
439 var items = matches && matches[1] ? matches[1].split(',') : [];
440
441 // If the number of comma separated items has changes recreate the
442 // entered items array and fire a change event.
443 if (str.substr(str.length - 1, 1) == ',' ||
444 items.length != this.enteredItems_.length) {
445 var lastItem = items[items.length - 1] || '';
446
447 // Auto complete text in input box based on the highlighted item.
448 if (this.getHighlighted() && lastItem != '') {
449 var caption = this.getHighlighted().getCaption();
450 if (caption.toLowerCase().indexOf(lastItem.toLowerCase()) == 0) {
451 items[items.length - 1] = caption;
452 this.filterInput_.value = items.join(',') + ',';
453 }
454 }
455 this.enteredItems_ = items;
456 this.dispatchEvent(goog.ui.Component.EventType.CHANGE);
457 this.setHighlightedIndex(-1);
458 }
459
460 if (matches) {
461 str = matches.length > 2 ? goog.string.trim(matches[2]) : '';
462 }
463 }
464
465 var matcher =
466 new RegExp('(^|[- ,_/.:])' + goog.string.regExpEscape(str), 'i');
467 for (var child, i = this.filterFromIndex_; child = this.getChildAt(i); i++) {
468 if (child instanceof goog.ui.FilterObservingMenuItem) {
469 child.callObserver(str);
470 } else if (!this.hasPersistentVisibility(child)) {
471 // Only show items matching the filter and highlight the part of the
472 // caption that matches.
473 var caption = child.getCaption();
474 if (caption) {
475 var matchArray = caption.match(matcher);
476 if (str == '' || matchArray) {
477 child.setVisible(true);
478 var pos = caption.indexOf(matchArray[0]);
479
480 // If position is non zero increase by one to skip the separator.
481 if (pos) {
482 pos++;
483 }
484 this.boldContent_(child, pos, str.length);
485 } else {
486 child.setVisible(false);
487 }
488 } else {
489 // Hide separators and other items without a caption if a filter string
490 // has been entered.
491 child.setVisible(str == '');
492 }
493 }
494 }
495 this.filterStr_ = str;
496 };
497
498
499 /**
500 * Updates the content of the given menu item, bolding the part of its caption
501 * from start and through the next len characters.
502 * @param {!goog.ui.Control} child The control to bold content on.
503 * @param {number} start The index at which to start bolding.
504 * @param {number} len How many characters to bold.
505 * @private
506 */
507 goog.ui.FilteredMenu.prototype.boldContent_ = function(child, start, len) {
508 var caption = child.getCaption();
509 var boldedCaption;
510 if (len == 0) {
511 boldedCaption = this.getDomHelper().createTextNode(caption);
512 } else {
513 var preMatch = caption.substr(0, start);
514 var match = caption.substr(start, len);
515 var postMatch = caption.substr(start + len);
516 boldedCaption = this.getDomHelper().createDom(
517 goog.dom.TagName.SPAN, null, preMatch,
518 this.getDomHelper().createDom(goog.dom.TagName.B, null, match),
519 postMatch);
520 }
521 var accelerator = child.getAccelerator && child.getAccelerator();
522 if (accelerator) {
523 child.setContent([
524 boldedCaption, this.getDomHelper().createDom(
525 goog.dom.TagName.SPAN,
526 goog.ui.MenuItem.ACCELERATOR_CLASS, accelerator)
527 ]);
528 } else {
529 child.setContent(boldedCaption);
530 }
531 };
532
533
534 /**
535 * Handles the menu's behavior for a key event. The highlighted menu item will
536 * be given the opportunity to handle the key behavior.
537 * @param {goog.events.KeyEvent} e A browser event.
538 * @return {boolean} Whether the event was handled.
539 * @override
540 */
541 goog.ui.FilteredMenu.prototype.handleKeyEventInternal = function(e) {
542 // Home, end and the arrow keys are normally used to change the selected menu
543 // item. Return false here to prevent the menu from preventing the default
544 // behavior for HOME, END and any key press with a modifier.
545 if (e.shiftKey || e.ctrlKey || e.altKey ||
546 e.keyCode == goog.events.KeyCodes.HOME ||
547 e.keyCode == goog.events.KeyCodes.END) {
548 return false;
549 }
550
551 if (e.keyCode == goog.events.KeyCodes.ESC) {
552 this.dispatchEvent(goog.ui.Component.EventType.BLUR);
553 return true;
554 }
555
556 return goog.ui.FilteredMenu.superClass_.handleKeyEventInternal.call(this, e);
557 };
558
559
560 /**
561 * Sets the highlighted index, unless the HIGHLIGHT event is intercepted and
562 * cancelled. -1 = no highlight. Also scrolls the menu item into view.
563 * @param {number} index Index of menu item to highlight.
564 * @override
565 */
566 goog.ui.FilteredMenu.prototype.setHighlightedIndex = function(index) {
567 goog.ui.FilteredMenu.superClass_.setHighlightedIndex.call(this, index);
568 var contentEl = this.getContentElement();
569 var el = /** @type {!HTMLElement} */ (
570 this.getHighlighted() ? this.getHighlighted().getElement() : null);
571 if (this.filterInput_) {
572 goog.a11y.aria.setActiveDescendant(this.filterInput_, el);
573 }
574
575 if (el && goog.dom.contains(contentEl, el)) {
576 var contentTop = goog.userAgent.IE && !goog.userAgent.isVersionOrHigher(8) ?
577 0 :
578 contentEl.offsetTop;
579
580 // IE (tested on IE8) sometime does not scroll enough by about
581 // 1px. So we add 1px to the scroll amount. This still looks ok in
582 // other browser except for the most degenerate case (menu height <=
583 // item height).
584
585 // Scroll down if the highlighted item is below the bottom edge.
586 var diff = (el.offsetTop + el.offsetHeight - contentTop) -
587 (contentEl.clientHeight + contentEl.scrollTop) + 1;
588 contentEl.scrollTop += Math.max(diff, 0);
589
590 // Scroll up if the highlighted item is above the top edge.
591 diff = contentEl.scrollTop - (el.offsetTop - contentTop) + 1;
592 contentEl.scrollTop -= Math.max(diff, 0);
593 }
594 };
595
596
597 /**
598 * Handles clicks on the filter label. Focuses the input element.
599 * @param {goog.events.BrowserEvent} e A browser event.
600 * @private
601 */
602 goog.ui.FilteredMenu.prototype.onFilterLabelClick_ = function(e) {
603 this.filterInput_.focus();
604 };
605
606
607 /** @override */
608 goog.ui.FilteredMenu.prototype.getContentElement = function() {
609 return this.contentElement_ || this.getElement();
610 };
611
612
613 /**
614 * Returns the filter input element.
615 * @return {Element} Input element.
616 */
617 goog.ui.FilteredMenu.prototype.getFilterInputElement = function() {
618 return this.filterInput_ || null;
619 };
620
621
622 /** @override */
623 goog.ui.FilteredMenu.prototype.decorateInternal = function(element) {
624 this.setElementInternal(element);
625
626 // Decorate the menu content.
627 this.decorateContent(element);
628
629 // Locate internally managed elements.
630 var el = this.getDomHelper().getElementsByTagNameAndClass(
631 goog.dom.TagName.DIV,
632 goog.getCssName(this.getRenderer().getCssClass(), 'filter'), element)[0];
633 this.labelEl_ = goog.dom.getFirstElementChild(el);
634 this.filterInput_ = goog.dom.getNextElementSibling(this.labelEl_);
635 this.contentElement_ = goog.dom.getNextElementSibling(el);
636
637 // Decorate additional menu items (like 'apply').
638 this.getRenderer().decorateChildren(
639 this,
640 /** @type {!Element} */ (el.parentNode), this.contentElement_);
641
642 this.initFilterInput_();
643 };