Changeset 7107


Ignore:
Timestamp:
07/15/11 17:26:43 (22 months ago)
Author:
Anna
Message:

API documentation revised for the source/core/config.js file.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • CKEditor/trunk/_source/core/config.js

    r6348 r7107  
    55 
    66/** 
    7  * @fileOverview Defines the {@link CKEDITOR.config} object, which holds the 
     7 * @fileOverview Defines the <code>{@link CKEDITOR.config}</code> object that stores the 
    88 * default configuration settings. 
    99 */ 
    1010 
    1111/** 
    12  * Used in conjuction with {@link CKEDITOR.config.enterMode} and 
    13  * {@link CKEDITOR.config.shiftEnterMode} to make the editor produce &lt;p&gt; 
    14  * tags when using the ENTER key. 
     12 * Used in conjunction with <code>{@link CKEDITOR.config.enterMode}</code> 
     13 * and <code>{@link CKEDITOR.config.shiftEnterMode}</code> configuration 
     14 * settings to make the editor produce <code>&lt;p&gt;</code> tags when 
     15 * using the <em>Enter</em> key. 
    1516 * @constant 
    1617 */ 
    … …  
    1819 
    1920/** 
    20  * Used in conjuction with {@link CKEDITOR.config.enterMode} and 
    21  * {@link CKEDITOR.config.shiftEnterMode} to make the editor produce &lt;br&gt; 
    22  * tags when using the ENTER key. 
     21 * Used in conjunction with <code>{@link CKEDITOR.config.enterMode}</code> 
     22 * and <code>{@link CKEDITOR.config.shiftEnterMode}</code> configuration 
     23 * settings to make the editor produce <code>&lt;br&gt;</code> tags when 
     24 * using the <em>Enter</em> key. 
    2325 * @constant 
    2426 */ 
    … …  
    2628 
    2729/** 
    28  * Used in conjuction with {@link CKEDITOR.config.enterMode} and 
    29  * {@link CKEDITOR.config.shiftEnterMode} to make the editor produce &lt;div&gt; 
    30  * tags when using the ENTER key. 
     30 * Used in conjunction with <code>{@link CKEDITOR.config.enterMode}</code> 
     31 * and <code>{@link CKEDITOR.config.shiftEnterMode}</code> configuration 
     32 * settings to make the editor produce <code>&lt;div&gt;</code> tags when 
     33 * using the <em>Enter</em> key. 
    3134 * @constant 
    3235 */ 
    … …  
    3437 
    3538/** 
    36  * @namespace Holds the default configuration settings. Changes to this object are 
    37  * reflected in all editor instances, if not specificaly specified for those 
    38  * instances. 
     39 * @namespace Stores default configuration settings. Changes to this object are 
     40 * reflected in all editor instances, if not specified otherwise for a particular 
     41 * instance. 
    3942 */ 
    4043CKEDITOR.config = 
    … …  
    4245        /** 
    4346         * The URL path for the custom configuration file to be loaded. If not 
    44          * overloaded with inline configurations, it defaults to the "config.js" 
     47         * overloaded with inline configuration, it defaults to the <code>config.js</code> 
    4548         * file present in the root of the CKEditor installation directory.<br /><br /> 
    4649         * 
    … …  
    4851         * other custom configuration files. 
    4952         * @type String 
    50          * @default '&lt;CKEditor folder&gt;/config.js' 
     53         * @default <code>'<em>&lt;CKEditor folder&gt;</em>/config.js'</code> 
    5154         * @example 
    5255         * // Load a specific configuration file. 
    53          * CKEDITOR.replace( 'myfiled', { customConfig : '/myconfig.js' } ); 
     56         * CKEDITOR.replace( 'myfield', { customConfig : '/myconfig.js' } ); 
    5457         * @example 
    5558         * // Do not load any custom configuration file. 
    56          * CKEDITOR.replace( 'myfiled', { customConfig : '' } ); 
     59         * CKEDITOR.replace( 'myfield', { customConfig : '' } ); 
    5760         */ 
    5861        customConfig : 'config.js', 
    5962 
    6063        /** 
    61          * Whether the replaced element (usually a textarea) is to be updated 
    62          * automatically when posting the form containing the editor. 
     64         * Whether the replaced element (usually a <code>&lt;textarea&gt;</code>) 
     65         * is to be updated automatically when posting the form containing the editor. 
    6366         * @type Boolean 
    64          * @default true 
     67         * @default <code>true</code> 
    6568         * @example 
    6669         * config.autoUpdateElement = true; 
    … …  
    7275         * editor content. 
    7376         * @type String 
    74          * @default '' (empty) 
     77         * @default <code>''</code> (empty) 
    7578         * @example 
    7679         * config.baseHref = 'http://www.example.com/path/'; 
    … …  
    7982 
    8083        /** 
    81          * The CSS file(s) to be used to apply style to the contents. It should 
     84         * The CSS file(s) to be used to apply style to editor contents. It should 
    8285         * reflect the CSS used in the final pages where the contents are to be 
    8386         * used. 
    8487         * @type String|Array 
    85          * @default '&lt;CKEditor folder&gt;/contents.css' 
     88         * @default <code>'<em>&lt;CKEditor folder&gt;</em>/contents.css'</code> 
    8689         * @example 
    8790         * config.contentsCss = '/css/mysitestyles.css'; 
    … …  
    9194 
    9295        /** 
    93          * The writting direction of the language used to write the editor 
     96         * The writing direction of the language used to create the editor 
    9497         * contents. Allowed values are: 
    9598         * <ul> 
    96          *     <li>'ui' - which indicate content direction will be the same with the user interface language direction;</li> 
    97          *     <li>'ltr' - for Left-To-Right language (like English);</li> 
    98          *     <li>'rtl' - for Right-To-Left languages (like Arabic).</li> 
     99         *     <li><code>'ui'</code> &ndash; indicates that content direction will be the same as the user interface language direction;</li> 
     100         *     <li><code>'ltr'</code> &ndash; for Left-To-Right language (like English);</li> 
     101         *     <li><code>'rtl'</code> &ndash; for Right-To-Left languages (like Arabic).</li> 
    99102         * </ul> 
    100          * @default 'ui' 
     103         * @default <code>'ui'</code> 
    101104         * @type String 
    102105         * @example 
    … …  
    106109 
    107110        /** 
    108          * Language code of  the writting language which is used to author the editor 
     111         * Language code of  the writing language which is used to create the editor 
    109112         * contents. 
    110          * @default Same value with editor's UI language. 
     113         * @default Same value as editor UI language. 
    111114         * @type String 
    112115         * @example 
    … …  
    116119 
    117120        /** 
    118          * The user interface language localization to use. If empty, the editor 
    119          * automatically localize the editor to the user language, if supported, 
    120          * otherwise the {@link CKEDITOR.config.defaultLanguage} language is used. 
    121          * @default '' (empty) 
     121         * The user interface language localization to use. If left empty, the editor 
     122         * will automatically be localized to the user language. If the user language is not supported, 
     123         * the language specified in the <code>{@link CKEDITOR.config.defaultLanguage}</code> 
     124         * configuration setting is used. 
     125         * @default <code>''</code> (empty) 
    122126         * @type String 
    123127         * @example 
    … …  
    128132 
    129133        /** 
    130          * The language to be used if {@link CKEDITOR.config.language} is left empty and it's not 
    131          * possible to localize the editor to the user language. 
    132          * @default 'en' 
     134         * The language to be used if the <code>{@link CKEDITOR.config.language}</code> 
     135         * setting is left empty and it is not possible to localize the editor to the user language. 
     136         * @default <code>'en'</code> 
    133137         * @type String 
    134138         * @example 
    … …  
    138142 
    139143        /** 
    140          * Sets the behavior for the ENTER key. It also dictates other behaviour 
    141          * rules in the editor, like whether the &lt;br&gt; element is to be used 
     144         * Sets the behavior of the <em>Enter</em> key. It also determines other behavior 
     145         * rules of the editor, like whether the <code>&lt;br&gt;</code> element is to be used 
    142146         * as a paragraph separator when indenting text. 
    143          * The allowed values are the following constants, and their relative 
    144          * behavior: 
     147         * The allowed values are the following constants that cause the behavior outlined below: 
    145148         * <ul> 
    146          *     <li>{@link CKEDITOR.ENTER_P} (1): new &lt;p&gt; paragraphs are created;</li> 
    147          *     <li>{@link CKEDITOR.ENTER_BR} (2): lines are broken with &lt;br&gt; elements;</li> 
    148          *     <li>{@link CKEDITOR.ENTER_DIV} (3): new &lt;div&gt; blocks are created.</li> 
     149         *     <li><code>{@link CKEDITOR.ENTER_P}</code> (1) &ndash; new <code>&lt;p&gt;</code> paragraphs are created;</li> 
     150         *     <li><code>{@link CKEDITOR.ENTER_BR}</code> (2) &ndash; lines are broken with <code>&lt;br&gt;</code> elements;</li> 
     151         *     <li><code>{@link CKEDITOR.ENTER_DIV}</code> (3) &ndash; new <code>&lt;div&gt;</code> blocks are created.</li> 
    149152         * </ul> 
    150          * <strong>Note</strong>: It's recommended to use the 
    151          * {@link CKEDITOR.ENTER_P} value because of its semantic value and 
    152          * correctness. The editor is optimized for this value. 
     153         * <strong>Note</strong>: It is recommended to use the 
     154         * <code>{@link CKEDITOR.ENTER_P}</code> setting because of its semantic value and 
     155         * correctness. The editor is optimized for this setting. 
    153156         * @type Number 
    154          * @default {@link CKEDITOR.ENTER_P} 
     157         * @default <code>{@link CKEDITOR.ENTER_P}</code> 
    155158         * @example 
    156159         * // Not recommended. 
    … …  
    160163 
    161164        /** 
    162          * Force the respect of {@link CKEDITOR.config.enterMode} as line break regardless of the context, 
    163          * E.g. If {@link CKEDITOR.config.enterMode} is set to {@link CKEDITOR.ENTER_P}, 
    164          * press enter key inside a 'div' will create a new paragraph with 'p' instead of 'div'. 
     165         * Force the use of <code>{@link CKEDITOR.config.enterMode}</code> as line break regardless 
     166         * of the context. If, for example, <code>{@link CKEDITOR.config.enterMode}</code> is set 
     167         * to <code>{@link CKEDITOR.ENTER_P}</code>, pressing the <em>Enter</em> key inside a 
     168         * <code>&lt;div&gt;</code> element will create a new paragraph with <code>&lt;p&gt;</code> 
     169         * instead of a <code>&lt;div&gt;</code>. 
    165170         * @since 3.2.1 
    166          * @default false 
     171         * @type Boolean 
     172         * @default <code>false</code> 
    167173         * @example 
    168174         * // Not recommended. 
    … …  
    172178 
    173179        /** 
    174          * Just like the {@link CKEDITOR.config.enterMode} setting, it defines the behavior for the SHIFT+ENTER key. 
    175          * The allowed values are the following constants, and their relative 
    176          * behavior: 
     180         * Similarly to the <code>{@link CKEDITOR.config.enterMode}</code> setting, it defines the behavior 
     181         * of the <em>Shift+Enter</em> key combination. 
     182         * The allowed values are the following constants the behavior outlined below: 
    177183         * <ul> 
    178          *     <li>{@link CKEDITOR.ENTER_P} (1): new &lt;p&gt; paragraphs are created;</li> 
    179          *     <li>{@link CKEDITOR.ENTER_BR} (2): lines are broken with &lt;br&gt; elements;</li> 
    180          *     <li>{@link CKEDITOR.ENTER_DIV} (3): new &lt;div&gt; blocks are created.</li> 
     184         *     <li><code>{@link CKEDITOR.ENTER_P}</code> (1) &ndash; new <code>&lt;p&gt;</code> paragraphs are created;</li> 
     185         *     <li><code>{@link CKEDITOR.ENTER_BR}</code> (2) &ndash; lines are broken with <code>&lt;br&gt;</code> elements;</li> 
     186         *     <li><code>{@link CKEDITOR.ENTER_DIV}</code> (3) &ndash; new <code>&lt;div&gt;</code> blocks are created.</li> 
    181187         * </ul> 
    182188         * @type Number 
    183          * @default {@link CKEDITOR.ENTER_BR} 
     189         * @default <code>{@link CKEDITOR.ENTER_BR}</code> 
    184190         * @example 
    185191         * config.shiftEnterMode = CKEDITOR.ENTER_P; 
    … …  
    189195        /** 
    190196         * A comma separated list of plugins that are not related to editor 
    191          * instances. Reserved to plugins that extend the core code only.<br /><br /> 
     197         * instances. Reserved for plugins that extend the core code only.<br /><br /> 
    192198         * 
    193          * There are no ways to override this setting, except by editing the source 
    194          * code of CKEditor (_source/core/config.js). 
     199         * There are no ways to override this setting except by editing the source 
     200         * code of CKEditor (<code>_source/core/config.js</code>). 
    195201         * @type String 
    196202         * @example 
    … …  
    199205 
    200206        /** 
    201          * Sets the doctype to be used when loading the editor content as HTML. 
    202          * @type String 
    203          * @default '&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;' 
    204          * @example 
    205          * // Set the doctype to the HTML 4 (quirks) mode. 
     207         * Sets the <code>DOCTYPE</code> to be used when loading the editor content as HTML. 
     208         * @type String 
     209         * @default <code>'&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;'</code> 
     210         * @example 
     211         * // Set the DOCTYPE to the HTML 4 (Quirks) mode. 
    206212         * config.docType = '&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"&gt;'; 
    207213         */ 
    … …  
    209215 
    210216        /** 
    211          * Sets the "id" attribute to be used on the body element of the editing 
    212          * area. This can be useful when reusing the original CSS file you're using 
    213          * on your live website and you want to assing to the editor the same id 
    214          * you're using for the region that'll hold the contents. In this way, 
    215          * id specific CSS rules will be enabled. 
     217         * Sets the <code>id</code> attribute to be used on the <code>body</code> element 
     218         * of the editing area. This can be useful when you intend to reuse the original CSS 
     219         * file you are using on your live website and want to assign the editor the same ID 
     220         * as the section that will include the contents. In this way ID-specific CSS rules will 
     221         * be enabled. 
    216222         * @since 3.1 
    217223         * @type String 
    218          * @default '' (empty) 
     224         * @default <code>''</code> (empty) 
    219225         * @example 
    220226         * config.bodyId = 'contents_id'; 
    … …  
    223229 
    224230        /** 
    225          * Sets the "class" attribute to be used on the body element of the editing 
    226          * area. This can be useful when reusing the original CSS file you're using 
    227          * on your live website and you want to assing to the editor the same class 
    228          * name you're using for the region that'll hold the contents. In this way, 
    229          * class specific CSS rules will be enabled. 
     231         * Sets the <code>class</code> attribute to be used on the <code>body</code> element 
     232         * of the editing area. This can be useful when you intend to reuse the original CSS 
     233         * file you are using on your live website and want to assign the editor the same class 
     234         * as the section that will include the contents. In this way class-specific CSS rules will 
     235         * be enabled.  
    230236         * @since 3.1 
    231237         * @type String 
    232          * @default '' (empty) 
     238         * @default <code>''</code> (empty) 
    233239         * @example 
    234240         * config.bodyClass = 'contents'; 
    … …  
    237243 
    238244        /** 
    239          * Indicates whether the contents to be edited are being inputted as a full 
    240          * HTML page. A full page includes the &lt;html&gt;, &lt;head&gt; and 
    241          * &lt;body&gt; tags. The final output will also reflect this setting, 
    242          * including the &lt;body&gt; contents only if this setting is disabled. 
     245         * Indicates whether the contents to be edited are being input as a full 
     246         * HTML page. A full page includes the <code>&lt;html&gt;</code>, 
     247         * <code>&lt;head&gt;</code>, and <code>&lt;body&gt;</code> elements. 
     248         * The final output will also reflect this setting, including the 
     249         * <code>&lt;body&gt;</code> contents only if this setting is disabled. 
    243250         * @since 3.1 
    244251         * @type Boolean 
    245          * @default false 
     252         * @default <code>false</code> 
    246253         * @example 
    247254         * config.fullPage = true; 
    … …  
    250257 
    251258        /** 
    252          * The height of editing area( content ), in relative or absolute, e.g. 30px, 5em. 
    253          * Note: Percentage unit is not supported yet. e.g. 30%. 
     259         * The height of the editing area (that includes the editor content), 
     260         * in relative or absolute units, e.g. <code>30px</code>, <code>5em</code>. 
     261         * <strong>Note:</strong> Percentage units, like <code>30%</code>, are not supported yet. 
    254262         * @type Number|String 
    255          * @default '200' 
     263         * @default <code>'200'</code> 
    256264         * @example 
    257265         * config.height = 500; 
    … …  
    262270 
    263271        /** 
    264          * Comma separated list of plugins to load and initialize for an editor 
    265          * instance. This should be rarely changed, using instead the 
    266          * {@link CKEDITOR.config.extraPlugins} and 
    267          * {@link CKEDITOR.config.removePlugins} for customizations. 
     272         * Comma separated list of plugins to be loaded and initialized for an editor 
     273         * instance. This setting should rarely be changed. It is recommended to use the 
     274         * <code>{@link CKEDITOR.config.extraPlugins}</code> and 
     275         * <code>{@link CKEDITOR.config.removePlugins}</code> for customization purposes instead. 
    268276         * @type String 
    269277         * @example 
    … …  
    329337 
    330338        /** 
    331          * List of additional plugins to be loaded. This is a tool setting which 
    332          * makes it easier to add new plugins, whithout having to touch and 
    333          * possibly breaking the {@link CKEDITOR.config.plugins} setting. 
     339         * A list of additional plugins to be loaded. This setting makes it easier 
     340         * to add new plugins without having to touch and potentially break the 
     341         * <code>{@link CKEDITOR.config.plugins}</code> setting. 
    334342         * @type String 
    335343         * @example 
    … …  
    339347 
    340348        /** 
    341          * List of plugins that must not be loaded. This is a tool setting which 
    342          * makes it easier to avoid loading plugins definied in the 
    343          * {@link CKEDITOR.config.plugins} setting, whithout having to touch it and 
    344          * potentially breaking it. 
     349         * A list of plugins that must not be loaded. This setting makes it possible 
     350         * to avoid loading some plugins defined in the <code>{@link CKEDITOR.config.plugins}</code> 
     351         * setting, without having to touch it and potentially break it. 
    345352         * @type String 
    346353         * @example 
    … …  
    350357 
    351358        /** 
    352          * List of regular expressions to be executed over the input HTML, 
    353          * indicating HTML source code that matched must <strong>not</strong> present in WYSIWYG mode for editing. 
     359         * List of regular expressions to be executed on input HTML, 
     360         * indicating HTML source code that when matched, must <strong>not</strong> be available in the WYSIWYG 
     361         * mode for editing. 
    354362         * @type Array 
    355          * @default [] (empty array) 
    356          * @example 
    357          * config.protectedSource.push( /<\?[\s\S]*?\?>/g );   // PHP Code 
    358          * config.protectedSource.push( /<%[\s\S]*?%>/g );   // ASP Code 
    359          * config.protectedSource.push( /(<asp:[^\>]+>[\s|\S]*?<\/asp:[^\>]+>)|(<asp:[^\>]+\/>)/gi );   // ASP.Net Code 
     363         * @default <code>[]</code> (empty array) 
     364         * @example 
     365         * config.protectedSource.push( /<\?[\s\S]*?\?>/g );   // PHP code 
     366         * config.protectedSource.push( /<%[\s\S]*?%>/g );   // ASP code 
     367         * config.protectedSource.push( /(<asp:[^\>]+>[\s|\S]*?<\/asp:[^\>]+>)|(<asp:[^\>]+\/>)/gi );   // ASP.Net code 
    360368         */ 
    361369        protectedSource : [], 
    362370 
    363371        /** 
    364          * The editor tabindex value. 
     372         * The editor <code>tabindex</code> value. 
    365373         * @type Number 
    366          * @default 0 (zero) 
     374         * @default <code>0</code> (zero) 
    367375         * @example 
    368376         * config.tabIndex = 1; 
    … …  
    371379 
    372380        /** 
    373          * The theme to be used to build the UI. 
    374          * @type String 
    375          * @default 'default' 
     381         * The theme to be used to build the user interface. 
     382         * @type String 
     383         * @default <code>'default'</code> 
    376384         * @see CKEDITOR.config.skin 
    377385         * @example 
    … …  
    384392         * editor installation path, or the name and the path separated by a comma. 
    385393         * @type String 
    386          * @default 'default' 
     394         * @default <code>'default'</code> 
    387395         * @example 
    388396         * config.skin = 'v2'; 
    … …  
    393401 
    394402        /** 
    395          * The editor width in CSS size format or pixel integer. 
     403         * The editor width in CSS-defined units or an integer denoting a value in pixels. 
    396404         * @type String|Number 
    397          * @default '' (empty) 
     405         * @default <code>''</code> (empty) 
    398406         * @example 
    399407         * config.width = 850; 
    … …  
    404412 
    405413        /** 
    406          * The base Z-index for floating dialogs and popups. 
     414         * The base Z-index for floating dialog windows and popups. 
    407415         * @type Number 
    408          * @default 10000 
     416         * @default <code>10000</code> 
    409417         * @example 
    410418         * config.baseFloatZIndex = 2000 
    … …  
    415423/** 
    416424 * Indicates that some of the editor features, like alignment and text 
    417  * direction, should used the "computed value" of the feature to indicate it's 
    418  * on/off state, instead of using the "real value".<br /> 
     425 * direction, should use the "computed value" of the feature to indicate its 
     426 * on/off state instead of using the "real value".<br /> 
    419427 * <br /> 
    420  * If enabled, in a left to right written document, the "Left Justify" 
    421  * alignment button will show as active, even if the aligment style is not 
     428 * If enabled in a Left-To-Right written document, the "Left Justify" 
     429 * alignment button will be shown as active, even if the alignment style is not 
    422430 * explicitly applied to the current paragraph in the editor. 
    423431 * @name CKEDITOR.config.useComputedState 
    424432 * @type Boolean 
    425  * @default true 
     433 * @default <code>true</code> 
    426434 * @since 3.4 
    427435 * @example 
Note: See TracChangeset for help on using the changeset viewer.
© 2003 – 2012 CKSource – Frederico Knabben. All rights reserved. | Terms of use | Privacy policy