X-Git-Url: https://jasonwoof.com/gitweb/?p=ckeditor.git;a=blobdiff_plain;f=_source%2Fcore%2Fconfig.js;h=db77f764e5232869851dc934f5b55d78cfc71418;hp=8d45ebed27d480aaea4603316a7d797f6d139dfa;hb=e73319a12b56100b29ef456fd74114fe5519e01c;hpb=f0610347140239143439a511ee2bd48cb784f470 diff --git a/_source/core/config.js b/_source/core/config.js index 8d45ebe..db77f76 100644 --- a/_source/core/config.js +++ b/_source/core/config.js @@ -4,64 +4,67 @@ For licensing, see LICENSE.html or http://ckeditor.com/license */ /** - * @fileOverview Defines the {@link CKEDITOR.config} object, which holds the + * @fileOverview Defines the {@link CKEDITOR.config} object that stores the * default configuration settings. */ /** - * Used in conjuction with {@link CKEDITOR.config.enterMode} and - * {@link CKEDITOR.config.shiftEnterMode} to make the editor produce <p> - * tags when using the ENTER key. + * Used in conjunction with {@link CKEDITOR.config.enterMode} + * and {@link CKEDITOR.config.shiftEnterMode} configuration + * settings to make the editor produce <p> tags when + * using the Enter key. * @constant */ CKEDITOR.ENTER_P = 1; /** - * Used in conjuction with {@link CKEDITOR.config.enterMode} and - * {@link CKEDITOR.config.shiftEnterMode} to make the editor produce <br> - * tags when using the ENTER key. + * Used in conjunction with {@link CKEDITOR.config.enterMode} + * and {@link CKEDITOR.config.shiftEnterMode} configuration + * settings to make the editor produce <br> tags when + * using the Enter key. * @constant */ CKEDITOR.ENTER_BR = 2; /** - * Used in conjuction with {@link CKEDITOR.config.enterMode} and - * {@link CKEDITOR.config.shiftEnterMode} to make the editor produce <div> - * tags when using the ENTER key. + * Used in conjunction with {@link CKEDITOR.config.enterMode} + * and {@link CKEDITOR.config.shiftEnterMode} configuration + * settings to make the editor produce <div> tags when + * using the Enter key. * @constant */ CKEDITOR.ENTER_DIV = 3; /** - * @namespace Holds the default configuration settings. Changes to this object are - * reflected in all editor instances, if not specificaly specified for those - * instances. + * @namespace Stores default configuration settings. Changes to this object are + * reflected in all editor instances, if not specified otherwise for a particular + * instance. */ CKEDITOR.config = { /** * The URL path for the custom configuration file to be loaded. If not - * overloaded with inline configurations, it defaults to the "config.js" + * overloaded with inline configuration, it defaults to the config.js * file present in the root of the CKEditor installation directory.

