[Summary view] [Print] [Text view]

   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              if ( opts !== undefined && $.type( opts ) !== 'object' ) {
  63                  opts = {
  64                      id: opts
  65                  };
  66              }
  67  
  68              opts = $.extend( {}, defaults, opts );
  69  
  70              var $spinner = $( '<div>', { 'class': 'mw-spinner', 'title': '...' } );
  71              if ( opts.id !== undefined ) {
  72                  $spinner.attr( 'id', 'mw-spinner-' + opts.id );
  73              }
  74  
  75              $spinner.addClass( opts.size === 'large' ? 'mw-spinner-large' : 'mw-spinner-small' );
  76              $spinner.addClass( opts.type === 'block' ? 'mw-spinner-block' : 'mw-spinner-inline' );
  77  
  78              return $spinner;
  79          },
  80  
  81          /**
  82           * Remove a spinner element
  83           *
  84           * @static
  85           * @inheritable
  86           * @param {string} id Id of the spinner, as passed to #createSpinner
  87           * @return {jQuery} The (now detached) spinner element
  88           */
  89          removeSpinner: function ( id ) {
  90              return $( '#mw-spinner-' + id ).remove();
  91          }
  92      } );
  93  
  94      /**
  95       * Inject a spinner after each element in the collection
  96       *
  97       * Inserts spinner as siblings (not children) of the target elements.
  98       * Collection contents remain unchanged.
  99       *
 100       * @param {Object|string} [opts] See #createSpinner
 101       * @return {jQuery}
 102       */
 103      $.fn.injectSpinner = function ( opts ) {
 104          return this.after( $.createSpinner( opts ) );
 105      };
 106  
 107      /**
 108       * @class jQuery
 109       * @mixins jQuery.plugin.spinner
 110       */
 111  
 112  }( jQuery ) );