2 Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.
\r
3 For licensing, see LICENSE.html or http://ckeditor.com/license
\r
7 * @fileOverview Defines the {@link CKEDITOR.tools} object, which contains
\r
16 * Utility functions.
\r
23 * Compare the elements of two arrays.
\r
24 * @param {Array} arrayA An array to be compared.
\r
25 * @param {Array} arrayB The other array to be compared.
\r
26 * @returns {Boolean} "true" is the arrays have the same lenght and
\r
27 * their elements match.
\r
29 * var a = [ 1, 'a', 3 ];
\r
30 * var b = [ 1, 3, 'a' ];
\r
31 * var c = [ 1, 'a', 3 ];
\r
32 * var d = [ 1, 'a', 3, 4 ];
\r
34 * alert( CKEDITOR.tools.arrayCompare( a, b ) ); // false
\r
35 * alert( CKEDITOR.tools.arrayCompare( a, c ) ); // true
\r
36 * alert( CKEDITOR.tools.arrayCompare( a, d ) ); // false
\r
38 arrayCompare : function( arrayA, arrayB )
\r
40 if ( !arrayA && !arrayB )
\r
43 if ( !arrayA || !arrayB || arrayA.length != arrayB.length )
\r
46 for ( var i = 0 ; i < arrayA.length ; i++ )
\r
48 if ( arrayA[ i ] != arrayB[ i ] )
\r
56 * Creates a deep copy of an object.
\r
57 * Attention: there is no support for recursive references.
\r
58 * @param {Object} object The object to be cloned.
\r
59 * @returns {Object} The object clone.
\r
66 * Mercedes : { color : 'blue' },
\r
67 * Porsche : { color : 'red' }
\r
70 * var clone = CKEDITOR.tools.clone( obj );
\r
71 * clone.name = 'Paul';
\r
72 * clone.cars.Porsche.color = 'silver';
\r
73 * alert( obj.name ); // John
\r
74 * alert( clone.name ); // Paul
\r
75 * alert( obj.cars.Porsche.color ); // red
\r
76 * alert( clone.cars.Porsche.color ); // silver
\r
78 clone : function( obj )
\r
83 if ( obj && ( obj instanceof Array ) )
\r
87 for ( var i = 0 ; i < obj.length ; i++ )
\r
88 clone[ i ] = this.clone( obj[ i ] );
\r
95 || ( typeof( obj ) != 'object' )
\r
96 || ( obj instanceof String )
\r
97 || ( obj instanceof Number )
\r
98 || ( obj instanceof Boolean )
\r
99 || ( obj instanceof Date )
\r
100 || ( obj instanceof RegExp) )
\r
106 clone = new obj.constructor();
\r
108 for ( var propertyName in obj )
\r
110 var property = obj[ propertyName ];
\r
111 clone[ propertyName ] = this.clone( property );
\r
118 * Turn the first letter of string to upper-case.
\r
119 * @param {String} str
\r
121 capitalize: function( str )
\r
123 return str.charAt( 0 ).toUpperCase() + str.substring( 1 ).toLowerCase();
\r
127 * Copy the properties from one object to another. By default, properties
\r
128 * already present in the target object <strong>are not</strong> overwritten.
\r
129 * @param {Object} target The object to be extended.
\r
130 * @param {Object} source[,souce(n)] The objects from which copy
\r
131 * properties. Any number of objects can be passed to this function.
\r
132 * @param {Boolean} [overwrite] If 'true' is specified it indicates that
\r
133 * properties already present in the target object could be
\r
134 * overwritten by subsequent objects.
\r
135 * @param {Object} [properties] Only properties within the specified names
\r
136 * list will be received from the source object.
\r
137 * @returns {Object} the extended object (target).
\r
139 * // Create the sample object.
\r
145 * // Extend the above object with two properties.
\r
146 * CKEDITOR.tools.extend( myObject,
\r
152 * // Alert "prop1", "prop2" and "prop3".
\r
153 * for ( var p in myObject )
\r
156 extend : function( target )
\r
158 var argsLength = arguments.length,
\r
159 overwrite, propertiesList;
\r
161 if ( typeof ( overwrite = arguments[ argsLength - 1 ] ) == 'boolean')
\r
163 else if ( typeof ( overwrite = arguments[ argsLength - 2 ] ) == 'boolean' )
\r
165 propertiesList = arguments [ argsLength -1 ];
\r
168 for ( var i = 1 ; i < argsLength ; i++ )
\r
170 var source = arguments[ i ];
\r
171 for ( var propertyName in source )
\r
173 // Only copy existed fields if in overwrite mode.
\r
174 if ( overwrite === true || target[ propertyName ] == undefined )
\r
176 // Only copy specified fields if list is provided.
\r
177 if ( !propertiesList || ( propertyName in propertiesList ) )
\r
178 target[ propertyName ] = source[ propertyName ];
\r
188 * Creates an object which is an instance of a class which prototype is a
\r
189 * predefined object. All properties defined in the source object are
\r
190 * automatically inherited by the resulting object, including future
\r
192 * @param {Object} source The source object to be used as the prototype for
\r
193 * the final object.
\r
194 * @returns {Object} The resulting copy.
\r
196 prototypedCopy : function( source )
\r
198 var copy = function()
\r
200 copy.prototype = source;
\r
205 * Checks if an object is an Array.
\r
206 * @param {Object} object The object to be checked.
\r
208 * @returns <i>true</i> if the object is an Array, otherwise <i>false</i>.
\r
210 * alert( CKEDITOR.tools.isArray( [] ) ); // "true"
\r
211 * alert( CKEDITOR.tools.isArray( 'Test' ) ); // "false"
\r
213 isArray : function( object )
\r
215 return ( !!object && object instanceof Array );
\r
218 isEmpty : function ( object )
\r
220 for ( var i in object )
\r
222 if ( object.hasOwnProperty( i ) )
\r
228 * Transforms a CSS property name to its relative DOM style name.
\r
229 * @param {String} cssName The CSS property name.
\r
230 * @returns {String} The transformed name.
\r
232 * alert( CKEDITOR.tools.cssStyleToDomStyle( 'background-color' ) ); // "backgroundColor"
\r
233 * alert( CKEDITOR.tools.cssStyleToDomStyle( 'float' ) ); // "cssFloat"
\r
235 cssStyleToDomStyle : ( function()
\r
237 var test = document.createElement( 'div' ).style;
\r
239 var cssFloat = ( typeof test.cssFloat != 'undefined' ) ? 'cssFloat'
\r
240 : ( typeof test.styleFloat != 'undefined' ) ? 'styleFloat'
\r
243 return function( cssName )
\r
245 if ( cssName == 'float' )
\r
249 return cssName.replace( /-./g, function( match )
\r
251 return match.substr( 1 ).toUpperCase();
\r
258 * Build the HTML snippet of a set of <style>/<link>.
\r
259 * @param css {String|Array} Each of which are url (absolute) of a CSS file or
\r
260 * a trunk of style text.
\r
262 buildStyleHtml : function ( css )
\r
264 css = [].concat( css );
\r
265 var item, retval = [];
\r
266 for ( var i = 0; i < css.length; i++ )
\r
269 // Is CSS style text ?
\r
270 if ( /@import|[{}]/.test(item) )
\r
271 retval.push('<style>' + item + '</style>');
\r
273 retval.push('<link type="text/css" rel=stylesheet href="' + item + '">');
\r
275 return retval.join( '' );
\r
279 * Replace special HTML characters in a string with their relative HTML
\r
281 * @param {String} text The string to be encoded.
\r
282 * @returns {String} The encode string.
\r
284 * alert( CKEDITOR.tools.htmlEncode( 'A > B & C < D' ) ); // "A &gt; B &amp; C &lt; D"
\r
286 htmlEncode : function( text )
\r
288 var standard = function( text )
\r
290 var span = new CKEDITOR.dom.element( 'span' );
\r
291 span.setText( text );
\r
292 return span.getHtml();
\r
295 var fix1 = ( standard( '\n' ).toLowerCase() == '<br>' ) ?
\r
298 // #3874 IE and Safari encode line-break into <br>
\r
299 return standard( text ).replace( /<br>/gi, '\n' );
\r
303 var fix2 = ( standard( '>' ) == '>' ) ?
\r
306 // WebKit does't encode the ">" character, which makes sense, but
\r
307 // it's different than other browsers.
\r
308 return fix1( text ).replace( />/g, '>' );
\r
312 var fix3 = ( standard( ' ' ) == ' ' ) ?
\r
315 // #3785 IE8 changes spaces (>= 2) to
\r
316 return fix2( text ).replace( / /g, ' ' );
\r
320 this.htmlEncode = fix3;
\r
322 return this.htmlEncode( text );
\r
326 * Replace special HTML characters in HTMLElement's attribute with their relative HTML entity values.
\r
327 * @param {String} The attribute's value to be encoded.
\r
328 * @returns {String} The encode value.
\r
330 * element.setAttribute( 'title', '<a " b >' );
\r
331 * alert( CKEDITOR.tools.htmlEncodeAttr( element.getAttribute( 'title' ) ); // ">a " b <"
\r
333 htmlEncodeAttr : function( text )
\r
335 return text.replace( /"/g, '"' ).replace( /</g, '<' ).replace( />/, '>' );
\r
339 * Replace characters can't be represented through CSS Selectors string
\r
340 * by CSS Escape Notation where the character escape sequence consists
\r
341 * of a backslash character (\) followed by the orginal characters.
\r
342 * Ref: http://www.w3.org/TR/css3-selectors/#grammar
\r
343 * @param cssSelectText
\r
344 * @return the escaped selector text.
\r
346 escapeCssSelector : function( cssSelectText )
\r
348 return cssSelectText.replace( /[\s#:.,$*^\[\]()~=+>]/g, '\\$&' );
\r
352 * Gets a unique number for this CKEDITOR execution session. It returns
\r
353 * progressive numbers starting at 1.
\r
355 * @returns {Number} A unique number.
\r
357 * alert( CKEDITOR.tools.<b>getNextNumber()</b> ); // "1" (e.g.)
\r
358 * alert( CKEDITOR.tools.<b>getNextNumber()</b> ); // "2"
\r
360 getNextNumber : (function()
\r
370 * Creates a function override.
\r
371 * @param {Function} originalFunction The function to be overridden.
\r
372 * @param {Function} functionBuilder A function that returns the new
\r
373 * function. The original function reference will be passed to this
\r
375 * @returns {Function} The new function.
\r
379 * myFunction : function( name )
\r
381 * alert( 'Name: ' + name );
\r
385 * example.myFunction = CKEDITOR.tools.override( example.myFunction, function( myFunctionOriginal )
\r
387 * return function( name )
\r
389 * alert( 'Override Name: ' + name );
\r
390 * myFunctionOriginal.call( this, name );
\r
394 override : function( originalFunction, functionBuilder )
\r
396 return functionBuilder( originalFunction );
\r
400 * Executes a function after specified delay.
\r
401 * @param {Function} func The function to be executed.
\r
402 * @param {Number} [milliseconds] The amount of time (millisecods) to wait
\r
403 * to fire the function execution. Defaults to zero.
\r
404 * @param {Object} [scope] The object to hold the function execution scope
\r
405 * (the "this" object). By default the "window" object.
\r
406 * @param {Object|Array} [args] A single object, or an array of objects, to
\r
407 * pass as arguments to the function.
\r
408 * @param {Object} [ownerWindow] The window that will be used to set the
\r
409 * timeout. By default the current "window".
\r
410 * @returns {Object} A value that can be used to cancel the function execution.
\r
412 * CKEDITOR.tools.<b>setTimeout(
\r
415 * alert( 'Executed after 2 seconds' );
\r
419 setTimeout : function( func, milliseconds, scope, args, ownerWindow )
\r
421 if ( !ownerWindow )
\r
422 ownerWindow = window;
\r
425 scope = ownerWindow;
\r
427 return ownerWindow.setTimeout(
\r
431 func.apply( scope, [].concat( args ) ) ;
\r
433 func.apply( scope ) ;
\r
435 milliseconds || 0 );
\r
439 * Remove spaces from the start and the end of a string. The following
\r
440 * characters are removed: space, tab, line break, line feed.
\r
442 * @param {String} str The text from which remove the spaces.
\r
443 * @returns {String} The modified string without the boundary spaces.
\r
445 * alert( CKEDITOR.tools.trim( ' example ' ); // "example"
\r
449 // We are not using \s because we don't want "non-breaking spaces" to be caught.
\r
450 var trimRegex = /(?:^[ \t\n\r]+)|(?:[ \t\n\r]+$)/g;
\r
451 return function( str )
\r
453 return str.replace( trimRegex, '' ) ;
\r
458 * Remove spaces from the start (left) of a string. The following
\r
459 * characters are removed: space, tab, line break, line feed.
\r
461 * @param {String} str The text from which remove the spaces.
\r
462 * @returns {String} The modified string excluding the removed spaces.
\r
464 * alert( CKEDITOR.tools.ltrim( ' example ' ); // "example "
\r
466 ltrim : (function()
\r
468 // We are not using \s because we don't want "non-breaking spaces" to be caught.
\r
469 var trimRegex = /^[ \t\n\r]+/g;
\r
470 return function( str )
\r
472 return str.replace( trimRegex, '' ) ;
\r
477 * Remove spaces from the end (right) of a string. The following
\r
478 * characters are removed: space, tab, line break, line feed.
\r
480 * @param {String} str The text from which remove the spaces.
\r
481 * @returns {String} The modified string excluding the removed spaces.
\r
483 * alert( CKEDITOR.tools.ltrim( ' example ' ); // " example"
\r
485 rtrim : (function()
\r
487 // We are not using \s because we don't want "non-breaking spaces" to be caught.
\r
488 var trimRegex = /[ \t\n\r]+$/g;
\r
489 return function( str )
\r
491 return str.replace( trimRegex, '' ) ;
\r
496 * Returns the index of an element in an array.
\r
497 * @param {Array} array The array to be searched.
\r
498 * @param {Object} entry The element to be found.
\r
499 * @returns {Number} The (zero based) index of the first entry that matches
\r
500 * the entry, or -1 if not found.
\r
502 * var letters = [ 'a', 'b', 0, 'c', false ];
\r
503 * alert( CKEDITOR.tools.indexOf( letters, '0' ) ); "-1" because 0 !== '0'
\r
504 * alert( CKEDITOR.tools.indexOf( letters, false ) ); "4" because 0 !== false
\r
507 // #2514: We should try to use Array.indexOf if it does exist.
\r
508 ( Array.prototype.indexOf ) ?
\r
509 function( array, entry )
\r
511 return array.indexOf( entry );
\r
514 function( array, entry )
\r
516 for ( var i = 0, len = array.length ; i < len ; i++ )
\r
518 if ( array[ i ] === entry )
\r
525 * Creates a function that will always execute in the context of a
\r
526 * specified object.
\r
527 * @param {Function} func The function to be executed.
\r
528 * @param {Object} obj The object to which bind the execution context.
\r
529 * @returns {Function} The function that can be used to execute the
\r
530 * "func" function in the context of "obj".
\r
532 * var obj = { text : 'My Object' };
\r
534 * function alertText()
\r
536 * alert( this.text );
\r
539 * var newFunc = <b>CKEDITOR.tools.bind( alertText, obj )</b>;
\r
540 * newFunc(); // Alerts "My Object".
\r
542 bind : function( func, obj )
\r
544 return function() { return func.apply( obj, arguments ); };
\r
548 * Class creation based on prototype inheritance, with supports of the
\r
549 * following features:
\r
551 * <li> Static fields </li>
\r
552 * <li> Private fields </li>
\r
553 * <li> Public (prototype) fields </li>
\r
554 * <li> Chainable base class constructor </li>
\r
556 * @param {Object} definition The class definition object.
\r
557 * @returns {Function} A class-like JavaScript function.
\r
559 createClass : function( definition )
\r
561 var $ = definition.$,
\r
562 baseClass = definition.base,
\r
563 privates = definition.privates || definition._,
\r
564 proto = definition.proto,
\r
565 statics = definition.statics;
\r
569 var originalConstructor = $;
\r
572 // Create (and get) the private namespace.
\r
573 var _ = this._ || ( this._ = {} );
\r
575 // Make some magic so "this" will refer to the main
\r
576 // instance when coding private functions.
\r
577 for ( var privateName in privates )
\r
579 var priv = privates[ privateName ];
\r
582 ( typeof priv == 'function' ) ? CKEDITOR.tools.bind( priv, this ) : priv;
\r
585 originalConstructor.apply( this, arguments );
\r
591 $.prototype = this.prototypedCopy( baseClass.prototype );
\r
592 $.prototype.constructor = $;
\r
593 $.prototype.base = function()
\r
595 this.base = baseClass.prototype.base;
\r
596 baseClass.apply( this, arguments );
\r
597 this.base = arguments.callee;
\r
602 this.extend( $.prototype, proto, true );
\r
605 this.extend( $, statics, true );
\r
611 * Creates a function reference that can be called later using
\r
612 * CKEDITOR.tools.callFunction. This approach is specially useful to
\r
613 * make DOM attribute function calls to JavaScript defined functions.
\r
614 * @param {Function} fn The function to be executed on call.
\r
615 * @param {Object} [scope] The object to have the context on "fn" execution.
\r
616 * @returns {Number} A unique reference to be used in conjuction with
\r
617 * CKEDITOR.tools.callFunction.
\r
619 * var ref = <b>CKEDITOR.tools.addFunction</b>(
\r
622 * alert( 'Hello!');
\r
624 * CKEDITOR.tools.callFunction( ref ); // Hello!
\r
626 addFunction : function( fn, scope )
\r
628 return functions.push( function()
\r
630 fn.apply( scope || this, arguments );
\r
635 * Removes the function reference created with {@see CKEDITOR.tools.addFunction}.
\r
636 * @param {Number} ref The function reference created with
\r
637 * CKEDITOR.tools.addFunction.
\r
639 removeFunction : function( ref )
\r
641 functions[ ref ] = null;
\r
645 * Executes a function based on the reference created with
\r
646 * CKEDITOR.tools.addFunction.
\r
647 * @param {Number} ref The function reference created with
\r
648 * CKEDITOR.tools.addFunction.
\r
649 * @param {[Any,[Any,...]} params Any number of parameters to be passed
\r
650 * to the executed function.
\r
651 * @returns {Any} The return value of the function.
\r
653 * var ref = CKEDITOR.tools.addFunction(
\r
656 * alert( 'Hello!');
\r
658 * <b>CKEDITOR.tools.callFunction( ref )</b>; // Hello!
\r
660 callFunction : function( ref )
\r
662 var fn = functions[ ref ];
\r
663 return fn && fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );
\r
666 cssLength : (function()
\r
668 var decimalRegex = /^\d+(?:\.\d+)?$/;
\r
669 return function( length )
\r
671 return length + ( decimalRegex.test( length ) ? 'px' : '' );
\r
675 repeat : function( str, times )
\r
677 return new Array( times + 1 ).join( str );
\r
680 tryThese : function()
\r
683 for ( var i = 0, length = arguments.length; i < length; i++ )
\r
685 var lambda = arguments[i];
\r
688 returnValue = lambda();
\r
693 return returnValue;
\r
698 // PACKAGER_RENAME( CKEDITOR.tools )
\r