* * CKEditor will recursively load custom configuration files defined inside * other custom configuration files. * @type String - * @default '<CKEditor folder>/config.js' + * @default '<CKEditor folder>/config.js' * @example * // Load a specific configuration file. - * CKEDITOR.replace( 'myfiled', { customConfig : '/myconfig.js' } ); + * CKEDITOR.replace( 'myfield', { customConfig : '/myconfig.js' } ); * @example * // Do not load any custom configuration file. - * CKEDITOR.replace( 'myfiled', { customConfig : '' } ); + * CKEDITOR.replace( 'myfield', { customConfig : '' } ); */ customConfig : 'config.js', /** - * Whether the replaced element (usually a textarea) is to be updated - * automatically when posting the form containing the editor. + * Whether the replaced element (usually a <textarea>) + * is to be updated automatically when posting the form containing the editor. * @type Boolean - * @default true + * @default true * @example * config.autoUpdateElement = true; */ @@ -71,18 +74,18 @@ CKEDITOR.config = * The base href URL used to resolve relative and absolute URLs in the * editor content. * @type String - * @default '' (empty) + * @default '' (empty) * @example * config.baseHref = 'http://www.example.com/path/'; */ baseHref : '', /** - * The CSS file(s) to be used to apply style to the contents. It should + * The CSS file(s) to be used to apply style to editor contents. It should * reflect the CSS used in the final pages where the contents are to be * used. * @type String|Array - * @default '<CKEditor folder>/contents.css' + * @default '<CKEditor folder>/contents.css' * @example * config.contentsCss = '/css/mysitestyles.css'; * config.contentsCss = ['/css/mysitestyles.css', '/css/anotherfile.css']; @@ -90,14 +93,14 @@ CKEDITOR.config = contentsCss : CKEDITOR.basePath + 'contents.css', /** - * The writting direction of the language used to write the editor + * The writing direction of the language used to create the editor * contents. Allowed values are: * - * @default 'ui' + * @default 'ui' * @type String * @example * config.contentsLangDirection = 'rtl'; @@ -105,9 +108,9 @@ CKEDITOR.config = contentsLangDirection : 'ui', /** - * Language code of the writting language which is used to author the editor + * Language code of the writing language which is used to create the editor * contents. - * @default Same value with editor's UI language. + * @default Same value as editor UI language. * @type String * @example * config.contentsLanguage = 'fr'; @@ -115,10 +118,11 @@ CKEDITOR.config = contentsLanguage : '', /** - * The user interface language localization to use. If empty, the editor - * automatically localize the editor to the user language, if supported, - * otherwise the {@link CKEDITOR.config.defaultLanguage} language is used. - * @default '' (empty) + * The user interface language localization to use. If left empty, the editor + * will automatically be localized to the user language. If the user language is not supported, + * the language specified in the {@link CKEDITOR.config.defaultLanguage} + * configuration setting is used. + * @default '' (empty) * @type String * @example * // Load the German interface. @@ -127,9 +131,9 @@ CKEDITOR.config = language : '', /** - * The language to be used if {@link CKEDITOR.config.language} is left empty and it's not - * possible to localize the editor to the user language. - * @default 'en' + * The language to be used if the {@link CKEDITOR.config.language} + * setting is left empty and it is not possible to localize the editor to the user language. + * @default 'en' * @type String * @example * config.defaultLanguage = 'it'; @@ -137,21 +141,20 @@ CKEDITOR.config = defaultLanguage : 'en', /** - * Sets the behavior for the ENTER key. It also dictates other behaviour - * rules in the editor, like whether the <br> element is to be used + * Sets the behavior of the Enter key. It also determines other behavior + * rules of the editor, like whether the <br> element is to be used * as a paragraph separator when indenting text. - * The allowed values are the following constants, and their relative - * behavior: + * The allowed values are the following constants that cause the behavior outlined below: * - * Note: It's recommended to use the - * {@link CKEDITOR.ENTER_P} value because of its semantic value and - * correctness. The editor is optimized for this value. + * Note: It is recommended to use the + * {@link CKEDITOR.ENTER_P} setting because of its semantic value and + * correctness. The editor is optimized for this setting. * @type Number - * @default {@link CKEDITOR.ENTER_P} + * @default {@link CKEDITOR.ENTER_P} * @example * // Not recommended. * config.enterMode = CKEDITOR.ENTER_BR; @@ -159,11 +162,14 @@ CKEDITOR.config = enterMode : CKEDITOR.ENTER_P, /** - * Force the respect of {@link CKEDITOR.config.enterMode} as line break regardless of the context, - * E.g. If {@link CKEDITOR.config.enterMode} is set to {@link CKEDITOR.ENTER_P}, - * press enter key inside a 'div' will create a new paragraph with 'p' instead of 'div'. + * Force the use of {@link CKEDITOR.config.enterMode} as line break regardless + * of the context. If, for example, {@link CKEDITOR.config.enterMode} is set + * to {@link CKEDITOR.ENTER_P}, pressing the Enter key inside a + * <div> element will create a new paragraph with <p> + * instead of a <div>. * @since 3.2.1 - * @default false + * @type Boolean + * @default false * @example * // Not recommended. * config.forceEnterMode = true; @@ -171,16 +177,16 @@ CKEDITOR.config = forceEnterMode : false, /** - * Just like the {@link CKEDITOR.config.enterMode} setting, it defines the behavior for the SHIFT+ENTER key. - * The allowed values are the following constants, and their relative - * behavior: + * Similarly to the {@link CKEDITOR.config.enterMode} setting, it defines the behavior + * of the Shift+Enter key combination. + * The allowed values are the following constants the behavior outlined below: * * @type Number - * @default {@link CKEDITOR.ENTER_BR} + * @default {@link CKEDITOR.ENTER_BR} * @example * config.shiftEnterMode = CKEDITOR.ENTER_P; */ @@ -188,71 +194,73 @@ CKEDITOR.config = /** * A comma separated list of plugins that are not related to editor - * instances. Reserved to plugins that extend the core code only.

