sources/plugins/button/plugin.js

   1 /**
   2  * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
   3  * For licensing, see LICENSE.md or http://ckeditor.com/license
   4  */
   5
   6 ( function() {
   7         var template = '<a id="{id}"' +
   8                 ' class="cke_button cke_button__{name} cke_button_{state} {cls}"' +
   9                 ( CKEDITOR.env.gecko && !CKEDITOR.env.hc ? '' : ' href="javascript:void(\'{titleJs}\')"' ) +
  10                 ' title="{title}"' +
  11                 ' tabindex="-1"' +
  12                 ' hidefocus="true"' +
  13                 ' role="button"' +
  14                 ' aria-labelledby="{id}_label"' +
  15                 ' aria-describedby="{id}_description"' +
  16                 ' aria-haspopup="{hasArrow}"' +
  17                 ' aria-disabled="{ariaDisabled}"';
  18
  19         // Some browsers don't cancel key events in the keydown but in the
  20         // keypress.
  21         // TODO: Check if really needed.
  22         if ( CKEDITOR.env.gecko && CKEDITOR.env.mac )
  23                 template += ' onkeypress="return false;"';
  24
  25         // With Firefox, we need to force the button to redraw, otherwise it
  26         // will remain in the focus state.
  27         if ( CKEDITOR.env.gecko )
  28                 template += ' onblur="this.style.cssText = this.style.cssText;"';
  29
  30         template += ' onkeydown="return CKEDITOR.tools.callFunction({keydownFn},event);"' +
  31                 ' onfocus="return CKEDITOR.tools.callFunction({focusFn},event);" ' +
  32                 ( CKEDITOR.env.ie ? 'onclick="return false;" onmouseup' : 'onclick' ) + // http://dev.ckeditor.com/ticket/188
  33                         '="CKEDITOR.tools.callFunction({clickFn},this);return false;">' +
  34                 '<span class="cke_button_icon cke_button__{iconName}_icon" style="{style}"';
  35
  36
  37         template += '>&nbsp;</span>' +
  38                 '<span id="{id}_label" class="cke_button_label cke_button__{name}_label" aria-hidden="false">{label}</span>' +
  39                 '<span id="{id}_description" class="cke_button_label" aria-hidden="false">{ariaShortcut}</span>' +
  40                 '{arrowHtml}' +
  41                 '</a>';
  42
  43         var templateArrow = '<span class="cke_button_arrow">' +
  44                 // BLACK DOWN-POINTING TRIANGLE
  45         ( CKEDITOR.env.hc ? '&#9660;' : '' ) +
  46                 '</span>';
  47
  48         var btnArrowTpl = CKEDITOR.addTemplate( 'buttonArrow', templateArrow ),
  49                 btnTpl = CKEDITOR.addTemplate( 'button', template );
  50
  51         CKEDITOR.plugins.add( 'button', {
  52                 lang: 'af,ar,az,bg,ca,cs,da,de,de-ch,el,en,en-gb,eo,es,es-mx,eu,fa,fi,fr,gl,he,hr,hu,id,it,ja,km,ko,ku,lt,nb,nl,no,oc,pl,pt,pt-br,ro,ru,sk,sl,sq,sv,tr,tt,ug,uk,vi,zh,zh-cn', // %REMOVE_LINE_CORE%
  53                 beforeInit: function( editor ) {
  54                         editor.ui.addHandler( CKEDITOR.UI_BUTTON, CKEDITOR.ui.button.handler );
  55                 }
  56         } );
  57
  58         /**
  59          * Button UI element.
  60          *
  61          * @readonly
  62          * @property {String} [='button']
  63          * @member CKEDITOR
  64          */
  65         CKEDITOR.UI_BUTTON = 'button';
  66
  67         /**
  68          * Represents a button UI element. This class should not be called directly. To
  69          * create new buttons use {@link CKEDITOR.ui#addButton} instead.
  70          *
  71          * @class
  72          * @constructor Creates a button class instance.
  73          * @param {Object} definition The button definition.
  74          */
  75         CKEDITOR.ui.button = function( definition ) {
  76                 CKEDITOR.tools.extend( this, definition,
  77                 // Set defaults.
  78                 {
  79                         title: definition.label,
  80                         click: definition.click ||
  81                         function( editor ) {
  82                                 editor.execCommand( definition.command );
  83                         }
  84                 } );
  85
  86                 this._ = {};
  87         };
  88
  89         /**
  90          * Represents the button handler object.
  91          *
  92          * @class
  93          * @singleton
  94          * @extends CKEDITOR.ui.handlerDefinition
  95          */
  96         CKEDITOR.ui.button.handler = {
  97                 /**
  98                  * Transforms a button definition in a {@link CKEDITOR.ui.button} instance.
  99                  *
 100                  * @member CKEDITOR.ui.button.handler
 101                  * @param {Object} definition
 102                  * @returns {CKEDITOR.ui.button}
 103                  */
 104                 create: function( definition ) {
 105                         return new CKEDITOR.ui.button( definition );
 106                 }
 107         };
 108
 109         /** @class CKEDITOR.ui.button */
 110         CKEDITOR.ui.button.prototype = {
 111                 /**
 112                  * Renders the button.
 113                  *
 114                  * @param {CKEDITOR.editor} editor The editor instance which this button is
 115                  * to be used by.
 116                  * @param {Array} output The output array to which the HTML code related to
 117                  * this button should be appended.
 118                  */
 119                 render: function( editor, output ) {
 120                         function updateState() {
 121                                 // "this" is a CKEDITOR.ui.button instance.
 122                                 var mode = editor.mode;
 123
 124                                 if ( mode ) {
 125                                         // Restore saved button state.
 126                                         var state = this.modes[ mode ] ? modeStates[ mode ] !== undefined ? modeStates[ mode ] : CKEDITOR.TRISTATE_OFF : CKEDITOR.TRISTATE_DISABLED;
 127
 128                                         state = editor.readOnly && !this.readOnly ? CKEDITOR.TRISTATE_DISABLED : state;
 129
 130                                         this.setState( state );
 131
 132                                         // Let plugin to disable button.
 133                                         if ( this.refresh )
 134                                                 this.refresh();
 135                                 }
 136                         }
 137
 138                         var env = CKEDITOR.env,
 139                                 id = this._.id = CKEDITOR.tools.getNextId(),
 140                                 stateName = '',
 141                                 command = this.command,
 142                                 // Get the command name.
 143                                 clickFn,
 144                                 keystroke,
 145                                 shortcut;
 146
 147                         this._.editor = editor;
 148
 149                         var instance = {
 150                                 id: id,
 151                                 button: this,
 152                                 editor: editor,
 153                                 focus: function() {
 154                                         var element = CKEDITOR.document.getById( id );
 155                                         element.focus();
 156                                 },
 157                                 execute: function() {
 158                                         this.button.click( editor );
 159                                 },
 160                                 attach: function( editor ) {
 161                                         this.button.attach( editor );
 162                                 }
 163                         };
 164
 165                         var keydownFn = CKEDITOR.tools.addFunction( function( ev ) {
 166                                 if ( instance.onkey ) {
 167                                         ev = new CKEDITOR.dom.event( ev );
 168                                         return ( instance.onkey( instance, ev.getKeystroke() ) !== false );
 169                                 }
 170                         } );
 171
 172                         var focusFn = CKEDITOR.tools.addFunction( function( ev ) {
 173                                 var retVal;
 174
 175                                 if ( instance.onfocus )
 176                                         retVal = ( instance.onfocus( instance, new CKEDITOR.dom.event( ev ) ) !== false );
 177
 178                                 return retVal;
 179                         } );
 180
 181                         var selLocked = 0;
 182
 183                         instance.clickFn = clickFn = CKEDITOR.tools.addFunction( function() {
 184
 185                                 // Restore locked selection in Opera.
 186                                 if ( selLocked ) {
 187                                         editor.unlockSelection( 1 );
 188                                         selLocked = 0;
 189                                 }
 190                                 instance.execute();
 191
 192                                 // Fixed iOS focus issue when your press disabled button (http://dev.ckeditor.com/ticket/12381).
 193                                 if ( env.iOS ) {
 194                                         editor.focus();
 195                                 }
 196                         } );
 197
 198
 199                         // Indicate a mode sensitive button.
 200                         if ( this.modes ) {
 201                                 var modeStates = {};
 202
 203                                 editor.on( 'beforeModeUnload', function() {
 204                                         if ( editor.mode && this._.state != CKEDITOR.TRISTATE_DISABLED )
 205                                                 modeStates[ editor.mode ] = this._.state;
 206                                 }, this );
 207
 208                                 // Update status when activeFilter, mode or readOnly changes.
 209                                 editor.on( 'activeFilterChange', updateState, this );
 210                                 editor.on( 'mode', updateState, this );
 211                                 // If this button is sensitive to readOnly state, update it accordingly.
 212                                 !this.readOnly && editor.on( 'readOnly', updateState, this );
 213
 214                         } else if ( command ) {
 215                                 // Get the command instance.
 216                                 command = editor.getCommand( command );
 217
 218                                 if ( command ) {
 219                                         command.on( 'state', function() {
 220                                                 this.setState( command.state );
 221                                         }, this );
 222
 223                                         stateName += ( command.state == CKEDITOR.TRISTATE_ON ? 'on' : command.state == CKEDITOR.TRISTATE_DISABLED ? 'disabled' : 'off' );
 224                                 }
 225                         }
 226
 227                         // For button that has text-direction awareness on selection path.
 228                         if ( this.directional ) {
 229                                 editor.on( 'contentDirChanged', function( evt ) {
 230                                         var el = CKEDITOR.document.getById( this._.id ),
 231                                                 icon = el.getFirst();
 232
 233                                         var pathDir = evt.data;
 234
 235                                         // Make a minor direction change to become style-able for the skin icon.
 236                                         if ( pathDir !=  editor.lang.dir )
 237                                                 el.addClass( 'cke_' + pathDir );
 238                                         else
 239                                                 el.removeClass( 'cke_ltr' ).removeClass( 'cke_rtl' );
 240
 241                                         // Inline style update for the plugin icon.
 242                                         icon.setAttribute( 'style', CKEDITOR.skin.getIconStyle( iconName, pathDir == 'rtl', this.icon, this.iconOffset ) );
 243                                 }, this );
 244                         }
 245
 246                         if ( !command ) {
 247                                 stateName += 'off';
 248                         } else {
 249                                 keystroke = editor.getCommandKeystroke( command );
 250
 251                                 if ( keystroke ) {
 252                                         shortcut = CKEDITOR.tools.keystrokeToString( editor.lang.common.keyboard, keystroke );
 253                                 }
 254                         }
 255
 256                         var name = this.name || this.command,
 257                                 iconName = name;
 258
 259                         // Check if we're pointing to an icon defined by another command. (http://dev.ckeditor.com/ticket/9555)
 260                         if ( this.icon && !( /\./ ).test( this.icon ) ) {
 261                                 iconName = this.icon;
 262                                 this.icon = null;
 263                         }
 264
 265                         var params = {
 266                                 id: id,
 267                                 name: name,
 268                                 iconName: iconName,
 269                                 label: this.label,
 270                                 cls: this.className || '',
 271                                 state: stateName,
 272                                 ariaDisabled: stateName == 'disabled' ? 'true' : 'false',
 273                                 title: this.title + ( shortcut ? ' (' + shortcut.display + ')' : '' ),
 274                                 ariaShortcut: shortcut ? editor.lang.common.keyboardShortcut + ' ' + shortcut.aria : '',
 275                                 titleJs: env.gecko && !env.hc ? '' : ( this.title || '' ).replace( "'", '' ),
 276                                 hasArrow: this.hasArrow ? 'true' : 'false',
 277                                 keydownFn: keydownFn,
 278                                 focusFn: focusFn,
 279                                 clickFn: clickFn,
 280                                 style: CKEDITOR.skin.getIconStyle( iconName, ( editor.lang.dir == 'rtl' ), this.icon, this.iconOffset ),
 281                                 arrowHtml: this.hasArrow ? btnArrowTpl.output() : ''
 282                         };
 283
 284                         btnTpl.output( params, output );
 285
 286                         if ( this.onRender )
 287                                 this.onRender();
 288
 289                         return instance;
 290                 },
 291
 292                 /**
 293                  * Sets the button state.
 294                  *
 295                  * @param {Number} state Indicates the button state. One of {@link CKEDITOR#TRISTATE_ON},
 296                  * {@link CKEDITOR#TRISTATE_OFF}, or {@link CKEDITOR#TRISTATE_DISABLED}.
 297                  */
 298                 setState: function( state ) {
 299                         if ( this._.state == state )
 300                                 return false;
 301
 302                         this._.state = state;
 303
 304                         var element = CKEDITOR.document.getById( this._.id );
 305
 306                         if ( element ) {
 307                                 element.setState( state, 'cke_button' );
 308
 309                                 state == CKEDITOR.TRISTATE_DISABLED ?
 310                                         element.setAttribute( 'aria-disabled', true ) :
 311                                         element.removeAttribute( 'aria-disabled' );
 312
 313                                 if ( !this.hasArrow ) {
 314                                         // Note: aria-pressed attribute should not be added to menuButton instances. (http://dev.ckeditor.com/ticket/11331)
 315                                         state == CKEDITOR.TRISTATE_ON ?
 316                                                 element.setAttribute( 'aria-pressed', true ) :
 317                                                 element.removeAttribute( 'aria-pressed' );
 318                                 } else {
 319                                         var newLabel = state == CKEDITOR.TRISTATE_ON ?
 320                                                 this._.editor.lang.button.selectedLabel.replace( /%1/g, this.label ) : this.label;
 321                                         CKEDITOR.document.getById( this._.id + '_label' ).setText( newLabel );
 322                                 }
 323
 324                                 return true;
 325                         } else {
 326                                 return false;
 327                         }
 328                 },
 329
 330                 /**
 331                  * Gets the button state.
 332                  *
 333                  * @returns {Number} The button state. One of {@link CKEDITOR#TRISTATE_ON},
 334                  * {@link CKEDITOR#TRISTATE_OFF}, or {@link CKEDITOR#TRISTATE_DISABLED}.
 335                  */
 336                 getState: function() {
 337                         return this._.state;
 338                 },
 339
 340                 /**
 341                  * Returns this button's {@link CKEDITOR.feature} instance.
 342                  *
 343                  * It may be this button instance if it has at least one of
 344                  * `allowedContent` and `requiredContent` properties. Otherwise,
 345                  * if a command is bound to this button by the `command` property, then
 346                  * that command will be returned.
 347                  *
 348                  * This method implements the {@link CKEDITOR.feature#toFeature} interface method.
 349                  *
 350                  * @since 4.1
 351                  * @param {CKEDITOR.editor} Editor instance.
 352                  * @returns {CKEDITOR.feature} The feature.
 353                  */
 354                 toFeature: function( editor ) {
 355                         if ( this._.feature )
 356                                 return this._.feature;
 357
 358                         var feature = this;
 359
 360                         // If button isn't a feature, return command if is bound.
 361                         if ( !this.allowedContent && !this.requiredContent && this.command )
 362                                 feature = editor.getCommand( this.command ) || feature;
 363
 364                         return this._.feature = feature;
 365                 }
 366         };
 367
 368         /**
 369          * Adds a button definition to the UI elements list.
 370          *
 371          *              editorInstance.ui.addButton( 'MyBold', {
 372          *                      label: 'My Bold',
 373          *                      command: 'bold',
 374          *                      toolbar: 'basicstyles,1'
 375          *              } );
 376          *
 377          * @member CKEDITOR.ui
 378          * @param {String} name The button name.
 379          * @param {Object} definition The button definition.
 380          * @param {String} definition.label The textual part of the button (if visible) and its tooltip.
 381          * @param {String} definition.command The command to be executed once the button is activated.
 382          * @param {String} definition.toolbar The {@link CKEDITOR.config#toolbarGroups toolbar group} into which
 383          * the button will be added. An optional index value (separated by a comma) determines the button position within the group.
 384          */
 385         CKEDITOR.ui.prototype.addButton = function( name, definition ) {
 386                 this.add( name, CKEDITOR.UI_BUTTON, definition );
 387         };
 388
 389 } )();