resources/src/jquery/jquery.spinner.js

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