ckeditor 3.4.2 → 3.4.3.pre

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/dom/rangelist.js

@@ -39,7 +39,9 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			createIterator : function()
 			{
 				var rangeList = this,
-					bookmarks = [],
+					bookmark = CKEDITOR.dom.walker.bookmark(),
+					guard = function( node ) { return ! ( node.is && node.is( 'tr' ) ); },
+						bookmarks = [],
 					current;
 
 				/**
@@ -49,8 +51,9 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 
 					/**
 					 * Retrieves the next range in the list.
+					 * @param {Boolean} mergeConsequent Whether join two adjacent ranges into single, e.g. consequent table cells.
 					 */
-					getNextRange : function()
+					getNextRange : function( mergeConsequent )
 					{
 						current = current == undefined ? 0 : current + 1;
 
@@ -65,11 +68,59 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 							if ( !current )
 							{
 								// Make sure bookmark correctness by reverse processing.
-								for ( var i = rangeList.length - 1; i > 0; i-- )
+								for ( var i = rangeList.length - 1; i >= 0; i-- )
 									bookmarks.unshift( rangeList[ i ].createBookmark( true ) );
 							}
-							else
-								range.moveToBookmark( bookmarks.shift() );
+
+							if ( mergeConsequent )
+							{
+								// Figure out how many ranges should be merged.
+								var mergeCount = 0;
+								while ( rangeList[ current + mergeCount + 1 ] )
+								{
+									var doc = range.document,
+										found = 0,
+										left =  doc.getById( bookmarks[ mergeCount ].endNode ),
+										right = doc.getById( bookmarks[ mergeCount + 1 ].startNode ),
+										next;
+
+									// Check subsequent range.
+									while ( 1 )
+									{
+										next = left.getNextSourceNode( false );
+										if ( !right.equals( next ) )
+										{
+											// This could be yet another bookmark or
+											// walking across block boundaries.
+											if ( bookmark( next ) || ( next.type == CKEDITOR.NODE_ELEMENT && next.isBlockBoundary() ) )
+											{
+												left = next;
+												continue;
+											}
+										}
+										else
+											found = 1;
+
+										break;
+									}
+
+									if ( !found )
+										break;
+
+									mergeCount++;
+								}
+							}
+
+							range.moveToBookmark( bookmarks.shift() );
+
+							var next;
+							// Merge ranges finally after moving to bookmarks.
+							while( mergeCount-- )
+							{
+								next = rangeList[ ++current ];
+								next.moveToBookmark( bookmarks.shift() );
+								range.setEnd( next.endContainer, next.endOffset );
+							}
 						}
 
 						return range;

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/dom/walker.js

@@ -261,7 +261,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			 */
 			previous : function()
 			{
-				return iterate.call( this, true );
+				return iterate.call( this, 1 );
 			},
 
 			/**
@@ -271,7 +271,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			 */
 			checkForward : function()
 			{
-				return iterate.call( this, false, true ) !== false;
+				return iterate.call( this, 0, 1 ) !== false;
 			},
 
 			/**
@@ -281,7 +281,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			 */
 			checkBackward : function()
 			{
-				return iterate.call( this, true, true ) !== false;
+				return iterate.call( this, 1, 1 ) !== false;
 			},
 
 			/**
@@ -303,7 +303,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			 */
 			lastBackward : function()
 			{
-				return iterateToLast.call( this, true );
+				return iterateToLast.call( this, 1 );
 			},
 
 			reset : function()
@@ -374,7 +374,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 		{
 			return ( node && node.getName
 					&& node.getName() == 'span'
-					&& node.hasAttribute('_cke_bookmark') );
+					&& node.hasAttribute( '_cke_bookmark' ) );
 		}
 
 		return function( node )
@@ -385,7 +385,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 						&& isBookmarkNode( parent ) );
 			// Is bookmark node?
 			isBookmark = contentOnly ? isBookmark : isBookmark || isBookmarkNode( node );
-			return isReject ^ isBookmark;
+			return !! ( isReject ^ isBookmark );
 		};
 	};
 
@@ -399,7 +399,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 		{
 			var isWhitespace = node && ( node.type == CKEDITOR.NODE_TEXT )
 							&& !CKEDITOR.tools.trim( node.getText() );
-			return isReject ^ isWhitespace;
+			return !! ( isReject ^ isWhitespace );
 		};
 	};
 
@@ -418,20 +418,20 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			// 'offsetHeight' instead of 'offsetWidth' for properly excluding
 			// all sorts of empty paragraph, e.g. <br />.
 			var isInvisible = whitespace( node ) || node.is && !node.$.offsetHeight;
-			return isReject ^ isInvisible;
+			return !! ( isReject ^ isInvisible );
 		};
 	};
 
 	var tailNbspRegex = /^[\t\r\n ]*(?:&nbsp;|\xa0)$/,
-		isNotWhitespaces = CKEDITOR.dom.walker.whitespaces( true ),
-		isNotBookmark = CKEDITOR.dom.walker.bookmark( false, true ),
+		isNotWhitespaces = CKEDITOR.dom.walker.whitespaces( 1 ),
+		isNotBookmark = CKEDITOR.dom.walker.bookmark( 0, 1 ),
 		fillerEvaluator = function( element )
 		{
 			return isNotBookmark( element ) && isNotWhitespaces( element );
 		};
 
 	// Check if there's a filler node at the end of an element, and return it.
