]>
git.immae.eu Git - perso/Immae/Projets/packagist/connexionswing-ckeditor-component.git/blob - sources/core/editor.js
2 * @license Copyright (c) 2003-2015, 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. (#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 #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 (#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 CKEDITOR
.tools
.extend( CKEDITOR
.editor
.prototype, {
659 * Adds a command definition to the editor instance. Commands added with
660 * this function can be executed later with the <code>{@link #execCommand}</code> method.
662 * editorInstance.addCommand( 'sample', {
663 * exec: function( editor ) {
664 * alert( 'Executing a command for the editor name "' + editor.name + '"!' );
668 * @param {String} commandName The indentifier name of the command.
669 * @param {CKEDITOR.commandDefinition} commandDefinition The command definition.
671 addCommand: function( commandName
, commandDefinition
) {
672 commandDefinition
.name
= commandName
.toLowerCase();
673 var cmd
= new CKEDITOR
.command( this, commandDefinition
);
675 // Update command when mode is set.
676 // This guarantees that commands added before first editor#mode
677 // aren't immediately updated, but waits for editor#mode and that
678 // commands added later are immediately refreshed, even when added
679 // before instanceReady. #10103, #10249
681 updateCommand( this, cmd
);
683 return this.commands
[ commandName
] = cmd
;
687 * Attaches the editor to a form to call {@link #updateElement} before form submission.
688 * This method is called by both creators ({@link CKEDITOR#replace replace} and
689 * {@link CKEDITOR#inline inline}), so there is no reason to call it manually.
693 _attachToForm: function() {
695 element
= editor
.element
,
696 form
= new CKEDITOR
.dom
.element( element
.$.form
);
698 // If are replacing a textarea, we must
699 if ( element
.is( 'textarea' ) ) {
701 form
.on( 'submit', onSubmit
);
703 // Check if there is no element/elements input with name == "submit".
704 // If they exists they will overwrite form submit function (form.$.submit).
705 // If form.$.submit is overwritten we can not do anything with it.
706 if ( isFunction( form
.$.submit
) ) {
707 // Setup the submit function because it doesn't fire the
709 form
.$.submit
= CKEDITOR
.tools
.override( form
.$.submit
, function( originalSubmit
) {
713 // For IE, the DOM submit function is not a
714 // function, so we need third check.
715 if ( originalSubmit
.apply
)
716 originalSubmit
.apply( this );
723 // Remove 'submit' events registered on form element before destroying.(#3988)
724 editor
.on( 'destroy', function() {
725 form
.removeListener( 'submit', onSubmit
);
730 function onSubmit( evt
) {
731 editor
.updateElement();
733 // #8031 If textarea had required attribute and editor is empty fire 'required' event and if
734 // it was cancelled, prevent submitting the form.
735 if ( editor
._
.required
&& !element
.getValue() && editor
.fire( 'required' ) === false ) {
736 // When user press save button event (evt) is undefined (see save plugin).
737 // This method works because it throws error so originalSubmit won't be called.
738 // Also this error won't be shown because it will be caught in save plugin.
739 evt
.data
.preventDefault();
743 function isFunction( f
) {
744 // For IE8 typeof fun == object so we cannot use it.
745 return !!( f
&& f
.call
&& f
.apply
);
750 * Destroys the editor instance, releasing all resources used by it.
751 * If the editor replaced an element, the element will be recovered.
753 * alert( CKEDITOR.instances.editor1 ); // e.g. object
754 * CKEDITOR.instances.editor1.destroy();
755 * alert( CKEDITOR.instances.editor1 ); // undefined
757 * @param {Boolean} [noUpdate] If the instance is replacing a DOM
758 * element, this parameter indicates whether or not to update the
759 * element with the instance content.
761 destroy: function( noUpdate
) {
762 this.fire( 'beforeDestroy' );
764 !noUpdate
&& updateEditorElement
.call( this );
766 this.editable( null );
769 this.filter
.destroy();
773 delete this.activeFilter
;
775 this.status
= 'destroyed';
777 this.fire( 'destroy' );
779 // Plug off all listeners to prevent any further events firing.
780 this.removeAllListeners();
782 CKEDITOR
.remove( this );
783 CKEDITOR
.fire( 'instanceDestroyed', null, this );
787 * Returns an {@link CKEDITOR.dom.elementPath element path} for the selection in the editor.
789 * @param {CKEDITOR.dom.node} [startNode] From which the path should start,
790 * if not specified defaults to editor selection's
791 * start element yielded by {@link CKEDITOR.dom.selection#getStartElement}.
792 * @returns {CKEDITOR.dom.elementPath}
794 elementPath: function( startNode
) {
796 var sel
= this.getSelection();
800 startNode
= sel
.getStartElement();
803 return startNode
? new CKEDITOR
.dom
.elementPath( startNode
, this.editable() ) : null;
807 * Shortcut to create a {@link CKEDITOR.dom.range} instance from the editable element.
809 * @returns {CKEDITOR.dom.range} The DOM range created if the editable has presented.
810 * @see CKEDITOR.dom.range
812 createRange: function() {
813 var editable
= this.editable();
814 return editable
? new CKEDITOR
.dom
.range( editable
) : null;
818 * Executes a command associated with the editor.
820 * editorInstance.execCommand( 'bold' );
822 * @param {String} commandName The indentifier name of the command.
823 * @param {Object} [data] The data to be passed to the command.
824 * @returns {Boolean} `true` if the command was executed
825 * successfully, otherwise `false`.
826 * @see CKEDITOR.editor#addCommand
828 execCommand: function( commandName
, data
) {
829 var command
= this.getCommand( commandName
);
837 if ( command
&& command
.state
!= CKEDITOR
.TRISTATE_DISABLED
) {
838 if ( this.fire( 'beforeCommandExec', eventData
) !== false ) {
839 eventData
.returnValue
= command
.exec( eventData
.commandData
);
841 // Fire the 'afterCommandExec' immediately if command is synchronous.
842 if ( !command
.async
&& this.fire( 'afterCommandExec', eventData
) !== false )
843 return eventData
.returnValue
;
847 // throw 'Unknown command name "' + commandName + '"';
852 * Gets one of the registered commands. Note that after registering a
853 * command definition with {@link #addCommand}, it is
854 * transformed internally into an instance of
855 * {@link CKEDITOR.command}, which will then be returned by this function.
857 * @param {String} commandName The name of the command to be returned.
858 * This is the same name that is used to register the command with `addCommand`.
859 * @returns {CKEDITOR.command} The command object identified by the provided name.
861 getCommand: function( commandName
) {
862 return this.commands
[ commandName
];
866 * Gets the editor data. The data will be in "raw" format. It is the same
867 * data that is posted by the editor.
869 * if ( CKEDITOR.instances.editor1.getData() == '' )
870 * alert( 'There is no data available.' );
872 * @param {Boolean} internal If set to `true`, it will prevent firing the
873 * {@link CKEDITOR.editor#beforeGetData} and {@link CKEDITOR.editor#event-getData} events, so
874 * the real content of the editor will not be read and cached data will be returned. The method will work
875 * much faster, but this may result in the editor returning the data that is not up to date. This parameter
876 * should thus only be set to `true` when you are certain that the cached data is up to date.
878 * @returns {String} The editor data.
880 getData: function( internal ) {
881 !internal && this.fire( 'beforeGetData' );
883 var eventData
= this._
.data
;
885 if ( typeof eventData
!= 'string' ) {
886 var element
= this.element
;
887 if ( element
&& this.elementMode
== CKEDITOR
.ELEMENT_MODE_REPLACE
)
888 eventData
= element
.is( 'textarea' ) ? element
.getValue() : element
.getHtml();
893 eventData
= { dataValue: eventData
};
895 // Fire "getData" so data manipulation may happen.
896 !internal && this.fire( 'getData', eventData
);
898 return eventData
.dataValue
;
902 * Gets the "raw data" currently available in the editor. This is a
903 * fast method which returns the data as is, without processing, so it is
904 * not recommended to use it on resulting pages. Instead it can be used
905 * combined with the {@link #method-loadSnapshot} method in order
906 * to automatically save the editor data from time to time
907 * while the user is using the editor, to avoid data loss, without risking
908 * performance issues.
910 * alert( editor.getSnapshot() );
914 * * {@link CKEDITOR.editor#method-getData}.
916 * @returns {String} Editor "raw data".
918 getSnapshot: function() {
919 var data
= this.fire( 'getSnapshot' );
921 if ( typeof data
!= 'string' ) {
922 var element
= this.element
;
924 if ( element
&& this.elementMode
== CKEDITOR
.ELEMENT_MODE_REPLACE
) {
925 data
= element
.is( 'textarea' ) ? element
.getValue() : element
.getHtml();
928 // If we don't have a proper element, set data to an empty string,
929 // as this method is expected to return a string. (#13385)
938 * Loads "raw data" into the editor. The data is loaded with processing
939 * straight to the editing area. It should not be used as a way to load
940 * any kind of data, but instead in combination with
941 * {@link #method-getSnapshot}-produced data.
943 * var data = editor.getSnapshot();
944 * editor.loadSnapshot( data );
946 * @see CKEDITOR.editor#setData
948 loadSnapshot: function( snapshot
) {
949 this.fire( 'loadSnapshot', snapshot
);
953 * Sets the editor data. The data must be provided in the "raw" format (HTML).
955 * Note that this method is asynchronous. The `callback` parameter must
956 * be used if interaction with the editor is needed after setting the data.
958 * CKEDITOR.instances.editor1.setData( '<p>This is the editor data.</p>' );
960 * CKEDITOR.instances.editor1.setData( '<p>Some other editor data.</p>', {
961 * callback: function() {
962 * this.checkDirty(); // true
966 * Note: In **CKEditor 4.4.2** the signature of this method has changed. All arguments
967 * except `data` were wrapped into the `options` object. However, backward compatibility
968 * was preserved and it is still possible to use the `data, callback, internal` arguments.
971 * @param {String} data The HTML code to replace current editor content.
972 * @param {Object} [options]
973 * @param {Boolean} [options.internal=false] Whether to suppress any event firing when copying data internally inside the editor.
974 * @param {Function} [options.callback] Function to be called after `setData` is completed (on {@link #dataReady}).
975 * @param {Boolean} [options.noSnapshot=false] If set to `true`, it will prevent recording an undo snapshot.
976 * Introduced in CKEditor 4.4.2.
978 setData: function( data
, options
, internal ) {
979 var fireSnapshot
= true,
980 // Backward compatibility.
984 if ( options
&& typeof options
== 'object' ) {
985 internal = options
.internal;
986 callback
= options
.callback
;
987 fireSnapshot
= !options
.noSnapshot
;
990 if ( !internal && fireSnapshot
)
991 this.fire( 'saveSnapshot' );
993 if ( callback
|| !internal ) {
994 this.once( 'dataReady', function( evt
) {
995 if ( !internal && fireSnapshot
)
996 this.fire( 'saveSnapshot' );
999 callback
.call( evt
.editor
);
1003 // Fire "setData" so data manipulation may happen.
1004 eventData
= { dataValue: data
};
1005 !internal && this.fire( 'setData', eventData
);
1007 this._
.data
= eventData
.dataValue
;
1009 !internal && this.fire( 'afterSetData', eventData
);
1013 * Puts or restores the editor into the read-only state. When in read-only,
1014 * the user is not able to change the editor content, but can still use
1015 * some editor features. This function sets the {@link #property-readOnly}
1016 * property of the editor, firing the {@link #event-readOnly} event.
1018 * **Note:** The current editing area will be reloaded.
1021 * @param {Boolean} [isReadOnly] Indicates that the editor must go
1022 * read-only (`true`, default) or be restored and made editable (`false`).
1024 setReadOnly: function( isReadOnly
) {
1025 isReadOnly
= ( isReadOnly
== null ) || isReadOnly
;
1027 if ( this.readOnly
!= isReadOnly
) {
1028 this.readOnly
= isReadOnly
;
1030 // Block or release BACKSPACE key according to current read-only
1031 // state to prevent browser's history navigation (#9761).
1032 this.keystrokeHandler
.blockedKeystrokes
[ 8 ] = +isReadOnly
;
1034 this.editable().setReadOnly( isReadOnly
);
1036 // Fire the readOnly event so the editor features can update
1037 // their state accordingly.
1038 this.fire( 'readOnly' );
1043 * Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.
1047 * CKEDITOR.instances.editor1.insertHtml( '<p>This is a new paragraph.</p>' );
1049 * Fires the {@link #event-insertHtml} and {@link #event-afterInsertHtml} events. The HTML is inserted
1050 * in the {@link #event-insertHtml} event's listener with a default priority (10) so you can add listeners with
1051 * lower or higher priorities in order to execute some code before or after the HTML is inserted.
1053 * @param {String} html HTML code to be inserted into the editor.
1054 * @param {String} [mode='html'] The mode in which the HTML code will be inserted. One of the following:
1056 * * `'html'` – The inserted content will completely override the styles at the selected position.
1057 * * `'unfiltered_html'` – Like `'html'` but the content is not filtered with {@link CKEDITOR.filter}.
1058 * * `'text'` – The inserted content will inherit the styles applied in
1059 * the selected position. This mode should be used when inserting "htmlified" plain text
1060 * (HTML without inline styles and styling elements like `<b>`, `<strong>`, `<span style="...">`).
1062 * @param {CKEDITOR.dom.range} [range] If specified, the HTML will be inserted into the range
1063 * instead of into the selection. The selection will be placed at the end of the insertion (like in the normal case).
1064 * Introduced in CKEditor 4.5.
1066 insertHtml: function( html
, mode
, range
) {
1067 this.fire( 'insertHtml', { dataValue: html
, mode: mode
, range: range
} );
1071 * Inserts text content into the currently selected position in the
1072 * editor in WYSIWYG mode. The styles of the selected element will be applied to the inserted text.
1073 * Spaces around the text will be left untouched.
1075 * CKEDITOR.instances.editor1.insertText( ' line1 \n\n line2' );
1077 * Fires the {@link #event-insertText} and {@link #event-afterInsertHtml} events. The text is inserted
1078 * in the {@link #event-insertText} event's listener with a default priority (10) so you can add listeners with
1079 * lower or higher priorities in order to execute some code before or after the text is inserted.
1082 * @param {String} text Text to be inserted into the editor.
1084 insertText: function( text
) {
1085 this.fire( 'insertText', text
);
1089 * Inserts an element into the currently selected position in the editor in WYSIWYG mode.
1091 * var element = CKEDITOR.dom.element.createFromHtml( '<img src="hello.png" border="0" title="Hello" />' );
1092 * CKEDITOR.instances.editor1.insertElement( element );
1094 * Fires the {@link #event-insertElement} event. The element is inserted in the listener with a default priority (10),
1095 * so you can add listeners with lower or higher priorities in order to execute some code before or after
1096 * the element is inserted.
1098 * @param {CKEDITOR.dom.element} element The element to be inserted into the editor.
1100 insertElement: function( element
) {
1101 this.fire( 'insertElement', element
);
1105 * Gets the selected HTML (it is returned as a {@link CKEDITOR.dom.documentFragment document fragment}
1106 * or a string). This method is designed to work as the user would expect the copy functionality to work.
1107 * For instance, if the following selection was made:
1109 * <p>a<b>b{c}d</b>e</p>
1111 * The following HTML will be returned:
1115 * As you can see, the information about the bold formatting was preserved, even though the selection was
1116 * anchored inside the `<b>` element.
1120 * * the {@link #extractSelectedHtml} method,
1121 * * the {@link CKEDITOR.editable#getHtmlFromRange} method.
1124 * @param {Boolean} [toString] If `true`, then stringified HTML will be returned.
1125 * @returns {CKEDITOR.dom.documentFragment/String}
1127 getSelectedHtml: function( toString
) {
1128 var editable
= this.editable(),
1129 selection
= this.getSelection(),
1130 ranges
= selection
&& selection
.getRanges();
1132 if ( !editable
|| !ranges
|| ranges
.length
=== 0 ) {
1136 var docFragment
= editable
.getHtmlFromRange( ranges
[ 0 ] );
1138 return toString
? docFragment
.getHtml() : docFragment
;
1142 * Gets the selected HTML (it is returned as a {@link CKEDITOR.dom.documentFragment document fragment}
1143 * or a string) and removes the selected part of the DOM. This method is designed to work as the user would
1144 * expect the cut and delete functionalities to work.
1148 * * the {@link #getSelectedHtml} method,
1149 * * the {@link CKEDITOR.editable#extractHtmlFromRange} method.
1152 * @param {Boolean} [toString] If `true`, then stringified HTML will be returned.
1153 * @param {Boolean} [removeEmptyBlock=false] Default `false` means that the function will keep an empty block (if the
1154 * entire content was removed) or it will create it (if a block element was removed) and set the selection in that block.
1155 * If `true`, the empty block will be removed or not created. In this case the function will not handle the selection.
1156 * @returns {CKEDITOR.dom.documentFragment/String/null}
1158 extractSelectedHtml: function( toString
, removeEmptyBlock
) {
1159 var editable
= this.editable(),
1160 ranges
= this.getSelection().getRanges();
1162 if ( !editable
|| ranges
.length
=== 0 ) {
1166 var range
= ranges
[ 0 ],
1167 docFragment
= editable
.extractHtmlFromRange( range
, removeEmptyBlock
);
1169 if ( !removeEmptyBlock
) {
1170 this.getSelection().selectRanges( [ range
] );
1173 return toString
? docFragment
.getHtml() : docFragment
;
1177 * Moves the selection focus to the editing area space in the editor.
1180 this.fire( 'beforeFocus' );
1184 * Checks whether the current editor content contains changes when
1185 * compared to the content loaded into the editor at startup, or to
1186 * the content available in the editor when {@link #resetDirty}
1189 * function beforeUnload( evt ) {
1190 * if ( CKEDITOR.instances.editor1.checkDirty() )
1191 * return evt.returnValue = "You will lose the changes made in the editor.";
1194 * if ( window.addEventListener )
1195 * window.addEventListener( 'beforeunload', beforeUnload, false );
1197 * window.attachEvent( 'onbeforeunload', beforeUnload );
1199 * @returns {Boolean} `true` if the content contains changes.
1201 checkDirty: function() {
1202 return this.status
== 'ready' && this._
.previousValue
!== this.getSnapshot();
1206 * Resets the "dirty state" of the editor so subsequent calls to
1207 * {@link #checkDirty} will return `false` if the user will not
1208 * have made further changes to the content.
1210 * alert( editor.checkDirty() ); // e.g. true
1211 * editor.resetDirty();
1212 * alert( editor.checkDirty() ); // false
1214 resetDirty: function() {
1215 this._
.previousValue
= this.getSnapshot();
1219 * Updates the `<textarea>` element that was replaced by the editor with
1220 * the current data available in the editor.
1222 * **Note:** This method will only affect those editor instances created
1223 * with the {@link CKEDITOR#ELEMENT_MODE_REPLACE} element mode or inline instances
1224 * bound to `<textarea>` elements.
1226 * CKEDITOR.instances.editor1.updateElement();
1227 * alert( document.getElementById( 'editor1' ).value ); // The current editor data.
1229 * @see CKEDITOR.editor#element
1231 updateElement: function() {
1232 return updateEditorElement
.call( this );
1236 * Assigns keystrokes associated with editor commands.
1238 * editor.setKeystroke( CKEDITOR.CTRL + 115, 'save' ); // Assigned Ctrl+S to the "save" command.
1239 * editor.setKeystroke( CKEDITOR.CTRL + 115, false ); // Disabled Ctrl+S keystroke assignment.
1240 * editor.setKeystroke( [
1241 * [ CKEDITOR.ALT + 122, false ],
1242 * [ CKEDITOR.CTRL + 121, 'link' ],
1243 * [ CKEDITOR.SHIFT + 120, 'bold' ]
1246 * This method may be used in the following cases:
1248 * * By plugins (like `link` or `basicstyles`) to set their keystrokes when plugins are being loaded.
1249 * * During the runtime to modify existing keystrokes.
1251 * The editor handles keystroke configuration in the following order:
1253 * 1. Plugins use this method to define default keystrokes.
1254 * 2. Editor extends default keystrokes with {@link CKEDITOR.config#keystrokes}.
1255 * 3. Editor blocks keystrokes defined in {@link CKEDITOR.config#blockedKeystrokes}.
1257 * You can then set new keystrokes using this method during the runtime.
1260 * @param {Number/Array} keystroke A keystroke or an array of keystroke definitions.
1261 * @param {String/Boolean} [behavior] A command to be executed on the keystroke.
1263 setKeystroke: function() {
1264 var keystrokes
= this.keystrokeHandler
.keystrokes
,
1265 newKeystrokes
= CKEDITOR
.tools
.isArray( arguments
[ 0 ] ) ? arguments
[ 0 ] : [ [].slice
.call( arguments
, 0 ) ],
1266 keystroke
, behavior
;
1268 for ( var i
= newKeystrokes
.length
; i
--; ) {
1269 keystroke
= newKeystrokes
[ i
];
1272 // It may be a pair of: [ key, command ]
1273 if ( CKEDITOR
.tools
.isArray( keystroke
) ) {
1274 behavior
= keystroke
[ 1 ];
1275 keystroke
= keystroke
[ 0 ];
1279 keystrokes
[ keystroke
] = behavior
;
1281 delete keystrokes
[ keystroke
];
1286 * Shorthand for {@link CKEDITOR.filter#addFeature}.
1289 * @param {CKEDITOR.feature} feature See {@link CKEDITOR.filter#addFeature}.
1290 * @returns {Boolean} See {@link CKEDITOR.filter#addFeature}.
1292 addFeature: function( feature
) {
1293 return this.filter
.addFeature( feature
);
1297 * Sets the active filter ({@link #activeFilter}). Fires the {@link #activeFilterChange} event.
1299 * // Set active filter which allows only 4 elements.
1300 * // Buttons like Bold, Italic will be disabled.
1301 * var filter = new CKEDITOR.filter( 'p strong em br' );
1302 * editor.setActiveFilter( filter );
1304 * Setting a new filter will also change the {@link #setActiveEnterMode active Enter modes} to the first values
1305 * allowed by the new filter (see {@link CKEDITOR.filter#getAllowedEnterMode}).
1308 * @param {CKEDITOR.filter} filter Filter instance or a falsy value (e.g. `null`) to reset to the default one.
1310 setActiveFilter: function( filter
) {
1312 filter
= this.filter
;
1314 if ( this.activeFilter
!== filter
) {
1315 this.activeFilter
= filter
;
1316 this.fire( 'activeFilterChange' );
1318 // Reset active filter to the main one - it resets enter modes, too.
1319 if ( filter
=== this.filter
)
1320 this.setActiveEnterMode( null, null );
1322 this.setActiveEnterMode(
1323 filter
.getAllowedEnterMode( this.enterMode
),
1324 filter
.getAllowedEnterMode( this.shiftEnterMode
, true )
1330 * Sets the active Enter modes: ({@link #enterMode} and {@link #shiftEnterMode}).
1331 * Fires the {@link #activeEnterModeChange} event.
1333 * Prior to CKEditor 4.3 Enter modes were static and it was enough to check {@link CKEDITOR.config#enterMode}
1334 * and {@link CKEDITOR.config#shiftEnterMode} when implementing a feature which should depend on the Enter modes.
1335 * Since CKEditor 4.3 these options are source of initial:
1337 * * static {@link #enterMode} and {@link #shiftEnterMode} values,
1338 * * dynamic {@link #activeEnterMode} and {@link #activeShiftEnterMode} values.
1340 * However, the dynamic Enter modes can be changed during runtime by using this method, to reflect the selection context.
1341 * For example, if selection is moved to the {@link CKEDITOR.plugins.widget widget}'s nested editable which
1342 * is a {@link #blockless blockless one}, then the active Enter modes should be changed to {@link CKEDITOR#ENTER_BR}
1343 * (in this case [Widget System](#!/guide/dev_widgets) takes care of that).
1345 * **Note:** This method should not be used to configure the editor – use {@link CKEDITOR.config#enterMode} and
1346 * {@link CKEDITOR.config#shiftEnterMode} instead. This method should only be used to dynamically change
1347 * Enter modes during runtime based on selection changes.
1348 * Keep in mind that changed Enter mode may be overwritten by another plugin/feature when it decided that
1349 * the changed context requires this.
1351 * **Note:** In case of blockless editor (inline editor based on an element which cannot contain block elements
1352 * — see {@link CKEDITOR.editor#blockless}) only {@link CKEDITOR#ENTER_BR} is a valid Enter mode. Therefore
1353 * this method will not allow to set other values.
1355 * **Note:** Changing the {@link #activeFilter active filter} may cause the Enter mode to change if default Enter modes
1356 * are not allowed by the new filter.
1359 * @param {Number} enterMode One of {@link CKEDITOR#ENTER_P}, {@link CKEDITOR#ENTER_DIV}, {@link CKEDITOR#ENTER_BR}.
1360 * Pass falsy value (e.g. `null`) to reset the Enter mode to the default value ({@link #enterMode} and/or {@link #shiftEnterMode}).
1361 * @param {Number} shiftEnterMode See the `enterMode` argument.
1363 setActiveEnterMode: function( enterMode
, shiftEnterMode
) {
1364 // Validate passed modes or use default ones (validated on init).
1365 enterMode
= enterMode
? validateEnterMode( this, enterMode
) : this.enterMode
;
1366 shiftEnterMode
= shiftEnterMode
? validateEnterMode( this, shiftEnterMode
) : this.shiftEnterMode
;
1368 if ( this.activeEnterMode
!= enterMode
|| this.activeShiftEnterMode
!= shiftEnterMode
) {
1369 this.activeEnterMode
= enterMode
;
1370 this.activeShiftEnterMode
= shiftEnterMode
;
1371 this.fire( 'activeEnterModeChange' );
1376 * Shows a notification to the user.
1378 * If the [Notification](http://ckeditor.com/addons/notification) plugin is not enabled, this function shows
1379 * a normal alert with the given `message`. The `type` and `progressOrDuration` parameters are supported
1380 * only by the Notification plugin.
1382 * If the Notification plugin is enabled, this method creates and shows a new notification.
1383 * By default the notification is shown over the editor content, in the viewport if it is possible.
1385 * See {@link CKEDITOR.plugins.notification}.
1388 * @member CKEDITOR.editor
1389 * @param {String} message The message displayed in the notification.
1390 * @param {String} [type='info'] The type of the notification. Can be `'info'`, `'warning'`, `'success'` or `'progress'`.
1391 * @param {Number} [progressOrDuration] If the type is `progress`, the third parameter may be a progress from `0` to `1`
1392 * (defaults to `0`). Otherwise the third parameter may be a notification duration denoting after how many milliseconds
1393 * the notification should be closed automatically. `0` means that the notification will not close automatically and the user
1394 * needs to close it manually. See {@link CKEDITOR.plugins.notification#duration}.
1395 * Note that `warning` notifications will not be closed automatically.
1396 * @returns {CKEDITOR.plugins.notification} Created and shown notification.
1398 showNotification: function( message
) {
1399 alert( message
); // jshint ignore:line
1405 * The editor has no associated element.
1408 * @property {Number} [=0]
1411 CKEDITOR
.ELEMENT_MODE_NONE
= 0;
1414 * The element is to be replaced by the editor instance.
1417 * @property {Number} [=1]
1420 CKEDITOR
.ELEMENT_MODE_REPLACE
= 1;
1423 * The editor is to be created inside the element.
1426 * @property {Number} [=2]
1429 CKEDITOR
.ELEMENT_MODE_APPENDTO
= 2;
1432 * The editor is to be attached to the element, using it as the editing block.
1435 * @property {Number} [=3]
1438 CKEDITOR
.ELEMENT_MODE_INLINE
= 3;
1441 * Whether to escape HTML when the editor updates the original input element.
1443 * config.htmlEncodeOutput = true;
1446 * @cfg {Boolean} [htmlEncodeOutput=false]
1447 * @member CKEDITOR.config
1451 * If `true`, makes the editor start in read-only state. Otherwise, it will check
1452 * if the linked `<textarea>` element has the `disabled` attribute.
1454 * Read more in the [documentation](#!/guide/dev_readonly)
1455 * and see the [SDK sample](http://sdk.ckeditor.com/samples/readonly.html).
1457 * config.readOnly = true;
1460 * @cfg {Boolean} [readOnly=false]
1461 * @member CKEDITOR.config
1462 * @see CKEDITOR.editor#setReadOnly
1466 * Whether an editable element should have focus when the editor is loading for the first time.
1468 * config.startupFocus = true;
1470 * @cfg {Boolean} [startupFocus=false]
1471 * @member CKEDITOR.config
1475 * Customizes the {@link CKEDITOR.editor#title human-readable title} of this editor. This title is displayed in
1476 * tooltips and impacts various [accessibility aspects](#!/guide/dev_a11y-section-announcing-the-editor-on-the-page),
1477 * e.g. it is commonly used by screen readers for distinguishing editor instances and for navigation.
1478 * Accepted values are a string or `false`.
1480 * **Note:** When `config.title` is set globally, the same value will be applied to all editor instances
1481 * loaded with this config. This may adversely affect accessibility as screen reader users will be unable
1482 * to distinguish particular editor instances and navigate between them.
1484 * **Note:** Setting `config.title = false` may also impair accessibility in a similar way.
1486 * **Note:** Please do not confuse this property with {@link CKEDITOR.editor#name}
1487 * which identifies the instance in the {@link CKEDITOR#instances} literal.
1489 * // Sets the title to 'My WYSIWYG editor.'. The original title of the element (if it exists)
1490 * // will be restored once the editor instance is destroyed.
1491 * config.title = 'My WYSIWYG editor.';
1493 * // Do not touch the title. If the element already has a title, it remains unchanged.
1494 * // Also if no `title` attribute exists, nothing new will be added.
1495 * config.title = false;
1499 * * CKEDITOR.editor#name
1500 * * CKEDITOR.editor#title
1503 * @cfg {String/Boolean} [title=based on editor.name]
1504 * @member CKEDITOR.config
1508 * Sets listeners on editor events.
1510 * **Note:** This property can only be set in the `config` object passed directly
1511 * to {@link CKEDITOR#replace}, {@link CKEDITOR#inline}, and other creators.
1513 * CKEDITOR.replace( 'editor1', {
1515 * instanceReady: function() {
1516 * alert( this.name ); // 'editor1'
1526 * @member CKEDITOR.config
1530 * The outermost element in the DOM tree in which the editable element resides. It is provided
1531 * by a specific editor creator after the editor UI is created and is not intended to
1534 * var editor = CKEDITOR.instances.editor1;
1535 * alert( editor.container.getName() ); // 'span'
1538 * @property {CKEDITOR.dom.element} container
1542 * The document that stores the editor content.
1544 * * For the classic (`iframe`-based) editor it is equal to the document inside the
1545 * `iframe` containing the editable element.
1546 * * For the inline editor it is equal to {@link CKEDITOR#document}.
1548 * The document object is available after the {@link #contentDom} event is fired
1549 * and may be invalidated when the {@link #contentDomUnload} event is fired
1550 * (classic editor only).
1552 * editor.on( 'contentDom', function() {
1553 * console.log( editor.document );
1557 * @property {CKEDITOR.dom.document} document
1561 * The window instance related to the {@link #document} property.
1563 * It is always equal to the `editor.document.getWindow()`.
1565 * See the {@link #document} property documentation.
1568 * @property {CKEDITOR.dom.window} window
1572 * The main filter instance used for input data filtering, data
1573 * transformations, and activation of features.
1575 * It points to a {@link CKEDITOR.filter} instance set up based on
1576 * editor configuration.
1580 * @property {CKEDITOR.filter} filter
1584 * The active filter instance which should be used in the current context (location selection).
1585 * This instance will be used to make a decision which commands, buttons and other
1586 * {@link CKEDITOR.feature features} can be enabled.
1588 * By default it equals the {@link #filter} and it can be changed by the {@link #setActiveFilter} method.
1590 * editor.on( 'activeFilterChange', function() {
1591 * if ( editor.activeFilter.check( 'cite' ) )
1592 * // Do something when <cite> was enabled - e.g. enable a button.
1594 * // Otherwise do something else.
1597 * See also the {@link #setActiveEnterMode} method for an explanation of dynamic settings.
1601 * @property {CKEDITOR.filter} activeFilter
1605 * The main (static) Enter mode which is a validated version of the {@link CKEDITOR.config#enterMode} setting.
1606 * Currently only one rule exists — {@link #blockless blockless editors} may have
1607 * Enter modes set only to {@link CKEDITOR#ENTER_BR}.
1611 * @property {Number} enterMode
1615 * See the {@link #enterMode} property.
1619 * @property {Number} shiftEnterMode
1623 * The dynamic Enter mode which should be used in the current context (selection location).
1624 * By default it equals the {@link #enterMode} and it can be changed by the {@link #setActiveEnterMode} method.
1626 * See also the {@link #setActiveEnterMode} method for an explanation of dynamic settings.
1630 * @property {Number} activeEnterMode
1634 * See the {@link #activeEnterMode} property.
1638 * @property {Number} activeShiftEnterMode
1642 * Event fired by the {@link #setActiveFilter} method when the {@link #activeFilter} is changed.
1645 * @event activeFilterChange
1649 * Event fired by the {@link #setActiveEnterMode} method when any of the active Enter modes is changed.
1650 * See also the {@link #activeEnterMode} and {@link #activeShiftEnterMode} properties.
1653 * @event activeEnterModeChange
1657 * Event fired when a CKEDITOR instance is created, but still before initializing it.
1658 * To interact with a fully initialized instance, use the
1659 * {@link CKEDITOR#instanceReady} event instead.
1661 * @event instanceCreated
1663 * @param {CKEDITOR.editor} editor The editor instance that has been created.
1667 * Event fired when CKEDITOR instance's components (configuration, languages and plugins) are fully
1668 * loaded and initialized. However, the editor will be fully ready for interaction
1669 * on {@link CKEDITOR#instanceReady}.
1671 * @event instanceLoaded
1673 * @param {CKEDITOR.editor} editor This editor instance that has been loaded.
1677 * Event fired when a CKEDITOR instance is destroyed.
1679 * @event instanceDestroyed
1681 * @param {CKEDITOR.editor} editor The editor instance that has been destroyed.
1685 * Event fired when a CKEDITOR instance is created, fully initialized and ready for interaction.
1687 * @event instanceReady
1689 * @param {CKEDITOR.editor} editor The editor instance that has been created.
1693 * Event fired when the language is loaded into the editor instance.
1697 * @param {CKEDITOR.editor} editor This editor instance.
1701 * Event fired when all plugins are loaded and initialized into the editor instance.
1703 * @event pluginsLoaded
1704 * @param {CKEDITOR.editor} editor This editor instance.
1708 * Event fired when the styles set is loaded. During the editor initialization
1709 * phase the {@link #getStylesSet} method returns only styles that
1710 * are already loaded, which may not include e.g. styles parsed
1711 * by the `stylesheetparser` plugin. Thus, to be notified when all
1712 * styles are ready, you can listen on this event.
1716 * @param {CKEDITOR.editor} editor This editor instance.
1717 * @param {Array} styles An array of styles definitions.
1721 * Event fired before the command execution when {@link #execCommand} is called.
1723 * @event beforeCommandExec
1724 * @param {CKEDITOR.editor} editor This editor instance.
1726 * @param {String} data.name The command name.
1727 * @param {Object} data.commandData The data to be sent to the command. This
1728 * can be manipulated by the event listener.
1729 * @param {CKEDITOR.command} data.command The command itself.
1733 * Event fired after the command execution when {@link #execCommand} is called.
1735 * @event afterCommandExec
1736 * @param {CKEDITOR.editor} editor This editor instance.
1738 * @param {String} data.name The command name.
1739 * @param {Object} data.commandData The data sent to the command.
1740 * @param {CKEDITOR.command} data.command The command itself.
1741 * @param {Object} data.returnValue The value returned by the command execution.
1745 * Event fired when a custom configuration file is loaded, before the final
1746 * configuration initialization.
1748 * Custom configuration files can be loaded thorugh the
1749 * {@link CKEDITOR.config#customConfig} setting. Several files can be loaded
1750 * by changing this setting.
1752 * @event customConfigLoaded
1753 * @param {CKEDITOR.editor} editor This editor instance.
1757 * Event fired once the editor configuration is ready (loaded and processed).
1759 * @event configLoaded
1760 * @param {CKEDITOR.editor} editor This editor instance.
1764 * Event fired when this editor instance is destroyed. The editor at this
1765 * point is not usable and this event should be used to perform the clean-up
1769 * @param {CKEDITOR.editor} editor This editor instance.
1773 * Internal event to get the current data.
1775 * @event beforeGetData
1776 * @param {CKEDITOR.editor} editor This editor instance.
1780 * Internal event to perform the {@link #method-getSnapshot} call.
1782 * @event getSnapshot
1783 * @param {CKEDITOR.editor} editor This editor instance.
1787 * Internal event to perform the {@link #method-loadSnapshot} call.
1789 * @event loadSnapshot
1790 * @param {CKEDITOR.editor} editor This editor instance.
1791 * @param {String} data The data that will be used.
1795 * Event fired before the {@link #method-getData} call returns, allowing for additional manipulation.
1798 * @param {CKEDITOR.editor} editor This editor instance.
1800 * @param {String} data.dataValue The data that will be returned.
1804 * Event fired before the {@link #method-setData} call is executed, allowing for additional manipulation.
1807 * @param {CKEDITOR.editor} editor This editor instance.
1809 * @param {String} data.dataValue The data that will be used.
1813 * Event fired at the end of the {@link #method-setData} call execution. Usually it is better to use the
1814 * {@link #dataReady} event.
1816 * @event afterSetData
1817 * @param {CKEDITOR.editor} editor This editor instance.
1819 * @param {String} data.dataValue The data that has been set.
1823 * Event fired as an indicator of the editor data loading. It may be the result of
1824 * calling {@link #method-setData} explicitly or an internal
1825 * editor function, like the editor editing mode switching (move to Source and back).
1828 * @param {CKEDITOR.editor} editor This editor instance.
1832 * Event fired when the CKEDITOR instance is completely created, fully initialized
1833 * and ready for interaction.
1835 * @event instanceReady
1836 * @param {CKEDITOR.editor} editor This editor instance.
1840 * Event fired when editor components (configuration, languages and plugins) are fully
1841 * loaded and initialized. However, the editor will be fully ready to for interaction
1842 * on {@link #instanceReady}.
1845 * @param {CKEDITOR.editor} editor This editor instance.
1849 * Event fired by the {@link #method-insertHtml} method. See the method documentation for more information
1850 * about how this event can be used.
1853 * @param {CKEDITOR.editor} editor This editor instance.
1855 * @param {String} data.mode The mode in which the data is inserted (see {@link #method-insertHtml}).
1856 * @param {String} data.dataValue The HTML code to insert.
1857 * @param {CKEDITOR.dom.range} [data.range] See {@link #method-insertHtml}'s `range` parameter.
1861 * Event fired by the {@link #method-insertText} method. See the method documentation for more information
1862 * about how this event can be used.
1865 * @param {CKEDITOR.editor} editor This editor instance.
1866 * @param {String} data The text to insert.
1870 * Event fired by the {@link #method-insertElement} method. See the method documentation for more information
1871 * about how this event can be used.
1873 * @event insertElement
1874 * @param {CKEDITOR.editor} editor This editor instance.
1875 * @param {CKEDITOR.dom.element} data The element to insert.
1879 * Event fired after data insertion using the {@link #method-insertHtml}, {@link CKEDITOR.editable#insertHtml},
1880 * or {@link CKEDITOR.editable#insertHtmlIntoRange} methods.
1883 * @event afterInsertHtml
1885 * @param {CKEDITOR.dom.range} [data.intoRange] If set, the HTML was not inserted into the current selection, but into
1886 * the specified range. This property is set if the {@link CKEDITOR.editable#insertHtmlIntoRange} method was used,
1887 * but not if for the {@link CKEDITOR.editable#insertHtml} method.
1891 * Event fired after the {@link #property-readOnly} property changes.
1895 * @param {CKEDITOR.editor} editor This editor instance.
1899 * Event fired when a UI template is added to the editor instance. It makes
1900 * it possible to bring customizations to the template source.
1903 * @param {CKEDITOR.editor} editor This editor instance.
1905 * @param {String} data.name The template name.
1906 * @param {String} data.source The source data for this template.
1910 * Event fired when the editor content (its DOM structure) is ready.
1911 * It is similar to the native `DOMContentLoaded` event, but it applies to
1912 * the editor content. It is also the first event fired after
1913 * the {@link CKEDITOR.editable} is initialized.
1915 * This event is particularly important for classic (`iframe`-based)
1916 * editor, because on editor initialization and every time the data are set
1917 * (by {@link CKEDITOR.editor#method-setData}) content DOM structure
1918 * is rebuilt. Thus, e.g. you need to attach DOM event listeners
1919 * on editable one more time.
1921 * For inline editor this event is fired only once — when the
1922 * editor is initialized for the first time. This is because setting
1923 * editor content does not cause editable destruction and creation.
1925 * The {@link #contentDom} event goes along with {@link #contentDomUnload}
1926 * which is fired before the content DOM structure is destroyed. This is the
1927 * right moment to detach content DOM event listener. Otherwise
1928 * browsers like IE or Opera may throw exceptions when accessing
1929 * elements from the detached document.
1931 * **Note:** {@link CKEDITOR.editable#attachListener} is a convenient
1932 * way to attach listeners that will be detached on {@link #contentDomUnload}.
1934 * editor.on( 'contentDom', function() {
1935 * var editable = editor.editable();
1937 * editable.attachListener( editable, 'click', function() {
1938 * console.log( 'The editable was clicked.' );
1943 * @param {CKEDITOR.editor} editor This editor instance.
1947 * Event fired before the content DOM structure is destroyed.
1948 * See {@link #contentDom} documentation for more details.
1950 * @event contentDomUnload
1951 * @param {CKEDITOR.editor} editor This editor instance.
1955 * Event fired when the content DOM changes and some of the references as well as
1956 * the native DOM event listeners could be lost.
1957 * This event is useful when it is important to keep track of references
1958 * to elements in the editable content from code.
1961 * @event contentDomInvalidated
1962 * @param {CKEDITOR.editor} editor This editor instance.