+ * instances. Reserved for plugins that extend the core code only.

* - * There are no ways to override this setting, except by editing the source - * code of CKEditor (_source/core/config.js). + * There are no ways to override this setting except by editing the source + * code of CKEditor (_source/core/config.js). * @type String * @example */ corePlugins : '', /** - * Sets the doctype to be used when loading the editor content as HTML. + * Sets the DOCTYPE to be used when loading the editor content as HTML. * @type String - * @default '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">' + * @default '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">' * @example - * // Set the doctype to the HTML 4 (quirks) mode. + * // Set the DOCTYPE to the HTML 4 (Quirks) mode. * config.docType = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">'; */ docType : '', /** - * Sets the "id" attribute to be used on the body element of the editing - * area. This can be useful when reusing the original CSS file you're using - * on your live website and you want to assing to the editor the same id - * you're using for the region that'll hold the contents. In this way, - * id specific CSS rules will be enabled. + * Sets the id attribute to be used on the body element + * of the editing area. This can be useful when you intend to reuse the original CSS + * file you are using on your live website and want to assign the editor the same ID + * as the section that will include the contents. In this way ID-specific CSS rules will + * be enabled. * @since 3.1 * @type String - * @default '' (empty) + * @default '' (empty) * @example * config.bodyId = 'contents_id'; */ bodyId : '', /** - * Sets the "class" attribute to be used on the body element of the editing - * area. This can be useful when reusing the original CSS file you're using - * on your live website and you want to assing to the editor the same class - * name you're using for the region that'll hold the contents. In this way, - * class specific CSS rules will be enabled. + * Sets the class attribute to be used on the body element + * of the editing area. This can be useful when you intend to reuse the original CSS + * file you are using on your live website and want to assign the editor the same class + * as the section that will include the contents. In this way class-specific CSS rules will + * be enabled. * @since 3.1 * @type String - * @default '' (empty) + * @default '' (empty) * @example * config.bodyClass = 'contents'; */ bodyClass : '', /** - * Indicates whether the contents to be edited are being inputted as a full - * HTML page. A full page includes the <html>, <head> and - * <body> tags. The final output will also reflect this setting, - * including the <body> contents only if this setting is disabled. + * Indicates whether the contents to be edited are being input as a full + * HTML page. A full page includes the <html>, + * <head>, and <body> elements. + * The final output will also reflect this setting, including the + * <body> contents only if this setting is disabled. * @since 3.1 * @type Boolean - * @default false + * @default false * @example * config.fullPage = true; */ fullPage : false, /** - * The height of editing area( content ), in relative or absolute, e.g. 30px, 5em. - * Note: Percentage unit is not supported yet. e.g. 30%. + * The height of the editing area (that includes the editor content), + * in relative or absolute units, e.g. 30px, 5em. + * Note: Percentage units, like 30%, are not supported yet. * @type Number|String - * @default '200' + * @default '200' * @example * config.height = 500; * config.height = '25em'; @@ -261,10 +269,10 @@ CKEDITOR.config = height : 200, /** - * Comma separated list of plugins to load and initialize for an editor - * instance. This should be rarely changed, using instead the - * {@link CKEDITOR.config.extraPlugins} and - * {@link CKEDITOR.config.removePlugins} for customizations. + * Comma separated list of plugins to be loaded and initialized for an editor + * instance. This setting should rarely be changed. It is recommended to use the + * {@link CKEDITOR.config.extraPlugins} and + * {@link CKEDITOR.config.removePlugins} for customization purposes instead. * @type String * @example */ @@ -328,9 +336,9 @@ CKEDITOR.config = 'wsc', /** - * List of additional plugins to be loaded. This is a tool setting which - * makes it easier to add new plugins, whithout having to touch and - * possibly breaking the {@link CKEDITOR.config.plugins} setting. + * A list of additional plugins to be loaded. This setting makes it easier + * to add new plugins without having to touch and potentially break the + * {@link CKEDITOR.config.plugins} setting. * @type String * @example * config.extraPlugins = 'myplugin,anotherplugin'; @@ -338,10 +346,9 @@ CKEDITOR.config = extraPlugins : '', /** - * List of plugins that must not be loaded. This is a tool setting which - * makes it easier to avoid loading plugins definied in the - * {@link CKEDITOR.config.plugins} setting, whithout having to touch it and - * potentially breaking it. + * A list of plugins that must not be loaded. This setting makes it possible + * to avoid loading some plugins defined in the {@link CKEDITOR.config.plugins} + * setting, without having to touch it and potentially break it. * @type String * @example * config.removePlugins = 'elementspath,save,font'; @@ -349,30 +356,31 @@ CKEDITOR.config = removePlugins : '', /** - * List of regular expressions to be executed over the input HTML, - * indicating HTML source code that matched must not present in WYSIWYG mode for editing. + * List of regular expressions to be executed on input HTML, + * indicating HTML source code that when matched, must not be available in the WYSIWYG + * mode for editing. * @type Array - * @default [] (empty array) + * @default [] (empty array) * @example - * config.protectedSource.push( /<\?[\s\S]*?\?>/g ); // PHP Code - * config.protectedSource.push( /<%[\s\S]*?%>/g ); // ASP Code - * config.protectedSource.push( /(]+>[\s|\S]*?<\/asp:[^\>]+>)|(]+\/>)/gi ); // ASP.Net Code + * config.protectedSource.push( /<\?[\s\S]*?\?>/g ); // PHP code + * config.protectedSource.push( /<%[\s\S]*?%>/g ); // ASP code + * config.protectedSource.push( /(]+>[\s|\S]*?<\/asp:[^\>]+>)|(]+\/>)/gi ); // ASP.Net code */ protectedSource : [], /** - * The editor tabindex value. + * The editor tabindex value. * @type Number - * @default 0 (zero) + * @default 0 (zero) * @example * config.tabIndex = 1; */ tabIndex : 0, /** - * The theme to be used to build the UI. + * The theme to be used to build the user interface. * @type String - * @default 'default' + * @default 'default' * @see CKEDITOR.config.skin * @example * config.theme = 'default'; @@ -383,7 +391,7 @@ CKEDITOR.config = * The skin to load. It may be the name of the skin folder inside the * editor installation path, or the name and the path separated by a comma. * @type String - * @default 'default' + * @default 'default' * @example * config.skin = 'v2'; * @example @@ -392,9 +400,9 @@ CKEDITOR.config = skin : 'kama', /** - * The editor width in CSS size format or pixel integer. + * The editor width in CSS-defined units or an integer denoting a value in pixels. * @type String|Number - * @default '' (empty) + * @default '' (empty) * @example * config.width = 850; * @example @@ -403,9 +411,9 @@ CKEDITOR.config = width : '', /** - * The base Z-index for floating dialogs and popups. + * The base Z-index for floating dialog windows and popups. * @type Number - * @default 10000 + * @default 10000 * @example * config.baseFloatZIndex = 2000 */ @@ -414,15 +422,15 @@ CKEDITOR.config = /** * Indicates that some of the editor features, like alignment and text - * direction, should used the "computed value" of the feature to indicate it's - * on/off state, instead of using the "real value".
+ * direction, should use the "computed value" of the feature to indicate its + * on/off state instead of using the "real value".
*
- * If enabled, in a left to right written document, the "Left Justify" - * alignment button will show as active, even if the aligment style is not + * If enabled in a Left-To-Right written document, the "Left Justify" + * alignment button will be shown as active, even if the alignment style is not * explicitly applied to the current paragraph in the editor. * @name CKEDITOR.config.useComputedState * @type Boolean - * @default true + * @default true * @since 3.4 * @example * config.useComputedState = false;