X-Git-Url: https://jasonwoof.com/gitweb/?a=blobdiff_plain;f=_source%2Fcore%2Fconfig.js;h=962f33b2230e796a4b9cf0cf9304c82146ec38ce;hb=2f22c0c38f17e75be5541089076885442aaa2377;hp=c53892da769809ccc8be5aa99bf38bd10affdb02;hpb=e7789c1ad838194d45eeee6ac2eb6e55f5cf35a1;p=ckeditor.git diff --git a/_source/core/config.js b/_source/core/config.js index c53892d..962f33b 100644 --- a/_source/core/config.js +++ b/_source/core/config.js @@ -1,52 +1,70 @@ /* -Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved. +Copyright (c) 2003-2012, CKSource - Frederico Knabben. All rights reserved. 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 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 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 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; /** - * Holds the default configuration settings. Changes to this object are - * reflected in all editor instances, if not specificaly specified for those - * instances. - * @namespace - * @example - * // All editor created after the following setting will not load custom - * // configuration files. - * CKEDITOR.config.customConfig = ''; + * @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; */ @@ -56,18 +74,18 @@ CKEDITOR.config = * The base href URL used to resolve relative and absolute URLs in the * editor content. * @type String - * @default '' (empty string) + * @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']; @@ -75,21 +93,36 @@ CKEDITOR.config = contentsCss : CKEDITOR.basePath + 'contents.css', /** - * The writting direction of the language used to write the editor - * contents. Allowed values are 'ltr' for Left-To-Right language (like - * English), or 'rtl' for Right-To-Left languages (like Arabic). - * @default 'ltr' + * The writing direction of the language used to create the editor + * contents. Allowed values are: + * + * @default 'ui' * @type String * @example * config.contentsLangDirection = 'rtl'; */ - contentsLangDirection : 'ltr', + contentsLangDirection : 'ui', /** - * 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) + * Language code of the writing language which is used to create the editor + * contents. + * @default Same value as editor UI language. + * @type String + * @example + * config.contentsLanguage = 'fr'; + */ + contentsLanguage : '', + + /** + * 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. @@ -98,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'; @@ -108,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; @@ -130,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; @@ -142,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; */ @@ -159,82 +194,154 @@ 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. + * 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 '' + * @default '' (empty) + * @example + * config.bodyId = 'contents_id'; */ bodyId : '', /** - * Sets the "class" attribute to be used on the body element of the editing - * area. + * 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 '' + * @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). This + * can be an integer, for pixel sizes, or any CSS-defined length unit.
+ *
+ * Note: Percent units (%) are not supported. * @type Number|String - * @default '200' + * @default 200 * @example - * config.height = 500; - * config.height = '25em'; - * config.height = '300px'; + * config.height = 500; // 500 pixels. + * @example + * config.height = '25em'; // CSS length. + * @example + * config.height = '300px'; // CSS length. */ 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 */ - plugins : 'about,a11yhelp,basicstyles,blockquote,button,clipboard,colorbutton,colordialog,contextmenu,div,elementspath,enterkey,entities,filebrowser,find,flash,font,format,forms,horizontalrule,htmldataprocessor,image,indent,justify,keystrokes,link,list,maximize,newpage,pagebreak,pastefromword,pastetext,popup,preview,print,removeformat,resize,save,scayt,smiley,showblocks,showborders,sourcearea,stylescombo,table,tabletools,specialchar,tab,templates,toolbar,undo,wysiwygarea,wsc', + plugins : + 'about,' + + 'a11yhelp,' + + 'basicstyles,' + + 'bidi,' + + 'blockquote,' + + 'button,' + + 'clipboard,' + + 'colorbutton,' + + 'colordialog,' + + 'contextmenu,' + + 'dialogadvtab,' + + 'div,' + + 'elementspath,' + + 'enterkey,' + + 'entities,' + + 'filebrowser,' + + 'find,' + + 'flash,' + + 'font,' + + 'format,' + + 'forms,' + + 'horizontalrule,' + + 'htmldataprocessor,' + + 'iframe,' + + 'image,' + + 'indent,' + + 'justify,' + + 'keystrokes,' + + 'link,' + + 'list,' + + 'liststyle,' + + 'maximize,' + + 'newpage,' + + 'pagebreak,' + + 'pastefromword,' + + 'pastetext,' + + 'popup,' + + 'preview,' + + 'print,' + + 'removeformat,' + + 'resize,' + + 'save,' + + 'scayt,' + + 'smiley,' + + 'showblocks,' + + 'showborders,' + + 'sourcearea,' + + 'stylescombo,' + + 'table,' + + 'tabletools,' + + 'specialchar,' + + 'tab,' + + 'templates,' + + 'toolbar,' + + 'undo,' + + 'wysiwygarea,' + + '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'; @@ -242,10 +349,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'; @@ -253,30 +359,31 @@ CKEDITOR.config = removePlugins : '', /** - * List of regular expressions to be executed over the input HTML, - * indicating code that must stay untouched. + * 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'; @@ -287,7 +394,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 @@ -296,24 +403,45 @@ CKEDITOR.config = skin : 'kama', /** - * The editor width in CSS size format or pixel integer. + * The editor UI outer width. This can be an integer, for pixel sizes, or + * any CSS-defined unit.
+ *
+ * Unlike the {@link CKEDITOR.config.height} setting, this + * one will set the outer width of the entire editor UI, not for the + * editing area only. * @type String|Number - * @default '' (empty) + * @default '' (empty) * @example - * config.width = 850; + * config.width = 850; // 850 pixels wide. * @example - * config.width = '75%'; + * config.width = '75%'; // CSS unit. */ 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 */ baseFloatZIndex : 10000 }; +/** + * Indicates that some of the editor features, like alignment and text + * 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 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 + * @since 3.4 + * @example + * config.useComputedState = false; + */ + // PACKAGER_RENAME( CKEDITOR.config )