diff --git a/src/js/_enqueues/lib/pointer.js b/src/js/_enqueues/lib/pointer.js
index a6b13c7fa5..91acd801c2 100644
a
|
b
|
|
1 | 1 | /* global wpPointerL10n */ |
2 | 2 | /** |
3 | | * Pointer jQuery widget. |
| 3 | * Initializes the wp-pointer widget using jQuery UI Widget Factory. |
4 | 4 | */ |
5 | 5 | (function($){ |
6 | 6 | var identifier = 0, |
7 | 7 | zindex = 9999; |
8 | 8 | |
9 | 9 | /** |
10 | | * @class $.widget.wp.pointer |
| 10 | * This is the jQuery widget function. |
11 | 11 | */ |
12 | 12 | $.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{ |
13 | 13 | options: { |
… |
… |
|
37 | 37 | document: document |
38 | 38 | }, |
39 | 39 | |
| 40 | /** |
| 41 | * Constructs the wp.pointer class. |
| 42 | * |
| 43 | * @class $.widget.wp.pointer |
| 44 | * @private |
| 45 | */ |
40 | 46 | _create: function() { |
41 | 47 | var positioning, |
42 | 48 | family; |
… |
… |
|
59 | 65 | .appendTo( this.options.document.body ); |
60 | 66 | }, |
61 | 67 | |
| 68 | /** |
| 69 | * Set options for the wp-pointer class. |
| 70 | * |
| 71 | * Changes to the document option will transfer the pointer to the body of the new document specified in the value. |
| 72 | * Changes to the pointerClass option will remove the current class and add the class specified in the value. |
| 73 | * Changes to the position option will call the reposition function. |
| 74 | * Changes to the content option will call the update function. |
| 75 | * |
| 76 | * @param {string} key The key of the option set. |
| 77 | * @param {*} value The value to set to the option key. |
| 78 | * @private |
| 79 | */ |
62 | 80 | _setOption: function( key, value ) { |
63 | 81 | var o = this.options, |
64 | 82 | tip = this.pointer; |
… |
… |
|
85 | 103 | } |
86 | 104 | }, |
87 | 105 | |
| 106 | /** |
| 107 | * Takes the pointer element out of the DOM and destroys the widget and all associated bindings |
| 108 | */ |
88 | 109 | destroy: function() { |
89 | 110 | this.pointer.remove(); |
90 | 111 | $.Widget.prototype.destroy.call( this ); |
91 | 112 | }, |
92 | 113 | |
| 114 | /** |
| 115 | * Returns the pointer element |
| 116 | * |
| 117 | * @returns {object} Pointer The pointer object |
| 118 | */ |
93 | 119 | widget: function() { |
94 | 120 | return this.pointer; |
95 | 121 | }, |
96 | 122 | |
| 123 | /** |
| 124 | * Updates the content of the pointer. |
| 125 | * |
| 126 | * The content is updated to what content is in options, which can |
| 127 | * either be a string or a callback function. |
| 128 | * |
| 129 | * @param {Object} event The event that caused the update. |
| 130 | */ |
97 | 131 | update: function( event ) { |
98 | 132 | var self = this, |
99 | 133 | o = this.options, |
… |
… |
|
124 | 158 | }, |
125 | 159 | |
126 | 160 | /** |
| 161 | * Updates the content and calls reposition on the pointer |
| 162 | * |
127 | 163 | * Update is separated into two functions to allow events to defer |
128 | 164 | * updating the pointer (e.g. fetch content with ajax, etc). |
| 165 | * |
| 166 | * @private |
| 167 | * |
| 168 | * @param {Object} event An event object. |
| 169 | * @param {Object} content The content object. |
| 170 | * |
| 171 | * @returns void |
129 | 172 | */ |
130 | 173 | _update: function( event, content ) { |
131 | 174 | var buttons, |
… |
… |
|
145 | 188 | this.reposition(); |
146 | 189 | }, |
147 | 190 | |
| 191 | /** |
| 192 | * Repositions the pointer, and calls the class's repoint function. |
| 193 | */ |
148 | 194 | reposition: function() { |
149 | 195 | var position; |
150 | 196 | |
… |
… |
|
166 | 212 | this.repoint(); |
167 | 213 | }, |
168 | 214 | |
| 215 | /** |
| 216 | * Sets the new edge of the object, and renames the arrow class. |
| 217 | * |
| 218 | * @returns {void} |
| 219 | */ |
169 | 220 | repoint: function() { |
170 | 221 | var o = this.options, |
171 | 222 | edge; |
… |
… |
|
182 | 233 | this.pointer.addClass( 'wp-pointer-' + edge ); |
183 | 234 | }, |
184 | 235 | |
| 236 | /** |
| 237 | * Processes the position for the pointer relative to the target element |
| 238 | * |
| 239 | * @param position |
| 240 | * @returns {Object} result An object containing position related data |
| 241 | * @private |
| 242 | */ |
185 | 243 | _processPosition: function( position ) { |
186 | 244 | var opposite = { |
187 | 245 | top: 'bottom', |
… |
… |
|
218 | 276 | return result; |
219 | 277 | }, |
220 | 278 | |
| 279 | /** |
| 280 | * Opens the widget pointer |
| 281 | * |
| 282 | * Only opens the widget pointer in case it is closed and not disabled, |
| 283 | * and calls 'update' before doing so |
| 284 | * |
| 285 | * @param {Object} event The event to use as callback on completed update |
| 286 | */ |
221 | 287 | open: function( event ) { |
222 | 288 | var self = this, |
223 | 289 | o = this.options; |
… |
… |
|
230 | 296 | }); |
231 | 297 | }, |
232 | 298 | |
| 299 | /** |
| 300 | * Opens and shows the pointer element |
| 301 | * |
| 302 | * @param {Object} event An event object. |
| 303 | * @private |
| 304 | */ |
233 | 305 | _open: function( event ) { |
234 | 306 | var self = this, |
235 | 307 | o = this.options; |
… |
… |
|
248 | 320 | })); |
249 | 321 | }, |
250 | 322 | |
| 323 | /** |
| 324 | * Closes and hides the pointer element |
| 325 | * |
| 326 | * @param {Object} event An event object. |
| 327 | */ |
251 | 328 | close: function( event ) { |
252 | 329 | if ( !this.active || this.options.disabled ) |
253 | 330 | return; |
… |
… |
|
263 | 340 | })); |
264 | 341 | }, |
265 | 342 | |
| 343 | /** |
| 344 | * Puts the pointer on top by increasing the z-index |
| 345 | */ |
266 | 346 | sendToTop: function() { |
267 | 347 | if ( this.active ) |
268 | 348 | this.pointer.css( 'z-index', zindex++ ); |
269 | 349 | }, |
270 | 350 | |
| 351 | /** |
| 352 | * Toggles the element between shown and hidden |
| 353 | * |
| 354 | * @param {Object} event An event object. |
| 355 | */ |
271 | 356 | toggle: function( event ) { |
272 | 357 | if ( this.pointer.is(':hidden') ) |
273 | 358 | this.open( event ); |
… |
… |
|
275 | 360 | this.close( event ); |
276 | 361 | }, |
277 | 362 | |
| 363 | /** |
| 364 | * Extends the pointer and the widget element with the supplied parameter, which is either an element or a function |
| 365 | * |
| 366 | * @private |
| 367 | * |
| 368 | * @param {Object} extend The object to be merged into the original object. |
| 369 | * |
| 370 | * @returns {Object} The extended object. |
| 371 | */ |
278 | 372 | _handoff: function( extend ) { |
279 | 373 | return $.extend({ |
280 | 374 | pointer: this.pointer, |