Skip to content

Commit

Permalink
Merge pull request #1 from Reinmar/docs-refinements
Browse files Browse the repository at this point in the history 
Docs refinements.
  • Loading branch information
@Reinmar
Reinmar committed Aug 22, 2012
2 parents 7582477 + 05594ec commit e193731
Show file tree
Hide file tree
Showing 4 changed files with 108 additions and 73 deletions.
112 changes: 51 additions & 61 deletions API-CHANGES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,23 @@ Changes not included here are instead pending analysis and v3 porting.
Change Entries
---

`CKEDITOR.event::fire` now returns `"false"` if the event has been canceled
(in v3 it returns `"true"`).
`CKEDITOR.event#fire` now returns `false` if the event has been canceled
(in v3 it returns `true`).

The listener function sent to `CKEDITOR.event::on` can now return the boolean
`"false"` to cancel the event.
The listener function sent to `CKEDITOR.event#on` can now return the boolean
`false` to cancel the event.

---

`CKEDITOR.config.corePlugins` is not any more needed, the "core plugins" in v3
are now really part of the core, with their provided API namespaces remained:

* plugins/selection/plugin.js => core/selection.js, the "select all" feature
originally provided by the selection plugin is now a standalone "selectall" plugin.
* plugins/styles/plugin.js => core/style.js
* plugins/styles/styles/default.js => core/styles.js
* plugins/domiterator/plugin.js => core/dom/iterator.js
* plugins/htmldataprocessor/plugin.js => core/htmldataprocessor.js
* `plugins/selection/plugin.js` => `core/selection.js`, the "select all" feature
originally provided by the `selection` plugin is now a standalone `selectall` plugin.
* `plugins/styles/plugin.js` => `core/style.js`
* `plugins/styles/styles/default.js` => `core/styles.js`
* `plugins/domiterator/plugin.js` => `core/dom/iterator.js`
* `plugins/htmldataprocessor/plugin.js` => `core/htmldataprocessor.js`

---

Expand All @@ -37,16 +37,16 @@ the same skin).
Because of the above, the following skin related properties have been moved global or deleted:

* `CKEDITOR.skins` => `CKEDITOR.skin`
* `CKEDITOR.skins.add` => **deprecated**
* `CKEDITOR.skins.add` => **removed**
* `CKEDITOR.skins.load( editor, partName, callback )` => `CKEDITOR.skin.loadPart( partName, callback )`
* `CKEDITOR.editor::skinName` => `CKEDITOR.skin.name`
* `CKEDITOR.editor::skinPath` => `CKEDITOR.skin.getPath( 'editor' )`
* `CKEDITOR.editor::skinClass` => **deprecated**
* `CKEDITOR.editor#skinName` => `CKEDITOR.skin.name`
* `CKEDITOR.editor#skinPath` => `CKEDITOR.skin.getPath( 'editor' )`
* `CKEDITOR.editor#skinClass` => **removed**

The skin definition file (skin.js) has been simplified in the following sense:
The skin definition file (`skin.js`) has been simplified in the following sense:

* No longer specify the stylesheet file for skin part, now editor will expect CSS
file name same as the part name, e.g. "dialog" part will be requiring the dialog.css file in skin directory.
file name same as the part name, e.g. `dialog` part will be requiring the `dialog.css` file in skin directory.
* No longer define theme related properties, e.g. dialog margins, combo grouping.

The "theme" concept is removed, the DOM structure of editor is now defined by creators or plugins individually,
Expand All @@ -56,21 +56,21 @@ The shared space feature provided by v3 theme is now **deprecated**, in favor of

---

`CKEDITOR.editor::setMode` and `CKEDITOR.editor::getMode` are feature provided by the themedui creator only,
which is not available in instance created by the inline creator, where `CKEDITOR.editor::mode` property will be always "wysiwyg".
`CKEDITOR.editor#setMode` and `CKEDITOR.editor#getMode` are feature provided by the themedui creator only,
which is not available in instance created by the inline creator, where `CKEDITOR.editor#mode` property will be always `'wysiwyg'`.

`CKEDITOR.config.editingBlock` has been removed, being the "editingBlock" renewed as "editable".
`CKEDITOR.config.editingBlock` has been removed, being the `editingBlock` renewed as `editable`.

---

`CKEDITOR.focusManager` is now managing the overall "active" state of the entire editor
instead of just the editing block, so all editor UI parts (toolbar, dialog, panel)
that receive DOM focus will turn `CKEDITOR.focusManager::hasFocus` true.
that receive DOM focus will turn `CKEDITOR.focusManager#hasFocus` true.

Because of above, now `CKEDITOR.editable::hasFocus` should be used instead for `CKEDITOR.focusManager::hasFocus`,
Because of above, now `CKEDITOR.editable#hasFocus` should be used instead for `CKEDITOR.focusManager#hasFocus`,
to check the focus state of editing block.

