_source/core/config.js

   1 /*
   2 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
   3 For licensing, see LICENSE.html or http://ckeditor.com/license
   4 */
   5
   6 /**
   7  * @fileOverview Defines the {@link CKEDITOR.config} object, which holds the
   8  * default configuration settings.
   9  */
  10
  11 /**
  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.
  15  * @constant
  16  */
  17 CKEDITOR.ENTER_P        = 1;
  18
  19 /**
  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.
  23  * @constant
  24  */
  25 CKEDITOR.ENTER_BR       = 2;
  26
  27 /**
  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.
  31  * @constant
  32  */
  33 CKEDITOR.ENTER_DIV      = 3;
  34
  35 /**
  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  */
  40 CKEDITOR.config =
  41 {
  42         /**
  43          * The URL path for the custom configuration file to be loaded. If not
  44          * overloaded with inline configurations, it defaults to the "config.js"
  45          * file present in the root of the CKEditor installation directory.<br /><br />
  46          *
  47          * CKEditor will recursively load custom configuration files defined inside
  48          * other custom configuration files.
  49          * @type String
  50          * @default '&lt;CKEditor folder&gt;/config.js'
  51          * @example
  52          * // Load a specific configuration file.
  53          * CKEDITOR.replace( 'myfiled', { customConfig : '/myconfig.js' } );
  54          * @example
  55          * // Do not load any custom configuration file.
  56          * CKEDITOR.replace( 'myfiled', { customConfig : '' } );
  57          */
  58         customConfig : 'config.js',
  59
  60         /**
  61          * Whether the replaced element (usually a textarea) is to be updated
  62          * automatically when posting the form containing the editor.
  63          * @type Boolean
  64          * @default true
  65          * @example
  66          * config.autoUpdateElement = true;
  67          */
  68         autoUpdateElement : true,
  69
  70         /**
  71          * The base href URL used to resolve relative and absolute URLs in the
  72          * editor content.
  73          * @type String
  74          * @default '' (empty)
  75          * @example
  76          * config.baseHref = 'http://www.example.com/path/';
  77          */
  78         baseHref : '',
  79
  80         /**
  81          * The CSS file(s) to be used to apply style to the contents. It should
  82          * reflect the CSS used in the final pages where the contents are to be
  83          * used.
  84          * @type String|Array
  85          * @default '&lt;CKEditor folder&gt;/contents.css'
  86          * @example
  87          * config.contentsCss = '/css/mysitestyles.css';
  88          * config.contentsCss = ['/css/mysitestyles.css', '/css/anotherfile.css'];
  89          */
  90         contentsCss : CKEDITOR.basePath + 'contents.css',
  91
  92         /**
  93          * The writting direction of the language used to write the editor
  94          * contents. Allowed values are:
  95          * <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          * </ul>
 100          * @default 'ui'
 101          * @type String
 102          * @example
 103          * config.contentsLangDirection = 'rtl';
 104          */
 105         contentsLangDirection : 'ui',
 106
 107         /**
 108          * Language code of  the writting language which is used to author the editor
 109          * contents.
 110          * @default Same value with editor's UI language.
 111          * @type String
 112          * @example
 113          * config.contentsLanguage = 'fr';
 114          */
 115         contentsLanguage : '',
 116
 117         /**
 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)
 122          * @type String
 123          * @example
 124          * // Load the German interface.
 125          * config.language = 'de';
 126          */
 127         language : '',
 128
 129         /**
 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'
 133          * @type String
 134          * @example
 135          * config.defaultLanguage = 'it';
 136          */
 137         defaultLanguage : 'en',
 138
 139         /**
 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
 142          * as a paragraph separator when indenting text.
 143          * The allowed values are the following constants, and their relative
 144          * behavior:
 145          * <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          * </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          * @type Number
 154          * @default {@link CKEDITOR.ENTER_P}
 155          * @example
 156          * // Not recommended.
 157          * config.enterMode = CKEDITOR.ENTER_BR;
 158          */
 159         enterMode : CKEDITOR.ENTER_P,
 160
 161         /**
 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          * @since 3.2.1
 166          * @default false
 167          * @example
 168          * // Not recommended.
 169          * config.forceEnterMode = true;
 170          */
 171         forceEnterMode : false,
 172
 173         /**
 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:
 177          * <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>
 181          * </ul>
 182          * @type Number
 183          * @default {@link CKEDITOR.ENTER_BR}
 184          * @example
 185          * config.shiftEnterMode = CKEDITOR.ENTER_P;
 186          */
 187         shiftEnterMode : CKEDITOR.ENTER_BR,
 188
 189         /**
 190          * 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 />
 192          *
 193          * There are no ways to override this setting, except by editing the source
 194          * code of CKEditor (_source/core/config.js).
 195          * @type String
 196          * @example
 197          */
 198         corePlugins : '',
 199
 200         /**
 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.
 206          * config.docType = '&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"&gt;';
 207          */
 208         docType : '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
 209
 210         /**
 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.
 216          * @since 3.1
 217          * @type String
 218          * @default '' (empty)
 219          * @example
 220          * config.bodyId = 'contents_id';
 221          */
 222         bodyId : '',
 223
 224         /**
 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.
 230          * @since 3.1
 231          * @type String
 232          * @default '' (empty)
 233          * @example
 234          * config.bodyClass = 'contents';
 235          */
 236         bodyClass : '',
 237
 238         /**
 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.
 243          * @since 3.1
 244          * @type Boolean
 245          * @default false
 246          * @example
 247          * config.fullPage = true;
 248          */
 249         fullPage : false,
 250
 251         /**
 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%.
 254          * @type Number|String
 255          * @default '200'
 256          * @example
 257          * config.height = 500;
 258          * config.height = '25em';
 259          * config.height = '300px';
 260          */
 261         height : 200,
 262
 263         /**
 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.
 268          * @type String
 269          * @example
 270          */
 271         plugins :
 272                 'about,' +
 273                 'a11yhelp,' +
 274                 'basicstyles,' +
 275                 'bidi,' +
 276                 'blockquote,' +
 277                 'button,' +
 278                 'clipboard,' +
 279                 'colorbutton,' +
 280                 'colordialog,' +
 281                 'contextmenu,' +
 282                 'dialogadvtab,' +
 283                 'div,' +
 284                 'elementspath,' +
 285                 'enterkey,' +
 286                 'entities,' +
 287                 'filebrowser,' +
 288                 'find,' +
 289                 'flash,' +
 290                 'font,' +
 291                 'format,' +
 292                 'forms,' +
 293                 'horizontalrule,' +
 294                 'htmldataprocessor,' +
 295                 'iframe,' +
 296                 'image,' +
 297                 'indent,' +
 298                 'justify,' +
 299                 'keystrokes,' +
 300                 'link,' +
 301                 'list,' +
 302                 'liststyle,' +
 303                 'maximize,' +
 304                 'newpage,' +
 305                 'pagebreak,' +
 306                 'pastefromword,' +
 307                 'pastetext,' +
 308                 'popup,' +
 309                 'preview,' +
 310                 'print,' +
 311                 'removeformat,' +
 312                 'resize,' +
 313                 'save,' +
 314                 'scayt,' +
 315                 'smiley,' +
 316                 'showblocks,' +
 317                 'showborders,' +
 318                 'sourcearea,' +
 319                 'stylescombo,' +
 320                 'table,' +
 321                 'tabletools,' +
 322                 'specialchar,' +
 323                 'tab,' +
 324                 'templates,' +
 325                 'toolbar,' +
 326                 'undo,' +
 327                 'wysiwygarea,' +
 328                 'wsc',
 329
 330         /**
 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.
 334          * @type String
 335          * @example
 336          * config.extraPlugins = 'myplugin,anotherplugin';
 337          */
 338         extraPlugins : '',
 339
 340         /**
 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.
 345          * @type String
 346          * @example
 347          * config.removePlugins = 'elementspath,save,font';
 348          */
 349         removePlugins : '',
 350
 351         /**
 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.
 354          * @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
 360          */
 361         protectedSource : [],
 362
 363         /**
 364          * The editor tabindex value.
 365          * @type Number
 366          * @default 0 (zero)
 367          * @example
 368          * config.tabIndex = 1;
 369          */
 370         tabIndex : 0,
 371
 372         /**
 373          * The theme to be used to build the UI.
 374          * @type String
 375          * @default 'default'
 376          * @see CKEDITOR.config.skin
 377          * @example
 378          * config.theme = 'default';
 379          */
 380         theme : 'default',
 381
 382         /**
 383          * The skin to load. It may be the name of the skin folder inside the
 384          * editor installation path, or the name and the path separated by a comma.
 385          * @type String
 386          * @default 'default'
 387          * @example
 388          * config.skin = 'v2';
 389          * @example
 390          * config.skin = 'myskin,/customstuff/myskin/';
 391          */
 392         skin : 'kama',
 393
 394         /**
 395          * The editor width in CSS size format or pixel integer.
 396          * @type String|Number
 397          * @default '' (empty)
 398          * @example
 399          * config.width = 850;
 400          * @example
 401          * config.width = '75%';
 402          */
 403         width : '',
 404
 405         /**
 406          * The base Z-index for floating dialogs and popups.
 407          * @type Number
 408          * @default 10000
 409          * @example
 410          * config.baseFloatZIndex = 2000
 411          */
 412         baseFloatZIndex : 10000
 413 };
 414
 415 /**
 416  * 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 />
 419  * <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
 422  * explicitly applied to the current paragraph in the editor.
 423  * @name CKEDITOR.config.useComputedState
 424  * @type Boolean
 425  * @default true
 426  * @since 3.4
 427  * @example
 428  * config.useComputedState = false;
 429  */
 430
 431 // PACKAGER_RENAME( CKEDITOR.config )