enhance jquery.spinner, keeping backwards compatibility

Replaced single `id` argument to $.createSpinner with an options object.
The options allow one to set the id (as before), spinner size (small or
large), and its display mode (inline or block). Analogic change was made
to $.fn.injectSpinner.

Default options are kept the same as they used to be, and old-style calls
still work. However, the definition of .mw-spinner CSS class has been
changed (although, with a bit of hairy code, it could be kept
compatible...).

These changes should be enough to allow us to replace old usages of
.mw-small-spinner and .mw-ajax-loader classes, as defined in shared.css.

This is a reimplementation of the idea described in Ie55ffb6b.

Copied spinner.gif and ajax-loader.gif from /skins/common/images/.

Change-Id: I0ff71ba1eef299e0e699df84c68f1be1c20492f7

diff --git a/resources/jquery/images/spinner-large.gif b/resources/jquery/images/spinner-large.gif
new file mode 100644 (file)
index 0000000..72203fd
Binary files /dev/null and b/resources/jquery/images/spinner-large.gif differ

diff --git a/resources/jquery/images/spinner.gif b/resources/jquery/images/spinner.gif
index 37d3a43..6146be4 100644 (file)
Binary files a/resources/jquery/images/spinner.gif and b/resources/jquery/images/spinner.gif differ

diff --git a/resources/jquery/jquery.spinner.css b/resources/jquery/jquery.spinner.css
index 150a51b..4a77528 100644 (file)
--- a/resources/jquery/jquery.spinner.css
+++ b/resources/jquery/jquery.spinner.css
@@ -1,12 +1,40 @@
 .mw-spinner {
+       background-color: transparent;
+       background-position: center center;
+       background-repeat: no-repeat;
+}
+
+.mw-spinner-small {
        /* @embed */
-       background: transparent url(images/spinner.gif);
+       background-image: url(images/spinner.gif);
        height: 20px;
        width: 20px;
+       /* Avoid issues with .mw-spinner-block when floated without width. */
+       min-width: 20px;
+}
+
+.mw-spinner-large {
+       /* @embed */
+       background-image: url(images/spinner-large.gif);
+       height: 32px;
+       width: 32px;
+       /* Avoid issues with .mw-spinner-block when floated without width. */
+       min-width: 32px;
+}
+
+.mw-spinner-block {
+       display: block;
+       /* This overrides width from .mw-spinner-large / .mw-spinner-small,
+        * This is where the min-width kicks in.
+        */
+       width: 100%;
+}
+
+.mw-spinner-inline {
        display: inline-block;
        vertical-align: middle;
        
-       /* IE < 8 Hacks */
+       /* IE < 8 */
        zoom: 1;
        *display: inline;
-}
\ No newline at end of file
+}

diff --git a/resources/jquery/jquery.spinner.js b/resources/jquery/jquery.spinner.js
index e8b683e..4a6ec3b 100644 (file)
--- a/resources/jquery/jquery.spinner.js
+++ b/resources/jquery/jquery.spinner.js
@@ -5,40 +5,91 @@
  */
 ( function ( $ ) {
 
-       $.extend( {
+       // Default options for new spinners,
+       // stored outside the function to share between calls.
+       var defaults = {
+               id: undefined,
+               size: 'small',
+               type: 'inline'
+       };
+
+       $.extend({
                /**
                 * Creates a spinner element.
                 *
-                * @param id {String} id of the spinner
-                * @return {jQuery} spinner
+                * The argument is an object with options used to construct the spinner. These can be:
+                *
+                * It is a good practice to keep a reference to the created spinner to be able to remove it later.
+                * Alternatively one can use the id option and removeSpinner() (but make sure to choose an id
+                * that's unlikely to cause conflicts, e.g. with extensions, gadgets or user scripts).
+                *
+                * CSS classes used:
+                *   .mw-spinner for every spinner
+                *   .mw-spinner-small / .mw-spinner-large for size
+                *   .mw-spinner-block / .mw-spinner-inline for display types
+                *
+                * @example
+                *   // Create a large spinner reserving all available horizontal space.
+                *   var $spinner = $.createSpinner({ size: 'large', type: 'block' });
+                *   // Insert above page content.
+                *   $( '#mw-content-text' ).prepend( $spinner );
+                * @example
+                *   // Place a small inline spinner next to the "Save" button
+                *   var $spinner = $.createSpinner({ size: 'small', type: 'inline' });
+                *   // Alternatively, just `$.createSpinner();` as these are the default options.
+                *   $( '#wpSave' ).after( $spinner );
+                * @example
+                *   // The following two are equivalent:
+                *   $.createSpinner( 'magic' );
+                *   $.createSpinner({ id: 'magic' });
+                *
+                * @param {Object|String} opts [optional] ID string or options:
+                *  - id: If given, spinner will be given an id of "mw-spinner-<id>"
+                *  - size: 'small' (default) or 'large' for a 20-pixel or 32-pixel spinner
+                *  - type: 'inline' (default) or 'block'. Inline creates an inline-block with width and
+                *    height equal to spinner size. Block is a block-level element with width 100%, height
+                *    equal to spinner size.
+                * @return {jQuery}
                 */
-               createSpinner: function ( id ) {
-                       return $( '<div>' ).attr( {
-                               id: 'mw-spinner-' + id,
-                               'class': 'mw-spinner',
-                               title: '...'
-                       } );
+               createSpinner: function ( opts ) {
+                       if ( opts !== undefined && $.type( opts ) !== 'object' ) {
+                               opts = {
+                                       id: opts
+                               };
+                       }
+
+                       opts = $.extend( {}, defaults, opts );
+
+                       var $spinner = $( '<div>', { 'class': 'mw-spinner', 'title': '...' } );
+                       if ( opts.id !== undefined ) {
+                               $spinner.attr( 'id', 'mw-spinner-' + opts.id );
+                       }
+
+                       $spinner.addClass( opts.size === 'large' ? 'mw-spinner-large' : 'mw-spinner-small' );
+                       $spinner.addClass( opts.type === 'block' ? 'mw-spinner-block' : 'mw-spinner-inline' );
+
+                       return $spinner;
                },
 
                /**
                 * Removes a spinner element.
                 *
-                * @param id {String}
-                * @return {jQuery} spinner
+                * @param {String} id [optional] Id of the spinner, as passed to createSpinner.
+                * @return {jQuery} The (now detached) spinner.
                 */
                removeSpinner: function ( id ) {
                        return $( '#mw-spinner-' + id ).remove();
                }
-       } );
+       });
 
        /**
-        * Injects a spinner after the elements in the jQuery collection.
+        * Injects a spinner after the elements in the jQuery collection
+        * (as siblings, not children). Collection contents remain unchanged.
         *
-        * @param id String id of the spinner
+        * @param {Object} opts See createSpinner() for description.
         * @return {jQuery}
         */
-       $.fn.injectSpinner = function ( id ) {
-               return this.after( $.createSpinner( id ) );
+       $.fn.injectSpinner = function ( opts ) {
+               return this.after( $.createSpinner( opts ) );
        };
-
 }( jQuery ) );