The `CKEDITOR.focusManager::forceBlur` method has been removed.
The `CKEDITOR.focusManager#forceBlur` method has been removed.

---

Expand All @@ -79,7 +79,7 @@ custom toolbar layout can be managed easier with `CKEDITOR.config.toolbarGroups`

---

The "additional CSS" feature provided by `CKEDITOR.editor::addCss` is now moved
The "additional CSS" feature provided by `CKEDITOR.editor#addCss` is now moved
to a global `CKEDITOR.addCss`, with specified style rules applies **document wide**.

Thus the proper way for a plugin to style it's editable content is to call `CKEDITOR.addCss`
Expand All @@ -90,10 +90,10 @@ inside of the plugin's `onLoad` function, rather than it's `init` function in v3
`CKEDITOR.env.version` now reflects the "document mode" in **IE** browsers,
**deprecated** the following properties:

* `CKEDITOR.ie6Compat`
* `CKEDITOR.ie7Compat`
* `CKEDITOR.ie8Compat`
* `CKEDITOR.ie9Compat`
* `CKEDITOR.env.ie6Compat`
* `CKEDITOR.env.ie7Compat`
* `CKEDITOR.env.ie8Compat`
* `CKEDITOR.env.ie9Compat`

If we'd check for old IEs before IE9, instead of checking for each the above properties in v3

Expand All @@ -105,71 +105,68 @@ We should check in the following simpler way in v4:

---

On plugin language files, the usual CKEDITOR.plugins.setLang call now enforces
a namespace in the format editor.lang.pluginName, which contains the provided
On plugin language files, the usual `CKEDITOR.plugins.setLang` call now enforces
a namespace in the format `editor.lang.pluginName`, which contains the provided
language entries.

So, in v3 we had:

CKEDITOR.plugins.setLang( 'myplugin', 'en',
{
myplugin :
{
title : 'My Plugin'
CKEDITOR.plugins.setLang( 'myplugin', 'en', {
myplugin: {
title: 'My Plugin'
}
});
} );

In v4 it should be changed to:

CKEDITOR.plugins.setLang( 'myplugin', 'en',
{
title : 'My Plugin'
});
CKEDITOR.plugins.setLang( 'myplugin', 'en', {
title: 'My Plugin'
} );

In this way the entry will be available at editor.lang.myplugin.title.
In this way the entry will be available at `editor.lang.myplugin.title`.

---

Constructor `CKEDITOR.editor` now receives two additional optional params (besides of the configuration object),
to simplify creator implementation:

CKEDITOR.editor( config,
/** @type {CKEDITOR.dom.element} */ element,
/** @type {Number} */ elementMode );
/** @type {CKEDITOR.dom.element} */ element,
/** @type {Number} */ elementMode );

---

CKEDITOR creators ( `CKEDITOR.replace`, `CKEDITOR.replace` and `CKEDITOR.appendTo` )
are not anymore available within ckeditor_basic.js, which are now provided by core/creators/themedui.js.
CKEDITOR creators (`CKEDITOR.replace`, `CKEDITOR.replace` and `CKEDITOR.appendTo`)
are not anymore available within `ckeditor_basic.js`, which are now provided by `core/creators/themedui.js`.


---

The `iconOffset` property, used in button definitions, must now point to the
exact offset position of the image in the icon file, instead of its logical order.

For example, in v3 its value could be set to "2". Now, in that same case,
it should be set to "-32" (2 x -16).
For example, in v3 its value could be set to `2`. Now, in that same case,
it should be set to `-32 (2 x -16)`.

---

The default value for `CKEDITOR.config.toolbarCanCollapse` has been changed to "false".
The default value for `CKEDITOR.config.toolbarCanCollapse` has been changed to `false`.

---

The default value for `CKEDITOR.config.docType` is now `"<!DOCTYPE html>"`,
The default value for `CKEDITOR.config.docType` is now `'<!DOCTYPE html>'`,
the HTML5 doctype.

---

Method `CKEDITOR.editor::getThemeSpace` has been moved to `CKEDITOR.editor::space`.
Method `CKEDITOR.editor#getThemeSpace` has been moved to `CKEDITOR.editor#space`.

Event `CKEDITOR.editor#themeSpace` event has been replaced with "CKEDITOR.editor#uiSpace".
Event `CKEDITOR.editor#themeSpace` event has been replaced with `CKEDITOR.editor#uiSpace`.

---

