resources/jquery/jquery.spinner.js

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