Debian Codegraph @

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

raw
1 // Copyright 2008 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 Show hovercards with a delay after the mouse moves over an
17 * element of a specified type and with a specific attribute.
18 *
19 * @see ../demos/hovercard.html
20 */
21
22 goog.provide('goog.ui.HoverCard');
23 goog.provide('goog.ui.HoverCard.EventType');
24 goog.provide('goog.ui.HoverCard.TriggerEvent');
25
26 goog.require('goog.array');
27 goog.require('goog.dom');
28 goog.require('goog.events');
29 goog.require('goog.events.Event');
30 goog.require('goog.events.EventType');
31 goog.require('goog.ui.AdvancedTooltip');
32 goog.require('goog.ui.PopupBase');
33 goog.require('goog.ui.Tooltip');
34
35
36
37 /**
38 * Create a hover card object. Hover cards extend tooltips in that they don't
39 * have to be manually attached to each element that can cause them to display.
40 * Instead, you can create a function that gets called when the mouse goes over
41 * any element on your page, and returns whether or not the hovercard should be
42 * shown for that element.
43 *
44 * Alternatively, you can define a map of tag names to the attribute name each
45 * tag should have for that tag to trigger the hover card. See example below.
46 *
47 * Hovercards can also be triggered manually by calling
48 * {@code triggerForElement}, shown without a delay by calling
49 * {@code showForElement}, or triggered over other elements by calling
50 * {@code attach}. For the latter two cases, the application is responsible
51 * for calling {@code detach} when finished.
52 *
53 * HoverCard objects fire a TRIGGER event when the mouse moves over an element
54 * that can trigger a hovercard, and BEFORE_SHOW when the hovercard is
55 * about to be shown. Clients can respond to these events and can prevent the
56 * hovercard from being triggered or shown.
57 *
58 * @param {Function|Object} isAnchor Function that returns true if a given
59 * element should trigger the hovercard. Alternatively, it can be a map of
60 * tag names to the attribute that the tag should have in order to trigger
61 * the hovercard, e.g., {A: 'href'} for all links. Tag names must be all
62 * upper case; attribute names are case insensitive.
63 * @param {boolean=} opt_checkDescendants Use false for a performance gain if
64 * you are sure that none of your triggering elements have child elements.
65 * Default is true.
66 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper to use for
67 * creating and rendering the hovercard element.
68 * @param {Document=} opt_triggeringDocument Optional document to use in place
69 * of the one included in the DomHelper for finding triggering elements.
70 * Defaults to the document included in the DomHelper.
71 * @constructor
72 * @extends {goog.ui.AdvancedTooltip}
73 */
74 goog.ui.HoverCard = function(
75 isAnchor, opt_checkDescendants, opt_domHelper, opt_triggeringDocument) {
76 goog.ui.AdvancedTooltip.call(this, null, null, opt_domHelper);
77
78 if (goog.isFunction(isAnchor)) {
79 // Override default implementation of {@code isAnchor_}.
80 this.isAnchor_ = isAnchor;
81 } else {
82 /**
83 * Map of tag names to attribute names that will trigger a hovercard.
84 * @type {Object}
85 * @private
86 */
87 this.anchors_ = isAnchor;
88 }
89
90 /**
91 * Whether anchors may have child elements. If true, then we need to check
92 * the parent chain of any mouse over event to see if any of those elements
93 * could be anchors. Default is true.
94 * @type {boolean}
95 * @private
96 */
97 this.checkDescendants_ = opt_checkDescendants != false;
98
99 /**
100 * Array of anchor elements that should be detached when we are no longer
101 * associated with them.
102 * @type {!Array<Element>}
103 * @private
104 */
105 this.tempAttachedAnchors_ = [];
106
107 /**
108 * Document containing the triggering elements, to which we listen for
109 * mouseover events.
110 * @type {Document}
111 * @private
112 */
113 this.document_ = opt_triggeringDocument ||
114 (opt_domHelper ? opt_domHelper.getDocument() : goog.dom.getDocument());
115
116 goog.events.listen(
117 this.document_, goog.events.EventType.MOUSEOVER,
118 this.handleTriggerMouseOver_, false, this);
119 };
120 goog.inherits(goog.ui.HoverCard, goog.ui.AdvancedTooltip);
121 goog.tagUnsealableClass(goog.ui.HoverCard);
122
123
124 /**
125 * Enum for event type fired by HoverCard.
126 * @enum {string}
127 */
128 goog.ui.HoverCard.EventType = {
129 TRIGGER: 'trigger',
130 CANCEL_TRIGGER: 'canceltrigger',
131 BEFORE_SHOW: goog.ui.PopupBase.EventType.BEFORE_SHOW,
132 SHOW: goog.ui.PopupBase.EventType.SHOW,
133 BEFORE_HIDE: goog.ui.PopupBase.EventType.BEFORE_HIDE,
134 HIDE: goog.ui.PopupBase.EventType.HIDE
135 };
136
137
138 /** @override */
139 goog.ui.HoverCard.prototype.disposeInternal = function() {
140 goog.ui.HoverCard.superClass_.disposeInternal.call(this);
141
142 goog.events.unlisten(
143 this.document_, goog.events.EventType.MOUSEOVER,
144 this.handleTriggerMouseOver_, false, this);
145 };
146
147
148 /**
149 * Anchor of hovercard currently being shown. This may be different from
150 * {@code anchor} property if a second hovercard is triggered, when
151 * {@code anchor} becomes the second hovercard while {@code currentAnchor_}
152 * is still the old (but currently displayed) anchor.
153 * @type {Element}
154 * @private
155 */
156 goog.ui.HoverCard.prototype.currentAnchor_;
157
158
159 /**
160 * Maximum number of levels to search up the dom when checking descendants.
161 * @type {number}
162 * @private
163 */
164 goog.ui.HoverCard.prototype.maxSearchSteps_;
165
166
167 /**
168 * This function can be overridden by passing a function as the first parameter
169 * to the constructor.
170 * @param {Node} node Node to test.
171 * @return {boolean} Whether or not hovercard should be shown.
172 * @private
173 */
174 goog.ui.HoverCard.prototype.isAnchor_ = function(node) {
175 return node.tagName in this.anchors_ &&
176 !!node.getAttribute(this.anchors_[node.tagName]);
177 };
178
179
180 /**
181 * If the user mouses over an element with the correct tag and attribute, then
182 * trigger the hovercard for that element. If anchors could have children, then
183 * we also need to check the parent chain of the given element.
184 * @param {goog.events.Event} e Mouse over event.
185 * @private
186 */
187 goog.ui.HoverCard.prototype.handleTriggerMouseOver_ = function(e) {
188 var target = /** @type {Element} */ (e.target);
189 // Target might be null when hovering over disabled input textboxes in IE.
190 if (!target) {
191 return;
192 }
193 if (this.isAnchor_(target)) {
194 this.setPosition(null);
195 this.triggerForElement(target);
196 } else if (this.checkDescendants_) {
197 var trigger = goog.dom.getAncestor(
198 target, goog.bind(this.isAnchor_, this), false, this.maxSearchSteps_);
199 if (trigger) {
200 this.setPosition(null);
201 this.triggerForElement(/** @type {!Element} */ (trigger));
202 }
203 }
204 };
205
206
207 /**
208 * Triggers the hovercard to show after a delay.
209 * @param {Element} anchorElement Element that is triggering the hovercard.
210 * @param {goog.positioning.AbstractPosition=} opt_pos Position to display
211 * hovercard.
212 * @param {Object=} opt_data Data to pass to the onTrigger event.
213 */
214 goog.ui.HoverCard.prototype.triggerForElement = function(
215 anchorElement, opt_pos, opt_data) {
216 if (anchorElement == this.currentAnchor_) {
217 // Element is already showing, just make sure it doesn't hide.
218 this.clearHideTimer();
219 return;
220 }
221 if (anchorElement == this.anchor) {
222 // Hovercard is pending, no need to retrigger.
223 return;
224 }
225
226 // If a previous hovercard was being triggered, cancel it.
227 this.maybeCancelTrigger_();
228
229 // Create a new event for this trigger
230 var triggerEvent = new goog.ui.HoverCard.TriggerEvent(
231 goog.ui.HoverCard.EventType.TRIGGER, this, anchorElement, opt_data);
232
233 if (!this.getElements().contains(anchorElement)) {
234 this.attach(anchorElement);
235 this.tempAttachedAnchors_.push(anchorElement);
236 }
237 this.anchor = anchorElement;
238 if (!this.onTrigger(triggerEvent)) {
239 this.onCancelTrigger();
240 return;
241 }
242 var pos = opt_pos || this.getPosition();
243 this.startShowTimer(
244 anchorElement,
245 /** @type {goog.positioning.AbstractPosition} */ (pos));
246 };
247
248
249 /**
250 * Sets the current anchor element at the time that the hovercard is shown.
251 * @param {Element} anchor New current anchor element, or null if there is
252 * no current anchor.
253 * @private
254 */
255 goog.ui.HoverCard.prototype.setCurrentAnchor_ = function(anchor) {
256 if (anchor != this.currentAnchor_) {
257 this.detachTempAnchor_(this.currentAnchor_);
258 }
259 this.currentAnchor_ = anchor;
260 };
261
262
263 /**
264 * If given anchor is in the list of temporarily attached anchors, then
265 * detach and remove from the list.
266 * @param {Element|undefined} anchor Anchor element that we may want to detach
267 * from.
268 * @private
269 */
270 goog.ui.HoverCard.prototype.detachTempAnchor_ = function(anchor) {
271 if (anchor) {
272 var pos = goog.array.indexOf(this.tempAttachedAnchors_, anchor);
273 if (pos != -1) {
274 this.detach(anchor);
275 this.tempAttachedAnchors_.splice(pos, 1);
276 }
277 }
278 };
279
280
281 /**
282 * Called when an element triggers the hovercard. This will return false
283 * if an event handler sets preventDefault to true, which will prevent
284 * the hovercard from being shown.
285 * @param {!goog.ui.HoverCard.TriggerEvent} triggerEvent Event object to use
286 * for trigger event.
287 * @return {boolean} Whether hovercard should be shown or cancelled.
288 * @protected
289 */
290 goog.ui.HoverCard.prototype.onTrigger = function(triggerEvent) {
291 return this.dispatchEvent(triggerEvent);
292 };
293
294
295 /**
296 * Abort pending hovercard showing, if any.
297 */
298 goog.ui.HoverCard.prototype.cancelTrigger = function() {
299 this.clearShowTimer();
300 this.onCancelTrigger();
301 };
302
303
304 /**
305 * If hovercard is in the process of being triggered, then cancel it.
306 * @private
307 */
308 goog.ui.HoverCard.prototype.maybeCancelTrigger_ = function() {
309 if (this.getState() == goog.ui.Tooltip.State.WAITING_TO_SHOW ||
310 this.getState() == goog.ui.Tooltip.State.UPDATING) {
311 this.cancelTrigger();
312 }
313 };
314
315
316 /**
317 * This method gets called when we detect that a trigger event will not lead
318 * to the hovercard being shown.
319 * @protected
320 */
321 goog.ui.HoverCard.prototype.onCancelTrigger = function() {
322 var event = new goog.ui.HoverCard.TriggerEvent(
323 goog.ui.HoverCard.EventType.CANCEL_TRIGGER, this, this.anchor || null);
324 this.dispatchEvent(event);
325 this.detachTempAnchor_(this.anchor);
326 delete this.anchor;
327 };
328
329
330 /**
331 * Gets the DOM element that triggered the current hovercard. Note that in
332 * the TRIGGER or CANCEL_TRIGGER events, the current hovercard's anchor may not
333 * be the one that caused the event, so use the event's anchor property instead.
334 * @return {Element} Object that caused the currently displayed hovercard (or
335 * pending hovercard if none is displayed) to be triggered.
336 */
337 goog.ui.HoverCard.prototype.getAnchorElement = function() {
338 // this.currentAnchor_ is only set if the hovercard is showing. If it isn't
339 // showing yet, then use this.anchor as the pending anchor.
340 return /** @type {Element} */ (this.currentAnchor_ || this.anchor);
341 };
342
343
344 /**
345 * Make sure we detach from temp anchor when we are done displaying hovercard.
346 * @protected
347 * @override
348 */
349 goog.ui.HoverCard.prototype.onHide = function() {
350 goog.ui.HoverCard.superClass_.onHide.call(this);
351 this.setCurrentAnchor_(null);
352 };
353
354
355 /**
356 * This mouse over event is only received if the anchor is already attached.
357 * If it was attached manually, then it may need to be triggered.
358 * @param {goog.events.BrowserEvent} event Mouse over event.
359 * @override
360 */
361 goog.ui.HoverCard.prototype.handleMouseOver = function(event) {
362 // If this is a child of a triggering element, find the triggering element.
363 var trigger = this.getAnchorFromElement(
364 /** @type {Element} */ (event.target));
365
366 // If we moused over an element different from the one currently being
367 // triggered (if any), then trigger this new element.
368 if (trigger && trigger != this.anchor) {
369 this.triggerForElement(trigger);
370 return;
371 }
372
373 goog.ui.HoverCard.superClass_.handleMouseOver.call(this, event);
374 };
375
376
377 /**
378 * If the mouse moves out of the trigger while we're being triggered, then
379 * cancel it.
380 * @param {goog.events.BrowserEvent} event Mouse out or blur event.
381 * @override
382 */
383 goog.ui.HoverCard.prototype.handleMouseOutAndBlur = function(event) {
384 // Get ready to see if a trigger should be cancelled.
385 var anchor = this.anchor;
386 var state = this.getState();
387 goog.ui.HoverCard.superClass_.handleMouseOutAndBlur.call(this, event);
388 if (state != this.getState() &&
389 (state == goog.ui.Tooltip.State.WAITING_TO_SHOW ||
390 state == goog.ui.Tooltip.State.UPDATING)) {
391 // Tooltip's handleMouseOutAndBlur method sets anchor to null. Reset
392 // so that the cancel trigger event will have the right data, and so that
393 // it will be properly detached.
394 this.anchor = anchor;
395 this.onCancelTrigger(); // This will remove and detach the anchor.
396 }
397 };
398
399
400 /**
401 * Called by timer from mouse over handler. If this is called and the hovercard
402 * is not shown for whatever reason, then send a cancel trigger event.
403 * @param {Element} el Element to show tooltip for.
404 * @param {goog.positioning.AbstractPosition=} opt_pos Position to display popup
405 * at.
406 * @override
407 */
408 goog.ui.HoverCard.prototype.maybeShow = function(el, opt_pos) {
409 goog.ui.HoverCard.superClass_.maybeShow.call(this, el, opt_pos);
410
411 if (!this.isVisible()) {
412 this.cancelTrigger();
413 } else {
414 this.setCurrentAnchor_(el);
415 }
416 };
417
418
419 /**
420 * Sets the max number of levels to search up the dom if checking descendants.
421 * @param {number} maxSearchSteps Maximum number of levels to search up the
422 * dom if checking descendants.
423 */
424 goog.ui.HoverCard.prototype.setMaxSearchSteps = function(maxSearchSteps) {
425 if (!maxSearchSteps) {
426 this.checkDescendants_ = false;
427 } else if (this.checkDescendants_) {
428 this.maxSearchSteps_ = maxSearchSteps;
429 }
430 };
431
432
433
434 /**
435 * Create a trigger event for specified anchor and optional data.
436 * @param {goog.ui.HoverCard.EventType} type Event type.
437 * @param {goog.ui.HoverCard} target Hovercard that is triggering the event.
438 * @param {Element} anchor Element that triggered event.
439 * @param {Object=} opt_data Optional data to be available in the TRIGGER event.
440 * @constructor
441 * @extends {goog.events.Event}
442 * @final
443 */
444 goog.ui.HoverCard.TriggerEvent = function(type, target, anchor, opt_data) {
445 goog.events.Event.call(this, type, target);
446
447 /**
448 * Element that triggered the hovercard event.
449 * @type {Element}
450 */
451 this.anchor = anchor;
452
453 /**
454 * Optional data to be passed to the listener.
455 * @type {Object|undefined}
456 */
457 this.data = opt_data;
458 };
459 goog.inherits(goog.ui.HoverCard.TriggerEvent, goog.events.Event);