X-Git-Url: https://jasonwoof.com/gitweb/?a=blobdiff_plain;f=_source%2Fcore%2Feditor.js;h=9801bbe3813105133542573e97d35606a3f445bc;hb=4e70ea24db840898be8cc21c950363a52a2a6aba;hp=0b373f7b2df1bca05e628345828b07f8ddf8823f;hpb=f8fc585c18d287eb325c575596d183122486b641;p=ckeditor.git diff --git a/_source/core/editor.js b/_source/core/editor.js index 0b373f7..9801bbe 100644 --- a/_source/core/editor.js +++ b/_source/core/editor.js @@ -1,5 +1,5 @@ /* -Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved. +Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved. For licensing, see LICENSE.html or http://ckeditor.com/license */ @@ -118,12 +118,57 @@ For licensing, see LICENSE.html or http://ckeditor.com/license '_source/' + // @Packager.RemoveLine 'skins/' + skinName + '/' ) ); + /** + * The name of the skin used by this editor instance. The skin name can + * be set though the {@link CKEDITOR.config.skin} setting. + * @name CKEDITOR.editor.prototype.skinName + * @type String + * @example + * alert( editor.skinName ); // "kama" (e.g.) + */ editor.skinName = skinName; + + /** + * The full URL of the skin directory. + * @name CKEDITOR.editor.prototype.skinPath + * @type String + * @example + * alert( editor.skinPath ); // "http://example.com/ckeditor/skins/kama/" (e.g.) + */ editor.skinPath = skinPath; + + /** + * The CSS class name used for skin identification purposes. + * @name CKEDITOR.editor.prototype.skinClass + * @type String + * @example + * alert( editor.skinClass ); // "cke_skin_kama" (e.g.) + */ editor.skinClass = 'cke_skin_' + skinName; + /** + * The tabbing + * navigation order that has been calculated for this editor + * instance. This can be set by the {@link CKEDITOR.config.tabIndex} + * setting or taken from the "tabindex" attribute of the + * {@link #element} associated to the editor. + * @name CKEDITOR.editor.prototype.tabIndex + * @type Number + * @default 0 (zero) + * @example + * alert( editor.tabIndex ); // "0" (e.g.) + */ editor.tabIndex = editor.config.tabIndex || editor.element.getAttribute( 'tabindex' ) || 0; + /** + * Indicates the read-only state of this editor. This is a read-only property. + * @name CKEDITOR.editor.prototype.readOnly + * @type Boolean + * @since 3.6 + * @see CKEDITOR.editor#setReadOnly + */ + editor.readOnly = !!( editor.config.readOnly || editor.element.getAttribute( 'disabled' ) ); + // Fire the "configLoaded" event. editor.fireOnce( 'configLoaded' ); @@ -135,8 +180,24 @@ For licensing, see LICENSE.html or http://ckeditor.com/license { CKEDITOR.lang.load( editor.config.language, editor.config.defaultLanguage, function( languageCode, lang ) { + /** + * The code for the language resources that have been loaded + * for the user internface elements of this editor instance. + * @name CKEDITOR.editor.prototype.langCode + * @type String + * @example + * alert( editor.langCode ); // "en" (e.g.) + */ editor.langCode = languageCode; + /** + * An object holding all language strings used by the editor + * interface. + * @name CKEDITOR.editor.prototype.lang + * @type CKEDITOR.lang + * @example + * alert( editor.lang.bold ); // "Negrito" (e.g. if language is Portuguese) + */ // As we'll be adding plugin specific entries that could come // from different language code files, we need a copy of lang, // not a direct reference to it. @@ -175,6 +236,9 @@ For licensing, see LICENSE.html or http://ckeditor.com/license plugins = plugins.replace( removeRegex, '' ); } + // Load the Adobe AIR plugin conditionally. + CKEDITOR.env.air && ( plugins += ',adobeair' ); + // Load all plugins defined in the "plugins" setting. CKEDITOR.plugins.load( plugins.split( ',' ), function( plugins ) { @@ -188,7 +252,14 @@ For licensing, see LICENSE.html or http://ckeditor.com/license // The list of URLs to language files. var languageFiles = []; - // Cache the loaded plugin names. + /** + * And object holding references to all plugins used by this + * editor istance. + * @name CKEDITOR.editor.prototype.plugins + * @type Object + * @example + * alert( editor.plugins.dialog.path ); // "http://example.com/ckeditor/plugins/dialog/" (e.g.) + */ editor.plugins = plugins; // Loop through all plugins, to build the list of language @@ -210,7 +281,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license // is not available, get the first one (default one). lang = ( CKEDITOR.tools.indexOf( pluginLangs, editor.langCode ) >= 0 ? editor.langCode : pluginLangs[ 0 ] ); - if ( !plugin.lang[ lang ] ) + if ( !plugin.langEntries || !plugin.langEntries[ lang ] ) { // Put the language file URL into the list of files to // get downloaded. @@ -218,7 +289,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license } else { - CKEDITOR.tools.extend( editor.lang, plugin.lang[ lang ] ); + CKEDITOR.tools.extend( editor.lang, plugin.langEntries[ lang ] ); lang = null; } } @@ -243,7 +314,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license // Uses the first loop to update the language entries also. if ( m === 0 && languageCodes[ i ] && plugin.lang ) - CKEDITOR.tools.extend( editor.lang, plugin.lang[ languageCodes[ i ] ] ); + CKEDITOR.tools.extend( editor.lang, plugin.langEntries[ languageCodes[ i ] ] ); // Call the plugin method (beforeInit and init). if ( plugin[ methods[ m ] ] ) @@ -271,6 +342,13 @@ For licensing, see LICENSE.html or http://ckeditor.com/license var theme = editor.config.theme; CKEDITOR.themes.load( theme, function() { + /** + * The theme used by this editor instance. + * @name CKEDITOR.editor.prototype.theme + * @type CKEDITOR.theme + * @example + * alert( editor.theme ); "http://example.com/ckeditor/themes/default/" (e.g.) + */ var editorTheme = editor.theme = CKEDITOR.themes.get( theme ); editorTheme.path = CKEDITOR.themes.getPath( theme ); editorTheme.build( editor ); @@ -298,7 +376,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license // Setup the submit function because it doesn't fire the // "submit" event. - if ( !form.$.submit.nodeName ) + if ( !form.$.submit.nodeName && !form.$.submit.length ) { form.$.submit = CKEDITOR.tools.override( form.$.submit, function( originalSubmit ) { @@ -325,16 +403,20 @@ For licensing, see LICENSE.html or http://ckeditor.com/license } }; - function updateCommandsMode() + function updateCommands() { var command, commands = this._.commands, mode = this.mode; + if ( !mode ) + return; + for ( var name in commands ) { command = commands[ name ]; - command[ command.startDisabled ? 'disable' : command.modes[ mode ] ? 'enable' : 'disable' ](); + command[ command.startDisabled ? 'disable' : + this.readOnly && !command.readOnly ? 'disable' : command.modes[ mode ] ? 'enable' : 'disable' ](); } } @@ -383,6 +465,13 @@ For licensing, see LICENSE.html or http://ckeditor.com/license throw '[CKEDITOR.editor] The instance "' + this.name + '" already exists.'; /** + * A unique random string assigned to each editor instance in the page. + * @name CKEDITOR.editor.prototype.id + * @type String + */ + this.id = CKEDITOR.tools.getNextId(); + + /** * The configurations for this editor instance. It inherits all * settings defined in (@link CKEDITOR.config}, combined with settings * loaded from custom configuration files and those defined inline in @@ -415,7 +504,8 @@ For licensing, see LICENSE.html or http://ckeditor.com/license CKEDITOR.fire( 'instanceCreated', null, this ); - this.on( 'mode', updateCommandsMode, null, null, 1 ); + this.on( 'mode', updateCommands, null, null, 1 ); + this.on( 'readOnly', updateCommands, null, null, 1 ); initConfig( this, instanceConfig ); }; @@ -471,44 +561,9 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, if ( !noUpdate ) this.updateElement(); - if ( this.mode ) - { - // -> currentMode.unload( holderElement ); - this._.modes[ this.mode ].unload( this.getThemeSpace( 'contents' ) ); - } - - this.theme.destroy( this ); - - var toolbars, - index = 0, - j, - items, - instance; - - if ( this.toolbox ) - { - toolbars = this.toolbox.toolbars; - for ( ; index < toolbars.length ; index++ ) - { - items = toolbars[ index ].items; - for ( j = 0 ; j < items.length ; j++ ) - { - instance = items[ j ]; - if ( instance.clickFn ) CKEDITOR.tools.removeFunction( instance.clickFn ); - if ( instance.keyDownFn ) CKEDITOR.tools.removeFunction( instance.keyDownFn ); - - if ( instance.index ) CKEDITOR.ui.button._.instances[ instance.index ] = null; - } - } - } - - if ( this.contextMenu ) - CKEDITOR.tools.removeFunction( this.contextMenu._.functionId ); - - if ( this._.filebrowserFn ) - CKEDITOR.tools.removeFunction( this._.filebrowserFn ); - this.fire( 'destroy' ); + this.theme && this.theme.destroy( this ); + CKEDITOR.remove( this ); CKEDITOR.fire( 'instanceDestroyed', null, this ); }, @@ -520,7 +575,7 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, * @returns {Boolean} "true" if the command has been successfuly * executed, otherwise "false". * @example - * editorInstance.execCommand( 'Bold' ); + * editorInstance.execCommand( 'bold' ); */ execCommand : function( commandName, data ) { @@ -596,6 +651,16 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, return eventData.dataValue; }, + /** + * Gets the "raw data" currently available in the editor. This is a + * fast method which return the data as is, without processing, so it's + * not recommended to use it on resulting pages. It can be used instead + * combined with the {@link #loadSnapshot} so one can automatic save + * the editor data from time to time while the user is using the + * editor, to avoid data loss, without risking performance issues. + * @example + * alert( editor.getSnapshot() ); + */ getSnapshot : function() { var data = this.fire( 'getSnapshot' ); @@ -610,6 +675,15 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, return data; }, + /** + * Loads "raw data" in the editor. This data is loaded with processing + * straight to the editing area. It should not be used as a way to load + * any kind of data, but instead in combination with + * {@link #getSnapshot} produced data. + * @example + * var data = editor.getSnapshot(); + * editor.loadSnapshot( data ); + */ loadSnapshot : function( snapshot ) { this.fire( 'loadSnapshot', snapshot ); @@ -624,6 +698,7 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, * editor. * @param {Function} callback Function to be called after the setData * is completed. + *@param {Boolean} internal Whether suppress any event firing when copying data internally inside editor. * @example * CKEDITOR.instances.editor1.setData( '<p>This is the editor data.</p>' ); * @example @@ -632,7 +707,7 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, * this.checkDirty(); // true * }); */ - setData : function( data , callback ) + setData : function( data , callback, internal ) { if( callback ) { @@ -645,11 +720,33 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, // Fire "setData" so data manipulation may happen. var eventData = { dataValue : data }; - this.fire( 'setData', eventData ); + !internal && this.fire( 'setData', eventData ); this._.data = eventData.dataValue; - this.fire( 'afterSetData', eventData ); + !internal && this.fire( 'afterSetData', eventData ); + }, + + /** + * Puts or restores the editor into read-only state. When in read-only, + * the user is not able to change the editor contents, but still use + * some editor features. This function sets the readOnly property of + * the editor, firing the "readOnly" event.

