]>
git.immae.eu Git - perso/Immae/Projets/packagist/piedsjaloux-ckeditor-component.git/blob - sources/core/editor.js
2 * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
3 * For licensing, see LICENSE.md or http://ckeditor.com/license
7 * @fileOverview Defines the {@link CKEDITOR.editor} class that represents an
12 // Override the basic constructor defined at editor_basic.js.
13 Editor
.prototype = CKEDITOR
.editor
.prototype;
14 CKEDITOR
.editor
= Editor
;
17 * Represents an editor instance. This constructor should be rarely
18 * used in favor of the {@link CKEDITOR} editor creation functions.
20 * @class CKEDITOR.editor
21 * @mixins CKEDITOR.event
22 * @constructor Creates an editor class instance.
23 * @param {Object} [instanceConfig] Configuration values for this specific instance.
24 * @param {CKEDITOR.dom.element} [element] The DOM element upon which this editor
26 * @param {Number} [mode] The element creation mode to be used by this editor.
28 function Editor( instanceConfig
, element
, mode
) {
29 // Call the CKEDITOR.event constructor to initialize this instance.
30 CKEDITOR
.event
.call( this );
32 // Make a clone of the config object, to avoid having it touched by our code. (http://dev.ckeditor.com/ticket/9636)
33 instanceConfig
= instanceConfig
&& CKEDITOR
.tools
.clone( instanceConfig
);
35 // if editor is created off one page element.
36 if ( element
!== undefined ) {
37 // Asserting element and mode not null.
38 if ( !( element
instanceof CKEDITOR
.dom
.element
) )
39 throw new Error( 'Expect element of type CKEDITOR.dom.element.' );
41 throw new Error( 'One of the element modes must be specified.' );
43 if ( CKEDITOR
.env
.ie
&& CKEDITOR
.env
.quirks
&& mode
== CKEDITOR
.ELEMENT_MODE_INLINE
)
44 throw new Error( 'Inline element mode is not supported on IE quirks.' );
46 if ( !isSupportedElement( element
, mode
) )
47 throw new Error( 'The specified element mode is not supported on element: "' + element
.getName() + '".' );
50 * The original host page element upon which the editor is created. It is only
51 * supposed to be provided by the particular editor creator and is not subject to
55 * @property {CKEDITOR.dom.element}
57 this.element
= element
;
60 * This property indicates the way this instance is associated with the {@link #element}.
61 * See also {@link CKEDITOR#ELEMENT_MODE_INLINE} and {@link CKEDITOR#ELEMENT_MODE_REPLACE}.
66 this.elementMode
= mode
;
68 this.name
= ( this.elementMode
!= CKEDITOR
.ELEMENT_MODE_APPENDTO
) && ( element
.getId() || element
.getNameAtt() );
70 this.elementMode
= CKEDITOR
.ELEMENT_MODE_NONE
;
73 // Declare the private namespace.
79 * Contains all UI templates created for this editor instance.
87 * A unique identifier of this editor instance.
89 * **Note:** It will be originated from the `id` or `name`
90 * attribute of the {@link #element}, otherwise a name pattern of
91 * `'editor{n}'` will be used.
96 this.name
= this.name
|| genEditorName();
99 * A unique random string assigned to each editor instance on the page.
104 this.id
= CKEDITOR
.tools
.getNextId();
107 * Indicates editor initialization status. The following statuses are available:
109 * * **unloaded**: The initial state — the editor instance was initialized,
110 * but its components (configuration, plugins, language files) are not loaded yet.
111 * * **loaded**: The editor components were loaded — see the {@link CKEDITOR.editor#loaded} event.
112 * * **ready**: The editor is fully initialized and ready — see the {@link CKEDITOR.editor#instanceReady} event.
113 * * **destroyed**: The editor was destroyed — see the {@link CKEDITOR.editor#method-destroy} method.
119 this.status
= 'unloaded';
122 * The configuration for this editor instance. It inherits all
123 * settings defined in {@link CKEDITOR.config}, combined with settings
124 * loaded from custom configuration files and those defined inline in
125 * the page when creating the editor.
127 * var editor = CKEDITOR.instances.editor1;
128 * alert( editor.config.skin ); // e.g. 'moono'
131 * @property {CKEDITOR.config}
133 this.config
= CKEDITOR
.tools
.prototypedCopy( CKEDITOR
.config
);
136 * The namespace containing UI features related to this editor instance.
139 * @property {CKEDITOR.ui}
141 this.ui
= new CKEDITOR
.ui( this );
144 * Controls the focus state of this editor instance. This property
145 * is rarely used for normal API operations. It is mainly
146 * targeted at developers adding UI elements to the editor interface.
149 * @property {CKEDITOR.focusManager}
151 this.focusManager
= new CKEDITOR
.focusManager( this );
154 * Controls keystroke typing in this editor instance.
157 * @property {CKEDITOR.keystrokeHandler}
159 this.keystrokeHandler
= new CKEDITOR
.keystrokeHandler( this );
161 // Make the editor update its command states on mode change.
162 this.on( 'readOnly', updateCommands
);
163 this.on( 'selectionChange', function( evt
) {
164 updateCommandsContext( this, evt
.data
.path
);
166 this.on( 'activeFilterChange', function() {
167 updateCommandsContext( this, this.elementPath(), true );
169 this.on( 'mode', updateCommands
);
171 // Handle startup focus.
172 this.on( 'instanceReady', function() {
173 this.config
.startupFocus
&& this.focus();
176 CKEDITOR
.fire( 'instanceCreated', null, this );
178 // Add this new editor to the CKEDITOR.instances collections.
179 CKEDITOR
.add( this );
181 // Return the editor instance immediately to enable early stage event registrations.
182 CKEDITOR
.tools
.setTimeout( function() {
183 if ( this.status
!== 'destroyed' ) {
184 initConfig( this, instanceConfig
);
186 CKEDITOR
.warn( 'editor-incorrect-destroy' );
193 function genEditorName() {
195 var name
= 'editor' + ( ++nameCounter
);
197 while ( CKEDITOR
.instances
[ name
] );
202 // Asserting element DTD depending on mode.
203 function isSupportedElement( element
, mode
) {
204 if ( mode
== CKEDITOR
.ELEMENT_MODE_INLINE
)
205 return element
.is( CKEDITOR
.dtd
.$editable
) || element
.is( 'textarea' );
206 else if ( mode
== CKEDITOR
.ELEMENT_MODE_REPLACE
)
207 return !element
.is( CKEDITOR
.dtd
.$nonBodyContent
);
211 function updateCommands() {
212 var commands
= this.commands
,
215 for ( name
in commands
)
216 updateCommand( this, commands
[ name
] );
219 function updateCommand( editor
, cmd
) {
220 cmd
[ cmd
.startDisabled
? 'disable' : editor
.readOnly
&& !cmd
.readOnly
? 'disable' : cmd
.modes
[ editor
.mode
] ? 'enable' : 'disable' ]();
223 function updateCommandsContext( editor
, path
, forceRefresh
) {
224 // Commands cannot be refreshed without a path. In edge cases
225 // it may happen that there's no selection when this function is executed.
226 // For example when active filter is changed in http://dev.ckeditor.com/ticket/10877.
232 commands
= editor
.commands
;
234 for ( name
in commands
) {
235 command
= commands
[ name
];
237 if ( forceRefresh
|| command
.contextSensitive
)
238 command
.refresh( editor
, path
);
242 // ##### START: Config Privates
244 // These function loads custom configuration files and cache the
245 // CKEDITOR.editorConfig functions defined on them, so there is no need to
246 // download them more than once for several instances.
247 var loadConfigLoaded
= {};
249 function loadConfig( editor
) {
250 var customConfig
= editor
.config
.customConfig
;
252 // Check if there is a custom config to load.
256 customConfig
= CKEDITOR
.getUrl( customConfig
);
258 var loadedConfig
= loadConfigLoaded
[ customConfig
] || ( loadConfigLoaded
[ customConfig
] = {} );
260 // If the custom config has already been downloaded, reuse it.
261 if ( loadedConfig
.fn
) {
262 // Call the cached CKEDITOR.editorConfig defined in the custom
263 // config file for the editor instance depending on it.
264 loadedConfig
.fn
.call( editor
, editor
.config
);
266 // If there is no other customConfig in the chain, fire the
267 // "configLoaded" event.
268 if ( CKEDITOR
.getUrl( editor
.config
.customConfig
) == customConfig
|| !loadConfig( editor
) )
269 editor
.fireOnce( 'customConfigLoaded' );
271 // Load the custom configuration file.
272 // To resolve customConfig race conflicts, use scriptLoader#queue
273 // instead of scriptLoader#load (http://dev.ckeditor.com/ticket/6504).
274 CKEDITOR
.scriptLoader
.queue( customConfig
, function() {
275 // If the CKEDITOR.editorConfig function has been properly
276 // defined in the custom configuration file, cache it.
277 if ( CKEDITOR
.editorConfig
)
278 loadedConfig
.fn
= CKEDITOR
.editorConfig
;
280 loadedConfig
.fn = function() {};
282 // Call the load config again. This time the custom
283 // config is already cached and so it will get loaded.
284 loadConfig( editor
);
291 function initConfig( editor
, instanceConfig
) {
292 // Setup the lister for the "customConfigLoaded" event.
293 editor
.on( 'customConfigLoaded', function() {
294 if ( instanceConfig
) {
295 // Register the events that may have been set at the instance
296 // configuration object.
297 if ( instanceConfig
.on
) {
298 for ( var eventName
in instanceConfig
.on
) {
299 editor
.on( eventName
, instanceConfig
.on
[ eventName
] );
303 // Overwrite the settings from the in-page config.
304 CKEDITOR
.tools
.extend( editor
.config
, instanceConfig
, true );
306 delete editor
.config
.on
;
309 onConfigLoaded( editor
);
312 // The instance config may override the customConfig setting to avoid
313 // loading the default ~/config.js file.
314 if ( instanceConfig
&& instanceConfig
.customConfig
!= null )
315 editor
.config
.customConfig
= instanceConfig
.customConfig
;
317 // Load configs from the custom configuration files.
318 if ( !loadConfig( editor
) )
319 editor
.fireOnce( 'customConfigLoaded' );
322 // ##### END: Config Privates
324 // Set config related properties.
325 function onConfigLoaded( editor
) {
326 var config
= editor
.config
;
329 * Indicates the read-only state of this editor. This is a read-only property.
330 * See also {@link CKEDITOR.editor#setReadOnly}.
334 * @property {Boolean}
336 editor
.readOnly
= isEditorReadOnly();
338 function isEditorReadOnly() {
339 if ( config
.readOnly
) {
343 if ( editor
.elementMode
== CKEDITOR
.ELEMENT_MODE_INLINE
) {
344 if ( editor
.element
.is( 'textarea' ) ) {
345 return editor
.element
.hasAttribute( 'disabled' ) || editor
.element
.hasAttribute( 'readonly' );
347 return editor
.element
.isReadOnly();
349 } else if ( editor
.elementMode
== CKEDITOR
.ELEMENT_MODE_REPLACE
) {
350 return editor
.element
.hasAttribute( 'disabled' ) || editor
.element
.hasAttribute( 'readonly' );
357 * Indicates that the editor is running in an environment where
358 * no block elements are accepted inside the content.
360 * This can be for example inline editor based on an `<h1>` element.
363 * @property {Boolean}
365 editor
.blockless
= editor
.elementMode
== CKEDITOR
.ELEMENT_MODE_INLINE
?
366 !( editor
.element
.is( 'textarea' ) || CKEDITOR
.dtd
[ editor
.element
.getName() ].p
) :
370 * The [tabbing navigation](http://en.wikipedia.org/wiki/Tabbing_navigation) order determined for this editor instance.
371 * This can be set by the <code>{@link CKEDITOR.config#tabIndex}</code>
372 * setting or taken from the `tabindex` attribute of the
373 * {@link #element} associated with the editor.
375 * alert( editor.tabIndex ); // e.g. 0
378 * @property {Number} [=0]
380 editor
.tabIndex
= config
.tabIndex
|| editor
.element
&& editor
.element
.getAttribute( 'tabindex' ) || 0;
382 editor
.activeEnterMode
= editor
.enterMode
= validateEnterMode( editor
, config
.enterMode
);
383 editor
.activeShiftEnterMode
= editor
.shiftEnterMode
= validateEnterMode( editor
, config
.shiftEnterMode
);
385 // Set CKEDITOR.skinName. Note that it is not possible to have
386 // different skins on the same page, so the last one to set it "wins".
388 CKEDITOR
.skinName
= config
.skin
;
390 // Fire the "configLoaded" event.
391 editor
.fireOnce( 'configLoaded' );
393 initComponents( editor
);
396 // Various other core components that read editor configuration.
397 function initComponents( editor
) {
398 // Documented in dataprocessor.js.
399 editor
.dataProcessor
= new CKEDITOR
.htmlDataProcessor( editor
);
401 // Set activeFilter directly to avoid firing event.
402 editor
.filter
= editor
.activeFilter
= new CKEDITOR
.filter( editor
);
407 function loadSkin( editor
) {
408 CKEDITOR
.skin
.loadPart( 'editor', function() {
413 function loadLang( editor
) {
414 CKEDITOR
.lang
.load( editor
.config
.language
, editor
.config
.defaultLanguage
, function( languageCode
, lang
) {
415 var configTitle
= editor
.config
.title
;
418 * The code for the language resources that have been loaded
419 * for the user interface elements of this editor instance.
421 * alert( editor.langCode ); // e.g. 'en'
426 editor
.langCode
= languageCode
;
429 * An object that contains all language strings used by the editor interface.
431 * alert( editor.lang.basicstyles.bold ); // e.g. 'Negrito' (if the language is set to Portuguese)
434 * @property {Object} lang
436 // As we'll be adding plugin specific entries that could come
437 // from different language code files, we need a copy of lang,
438 // not a direct reference to it.
439 editor
.lang
= CKEDITOR
.tools
.prototypedCopy( lang
);
442 * Indicates the human-readable title of this editor. Although this is a read-only property,
443 * it can be initialized with {@link CKEDITOR.config#title}.
445 * **Note:** Please do not confuse this property with {@link CKEDITOR.editor#name editor.name}
446 * which identifies the instance in the {@link CKEDITOR#instances} literal.
450 * @property {String/Boolean}
452 editor
.title
= typeof configTitle
== 'string' || configTitle
=== false ? configTitle : [ editor
.lang
.editor
, editor
.name
].join( ', ' );
454 if ( !editor
.config
.contentsLangDirection
) {
455 // Fallback to either the editable element direction or editor UI direction depending on creators.
456 editor
.config
.contentsLangDirection
= editor
.elementMode
== CKEDITOR
.ELEMENT_MODE_INLINE
? editor
.element
.getDirection( 1 ) : editor
.lang
.dir
;
459 editor
.fire( 'langLoaded' );
461 preloadStylesSet( editor
);
465 // Preloads styles set file (config.stylesSet).
466 // If stylesSet was defined directly (by an array)
467 // this function will call loadPlugins fully synchronously.
468 // If stylesSet is a string (path) loadPlugins will
469 // be called asynchronously.
470 // In both cases - styles will be preload before plugins initialization.
471 function preloadStylesSet( editor
) {
472 editor
.getStylesSet( function( styles
) {
473 // Wait for editor#loaded, so plugins could add their listeners.
474 // But listen with high priority to fire editor#stylesSet before editor#uiReady and editor#setData.
475 editor
.once( 'loaded', function() {
476 // Note: we can't use fireOnce because this event may canceled and fired again.
477 editor
.fire( 'stylesSet', { styles: styles
} );
480 loadPlugins( editor
);
484 function loadPlugins( editor
) {
485 var config
= editor
.config
,
486 plugins
= config
.plugins
,
487 extraPlugins
= config
.extraPlugins
,
488 removePlugins
= config
.removePlugins
;
490 if ( extraPlugins
) {
491 // Remove them first to avoid duplications.
492 var extraRegex
= new RegExp( '(?:^|,)(?:' + extraPlugins
.replace( /\s*,\s*/g, '|' ) + ')(?=,|$)', 'g' );
493 plugins
= plugins
.replace( extraRegex
, '' );
495 plugins
+= ',' + extraPlugins
;
498 if ( removePlugins
) {
499 var removeRegex
= new RegExp( '(?:^|,)(?:' + removePlugins
.replace( /\s*,\s*/g, '|' ) + ')(?=,|$)', 'g' );
500 plugins
= plugins
.replace( removeRegex
, '' );
503 // Load the Adobe AIR plugin conditionally.
504 CKEDITOR
.env
.air
&& ( plugins
+= ',adobeair' );
506 // Load all plugins defined in the "plugins" setting.
507 CKEDITOR
.plugins
.load( plugins
.split( ',' ), function( plugins
) {
508 // The list of plugins.
509 var pluginsArray
= [];
511 // The language code to get loaded for each plugin. Null
512 // entries will be appended for plugins with no language files.
513 var languageCodes
= [];
515 // The list of URLs to language files.
516 var languageFiles
= [];
519 * An object that contains references to all plugins used by this
522 * alert( editor.plugins.dialog.path ); // e.g. 'http://example.com/ckeditor/plugins/dialog/'
524 * // Check if a plugin is available.
525 * if ( editor.plugins.image ) {
532 editor
.plugins
= plugins
;
534 // Loop through all plugins, to build the list of language
535 // files to get loaded.
537 // Check also whether any of loaded plugins doesn't require plugins
538 // defined in config.removePlugins. Throw non-blocking error if this happens.
539 for ( var pluginName
in plugins
) {
540 var plugin
= plugins
[ pluginName
],
541 pluginLangs
= plugin
.lang
,
543 requires
= plugin
.requires
,
546 // Transform it into a string, if it's not one.
547 if ( CKEDITOR
.tools
.isArray( requires
) )
548 requires
= requires
.join( ',' );
550 if ( requires
&& ( match
= requires
.match( removeRegex
) ) ) {
551 while ( ( name
= match
.pop() ) ) {
552 CKEDITOR
.error( 'editor-plugin-required', { plugin: name
.replace( ',', '' ), requiredBy: pluginName
} );
556 // If the plugin has "lang".
557 if ( pluginLangs
&& !editor
.lang
[ pluginName
] ) {
558 // Trasnform the plugin langs into an array, if it's not one.
559 if ( pluginLangs
.split
)
560 pluginLangs
= pluginLangs
.split( ',' );
562 // Resolve the plugin language. If the current language
563 // is not available, get English or the first one.
564 if ( CKEDITOR
.tools
.indexOf( pluginLangs
, editor
.langCode
) >= 0 )
565 lang
= editor
.langCode
;
567 // The language code may have the locale information (zh-cn).
568 // Fall back to locale-less in that case (zh).
569 var langPart
= editor
.langCode
.replace( /-.*/, '' );
570 if ( langPart
!= editor
.langCode
&& CKEDITOR
.tools
.indexOf( pluginLangs
, langPart
) >= 0 )
572 // Try the only "generic" option we have: English.
573 else if ( CKEDITOR
.tools
.indexOf( pluginLangs
, 'en' ) >= 0 )
576 lang
= pluginLangs
[ 0 ];
579 if ( !plugin
.langEntries
|| !plugin
.langEntries
[ lang
] ) {
580 // Put the language file URL into the list of files to
582 languageFiles
.push( CKEDITOR
.getUrl( plugin
.path
+ 'lang/' + lang
+ '.js' ) );
584 editor
.lang
[ pluginName
] = plugin
.langEntries
[ lang
];
589 // Save the language code, so we know later which
590 // language has been resolved to this plugin.
591 languageCodes
.push( lang
);
593 pluginsArray
.push( plugin
);
596 // Load all plugin specific language files in a row.
597 CKEDITOR
.scriptLoader
.load( languageFiles
, function() {
598 // Initialize all plugins that have the "beforeInit" and "init" methods defined.
599 var methods
= [ 'beforeInit', 'init', 'afterInit' ];
600 for ( var m
= 0; m
< methods
.length
; m
++ ) {
601 for ( var i
= 0; i
< pluginsArray
.length
; i
++ ) {
602 var plugin
= pluginsArray
[ i
];
604 // Uses the first loop to update the language entries also.
605 if ( m
=== 0 && languageCodes
[ i
] && plugin
.lang
&& plugin
.langEntries
)
606 editor
.lang
[ plugin
.name
] = plugin
.langEntries
[ languageCodes
[ i
] ];
608 // Call the plugin method (beforeInit and init).
609 if ( plugin
[ methods
[ m
] ] )
610 plugin
[ methods
[ m
] ]( editor
);
614 editor
.fireOnce( 'pluginsLoaded' );
616 // Setup the configured keystrokes.
617 config
.keystrokes
&& editor
.setKeystroke( editor
.config
.keystrokes
);
619 // Setup the configured blocked keystrokes.
620 for ( i
= 0; i
< editor
.config
.blockedKeystrokes
.length
; i
++ )
621 editor
.keystrokeHandler
.blockedKeystrokes
[ editor
.config
.blockedKeystrokes
[ i
] ] = 1;
623 editor
.status
= 'loaded';
624 editor
.fireOnce( 'loaded' );
625 CKEDITOR
.fire( 'instanceLoaded', null, editor
);
630 // Send to data output back to editor's associated element.
631 function updateEditorElement() {
632 var element
= this.element
;
634 // Some editor creation mode will not have the
635 // associated element.
636 if ( element
&& this.elementMode
!= CKEDITOR
.ELEMENT_MODE_APPENDTO
) {
637 var data
= this.getData();
639 if ( this.config
.htmlEncodeOutput
)
640 data
= CKEDITOR
.tools
.htmlEncode( data
);
642 if ( element
.is( 'textarea' ) )
643 element
.setValue( data
);
645 element
.setHtml( data
);
652 // Always returns ENTER_BR in case of blockless editor.
653 function validateEnterMode( editor
, enterMode
) {
654 return editor
.blockless
? CKEDITOR
.ENTER_BR : enterMode
;
657 // Create DocumentFragment from specified ranges. For now it handles only tables
658 // and returns DocumentFragment from the 1. range for other cases. (http://dev.ckeditor.com/ticket/13884)
659 function createDocumentFragmentFromRanges( ranges
, editable
) {
660 var docFragment
= new CKEDITOR
.dom
.documentFragment(),
665 // We must handle two cases here:
666 // 1. <tr>[<td>Cell</td>]</tr> (IE9+, Edge, Chrome, Firefox)
667 // 2. <td>[Cell]</td> (IE8-, Safari)
668 function isSelectedCell( range
) {
669 var start
= range
.startContainer
,
670 end
= range
.endContainer
;
672 if ( start
.is
&& ( start
.is( 'tr' ) ||
673 ( start
.is( 'td' ) && start
.equals( end
) && range
.endOffset
=== start
.getChildCount() ) ) ) {
680 function cloneCell( range
) {
681 var start
= range
.startContainer
;
683 if ( start
.is( 'tr' ) ) {
684 return range
.cloneContents();
687 return start
.clone( true );
690 for ( var i
= 0; i
< ranges
.length
; i
++ ) {
691 var range
= ranges
[ i
],
692 container
= range
.startContainer
.getAscendant( 'tr', true );
694 if ( isSelectedCell( range
) ) {
696 tableClone
= container
.getAscendant( 'table' ).clone();
697 tableClone
.append( container
.getAscendant( { thead: 1, tbody: 1, tfoot: 1 } ).clone() );
698 docFragment
.append( tableClone
);
699 tableClone
= tableClone
.findOne( 'thead, tbody, tfoot' );
702 if ( !( currentRow
&& currentRow
.equals( container
) ) ) {
703 currentRow
= container
;
704 currentRowClone
= container
.clone();
705 tableClone
.append( currentRowClone
);
708 currentRowClone
.append( cloneCell( range
) );
710 // If there was something else copied with table,
711 // append it to DocumentFragment.
712 docFragment
.append( range
.cloneContents() );
717 return editable
.getHtmlFromRange( ranges
[ 0 ] );
723 CKEDITOR
.tools
.extend( CKEDITOR
.editor
.prototype, {
725 * Adds a command definition to the editor instance. Commands added with
726 * this function can be executed later with the <code>{@link #execCommand}</code> method.
728 * editorInstance.addCommand( 'sample', {
729 * exec: function( editor ) {
730 * alert( 'Executing a command for the editor name "' + editor.name + '"!' );
734 * @param {String} commandName The indentifier name of the command.
735 * @param {CKEDITOR.commandDefinition} commandDefinition The command definition.
737 addCommand: function( commandName
, commandDefinition
) {
738 commandDefinition
.name
= commandName
.toLowerCase();
739 var cmd
= new CKEDITOR
.command( this, commandDefinition
);
741 // Update command when mode is set.
742 // This guarantees that commands added before first editor#mode
743 // aren't immediately updated, but waits for editor#mode and that
744 // commands added later are immediately refreshed, even when added
745 // before instanceReady. http://dev.ckeditor.com/ticket/10103, http://dev.ckeditor.com/ticket/10249
747 updateCommand( this, cmd
);
749 return this.commands
[ commandName
] = cmd
;
753 * Attaches the editor to a form to call {@link #updateElement} before form submission.
754 * This method is called by both creators ({@link CKEDITOR#replace replace} and
755 * {@link CKEDITOR#inline inline}), so there is no reason to call it manually.
759 _attachToForm: function() {
761 element
= editor
.element
,
762 form
= new CKEDITOR
.dom
.element( element
.$.form
);
764 // If are replacing a textarea, we must
765 if ( element
.is( 'textarea' ) ) {
767 form
.on( 'submit', onSubmit
);
769 // Check if there is no element/elements input with name == "submit".
770 // If they exists they will overwrite form submit function (form.$.submit).
771 // If form.$.submit is overwritten we can not do anything with it.
772 if ( isFunction( form
.$.submit
) ) {
773 // Setup the submit function because it doesn't fire the
775 form
.$.submit
= CKEDITOR
.tools
.override( form
.$.submit
, function( originalSubmit
) {
779 // For IE, the DOM submit function is not a
780 // function, so we need third check.
781 if ( originalSubmit
.apply
)
782 originalSubmit
.apply( this );
789 // Remove 'submit' events registered on form element before destroying.(http://dev.ckeditor.com/ticket/3988)
790 editor
.on( 'destroy', function() {
791 form
.removeListener( 'submit', onSubmit
);
796 function onSubmit( evt
) {
797 editor
.updateElement();
799 // http://dev.ckeditor.com/ticket/8031 If textarea had required attribute and editor is empty fire 'required' event and if
800 // it was cancelled, prevent submitting the form.
801 if ( editor
._
.required
&& !element
.getValue() && editor
.fire( 'required' ) === false ) {
802 // When user press save button event (evt) is undefined (see save plugin).
803 // This method works because it throws error so originalSubmit won't be called.
804 // Also this error won't be shown because it will be caught in save plugin.
805 evt
.data
.preventDefault();
809 function isFunction( f
) {
810 // For IE8 typeof fun == object so we cannot use it.
811 return !!( f
&& f
.call
&& f
.apply
);
816 * Destroys the editor instance, releasing all resources used by it.
817 * If the editor replaced an element, the element will be recovered.
819 * alert( CKEDITOR.instances.editor1 ); // e.g. object
820 * CKEDITOR.instances.editor1.destroy();
821 * alert( CKEDITOR.instances.editor1 ); // undefined
823 * @param {Boolean} [noUpdate] If the instance is replacing a DOM
824 * element, this parameter indicates whether or not to update the
825 * element with the instance content.
827 destroy: function( noUpdate
) {
828 this.fire( 'beforeDestroy' );
830 !noUpdate
&& updateEditorElement
.call( this );
832 this.editable( null );
835 this.filter
.destroy();
839 delete this.activeFilter
;
841 this.status
= 'destroyed';
843 this.fire( 'destroy' );
845 // Plug off all listeners to prevent any further events firing.
846 this.removeAllListeners();
848 CKEDITOR
.remove( this );
849 CKEDITOR
.fire( 'instanceDestroyed', null, this );
853 * Returns an {@link CKEDITOR.dom.elementPath element path} for the selection in the editor.
855 * @param {CKEDITOR.dom.node} [startNode] From which the path should start,
856 * if not specified defaults to editor selection's
857 * start element yielded by {@link CKEDITOR.dom.selection#getStartElement}.
858 * @returns {CKEDITOR.dom.elementPath}
860 elementPath: function( startNode
) {
862 var sel
= this.getSelection();
866 startNode
= sel
.getStartElement();
869 return startNode
? new CKEDITOR
.dom
.elementPath( startNode
, this.editable() ) : null;
873 * Shortcut to create a {@link CKEDITOR.dom.range} instance from the editable element.
875 * @returns {CKEDITOR.dom.range} The DOM range created if the editable has presented.
876 * @see CKEDITOR.dom.range
878 createRange: function() {
879 var editable
= this.editable();
880 return editable
? new CKEDITOR
.dom
.range( editable
) : null;
884 * Executes a command associated with the editor.
886 * editorInstance.execCommand( 'bold' );
888 * @param {String} commandName The identifier name of the command.
889 * @param {Object} [data] The data to be passed to the command. It defaults to
890 * an empty object starting from 4.7.0.
891 * @returns {Boolean} `true` if the command was executed successfully, `false` otherwise.
892 * @see CKEDITOR.editor#addCommand
894 execCommand: function( commandName
, data
) {
895 var command
= this.getCommand( commandName
);
899 commandData: data
|| {},
903 if ( command
&& command
.state
!= CKEDITOR
.TRISTATE_DISABLED
) {
904 if ( this.fire( 'beforeCommandExec', eventData
) !== false ) {
905 eventData
.returnValue
= command
.exec( eventData
.commandData
);
907 // Fire the 'afterCommandExec' immediately if command is synchronous.
908 if ( !command
.async
&& this.fire( 'afterCommandExec', eventData
) !== false )
909 return eventData
.returnValue
;
913 // throw 'Unknown command name "' + commandName + '"';
918 * Gets one of the registered commands. Note that after registering a
919 * command definition with {@link #addCommand}, it is
920 * transformed internally into an instance of
921 * {@link CKEDITOR.command}, which will then be returned by this function.
923 * @param {String} commandName The name of the command to be returned.
924 * This is the same name that is used to register the command with `addCommand`.
925 * @returns {CKEDITOR.command} The command object identified by the provided name.
927 getCommand: function( commandName
) {
928 return this.commands
[ commandName
];
932 * Gets the editor data. The data will be in "raw" format. It is the same
933 * data that is posted by the editor.
935 * if ( CKEDITOR.instances.editor1.getData() == '' )
936 * alert( 'There is no data available.' );
938 * @param {Boolean} internal If set to `true`, it will prevent firing the
939 * {@link CKEDITOR.editor#beforeGetData} and {@link CKEDITOR.editor#event-getData} events, so
940 * the real content of the editor will not be read and cached data will be returned. The method will work
941 * much faster, but this may result in the editor returning the data that is not up to date. This parameter
942 * should thus only be set to `true` when you are certain that the cached data is up to date.
944 * @returns {String} The editor data.
946 getData: function( internal ) {
947 !internal && this.fire( 'beforeGetData' );
949 var eventData
= this._
.data
;
951 if ( typeof eventData
!= 'string' ) {
952 var element
= this.element
;
953 if ( element
&& this.elementMode
== CKEDITOR
.ELEMENT_MODE_REPLACE
)
954 eventData
= element
.is( 'textarea' ) ? element
.getValue() : element
.getHtml();
959 eventData
= { dataValue: eventData
};
961 // Fire "getData" so data manipulation may happen.
962 !internal && this.fire( 'getData', eventData
);
964 return eventData
.dataValue
;
968 * Gets the "raw data" currently available in the editor. This is a
969 * fast method which returns the data as is, without processing, so it is
970 * not recommended to use it on resulting pages. Instead it can be used
971 * combined with the {@link #method-loadSnapshot} method in order
972 * to automatically save the editor data from time to time
973 * while the user is using the editor, to avoid data loss, without risking
974 * performance issues.
976 * alert( editor.getSnapshot() );
980 * * {@link CKEDITOR.editor#method-getData}.
982 * @returns {String} Editor "raw data".
984 getSnapshot: function() {
985 var data
= this.fire( 'getSnapshot' );
987 if ( typeof data
!= 'string' ) {
988 var element
= this.element
;
990 if ( element
&& this.elementMode
== CKEDITOR
.ELEMENT_MODE_REPLACE
) {
991 data
= element
.is( 'textarea' ) ? element
.getValue() : element
.getHtml();
994 // If we don't have a proper element, set data to an empty string,
995 // as this method is expected to return a string. (http://dev.ckeditor.com/ticket/13385)
1004 * Loads "raw data" into the editor. The data is loaded with processing
1005 * straight to the editing area. It should not be used as a way to load
1006 * any kind of data, but instead in combination with
1007 * {@link #method-getSnapshot}-produced data.
1009 * var data = editor.getSnapshot();
1010 * editor.loadSnapshot( data );
1012 * @see CKEDITOR.editor#setData
1014 loadSnapshot: function( snapshot
) {
1015 this.fire( 'loadSnapshot', snapshot
);
1019 * Sets the editor data. The data must be provided in the "raw" format (HTML).
1021 * Note that this method is asynchronous. The `callback` parameter must
1022 * be used if interaction with the editor is needed after setting the data.
1024 * CKEDITOR.instances.editor1.setData( '<p>This is the editor data.</p>' );
1026 * CKEDITOR.instances.editor1.setData( '<p>Some other editor data.</p>', {
1027 * callback: function() {
1028 * this.checkDirty(); // true
1032 * Note: In **CKEditor 4.4.2** the signature of this method has changed. All arguments
1033 * except `data` were wrapped into the `options` object. However, backward compatibility
1034 * was preserved and it is still possible to use the `data, callback, internal` arguments.
1037 * @param {String} data The HTML code to replace current editor content.
1038 * @param {Object} [options]
1039 * @param {Boolean} [options.internal=false] Whether to suppress any event firing when copying data internally inside the editor.
1040 * @param {Function} [options.callback] Function to be called after `setData` is completed (on {@link #dataReady}).
1041 * @param {Boolean} [options.noSnapshot=false] If set to `true`, it will prevent recording an undo snapshot.
1042 * Introduced in CKEditor 4.4.2.
1044 setData: function( data
, options
, internal ) {
1045 var fireSnapshot
= true,
1046 // Backward compatibility.
1050 if ( options
&& typeof options
== 'object' ) {
1051 internal = options
.internal;
1052 callback
= options
.callback
;
1053 fireSnapshot
= !options
.noSnapshot
;
1056 if ( !internal && fireSnapshot
)
1057 this.fire( 'saveSnapshot' );
1059 if ( callback
|| !internal ) {
1060 this.once( 'dataReady', function( evt
) {
1061 if ( !internal && fireSnapshot
)
1062 this.fire( 'saveSnapshot' );
1065 callback
.call( evt
.editor
);
1069 // Fire "setData" so data manipulation may happen.
1070 eventData
= { dataValue: data
};
1071 !internal && this.fire( 'setData', eventData
);
1073 this._
.data
= eventData
.dataValue
;
1075 !internal && this.fire( 'afterSetData', eventData
);
1079 * Puts or restores the editor into the read-only state. When in read-only,
1080 * the user is not able to change the editor content, but can still use
1081 * some editor features. This function sets the {@link #property-readOnly}
1082 * property of the editor, firing the {@link #event-readOnly} event.
1084 * **Note:** The current editing area will be reloaded.
1087 * @param {Boolean} [isReadOnly] Indicates that the editor must go
1088 * read-only (`true`, default) or be restored and made editable (`false`).
1090 setReadOnly: function( isReadOnly
) {
1091 isReadOnly
= ( isReadOnly
== null ) || isReadOnly
;
1093 if ( this.readOnly
!= isReadOnly
) {
1094 this.readOnly
= isReadOnly
;
1096 // Block or release BACKSPACE key according to current read-only
1097 // state to prevent browser's history navigation (http://dev.ckeditor.com/ticket/9761).
1098 this.keystrokeHandler
.blockedKeystrokes
[ 8 ] = +isReadOnly
;
1100 this.editable().setReadOnly( isReadOnly
);
1102 // Fire the readOnly event so the editor features can update
1103 // their state accordingly.
1104 this.fire( 'readOnly' );
1109 * Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.
1113 * CKEDITOR.instances.editor1.insertHtml( '<p>This is a new paragraph.</p>' );
1115 * Fires the {@link #event-insertHtml} and {@link #event-afterInsertHtml} events. The HTML is inserted
1116 * in the {@link #event-insertHtml} event's listener with a default priority (10) so you can add listeners with
1117 * lower or higher priorities in order to execute some code before or after the HTML is inserted.
1119 * @param {String} html HTML code to be inserted into the editor.
1120 * @param {String} [mode='html'] The mode in which the HTML code will be inserted. One of the following:
1122 * * `'html'` – The inserted content will completely override the styles at the selected position.
1123 * * `'unfiltered_html'` – Like `'html'` but the content is not filtered with {@link CKEDITOR.filter}.
1124 * * `'text'` – The inserted content will inherit the styles applied in
1125 * the selected position. This mode should be used when inserting "htmlified" plain text
1126 * (HTML without inline styles and styling elements like `<b>`, `<strong>`, `<span style="...">`).
1128 * @param {CKEDITOR.dom.range} [range] If specified, the HTML will be inserted into the range
1129 * instead of into the selection. The selection will be placed at the end of the insertion (like in the normal case).
1130 * Introduced in CKEditor 4.5.
1132 insertHtml: function( html
, mode
, range
) {
1133 this.fire( 'insertHtml', { dataValue: html
, mode: mode
, range: range
} );
1137 * Inserts text content into the currently selected position in the
1138 * editor in WYSIWYG mode. The styles of the selected element will be applied to the inserted text.
1139 * Spaces around the text will be left untouched.
1141 * CKEDITOR.instances.editor1.insertText( ' line1 \n\n line2' );
1143 * Fires the {@link #event-insertText} and {@link #event-afterInsertHtml} events. The text is inserted
1144 * in the {@link #event-insertText} event's listener with a default priority (10) so you can add listeners with
1145 * lower or higher priorities in order to execute some code before or after the text is inserted.
1148 * @param {String} text Text to be inserted into the editor.
1150 insertText: function( text
) {
1151 this.fire( 'insertText', text
);
1155 * Inserts an element into the currently selected position in the editor in WYSIWYG mode.
1157 * var element = CKEDITOR.dom.element.createFromHtml( '<img src="hello.png" border="0" title="Hello" />' );
1158 * CKEDITOR.instances.editor1.insertElement( element );
1160 * Fires the {@link #event-insertElement} event. The element is inserted in the listener with a default priority (10),
1161 * so you can add listeners with lower or higher priorities in order to execute some code before or after
1162 * the element is inserted.
1164 * @param {CKEDITOR.dom.element} element The element to be inserted into the editor.
1166 insertElement: function( element
) {
1167 this.fire( 'insertElement', element
);
1171 * Gets the selected HTML (it is returned as a {@link CKEDITOR.dom.documentFragment document fragment}
1172 * or a string). This method is designed to work as the user would expect the copy functionality to work.
1173 * For instance, if the following selection was made:
1175 * <p>a<b>b{c}d</b>e</p>
1177 * The following HTML will be returned:
1181 * As you can see, the information about the bold formatting was preserved, even though the selection was
1182 * anchored inside the `<b>` element.
1186 * * the {@link #extractSelectedHtml} method,
1187 * * the {@link CKEDITOR.editable#getHtmlFromRange} method.
1190 * @param {Boolean} [toString] If `true`, then stringified HTML will be returned.
1191 * @returns {CKEDITOR.dom.documentFragment/String}
1193 getSelectedHtml: function( toString
) {
1194 var editable
= this.editable(),
1195 selection
= this.getSelection(),
1196 ranges
= selection
&& selection
.getRanges();
1198 if ( !editable
|| !ranges
|| ranges
.length
=== 0 ) {
1202 var docFragment
= createDocumentFragmentFromRanges( ranges
, editable
);
1204 return toString
? docFragment
.getHtml() : docFragment
;
1208 * Gets the selected HTML (it is returned as a {@link CKEDITOR.dom.documentFragment document fragment}
1209 * or a string) and removes the selected part of the DOM. This method is designed to work as the user would
1210 * expect the cut and delete functionalities to work.
1214 * * the {@link #getSelectedHtml} method,
1215 * * the {@link CKEDITOR.editable#extractHtmlFromRange} method.
1218 * @param {Boolean} [toString] If `true`, then stringified HTML will be returned.
1219 * @param {Boolean} [removeEmptyBlock=false] Default `false` means that the function will keep an empty block (if the
1220 * entire content was removed) or it will create it (if a block element was removed) and set the selection in that block.
1221 * If `true`, the empty block will be removed or not created. In this case the function will not handle the selection.
1222 * @returns {CKEDITOR.dom.documentFragment/String/null}
1224 extractSelectedHtml: function( toString
, removeEmptyBlock
) {
1225 var editable
= this.editable(),
1226 ranges
= this.getSelection().getRanges(),
1227 docFragment
= new CKEDITOR
.dom
.documentFragment(),
1230 if ( !editable
|| ranges
.length
=== 0 ) {
1234 for ( i
= 0; i
< ranges
.length
; i
++ ) {
1235 docFragment
.append( editable
.extractHtmlFromRange( ranges
[ i
], removeEmptyBlock
) );
1238 if ( !removeEmptyBlock
) {
1239 this.getSelection().selectRanges( [ ranges
[ 0 ] ] );
1242 return toString
? docFragment
.getHtml() : docFragment
;
1246 * Moves the selection focus to the editing area space in the editor.
1249 this.fire( 'beforeFocus' );
1253 * Checks whether the current editor content contains changes when
1254 * compared to the content loaded into the editor at startup, or to
1255 * the content available in the editor when {@link #resetDirty}
1258 * function beforeUnload( evt ) {
1259 * if ( CKEDITOR.instances.editor1.checkDirty() )
1260 * return evt.returnValue = "You will lose the changes made in the editor.";
1263 * if ( window.addEventListener )
1264 * window.addEventListener( 'beforeunload', beforeUnload, false );
1266 * window.attachEvent( 'onbeforeunload', beforeUnload );
1268 * @returns {Boolean} `true` if the content contains changes.
1270 checkDirty: function() {
1271 return this.status
== 'ready' && this._
.previousValue
!== this.getSnapshot();
1275 * Resets the "dirty state" of the editor so subsequent calls to
1276 * {@link #checkDirty} will return `false` if the user will not
1277 * have made further changes to the content.
1279 * alert( editor.checkDirty() ); // e.g. true
1280 * editor.resetDirty();
1281 * alert( editor.checkDirty() ); // false
1283 resetDirty: function() {
1284 this._
.previousValue
= this.getSnapshot();
1288 * Updates the `<textarea>` element that was replaced by the editor with
1289 * the current data available in the editor.
1291 * **Note:** This method will only affect those editor instances created
1292 * with the {@link CKEDITOR#ELEMENT_MODE_REPLACE} element mode or inline instances
1293 * bound to `<textarea>` elements.
1295 * CKEDITOR.instances.editor1.updateElement();
1296 * alert( document.getElementById( 'editor1' ).value ); // The current editor data.
1298 * @see CKEDITOR.editor#element
1300 updateElement: function() {
1301 return updateEditorElement
.call( this );
1305 * Assigns keystrokes associated with editor commands.
1307 * editor.setKeystroke( CKEDITOR.CTRL + 115, 'save' ); // Assigned Ctrl+S to the "save" command.
1308 * editor.setKeystroke( CKEDITOR.CTRL + 115, false ); // Disabled Ctrl+S keystroke assignment.
1309 * editor.setKeystroke( [
1310 * [ CKEDITOR.ALT + 122, false ],
1311 * [ CKEDITOR.CTRL + 121, 'link' ],
1312 * [ CKEDITOR.SHIFT + 120, 'bold' ]
1315 * This method may be used in the following cases:
1317 * * By plugins (like `link` or `basicstyles`) to set their keystrokes when plugins are being loaded.
1318 * * During the runtime to modify existing keystrokes.
1320 * The editor handles keystroke configuration in the following order:
1322 * 1. Plugins use this method to define default keystrokes.
1323 * 2. Editor extends default keystrokes with {@link CKEDITOR.config#keystrokes}.
1324 * 3. Editor blocks keystrokes defined in {@link CKEDITOR.config#blockedKeystrokes}.
1326 * You can then set new keystrokes using this method during the runtime.
1329 * @param {Number/Array} keystroke A keystroke or an array of keystroke definitions.
1330 * @param {String/Boolean} [behavior] A command to be executed on the keystroke.
1332 setKeystroke: function() {
1333 var keystrokes
= this.keystrokeHandler
.keystrokes
,
1334 newKeystrokes
= CKEDITOR
.tools
.isArray( arguments
[ 0 ] ) ? arguments
[ 0 ] : [ [].slice
.call( arguments
, 0 ) ],
1335 keystroke
, behavior
;
1337 for ( var i
= newKeystrokes
.length
; i
--; ) {
1338 keystroke
= newKeystrokes
[ i
];
1341 // It may be a pair of: [ key, command ]
1342 if ( CKEDITOR
.tools
.isArray( keystroke
) ) {
1343 behavior
= keystroke
[ 1 ];
1344 keystroke
= keystroke
[ 0 ];
1348 keystrokes
[ keystroke
] = behavior
;
1350 delete keystrokes
[ keystroke
];
1355 * Returns the keystroke that is assigned to a specified {@link CKEDITOR.command}. If no keystroke is assigned,
1356 * it returns `null`.
1358 * Since version 4.7.0 this function also accepts a `command` parameter as a string.
1361 * @param {CKEDITOR.command/String} command The {@link CKEDITOR.command} instance or a string with the command name.
1362 * @returns {Number/null} The keystroke assigned to the provided command or `null` if there is no keystroke.
1364 getCommandKeystroke: function( command
) {
1365 var commandInstance
= ( typeof command
=== 'string' ? this.getCommand( command
) : command
);
1367 if ( commandInstance
) {
1368 var commandName
= CKEDITOR
.tools
.object
.findKey( this.commands
, commandInstance
),
1369 keystrokes
= this.keystrokeHandler
.keystrokes
,
1372 // Some commands have a fake keystroke - for example CUT/COPY/PASTE commands are handled natively.
1373 if ( commandInstance
.fakeKeystroke
) {
1374 return commandInstance
.fakeKeystroke
;
1377 for ( key
in keystrokes
) {
1378 if ( keystrokes
.hasOwnProperty( key
) && keystrokes
[ key
] == commandName
) {
1387 * Shorthand for {@link CKEDITOR.filter#addFeature}.
1390 * @param {CKEDITOR.feature} feature See {@link CKEDITOR.filter#addFeature}.
1391 * @returns {Boolean} See {@link CKEDITOR.filter#addFeature}.
1393 addFeature: function( feature
) {
1394 return this.filter
.addFeature( feature
);
1398 * Sets the active filter ({@link #activeFilter}). Fires the {@link #activeFilterChange} event.
1400 * // Set active filter which allows only 4 elements.
1401 * // Buttons like Bold, Italic will be disabled.
1402 * var filter = new CKEDITOR.filter( 'p strong em br' );
1403 * editor.setActiveFilter( filter );
1405 * Setting a new filter will also change the {@link #setActiveEnterMode active Enter modes} to the first values
1406 * allowed by the new filter (see {@link CKEDITOR.filter#getAllowedEnterMode}).
1409 * @param {CKEDITOR.filter} filter Filter instance or a falsy value (e.g. `null`) to reset to the default one.
1411 setActiveFilter: function( filter
) {
1413 filter
= this.filter
;
1415 if ( this.activeFilter
!== filter
) {
1416 this.activeFilter
= filter
;
1417 this.fire( 'activeFilterChange' );
1419 // Reset active filter to the main one - it resets enter modes, too.
1420 if ( filter
=== this.filter
)
1421 this.setActiveEnterMode( null, null );
1423 this.setActiveEnterMode(
1424 filter
.getAllowedEnterMode( this.enterMode
),
1425 filter
.getAllowedEnterMode( this.shiftEnterMode
, true )
1431 * Sets the active Enter modes: ({@link #enterMode} and {@link #shiftEnterMode}).
1432 * Fires the {@link #activeEnterModeChange} event.
1434 * Prior to CKEditor 4.3 Enter modes were static and it was enough to check {@link CKEDITOR.config#enterMode}
1435 * and {@link CKEDITOR.config#shiftEnterMode} when implementing a feature which should depend on the Enter modes.
1436 * Since CKEditor 4.3 these options are source of initial:
1438 * * static {@link #enterMode} and {@link #shiftEnterMode} values,
1439 * * dynamic {@link #activeEnterMode} and {@link #activeShiftEnterMode} values.
1441 * However, the dynamic Enter modes can be changed during runtime by using this method, to reflect the selection context.
1442 * For example, if selection is moved to the {@link CKEDITOR.plugins.widget widget}'s nested editable which
1443 * is a {@link #blockless blockless one}, then the active Enter modes should be changed to {@link CKEDITOR#ENTER_BR}
1444 * (in this case [Widget System](#!/guide/dev_widgets) takes care of that).
1446 * **Note:** This method should not be used to configure the editor – use {@link CKEDITOR.config#enterMode} and
1447 * {@link CKEDITOR.config#shiftEnterMode} instead. This method should only be used to dynamically change
1448 * Enter modes during runtime based on selection changes.
1449 * Keep in mind that changed Enter mode may be overwritten by another plugin/feature when it decided that
1450 * the changed context requires this.
1452 * **Note:** In case of blockless editor (inline editor based on an element which cannot contain block elements
1453 * — see {@link CKEDITOR.editor#blockless}) only {@link CKEDITOR#ENTER_BR} is a valid Enter mode. Therefore
1454 * this method will not allow to set other values.
1456 * **Note:** Changing the {@link #activeFilter active filter} may cause the Enter mode to change if default Enter modes
1457 * are not allowed by the new filter.
1460 * @param {Number} enterMode One of {@link CKEDITOR#ENTER_P}, {@link CKEDITOR#ENTER_DIV}, {@link CKEDITOR#ENTER_BR}.
1461 * Pass falsy value (e.g. `null`) to reset the Enter mode to the default value ({@link #enterMode} and/or {@link #shiftEnterMode}).
1462 * @param {Number} shiftEnterMode See the `enterMode` argument.
1464 setActiveEnterMode: function( enterMode
, shiftEnterMode
) {
1465 // Validate passed modes or use default ones (validated on init).
1466 enterMode
= enterMode
? validateEnterMode( this, enterMode
) : this.enterMode
;
1467 shiftEnterMode
= shiftEnterMode
? validateEnterMode( this, shiftEnterMode
) : this.shiftEnterMode
;
1469 if ( this.activeEnterMode
!= enterMode
|| this.activeShiftEnterMode
!= shiftEnterMode
) {
1470 this.activeEnterMode
= enterMode
;
1471 this.activeShiftEnterMode
= shiftEnterMode
;
1472 this.fire( 'activeEnterModeChange' );
1477 * Shows a notification to the user.
1479 * If the [Notification](http://ckeditor.com/addons/notification) plugin is not enabled, this function shows
1480 * a normal alert with the given `message`. The `type` and `progressOrDuration` parameters are supported
1481 * only by the Notification plugin.
1483 * If the Notification plugin is enabled, this method creates and shows a new notification.
1484 * By default the notification is shown over the editor content, in the viewport if it is possible.
1486 * See {@link CKEDITOR.plugins.notification}.
1489 * @member CKEDITOR.editor
1490 * @param {String} message The message displayed in the notification.
1491 * @param {String} [type='info'] The type of the notification. Can be `'info'`, `'warning'`, `'success'` or `'progress'`.
1492 * @param {Number} [progressOrDuration] If the type is `progress`, the third parameter may be a progress from `0` to `1`
1493 * (defaults to `0`). Otherwise the third parameter may be a notification duration denoting after how many milliseconds
1494 * the notification should be closed automatically. `0` means that the notification will not close automatically and the user
1495 * needs to close it manually. See {@link CKEDITOR.plugins.notification#duration}.
1496 * Note that `warning` notifications will not be closed automatically.
1497 * @returns {CKEDITOR.plugins.notification} Created and shown notification.
1499 showNotification: function( message
) {
1500 alert( message
); // jshint ignore:line
1506 * The editor has no associated element.
1509 * @property {Number} [=0]
1512 CKEDITOR
.ELEMENT_MODE_NONE
= 0;
1515 * The element is to be replaced by the editor instance.
1518 * @property {Number} [=1]
1521 CKEDITOR
.ELEMENT_MODE_REPLACE
= 1;
1524 * The editor is to be created inside the element.
1527 * @property {Number} [=2]
1530 CKEDITOR
.ELEMENT_MODE_APPENDTO
= 2;
1533 * The editor is to be attached to the element, using it as the editing block.
1536 * @property {Number} [=3]
1539 CKEDITOR
.ELEMENT_MODE_INLINE
= 3;
1542 * Whether to escape HTML when the editor updates the original input element.
1544 * config.htmlEncodeOutput = true;
1547 * @cfg {Boolean} [htmlEncodeOutput=false]
1548 * @member CKEDITOR.config
1552 * If `true`, makes the editor start in read-only state. Otherwise, it will check
1553 * if the linked `<textarea>` element has the `disabled` attribute.
1555 * Read more in the [documentation](#!/guide/dev_readonly)
1556 * and see the [SDK sample](http://sdk.ckeditor.com/samples/readonly.html).
1558 * config.readOnly = true;
1561 * @cfg {Boolean} [readOnly=false]
1562 * @member CKEDITOR.config
1563 * @see CKEDITOR.editor#setReadOnly
1567 * Whether an editable element should have focus when the editor is loading for the first time.
1569 * config.startupFocus = true;
1571 * @cfg {Boolean} [startupFocus=false]
1572 * @member CKEDITOR.config
1576 * Customizes the {@link CKEDITOR.editor#title human-readable title} of this editor. This title is displayed in
1577 * tooltips and impacts various [accessibility aspects](#!/guide/dev_a11y-section-announcing-the-editor-on-the-page),
1578 * e.g. it is commonly used by screen readers for distinguishing editor instances and for navigation.
1579 * Accepted values are a string or `false`.
1581 * **Note:** When `config.title` is set globally, the same value will be applied to all editor instances
1582 * loaded with this config. This may adversely affect accessibility as screen reader users will be unable
1583 * to distinguish particular editor instances and navigate between them.
1585 * **Note:** Setting `config.title = false` may also impair accessibility in a similar way.
1587 * **Note:** Please do not confuse this property with {@link CKEDITOR.editor#name}
1588 * which identifies the instance in the {@link CKEDITOR#instances} literal.
1590 * // Sets the title to 'My WYSIWYG editor.'. The original title of the element (if it exists)
1591 * // will be restored once the editor instance is destroyed.
1592 * config.title = 'My WYSIWYG editor.';
1594 * // Do not touch the title. If the element already has a title, it remains unchanged.
1595 * // Also if no `title` attribute exists, nothing new will be added.
1596 * config.title = false;
1600 * * CKEDITOR.editor#name
1601 * * CKEDITOR.editor#title
1604 * @cfg {String/Boolean} [title=based on editor.name]
1605 * @member CKEDITOR.config
1609 * Sets listeners on editor events.
1611 * **Note:** This property can only be set in the `config` object passed directly
1612 * to {@link CKEDITOR#replace}, {@link CKEDITOR#inline}, and other creators.
1614 * CKEDITOR.replace( 'editor1', {
1616 * instanceReady: function() {
1617 * alert( this.name ); // 'editor1'
1627 * @member CKEDITOR.config
1631 * The outermost element in the DOM tree in which the editable element resides. It is provided
1632 * by a specific editor creator after the editor UI is created and is not intended to
1635 * var editor = CKEDITOR.instances.editor1;
1636 * alert( editor.container.getName() ); // 'span'
1639 * @property {CKEDITOR.dom.element} container
1643 * The document that stores the editor content.
1645 * * For the classic (`iframe`-based) editor it is equal to the document inside the
1646 * `iframe` containing the editable element.
1647 * * For the inline editor it is equal to {@link CKEDITOR#document}.
1649 * The document object is available after the {@link #contentDom} event is fired
1650 * and may be invalidated when the {@link #contentDomUnload} event is fired
1651 * (classic editor only).
1653 * editor.on( 'contentDom', function() {
1654 * console.log( editor.document );
1658 * @property {CKEDITOR.dom.document} document
1662 * The window instance related to the {@link #document} property.
1664 * It is always equal to the `editor.document.getWindow()`.
1666 * See the {@link #document} property documentation.
1669 * @property {CKEDITOR.dom.window} window
1673 * The main filter instance used for input data filtering, data
1674 * transformations, and activation of features.
1676 * It points to a {@link CKEDITOR.filter} instance set up based on
1677 * editor configuration.
1681 * @property {CKEDITOR.filter} filter
1685 * The active filter instance which should be used in the current context (location selection).
1686 * This instance will be used to make a decision which commands, buttons and other
1687 * {@link CKEDITOR.feature features} can be enabled.
1689 * By default it equals the {@link #filter} and it can be changed by the {@link #setActiveFilter} method.
1691 * editor.on( 'activeFilterChange', function() {
1692 * if ( editor.activeFilter.check( 'cite' ) )
1693 * // Do something when <cite> was enabled - e.g. enable a button.
1695 * // Otherwise do something else.
1698 * See also the {@link #setActiveEnterMode} method for an explanation of dynamic settings.
1702 * @property {CKEDITOR.filter} activeFilter
1706 * The main (static) Enter mode which is a validated version of the {@link CKEDITOR.config#enterMode} setting.
1707 * Currently only one rule exists — {@link #blockless blockless editors} may have
1708 * Enter modes set only to {@link CKEDITOR#ENTER_BR}.
1712 * @property {Number} enterMode
1716 * See the {@link #enterMode} property.
1720 * @property {Number} shiftEnterMode
1724 * The dynamic Enter mode which should be used in the current context (selection location).
1725 * By default it equals the {@link #enterMode} and it can be changed by the {@link #setActiveEnterMode} method.
1727 * See also the {@link #setActiveEnterMode} method for an explanation of dynamic settings.
1731 * @property {Number} activeEnterMode
1735 * See the {@link #activeEnterMode} property.
1739 * @property {Number} activeShiftEnterMode
1743 * Event fired by the {@link #setActiveFilter} method when the {@link #activeFilter} is changed.
1746 * @event activeFilterChange
1750 * Event fired by the {@link #setActiveEnterMode} method when any of the active Enter modes is changed.
1751 * See also the {@link #activeEnterMode} and {@link #activeShiftEnterMode} properties.
1754 * @event activeEnterModeChange
1758 * Event fired when a CKEDITOR instance is created, but still before initializing it.
1759 * To interact with a fully initialized instance, use the
1760 * {@link CKEDITOR#instanceReady} event instead.
1762 * @event instanceCreated
1764 * @param {CKEDITOR.editor} editor The editor instance that has been created.
1768 * Event fired when CKEDITOR instance's components (configuration, languages and plugins) are fully
1769 * loaded and initialized. However, the editor will be fully ready for interaction
1770 * on {@link CKEDITOR#instanceReady}.
1772 * @event instanceLoaded
1774 * @param {CKEDITOR.editor} editor This editor instance that has been loaded.
1778 * Event fired when a CKEDITOR instance is destroyed.
1780 * @event instanceDestroyed
1782 * @param {CKEDITOR.editor} editor The editor instance that has been destroyed.
1786 * Event fired when a CKEDITOR instance is created, fully initialized and ready for interaction.
1788 * @event instanceReady
1790 * @param {CKEDITOR.editor} editor The editor instance that has been created.
1794 * Event fired when the language is loaded into the editor instance.
1798 * @param {CKEDITOR.editor} editor This editor instance.
1802 * Event fired when all plugins are loaded and initialized into the editor instance.
1804 * @event pluginsLoaded
1805 * @param {CKEDITOR.editor} editor This editor instance.
1809 * Event fired when the styles set is loaded. During the editor initialization
1810 * phase the {@link #getStylesSet} method returns only styles that
1811 * are already loaded, which may not include e.g. styles parsed
1812 * by the `stylesheetparser` plugin. Thus, to be notified when all
1813 * styles are ready, you can listen on this event.
1817 * @param {CKEDITOR.editor} editor This editor instance.
1818 * @param {Array} styles An array of styles definitions.
1822 * Event fired before the command execution when {@link #execCommand} is called.
1824 * @event beforeCommandExec
1825 * @param {CKEDITOR.editor} editor This editor instance.
1827 * @param {String} data.name The command name.
1828 * @param {Object} data.commandData The data to be sent to the command. This
1829 * can be manipulated by the event listener.
1830 * @param {CKEDITOR.command} data.command The command itself.
1834 * Event fired after the command execution when {@link #execCommand} is called.
1836 * @event afterCommandExec
1837 * @param {CKEDITOR.editor} editor This editor instance.
1839 * @param {String} data.name The command name.
1840 * @param {Object} data.commandData The data sent to the command.
1841 * @param {CKEDITOR.command} data.command The command itself.
1842 * @param {Object} data.returnValue The value returned by the command execution.
1846 * Event fired when a custom configuration file is loaded, before the final
1847 * configuration initialization.
1849 * Custom configuration files can be loaded thorugh the
1850 * {@link CKEDITOR.config#customConfig} setting. Several files can be loaded
1851 * by changing this setting.
1853 * @event customConfigLoaded
1854 * @param {CKEDITOR.editor} editor This editor instance.
1858 * Event fired once the editor configuration is ready (loaded and processed).
1860 * @event configLoaded
1861 * @param {CKEDITOR.editor} editor This editor instance.
1865 * Event fired when this editor instance is destroyed. The editor at this
1866 * point is not usable and this event should be used to perform the clean-up
1870 * @param {CKEDITOR.editor} editor This editor instance.
1874 * Event fired when the {@link #method-destroy} method is called,
1875 * but before destroying the editor.
1877 * @event beforeDestroy
1878 * @param {CKEDITOR.editor} editor This editor instance.
1882 * Internal event to get the current data.
1884 * @event beforeGetData
1885 * @param {CKEDITOR.editor} editor This editor instance.
1889 * Internal event to perform the {@link #method-getSnapshot} call.
1891 * @event getSnapshot
1892 * @param {CKEDITOR.editor} editor This editor instance.
1896 * Internal event to perform the {@link #method-loadSnapshot} call.
1898 * @event loadSnapshot
1899 * @param {CKEDITOR.editor} editor This editor instance.
1900 * @param {String} data The data that will be used.
1904 * Event fired before the {@link #method-getData} call returns, allowing for additional manipulation.
1907 * @param {CKEDITOR.editor} editor This editor instance.
1909 * @param {String} data.dataValue The data that will be returned.
1913 * Event fired before the {@link #method-setData} call is executed, allowing for additional manipulation.
1916 * @param {CKEDITOR.editor} editor This editor instance.
1918 * @param {String} data.dataValue The data that will be used.
1922 * Event fired at the end of the {@link #method-setData} call execution. Usually it is better to use the
1923 * {@link #dataReady} event.
1925 * @event afterSetData
1926 * @param {CKEDITOR.editor} editor This editor instance.
1928 * @param {String} data.dataValue The data that has been set.
1932 * Event fired as an indicator of the editor data loading. It may be the result of
1933 * calling {@link #method-setData} explicitly or an internal
1934 * editor function, like the editor editing mode switching (move to Source and back).
1937 * @param {CKEDITOR.editor} editor This editor instance.
1941 * Event fired when the CKEDITOR instance is completely created, fully initialized
1942 * and ready for interaction.
1944 * @event instanceReady
1945 * @param {CKEDITOR.editor} editor This editor instance.
1949 * Event fired when editor components (configuration, languages and plugins) are fully
1950 * loaded and initialized. However, the editor will be fully ready to for interaction
1951 * on {@link #instanceReady}.
1954 * @param {CKEDITOR.editor} editor This editor instance.
1958 * Event fired by the {@link #method-insertHtml} method. See the method documentation for more information
1959 * about how this event can be used.
1962 * @param {CKEDITOR.editor} editor This editor instance.
1964 * @param {String} data.mode The mode in which the data is inserted (see {@link #method-insertHtml}).
1965 * @param {String} data.dataValue The HTML code to insert.
1966 * @param {CKEDITOR.dom.range} [data.range] See {@link #method-insertHtml}'s `range` parameter.
1970 * Event fired by the {@link #method-insertText} method. See the method documentation for more information
1971 * about how this event can be used.
1974 * @param {CKEDITOR.editor} editor This editor instance.
1975 * @param {String} data The text to insert.
1979 * Event fired by the {@link #method-insertElement} method. See the method documentation for more information
1980 * about how this event can be used.
1982 * @event insertElement
1983 * @param {CKEDITOR.editor} editor This editor instance.
1984 * @param {CKEDITOR.dom.element} data The element to insert.
1988 * Event fired after data insertion using the {@link #method-insertHtml}, {@link CKEDITOR.editable#insertHtml},
1989 * or {@link CKEDITOR.editable#insertHtmlIntoRange} methods.
1992 * @event afterInsertHtml
1994 * @param {CKEDITOR.dom.range} [data.intoRange] If set, the HTML was not inserted into the current selection, but into
1995 * the specified range. This property is set if the {@link CKEDITOR.editable#insertHtmlIntoRange} method was used,
1996 * but not if for the {@link CKEDITOR.editable#insertHtml} method.
2000 * Event fired after the {@link #property-readOnly} property changes.
2004 * @param {CKEDITOR.editor} editor This editor instance.
2008 * Event fired when a UI template is added to the editor instance. It makes
2009 * it possible to bring customizations to the template source.
2012 * @param {CKEDITOR.editor} editor This editor instance.
2014 * @param {String} data.name The template name.
2015 * @param {String} data.source The source data for this template.
2019 * Event fired when the editor content (its DOM structure) is ready.
2020 * It is similar to the native `DOMContentLoaded` event, but it applies to
2021 * the editor content. It is also the first event fired after
2022 * the {@link CKEDITOR.editable} is initialized.
2024 * This event is particularly important for classic (`iframe`-based)
2025 * editor, because on editor initialization and every time the data are set
2026 * (by {@link CKEDITOR.editor#method-setData}) content DOM structure
2027 * is rebuilt. Thus, e.g. you need to attach DOM event listeners
2028 * on editable one more time.
2030 * For inline editor this event is fired only once — when the
2031 * editor is initialized for the first time. This is because setting
2032 * editor content does not cause editable destruction and creation.
2034 * The {@link #contentDom} event goes along with {@link #contentDomUnload}
2035 * which is fired before the content DOM structure is destroyed. This is the
2036 * right moment to detach content DOM event listener. Otherwise
2037 * browsers like IE or Opera may throw exceptions when accessing
2038 * elements from the detached document.
2040 * **Note:** {@link CKEDITOR.editable#attachListener} is a convenient
2041 * way to attach listeners that will be detached on {@link #contentDomUnload}.
2043 * editor.on( 'contentDom', function() {
2044 * var editable = editor.editable();
2046 * editable.attachListener( editable, 'click', function() {
2047 * console.log( 'The editable was clicked.' );
2052 * @param {CKEDITOR.editor} editor This editor instance.
2056 * Event fired before the content DOM structure is destroyed.
2057 * See {@link #contentDom} documentation for more details.
2059 * @event contentDomUnload
2060 * @param {CKEDITOR.editor} editor This editor instance.
2064 * Event fired when the content DOM changes and some of the references as well as
2065 * the native DOM event listeners could be lost.
2066 * This event is useful when it is important to keep track of references
2067 * to elements in the editable content from code.
2070 * @event contentDomInvalidated
2071 * @param {CKEDITOR.editor} editor This editor instance.