V3: Configurations

[Frederico Caldeira Knabben]

In the CKEditor prototype, the CKEDITOR.config object holds all configurations (core/config.js). It means that the default settings will be included in the core code, not anymore in an external file. It will also mean that we'll be able to fully document each setting in the code.

Also, not all settings are defined in that file. Each plugin that has custom configurations can extend this object to its needs. See "plugins/toolbar" for an example.

When creating an editor instance, the <instance>.config property is created. It is an empty object, which prototype is CKEDITOR.config. It means that additions to CKEDITOR.config will be automatically propagated to all editor instances, still making it possible to override them with custom settings for each instance.

Then, for each instance, the <instance>.config.customConfig setting is checked. If defined, the external file is downloaded. That file must define the CKEDITOR.editorConfig function, which overrides configurations in the editor instance. By default, the editor is configured to download the config.js, from the root of the distribution.

Once the custom configuration file is downloaded, its CKEDITOR.editorConfig function is "cached". If other editor instances use the same file, it will not be downloaded anymore, and the cached function will be used.

Then, the <instance>.config.customConfig is checked again. The above process repeats until no more configuration files are to be downloaded.

There are two ways to avoid loading external configuration files. The "core/config.js" file can be edited, setting customConfig to '' (empty). The core code must be packed again at this point. Or, when creating the editor instance, the customConfig configuration can be set to '' (empty) for the instance. This is the only inline setting that is considered beforehand.

Finally, once all external files are downloaded, overriding the global settings, the inline settings are merged into the <instance>.config object, overriding any of the previous settings.

To summarize:

1. <instance>.config is created from CKEDITOR.config.
2. If the inline setting for customConfig is defined, it overrides <instance>.config.customConfig.
3. The external configuration files are loaded, overriding settings in <instance>.config.
4. The inline settings override settings in <instance>.config.