+ * Note: the current editing area will be reloaded. + * @param {Boolean} [makeEditable] Indicates that the editor must be + * restored from read-only mode, making it editable. + * @since 3.6 + */ + setReadOnly : function( makeEditable ) + { + if ( this.readOnly != !makeEditable ) + { + this.readOnly = !makeEditable; + + // Fire the readOnly event so the editor features can update + // their state accordingly. + this.fire( 'readOnly' ); + } }, /** @@ -664,6 +761,22 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, }, /** + * Insert text content into the currently selected position in the + * editor, in WYSIWYG mode, styles of the selected element will be applied to the inserted text, + * spaces around the text will be leaving untouched. + * Note: two subsequent line-breaks will introduce one paragraph, which element depends on {@link CKEDITOR.config.enterMode}; + * A single line-break will be instead translated into one <br />. + * @since 3.5 + * @param {String} text Text to be inserted into the editor. + * @example + * CKEDITOR.instances.editor1.insertText( ' line1 \n\n line2' ); + */ + insertText : function( text ) + { + this.fire( 'insertText', text ); + }, + + /** * Inserts an element into the currently selected position in the * editor. * @param {CKEDITOR.dom.element} element The element to be inserted @@ -677,11 +790,38 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype, this.fire( 'insertElement', element ); }, + /** + * Checks whether the current editor contents present changes when + * compared to the contents loaded into the editor at startup, or to + * the contents available in the editor when {@link #resetDirty} has + * been called. + * @returns {Boolean} "true" is the contents present changes. + * @example + * function beforeUnload( e ) + * { + * if ( CKEDITOR.instances.editor1.checkDirty() ) + * return e.returnValue = "You'll loose the changes made in the editor."; + * } + * + * if ( window.addEventListener ) + * window.addEventListener( 'beforeunload', beforeUnload, false ); + * else + * window.attachEvent( 'onbeforeunload', beforeUnload ); + */ checkDirty : function() { return ( this.mayBeDirty && this._.previousValue !== this.getSnapshot() ); }, + /** + * Resets the "dirty state" of the editor so subsequent calls to + * {@link #checkDirty} will return "false" if the user will not make + * further changes to the contents. + * @example + * alert( editor.checkDirty() ); // "true" (e.g.) + * editor.resetDirty(); + * alert( editor.checkDirty() ); // "false" + */ resetDirty : function() { if ( this.mayBeDirty ) @@ -737,6 +877,18 @@ CKEDITOR.on( 'loaded', function() */ /** + * If "true", makes the editor start in read-only state. Otherwise, it'll check + * if the linked <textarea> has the "disabled" attribute. + * @name CKEDITOR.config.readOnly + * @see CKEDITOR.editor#setReadOnly + * @type Boolean + * @default false + * @since 3.6 + * @example + * config.readOnly = true; + */ + +/** * Fired when a CKEDITOR instance is created, but still before initializing it. * To interact with a fully initialized instance, use the * {@link CKEDITOR#instanceReady} event instead. @@ -754,6 +906,136 @@ CKEDITOR.on( 'loaded', function() /** * Fired when all plugins are loaded and initialized into the editor instance. - * @name CKEDITOR#pluginsLoaded + * @name CKEDITOR.editor#pluginsLoaded + * @event + * @param {CKEDITOR.editor} editor This editor instance. + */ + +/** + * Fired before the command execution when {@link #execCommand} is called. + * @name CKEDITOR.editor#beforeCommandExec + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} data.name The command name. + * @param {Object} data.commandData The data to be sent to the command. This + * can be manipulated by the event listener. + * @param {CKEDITOR.command} data.command The command itself. + */ + +/** + * Fired after the command execution when {@link #execCommand} is called. + * @name CKEDITOR.editor#afterCommandExec + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} data.name The command name. + * @param {Object} data.commandData The data sent to the command. + * @param {CKEDITOR.command} data.command The command itself. + * @param {Object} data.returnValue The value returned by the command execution. + */ + +/** + * Fired every custom configuration file is loaded, before the final + * configurations initialization.
+ *
+ * Custom configuration files can be loaded thorugh the + * {@link CKEDITOR.config.customConfig} setting. Several files can be loading + * by chaning this setting. + * @name CKEDITOR.editor#customConfigLoaded + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @example + */ + +/** + * Fired once the editor configuration is ready (loaded and processed). + * @name CKEDITOR.editor#configLoaded + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @example + * if( editor.config.fullPage ) + * alert( 'This is a full page editor' ); + */ + +/** + * Fired when this editor instance is destroyed. The editor at this + * point isn't usable and this event should be used to perform clean up + * in any plugin. + * @name CKEDITOR.editor#destroy + * @event + */ + +/** + * Internal event to get the current data. + * @name CKEDITOR.editor#beforeGetData + * @event + */ + +/** + * Internal event to perform the #getSnapshot call. + * @name CKEDITOR.editor#getSnapshot + * @event + */ + +/** + * Internal event to perform the #loadSnapshot call. + * @name CKEDITOR.editor#loadSnapshot + * @event + */ + + +/** + * Event fired before the #getData call returns allowing additional manipulation. + * @name CKEDITOR.editor#getData + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} data.dataValue The data that will be returned. + */ + +/** + * Event fired before the #setData call is executed allowing additional manipulation. + * @name CKEDITOR.editor#setData + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} data.dataValue The data that will be used. + */ + +/** + * Event fired at the end of the #setData call is executed. Usually it's better to use the + * {@link CKEDITOR.editor.prototype.dataReady} event. + * @name CKEDITOR.editor#afterSetData + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} data.dataValue The data that has been set. + */ + +/** + * Internal event to perform the #insertHtml call + * @name CKEDITOR.editor#insertHtml + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} data The HTML to insert. + */ + +/** + * Internal event to perform the #insertText call + * @name CKEDITOR.editor#insertText + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {String} text The text to insert. + */ + +/** + * Internal event to perform the #insertElement call + * @name CKEDITOR.editor#insertElement + * @event + * @param {CKEDITOR.editor} editor This editor instance. + * @param {Object} element The element to insert. + */ + +/** + * Event fired after {@link CKEDITOR.editor#readOnly} property changes. + * @name CKEDITOR.editor#readOnly * @event + * @since 3.6 + * @param {CKEDITOR.editor} editor This editor instance. */