1/**
2 * @output wp-includes/js/wp-pointer.js
3 */
4
5/**
6 * Initializes the wp-pointer widget using jQuery UI Widget Factory.
7 */
8(function($){
9 var identifier = 0,
10 zindex = 9999;
11
12 $.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
13 options: {
14 pointerClass: 'wp-pointer',
15 pointerWidth: 320,
16 content: function() {
17 return $(this).text();
18 },
19 buttons: function( event, t ) {
20 var button = $('<a class="close" href="#"></a>').text( wp.i18n.__( 'Dismiss' ) );
21
22 return button.on( 'click.pointer', function(e) {
23 e.preventDefault();
24 t.element.pointer('close');
25 });
26 },
27 position: 'top',
28 show: function( event, t ) {
29 t.pointer.show();
30 t.opened();
31 },
32 hide: function( event, t ) {
33 t.pointer.hide();
34 t.closed();
35 },
36 document: document
37 },
38
39 /**
40 * A class that represents a WordPress pointer.
41 *
42 * @since 3.3.0
43 * @private
44 *
45 * @constructs $.widget.wp.pointer
46 */
47 _create: function() {
48 var positioning,
49 family;
50
51 this.content = $('<div class="wp-pointer-content"></div>');
52 this.arrow = $('<div class="wp-pointer-arrow"><div class="wp-pointer-arrow-inner"></div></div>');
53
54 family = this.element.parents().add( this.element );
55 positioning = 'absolute';
56
57 if ( family.filter(function(){ return 'fixed' === $(this).css('position'); }).length )
58 positioning = 'fixed';
59
60 this.pointer = $('<div />')
61 .append( this.content )
62 .append( this.arrow )
63 .attr('id', 'wp-pointer-' + identifier++)
64 .addClass( this.options.pointerClass )
65 .css({'position': positioning, 'width': this.options.pointerWidth+'px', 'display': 'none'})
66 .appendTo( this.options.document.body );
67 },
68
69 /**
70 * Sets an option on the pointer instance.
71 *
72 * There are 4 special values that do something extra:
73 *
74 * - `document` will transfer the pointer to the body of the new document
75 * specified by the value.
76 * - `pointerClass` will change the class of the pointer element.
77 * - `position` will reposition the pointer.
78 * - `content` will update the content of the pointer.
79 *
80 * @since 3.3.0
81 * @private
82 *
83 * @param {string} key The key of the option to set.
84 * @param {*} value The value to set the option to.
85 */
86 _setOption: function( key, value ) {
87 var o = this.options,
88 tip = this.pointer;
89
90 // Handle document transfer.
91 if ( key === 'document' && value !== o.document ) {
92 tip.detach().appendTo( value.body );
93
94 // Handle class change.
95 } else if ( key === 'pointerClass' ) {
96 tip.removeClass( o.pointerClass ).addClass( value );
97 }
98
99 // Call super method.
100 $.Widget.prototype._setOption.apply( this, arguments );
101
102 // Reposition automatically.
103 if ( key === 'position' ) {
104 this.reposition();
105
106 // Update content automatically if pointer is open.
107 } else if ( key === 'content' && this.active ) {
108 this.update();
109 }
110 },
111
112 /**
113 * Removes the pointer element from of the DOM.
114 *
115 * Makes sure that the widget and all associated bindings are destroyed.
116 *
117 * @since 3.3.0
118 */
119 destroy: function() {
120 this.pointer.remove();
121 $.Widget.prototype.destroy.call( this );
122 },
123
124 /**
125 * Returns the pointer element.
126 *
127 * @since 3.3.0
128 *
129 * @return {Object} Pointer The pointer object.
130 */
131 widget: function() {
132 return this.pointer;
133 },
134
135 /**
136 * Updates the content of the pointer.
137 *
138 * This function doesn't update the content of the pointer itself. That is done
139 * by the `_update` method. This method will make sure that the `_update` method
140 * is called with the right content.
141 *
142 * The content in the options can either be a string or a callback. If it is a
143 * callback the result of this callback is used as the content.
144 *
145 * @since 3.3.0
146 *
147 * @param {Object} event The event that caused the update.
148 *
149 * @return {Promise} Resolves when the update has been executed.
150 */
151 update: function( event ) {
152 var self = this,
153 o = this.options,
154 dfd = $.Deferred(),
155 content;
156
157 if ( o.disabled )
158 return;
159
160 dfd.done( function( content ) {
161 self._update( event, content );
162 });
163
164 // Either o.content is a string...
165 if ( typeof o.content === 'string' ) {
166 content = o.content;
167
168 // ...or o.content is a callback.
169 } else {
170 content = o.content.call( this.element[0], dfd.resolve, event, this._handoff() );
171 }
172
173 // If content is set, then complete the update.
174 if ( content )
175 dfd.resolve( content );
176
177 return dfd.promise();
178 },
179
180 /**
181 * Updates the content of the pointer.
182 *
183 * Will make sure that the pointer is correctly positioned.
184 *
185 * @since 3.3.0
186 * @private
187 *
188 * @param {Object} event The event that caused the update.
189 * @param {*} content The content object. Either a string or a jQuery tree.
190 */
191 _update: function( event, content ) {
192 var buttons,
193 o = this.options;
194
195 if ( ! content )
196 return;
197
198 // Kill any animations on the pointer.
199 this.pointer.stop();
200 this.content.html( content );
201
202 buttons = o.buttons.call( this.element[0], event, this._handoff() );
203 if ( buttons ) {
204 buttons.wrap('<div class="wp-pointer-buttons" />').parent().appendTo( this.content );
205 }
206
207 this.reposition();
208 },
209
210 /**
211 * Repositions the pointer.
212 *
213 * Makes sure the pointer is the correct size for its content and makes sure it
214 * is positioned to point to the right element.
215 *
216 * @since 3.3.0
217 */
218 reposition: function() {
219 var position;
220
221 if ( this.options.disabled )
222 return;
223
224 position = this._processPosition( this.options.position );
225
226 // Reposition pointer.
227 this.pointer.css({
228 top: 0,
229 left: 0,
230 zIndex: zindex++ // Increment the z-index so that it shows above other opened pointers.
231 }).show().position($.extend({
232 of: this.element,
233 collision: 'fit none'
234 }, position )); // The object comes before this.options.position so the user can override position.of.
235
236 this.repoint();
237 },
238
239 /**
240 * Sets the arrow of the pointer to the correct side of the pointer element.
241 *
242 * @since 3.3.0
243 */
244 repoint: function() {
245 var o = this.options,
246 edge;
247
248 if ( o.disabled )
249 return;
250
251 edge = ( typeof o.position == 'string' ) ? o.position : o.position.edge;
252
253 // Remove arrow classes.
254 this.pointer[0].className = this.pointer[0].className.replace( /wp-pointer-[^\s'"]*/, '' );
255
256 // Add arrow class.
257 this.pointer.addClass( 'wp-pointer-' + edge );
258 },
259
260 /**
261 * Calculates the correct position based on a position in the settings.
262 *
263 * @since 3.3.0
264 * @private
265 *
266 * @param {string|Object} position Either a side of a pointer or an object
267 * containing a pointer.
268 *
269 * @return {Object} result An object containing position related data.
270 */
271 _processPosition: function( position ) {
272 var opposite = {
273 top: 'bottom',
274 bottom: 'top',
275 left: 'right',
276 right: 'left'
277 },
278 result;
279
280 // If the position object is a string, it is shorthand for position.edge.
281 if ( typeof position == 'string' ) {
282 result = {
283 edge: position + ''
284 };
285 } else {
286 result = $.extend( {}, position );
287 }
288
289 if ( ! result.edge )
290 return result;
291
292 if ( result.edge == 'top' || result.edge == 'bottom' ) {
293 result.align = result.align || 'left';
294
295 result.at = result.at || result.align + ' ' + opposite[ result.edge ];
296 result.my = result.my || result.align + ' ' + result.edge;
297 } else {
298 result.align = result.align || 'top';
299
300 result.at = result.at || opposite[ result.edge ] + ' ' + result.align;
301 result.my = result.my || result.edge + ' ' + result.align;
302 }
303
304 return result;
305 },
306
307 /**
308 * Opens the pointer.
309 *
310 * Only opens the pointer widget in case it is closed and not disabled, and
311 * calls 'update' before doing so. Calling update makes sure that the pointer
312 * is correctly sized and positioned.
313 *
314 * @since 3.3.0
315 *
316 * @param {Object} event The event that triggered the opening of this pointer.
317 */
318 open: function( event ) {
319 var self = this,
320 o = this.options;
321
322 if ( this.active || o.disabled || this.element.is(':hidden') )
323 return;
324
325 this.update().done( function() {
326 self._open( event );
327 });
328 },
329
330 /**
331 * Opens and shows the pointer element.
332 *
333 * @since 3.3.0
334 * @private
335 *
336 * @param {Object} event An event object.
337 */
338 _open: function( event ) {
339 var self = this,
340 o = this.options;
341
342 if ( this.active || o.disabled || this.element.is(':hidden') )
343 return;
344
345 this.active = true;
346
347 this._trigger( 'open', event, this._handoff() );
348
349 this._trigger( 'show', event, this._handoff({
350 opened: function() {
351 self._trigger( 'opened', event, self._handoff() );
352 }
353 }));
354 },
355
356 /**
357 * Closes and hides the pointer element.
358 *
359 * @since 3.3.0
360 *
361 * @param {Object} event An event object.
362 */
363 close: function( event ) {
364 if ( !this.active || this.options.disabled )
365 return;
366
367 var self = this;
368 this.active = false;
369
370 this._trigger( 'close', event, this._handoff() );
371 this._trigger( 'hide', event, this._handoff({
372 closed: function() {
373 self._trigger( 'closed', event, self._handoff() );
374 }
375 }));
376 },
377
378 /**
379 * Puts the pointer on top by increasing the z-index.
380 *
381 * @since 3.3.0
382 */
383 sendToTop: function() {
384 if ( this.active )
385 this.pointer.css( 'z-index', zindex++ );
386 },
387
388 /**
389 * Toggles the element between shown and hidden.
390 *
391 * @since 3.3.0
392 *
393 * @param {Object} event An event object.
394 */
395 toggle: function( event ) {
396 if ( this.pointer.is(':hidden') )
397 this.open( event );
398 else
399 this.close( event );
400 },
401
402 /**
403 * Extends the pointer and the widget element with the supplied parameter, which
404 * is either an element or a function.
405 *
406 * @since 3.3.0
407 * @private
408 *
409 * @param {Object} extend The object to be merged into the original object.
410 *
411 * @return {Object} The extended object.
412 */
413 _handoff: function( extend ) {
414 return $.extend({
415 pointer: this.pointer,
416 element: this.element
417 }, extend);
418 }
419 });
420})(jQuery);
421