-	CKEDITOR.dom.element.prototype.getBogus = function ()
+	CKEDITOR.dom.element.prototype.getBogus = function()
 	{
 		var tail = this.getLast( fillerEvaluator );
 		if ( tail && ( !CKEDITOR.env.ie ? tail.is && tail.is( 'br' )

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/dtd.js

@@ -10,16 +10,15 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
  */
 
 /**
- * Holds and object representation of the HTML DTD to be used by the editor in
- * its internal operations.
- *
- * Each element in the DTD is represented by a
- * property in this object. Each property contains the list of elements that
- * can be contained by the element. Text is represented by the "#" property.
- *
+ * @namespace Holds and object representation of the HTML DTD to be used by the
+ * editor in its internal operations.<br />
+ * <br />
+ * Each element in the DTD is represented by a property in this object. Each
+ * property contains the list of elements that can be contained by the element.
+ * Text is represented by the "#" property.<br />
+ * <br />
  * Several special grouping properties are also available. Their names start
  * with the "$" character.
- * @namespace
  * @example
  * // Check if "div" can be contained in a "p" element.
  * alert( !!CKEDITOR.dtd[ 'p' ][ 'div' ] );  "false"
@@ -81,8 +80,14 @@ CKEDITOR.dtd = (function()
 		 */
 		$blockLimit : { body:1,div:1,td:1,th:1,caption:1,form:1 },
 
+		/**
+		 * List of inline (&lt;span&gt; like) elements.
+		 */
 		$inline : L,	// Just like span.
 
+		/**
+		 * list of elements that can be children at &lt;body&gt;.
+		 */
 		$body : X({script:1,style:1}, block),
 
 		$cdata : {script:1,style:1},

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/editor.js

@@ -118,10 +118,46 @@ 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 <a href="http://en.wikipedia.org/wiki/Tabbing_navigation">tabbing
+		 * navigation</a> 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;
 
 		// Fire the "configLoaded" event.
@@ -135,8 +171,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.
@@ -188,7 +240,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
@@ -271,6 +330,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 );
@@ -382,6 +448,13 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			if ( this.name in CKEDITOR.instances )
 				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
@@ -596,6 +669,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 +693,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.<b>loadSnapshot( data )</b>;
+		 */
 		loadSnapshot : function( snapshot )
 		{
 			this.fire( 'loadSnapshot', snapshot );
@@ -677,11 +769,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.<b>checkDirty()</b> )
+		 * 	        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.<b>resetDirty()</b>;
+		 * alert( editor.checkDirty() );  // "false"
+		 */
 		resetDirty : function()
 		{
 			if ( this.mayBeDirty )
@@ -756,4 +875,50 @@ CKEDITOR.on( 'loaded', function()
  * Fired when all plugins are loaded and initialized into the editor instance.
  * @name CKEDITOR#pluginsLoaded
  * @event
+ * @param {CKEDITOR.editor} editor The editor instance that has been destroyed.
+ */
+
+/**
+ * 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.<br />
+ * <br />
+ * 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' );
  */

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/editor_basic.js

@@ -27,15 +27,15 @@ if ( !CKEDITOR.editor )
 	CKEDITOR.ELEMENT_MODE_APPENDTO = 2;
 
 	/**
-	 * Represents an editor instance. This constructor should be rarely used,
-	 * being the {@link CKEDITOR} methods preferible.
-	 * @constructor
+	 * Creates an editor class instance. This constructor should be rarely
+	 * used, in favor of the {@link CKEDITOR} editor creation functions.
+	 * @ class Represents an editor instance.
 	 * @param {Object} instanceConfig Configuration values for this specific
 	 *		instance.
 	 * @param {CKEDITOR.dom.element} [element] The element linked to this
 	 *		instance.
 	 * @param {Number} [mode] The mode in which the element is linked to this
-	 *		instance.
+	 *		instance. See {@link #elementMode}.
 	 * @param {String} [data] Since 3.3. Initial value for the instance.
 	 * @augments CKEDITOR.event
 	 * @example
@@ -54,11 +54,11 @@ if ( !CKEDITOR.editor )
 		 * The mode in which the {@link #element} is linked to this editor
 		 * instance. It can be any of the following values:
 		 * <ul>
-		 * <li><b>CKEDITOR.ELEMENT_MODE_NONE</b>: No element is linked to the
+		 * <li>{@link CKEDITOR.ELEMENT_MODE_NONE}: No element is linked to the
 		 *		editor instance.</li>
-		 * <li><b>CKEDITOR.ELEMENT_MODE_REPLACE</b>: The element is to be
+		 * <li>{@link CKEDITOR.ELEMENT_MODE_REPLACE}: The element is to be
 		 *		replaced by the editor instance.</li>
-		 * <li><b>CKEDITOR.ELEMENT_MODE_APPENDTO</b>: The editor is to be
+		 * <li>{@link CKEDITOR.ELEMENT_MODE_APPENDTO}: The editor is to be
 		 *		created inside the element.</li>
 		 * </ul>
 		 * @name CKEDITOR.editor.prototype.elementMode