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