resources/src/jquery.spinner/spinner.js

   1 /**
   2  * Provides a {@link jQuery} plugins that manage spinners.
   3  *
   4  * To use these jQuery plugins, load the `jquery.spinner` module with {@link mw.loader}.
   5  *
   6  * @example
   7  * mw.loader.using( 'jquery.spinner' ).then( () => {
   8  *       $( '#bodyContent' ).injectSpinner();
   9  * } );
  10  *
  11  * @module jquery.spinner
  12  */
  13 ( function () {
  14
  15         /**
  16          * Default options for new spinners,
  17          * stored outside the function to share between calls.
  18          *
  19          * @type {module:jquery.spinner~SpinnerOpts}
  20          */
  21         const defaults = {
  22                 id: undefined,
  23                 size: 'small',
  24                 type: 'inline'
  25         };
  26
  27         /**
  28          * @typedef {Object} module:jquery.spinner~SpinnerOpts Options for {@link module:jquery.spinner.$.fn.injectSpinner injectSpinner}.
  29          * @property {string} [id] If given, spinner will be given an id of "mw-spinner-{id}".
  30          * @property {'small'|'large'} [size='small'] 'small' or 'large' for a 20-pixel or 32-pixel spinner.
  31          * @property {'inline'|'block'} [type='inline'] 'inline' or 'block'. Inline creates an inline-block with
  32          *   width and height equal to spinner size. Block is a block-level element with width 100%,
  33          *   height equal to spinner size.
  34          */
  35
  36         $.extend( {
  37                 /**
  38                  * Create a spinner element
  39                  *
  40                  * The argument is an object with options used to construct the spinner (see below).
  41                  *
  42                  * It is a good practice to keep a reference to the created spinner to be able to remove it later.
  43                  * Alternatively, one can use the 'id' option and {@link module:jquery.spinner.removeSpinner removeSpinner}
  44                  * (but make sure to choose an id that's unlikely to cause conflicts, e.g. with extensions, gadgets or user scripts).
  45                  *
  46                  * CSS classes used:
  47                  *
  48                  * - .mw-spinner for every spinner
  49                  * - .mw-spinner-small / .mw-spinner-large for size
  50                  * - .mw-spinner-block / .mw-spinner-inline for display types
  51                  *
  52                  * @example
  53                  * // Create a large spinner reserving all available horizontal space.
  54                  * const $spinner = $.createSpinner( { size: 'large', type: 'block' } );
  55                  * // Insert above page content.
  56                  * $( '#mw-content-text' ).prepend( $spinner );
  57                  *
  58                  * // Place a small inline spinner next to the "Save" button
  59                  * const $spinner = $.createSpinner( { size: 'small', type: 'inline' } );
  60                  * // Alternatively, just `$.createSpinner();` as these are the default options.
  61                  * $( '#wpSave' ).after( $spinner );
  62                  *
  63                  * // The following two are equivalent:
  64                  * $.createSpinner( 'magic' );
  65                  * $.createSpinner( { id: 'magic' } );
  66                  *
  67                  * @memberof module:jquery.spinner
  68                  * @static
  69                  * @inheritable
  70                  * @param {module:jquery.spinner~SpinnerOpts|string} [opts] Options. If a string is given, it will be treated as the value
  71                  *   of the {@link module:mediawiki.jqueryMsg~SpinnerOpts#id} option.
  72                  * @return {jQuery}
  73                  */
  74                 createSpinner: ( opts ) => {
  75                         if ( typeof opts === 'string' ) {
  76                                 opts = {
  77                                         id: opts
  78                                 };
  79                         }
  80
  81                         opts = Object.assign( {}, defaults, opts );
  82
  83                         const $spinner = $( '<div>' ).addClass( 'mw-spinner' );
  84                         if ( opts.id !== undefined ) {
  85                                 $spinner.attr( 'id', 'mw-spinner-' + opts.id );
  86                         }
  87
  88                         $spinner
  89                                 .addClass( opts.size === 'large' ? 'mw-spinner-large' : 'mw-spinner-small' )
  90                                 .addClass( opts.type === 'block' ? 'mw-spinner-block' : 'mw-spinner-inline' );
  91
  92                         const $container = $( '<div>' ).addClass( 'mw-spinner-container' ).appendTo( $spinner );
  93                         for ( let i = 0; i < 12; i++ ) {
  94                                 $container.append( $( '<div>' ) );
  95                         }
  96
  97                         return $spinner;
  98                 },
  99
 100                 /**
 101                  * Remove a spinner element
 102                  *
 103                  * @memberof module:jquery.spinner
 104                  * @inheritable
 105                  * @param {string} id Id of the spinner, as passed to {@link module:jquery.spinner.createSpinner createSpinner}
 106                  * @return {jQuery} The (now detached) spinner element
 107                  */
 108                 removeSpinner: ( id ) => $( '#mw-spinner-' + id ).remove()
 109         } );
 110
 111         /**
 112          * Inject a spinner after each element in the collection.
 113          *
 114          * Inserts spinner as siblings (not children) of the target elements.
 115          * Collection contents remain unchanged.
 116          *
 117          * @memberof module:jquery.spinner
 118          * @param {module:jquery.spinner~SpinnerOpts|string} [opts] Options. If a string is given, it will be treated as the value
 119          *   of the {@link module:jquery.spinner~SpinnerOpts SpinnerOpts id} option.
 120          * @return {jQuery}
 121          */
 122         $.fn.injectSpinner = function ( opts ) {
 123                 return this.after( $.createSpinner( opts ) );
 124         };
 125
 126         /**
 127          * @class jQuery
 128          * @mixes jQuery.plugin.spinner
 129          */
 130
 131 }() );