Method `CKEDITOR.htmlParser.fragment.fromHtml( fragmentHtml, fixForBody, /** @type {CKEDITOR.htmlParser.element}*/ contextNode )`
has changed signature to `CKEDITOR.htmlParser.fragment.fromHtml( fragmentHtml, /** @type {CKEDITOR.htmlParser.element|String}*/ parent, fixForBody )`.
Method `CKEDITOR.htmlParser.fragment.fromHtml( fragmentHtml, fixForBody, /** @type {CKEDITOR.htmlParser.element} */ contextNode )`
has changed signature to `CKEDITOR.htmlParser.fragment.fromHtml( fragmentHtml, /** @type {CKEDITOR.htmlParser.element/String} */ parent, fixForBody )`.

---

Expand All @@ -183,13 +180,6 @@ They have been replaced by `evt.data.dataValue` and `evt.data.type` to help iden

---

`CKEDITOR.dtd.$captionBlock` is now removed, to check if one element can be appear inside of table caption, use instead the dtd check:

assert.isTrue( !!CKEDITOR.dtd.caption[ element.getName() ] );






`CKEDITOR.dtd.$captionBlock` is now removed, to check if one element can be appear inside of table caption, use instead the DTD check:

assert.isTrue( !!CKEDITOR.dtd.caption[ element.getName() ] );
31 changes: 19 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,41 @@ CKEditor 4 – The best browser-based WYSIWYG editor

This repository contains the development version of CKEditor.

**Attention:** The code in this repository should be used locally, for development purposes only. We don’t recommend distributing it on remote websites because the user experience will be very limited. For that purpose, you should build it (see bellow) or use an official release instead, available in the [CKEditor website](http://ckeditor.com).
**Attention:** The code in this repository should be used locally, for development purposes only.
We don’t recommend distributing it on remote websites because the user experience will be very limited.
For that purpose, you should build it (see bellow) or use an official release instead,
available in the [CKEditor website](http://ckeditor.com).

### Code Installation

There is no special installation procedure to install the development code. Simply clone it on any local directory and you’re set.
There is no special installation procedure to install the development code.
Simply clone it on any local directory and you’re set.

### Samples

The **“samples”** folder contains a good set of examples that can be used to test your installation as well as being a precious resource for learning some aspects of the CKEditor JavaScript API and its integration on web pages.
The `samples/` folder contains a good set of examples that can be used
to test your installation as well as being a precious resource for learning
some aspects of the CKEditor JavaScript API and its integration on web pages.

### Code Structure

The development code contains the following main elements:

- Main coding folders:
- “core”: the core API of CKEditor. Alone, it does nothing, but it provides the entire JavaScript API that makes the magic happen.
- “plugins”: contains most of the plugins maintained by the CKEditor core team.
- “skin”: contains the official default skin of CKEditor.
- “dev”: contains “developer tools”.
- Main coding folders:
- `core/`: the core API of CKEditor. Alone, it does nothing, but
it provides the entire JavaScript API that makes the magic happen.
- `plugins/`: contains most of the plugins maintained by the CKEditor core team.
- `skin/`: contains the official default skin of CKEditor.
- `dev/`: contains “developer tools”.

### Building a Release

A release optimized version of the development code can be easily created locally. The “dev/builder/builder.sh” script can be used for that purpose:
A release optimized version of the development code can be easily created locally.
The `dev/builder/builder.sh` script can be used for that purpose:

> cd dev/builder
> builder.sh
> ./dev/builder/builder.sh

A “release ready” version of you development code working copy will be built in the new **“release”** folder.
A “release ready” version of you development code working copy will be built in the new `dev/builder/release/` folder.
Internet connection is necessary to run the builder, for its first time at least.

### License
Expand Down
31 changes: 31 additions & 0 deletions core/env.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,37 @@ if ( !CKEDITOR.env ) {
env.ie8Compat = version == 8;
env.ie7Compat = version == 7;
env.ie6Compat = version < 7 || env.quirks;

/**
* Indicates that CKEditor is running on an IE6-like environment, which
* includes IE6 itself and IE7 and IE8 quirks mode.
*
* @deprecated
* @property {Boolean} ie6Compat
*/

/**
* Indicates that CKEditor is running on an IE7-like environment, which
* includes IE7 itself and IE8's IE7 document mode.
*
* @deprecated
* @property {Boolean} ie7Compat
*/

/**
* Indicates that CKEditor is running on Internet Explorer 8 on
* standards mode.
*
* @deprecated
* @property {Boolean} ie8Compat
*/

/**
* Indicates that CKEditor is running on Internet Explorer 9's standards mode.
*
* @deprecated
* @property {Boolean} ie9Compat
*/
}

// Gecko.
Expand Down
7 changes: 7 additions & 0 deletions core/skin.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,13 @@
* @todo type?
*/

/**
* Current skin name.
*
* @property {String} name
* @todo
*/

/**
* The editor skin name. Note that is is not possible to have editors with
* different skin settings in the same page. In such case, just one of the
Expand Down

0 comments on commit e193731

Please sign in to comment.