WordPress.org

Make WordPress Core

Ticket #44325: 44325.diff

File 44325.diff, 5.1 KB (added by maartenleenders, 18 months ago)
  • src/js/_enqueues/lib/pointer.js

    diff --git a/src/js/_enqueues/lib/pointer.js b/src/js/_enqueues/lib/pointer.js
    index a6b13c7fa5..91acd801c2 100644
    a b  
    11/* global wpPointerL10n */
    22/**
    3  * Pointer jQuery widget.
     3 * Initializes the wp-pointer widget using jQuery UI Widget Factory.
    44 */
    55(function($){
    66        var identifier = 0,
    77                zindex = 9999;
    88
    99        /**
    10          * @class $.widget.wp.pointer
     10         * This is the jQuery widget function.
    1111         */
    1212        $.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
    1313                options: {
     
    3737                        document: document
    3838                },
    3939
     40                /**
     41                 * Constructs the wp.pointer class.
     42                 *
     43                 * @class   $.widget.wp.pointer
     44                 * @private
     45                 */
    4046                _create: function() {
    4147                        var positioning,
    4248                                family;
     
    5965                                .appendTo( this.options.document.body );
    6066                },
    6167
     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                 */
    6280                _setOption: function( key, value ) {
    6381                        var o   = this.options,
    6482                                tip = this.pointer;
     
    85103                        }
    86104                },
    87105
     106                /**
     107                 * Takes the pointer element out of the DOM and destroys the widget and all associated bindings
     108                 */
    88109                destroy: function() {
    89110                        this.pointer.remove();
    90111                        $.Widget.prototype.destroy.call( this );
    91112                },
    92113
     114                /**
     115                 * Returns the pointer element
     116                 *
     117                 * @returns {object} Pointer The pointer object
     118                 */
    93119                widget: function() {
    94120                        return this.pointer;
    95121                },
    96122
     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                 */
    97131                update: function( event ) {
    98132                        var self = this,
    99133                                o    = this.options,
     
    124158                },
    125159
    126160                /**
     161                 * Updates the content and calls reposition on the pointer
     162                 *
    127163                 * Update is separated into two functions to allow events to defer
    128164                 * 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
    129172                 */
    130173                _update: function( event, content ) {
    131174                        var buttons,
     
    145188                        this.reposition();
    146189                },
    147190
     191                /**
     192                 * Repositions the pointer, and calls the class's repoint function.
     193                 */
    148194                reposition: function() {
    149195                        var position;
    150196
     
    166212                        this.repoint();
    167213                },
    168214
     215                /**
     216                 * Sets the new edge of the object, and renames the arrow class.
     217                 *
     218                 * @returns {void}
     219                 */
    169220                repoint: function() {
    170221                        var o = this.options,
    171222                                edge;
     
    182233                        this.pointer.addClass( 'wp-pointer-' + edge );
    183234                },
    184235
     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                 */
    185243                _processPosition: function( position ) {
    186244                        var opposite = {
    187245                                        top: 'bottom',
     
    218276                        return result;
    219277                },
    220278
     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                 */
    221287                open: function( event ) {
    222288                        var self = this,
    223289                                o    = this.options;
     
    230296                        });
    231297                },
    232298
     299                /**
     300                 * Opens and shows the pointer element
     301                 *
     302                 * @param {Object} event An event object.
     303                 * @private
     304                 */
    233305                _open: function( event ) {
    234306                        var self = this,
    235307                                o    = this.options;
     
    248320                        }));
    249321                },
    250322
     323                /**
     324                 * Closes and hides the pointer element
     325                 *
     326                 * @param {Object} event An event object.
     327                 */
    251328                close: function( event ) {
    252329                        if ( !this.active || this.options.disabled )
    253330                                return;
     
    263340                        }));
    264341                },
    265342
     343                /**
     344                 * Puts the pointer on top by increasing the z-index
     345                 */
    266346                sendToTop: function() {
    267347                        if ( this.active )
    268348                                this.pointer.css( 'z-index', zindex++ );
    269349                },
    270350
     351                /**
     352                 * Toggles the element between shown and hidden
     353                 *
     354                 * @param {Object} event An event object.
     355                 */
    271356                toggle: function( event ) {
    272357                        if ( this.pointer.is(':hidden') )
    273358                                this.open( event );
     
    275360                                this.close( event );
    276361                },
    277362
     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                 */
    278372                _handoff: function( extend ) {
    279373                        return $.extend({
    280374                                pointer: this.pointer,