Changeset 7107


Ignore:
Timestamp:
07/15/11 17:26:43 (4 years 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 – 2015 CKSource – Frederico Knabben. All rights reserved. | Terms of use | Privacy policy