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