resources/src/mediawiki.toolbar/toolbar.js

   1 /**
   2  * Interface for the classic edit toolbar.
   3  *
   4  * @class mw.toolbar
   5  * @singleton
   6  */
   7 ( function ( mw, $ ) {
   8         var toolbar, isReady, $toolbar, queue, slice, $currentFocused;
   9
  10         /**
  11          * Internal helper that does the actual insertion of the button into the toolbar.
  12          *
  13          * See #addButton for parameter documentation.
  14          *
  15          * @private
  16          */
  17         function insertButton( b, speedTip, tagOpen, tagClose, sampleText, imageId ) {
  18                 var $button;
  19
  20                 // Backwards compatibility
  21                 if ( typeof b !== 'object' ) {
  22                         b = {
  23                                 imageFile: b,
  24                                 speedTip: speedTip,
  25                                 tagOpen: tagOpen,
  26                                 tagClose: tagClose,
  27                                 sampleText: sampleText,
  28                                 imageId: imageId
  29                         };
  30                 }
  31
  32                 if ( b.imageFile ) {
  33                         $button = $( '<img>' ).attr( {
  34                         src: b.imageFile,
  35                         alt: b.speedTip,
  36                         title: b.speedTip,
  37                         id: b.imageId || undefined,
  38                         'class': 'mw-toolbar-editbutton'
  39                         } );
  40                 } else {
  41                         $button = $( '<div>' ).attr( {
  42                                 title: b.speedTip,
  43                                 id: b.imageId || undefined,
  44                                 'class': 'mw-toolbar-editbutton'
  45                         } );
  46                 }
  47
  48                 $button.click( function ( e ) {
  49                         if ( b.onClick !== undefined ) {
  50                                 b.onClick( e );
  51                         } else {
  52                                 toolbar.insertTags( b.tagOpen, b.tagClose, b.sampleText );
  53                         }
  54
  55                         return false;
  56                 } );
  57
  58                 $toolbar.append( $button );
  59         }
  60
  61         isReady = false;
  62         $toolbar = false;
  63
  64         /**
  65          * @private
  66          * @property {Array}
  67          * Contains button objects (and for backwards compatibilty, it can
  68          * also contains an arguments array for insertButton).
  69          */
  70         queue = [];
  71         slice = queue.slice;
  72
  73         toolbar = {
  74
  75                 /**
  76                  * Add buttons to the toolbar.
  77                  *
  78                  * Takes care of race conditions and time-based dependencies
  79                  * by placing buttons in a queue if this method is called before
  80                  * the toolbar is created.
  81                  *
  82                  * For backwards-compatibility, passing `imageFile`, `speedTip`, `tagOpen`, `tagClose`,
  83                  * `sampleText` and `imageId` as separate arguments (in this order) is also supported.
  84                  *
  85                  * @param {Object} button Object with the following properties.
  86                  *  You are required to provide *either* the `onClick` parameter, or the three parameters
  87                  *  `tagOpen`, `tagClose` and `sampleText`, but not both (they're mutually exclusive).
  88                  * @param {string} [button.imageFile] Image to use for the button.
  89                  * @param {string} button.speedTip Tooltip displayed when user mouses over the button.
  90                  * @param {Function} [button.onClick] Function to be executed when the button is clicked.
  91                  * @param {string} [button.tagOpen]
  92                  * @param {string} [button.tagClose]
  93                  * @param {string} [button.sampleText] Alternative to `onClick`. `tagOpen`, `tagClose` and
  94                  *  `sampleText` together provide the markup that should be inserted into page text at
  95                  *  current cursor position.
  96                  * @param {string} [button.imageId] `id` attribute of the button HTML element. Can be
  97          *  used to define the image with CSS if it's not provided as `imageFile`.
  98                  */
  99                 addButton: function () {
 100                         if ( isReady ) {
 101                                 insertButton.apply( toolbar, arguments );
 102                         } else {
 103                                 // Convert arguments list to array
 104                                 queue.push( slice.call( arguments ) );
 105                         }
 106                 },
 107                 /**
 108                  * Add multiple buttons to the toolbar (see also #addButton).
 109                  *
 110                  * Example usage:
 111                  *
 112                  *     addButtons( [ { .. }, { .. }, { .. } ] );
 113                  *     addButtons( { .. }, { .. } );
 114                  *
 115                  * @param {Object|Array...} [buttons] An array of button objects or the first
 116                  *  button object in a list of variadic arguments.
 117                  */
 118                 addButtons: function ( buttons ) {
 119                         if ( !$.isArray( buttons ) ) {
 120                                 buttons = slice.call( arguments );
 121                         }
 122                         if ( isReady ) {
 123                                 $.each( buttons, function () {
 124                                         insertButton( this );
 125                                 } );
 126                         } else {
 127                                 // Push each button into the queue
 128                                 queue.push.apply( queue, buttons );
 129                         }
 130                 },
 131
 132                 /**
 133                  * Apply tagOpen/tagClose to selection in currently focused textarea.
 134                  *
 135                  * Uses `sampleText` if selection is empty.
 136                  *
 137                  * @param {string} tagOpen
 138                  * @param {string} tagClose
 139                  * @param {string} sampleText
 140                  */
 141                 insertTags: function ( tagOpen, tagClose, sampleText ) {
 142                         if ( $currentFocused && $currentFocused.length ) {
 143                                 $currentFocused.textSelection(
 144                                         'encapsulateSelection', {
 145                                                 pre: tagOpen,
 146                                                 peri: sampleText,
 147                                                 post: tagClose
 148                                         }
 149                                 );
 150                         }
 151                 },
 152
 153                 // For backwards compatibility,
 154                 // Called from EditPage.php, maybe in other places as well.
 155                 init: function () {}
 156         };
 157
 158         // Legacy (for compatibility with the code previously in skins/common.edit.js)
 159         mw.log.deprecate( window, 'addButton', toolbar.addButton, 'Use mw.toolbar.addButton instead.' );
 160         mw.log.deprecate( window, 'insertTags', toolbar.insertTags, 'Use mw.toolbar.insertTags instead.' );
 161
 162         // Expose API publicly
 163         mw.toolbar = toolbar;
 164
 165         $( function () {
 166                 var i, b;
 167
 168                 // Used to determine where to insert tags
 169                 $currentFocused = $( '#wpTextbox1' );
 170
 171                 // Populate the selector cache for $toolbar
 172                 $toolbar = $( '#toolbar' );
 173
 174                 for ( i = 0; i < queue.length; i++ ) {
 175                         b = queue[i];
 176                         if ( $.isArray( b ) ) {
 177                                 // Forwarded arguments array from mw.toolbar.addButton
 178                                 insertButton.apply( toolbar, b );
 179                         } else {
 180                                 // Raw object from mw.toolbar.addButtons
 181                                 insertButton( b );
 182                         }
 183                 }
 184
 185                 // Clear queue
 186                 queue.length = 0;
 187
 188                 // This causes further calls to addButton to go to insertion directly
 189                 // instead of to the queue.
 190                 // It is important that this is after the one and only loop through
 191                 // the the queue
 192                 isReady = true;
 193
 194                 // Apply to dynamically created textboxes as well as normal ones
 195                 $( document ).on( 'focus', 'textarea, input:text', function () {
 196                         $currentFocused = $( this );
 197                 } );
 198         } );
 199
 200 }( mediaWiki, jQuery ) );