Skip to content

Commit

Permalink
Merge stable into master
Browse files Browse the repository at this point in the history
  • Loading branch information
@CKTravisBot
CKTravisBot authored Aug 16, 2023
2 parents cc319ca + 8a6768c commit 94a9771
Show file tree
Hide file tree
Showing 11 changed files with 701 additions and 397 deletions.
403 changes: 403 additions & 0 deletions docs/examples/how-tos.md
View file

Large diffs are not rendered by default.

8 changes: 8 additions & 0 deletions docs/features/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,14 @@ Each rich-text editor feature is presented on a separate page, with one or more
**In most feature demos the number of features enabled is limited** to make the currently highlighted piece of functionality stand out more, as shown in the screenshots above. However, in your CKEditor 5 WYSIWYG editor implementation, you are free to choose and combine any features you like from those available. This can be easily and conveniently done in the [CKEditor 5 online builder](https://ckeditor.com/ckeditor-5/online-builder/).
</info-box>

## Why does the editor filter out my content (styles, classes, elements)?

CKEditor 5 implements a custom {@link framework/architecture/editing-engine data model}. This means that every piece of content that is loaded into the editor needs to be converted to that model and then rendered back to the view.

Each kind of content must be handled by some feature. For example, the [`ckeditor5-basic-styles`](https://www.npmjs.com/package/@ckeditor/ckeditor5-basic-styles) package handles HTML elements such as `<b>`, `<i>`, `<u>`, etc. along with their representation in the model. The feature defines the two–way conversion between the HTML (view) and the editor model.

If you load some content unknown to any editor feature, it will be dropped. If you want all the HTML5 elements to be supported, you need to write plugins to support them or use {@link features/general-html-support general HTML support} feature. Once you do that, CKEditor 5 will not filter anything out.

## Looking for more?

The examples mentioned above do not present all features included in CKEditor&nbsp;5, nor does the list on the left panel. For example, some end-user features like undo and redo are quite self-explanatory and therefore only mentioned in the keyboard shortcuts guide.
Expand Down
76 changes: 76 additions & 0 deletions docs/installation/getting-started/api-and-events.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
category: getting-started
order: 80
---

# API and events

<info-box hint>
**Quick recap**

In the {@link installation/getting-started/getting-and-setting-data previous guide} you have learned how to set and get data from the editor. You can also start using the editor's API and events.
</info-box>

CKEditor 5 and its plugins expose structured API and Events that are allowing to interact with an editor and to react to changes.

## Using the API

The API allows you to do multiple things with the editor and its content:

```js
editor.model.change( writer => {
// Move selection to the end of the document.
writer.setSelection(
writer.createPositionAt( editor.model.document.getRoot(), 'end' )
);

// Execute the enter command.
editor.execute( 'enter' );

// Insert text.
editor.model.change( writer => {
editor.model.insertContent( writer.createText( 'The End!' ) );
} );
} );
```

In the example above, you use a selection, a command, and you change the content using the editor's model. All of this could be reverted with one undo step. This is a simple example of what the API can do.

Check more {@link examples/how-tos#editors-api examples how to use the API}.

## Using events

The editor's instance can also be used to set up listeners for events. Every plugin in the editor publishes events that you can subscribe to and interact with. For example, the {@link module:engine/model/document~Document#event:change:data `Document#change:data`} event is fired when the document changes in such a way that is "visible" in the editor data:

```js
editor.model.document.on( 'change:data', () => {
console.log( 'The data has changed!' );
} );
```

Events could be used to alter the behavior of the editor. Imagine a user wants to swap the <kbd>Enter</kbd> with the <kbd>Shift</kbd> + <kbd>Enter</kbd>, so <kbd>Shift</kbd> + <kbd>Enter</kbd> will insert a new block, while <kbd>Enter</kbd> will insert a `<br>`.

```js
editor.editing.view.document.on( 'enter', ( evt, data ) => {
data.preventDefault();
evt.stop();

if ( data.isSoft ) {
editor.execute( 'enter' );
editor.editing.view.scrollToTheSelection();

return;
}

editor.execute( 'shiftEnter' );
editor.editing.view.scrollToTheSelection();
}, { priority: 'high' } );
```

You can find more information about events in {@link framework/architecture/core-editor-architecture#event-system-and-observables the framework documentation}.

<info-box hint>
**What's next?**

Having explored the API and events, it's time to take the next step: {@link installation/getting-started/extending-features extend your editor's features}.
</info-box>
119 changes: 34 additions & 85 deletions docs/installation/getting-started/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ order: 40
<info-box hint>
**Quick recap**

In the {@link installation/getting-started/quick-start-other previous tutorial} you have learned about various ways for setting up CKEditor&nbsp;5 in the project. Now, you know how to use online builder or create the editor from source. It is time to play a bit with the configuration!
In the {@link installation/getting-started/quick-start-other previous guide} you have learned about various ways for setting up CKEditor 5 in the project. Now, you know how to use the online builder or create the editor from the source. It is time to play a bit with the configuration!
</info-box>

When creating an editor in your page, it is possible to set up {@link module:core/editor/editorconfig~EditorConfig configurations} that change many of its aspects. For example:
When creating an editor on your page, it is possible to set up {@link module:core/editor/editorconfig~EditorConfig configurations} that change many of its aspects. For example:

```js
ClassicEditor
Expand All @@ -37,9 +37,35 @@ ClassicEditor

As you can see, the configuration is set by a simple JavaScript object passed to the `create()` method.

See {@link module:core/editor/editorconfig~EditorConfig} to learn about all available configuration options.

Some of the options may require loading plugins that are not available in the build you use. Return to the {@link installation/getting-started/quick-start-other Customized installation} guide for instructions on creating a custom build.

## Toolbar setup

In the builds that contain toolbars, an optimal default configuration is defined for it. You may need a different toolbar arrangement, though, and this can be achieved through configuration. Check the detailed {@link features/toolbar toolbar feature guide} for the available options.

When you create a {@link installation/getting-started/quick-start-other#creating-custom-builds-with-online-builder custom build using CKEditor 5 online builder}, setting up your toolbar configuration is one of the steps in the build creation process that uses an intuitive drag and drop interface.

## Adding features

All the features of CKEditor 5 all implemented by plugins. {@link installation/plugins/plugins Read more about the plugin concept.}

### List of plugins

Each build has some plugins available. You can easily list all plugins available in your build:

```js
ClassicEditor.builtinPlugins.map( plugin => plugin.pluginName );
```

### Installing plugins

Predefined CKEditor 5 builds do not include all possible features. To add more features you can {@link installation/plugins/installing-plugins install plugins} to custom builds and to editors integrated from the source.

## Removing features

The {@link installation/getting-started/predefined-builds predefined CKEditor&nbsp;5 builds} come with all the features included in the distribution package enabled by default. They are defined as plugins for CKEditor&nbsp;5.
The {@link installation/getting-started/predefined-builds predefined CKEditor 5 builds} come with all the features included in the distribution package enabled by default. They are defined as plugins for CKEditor 5.

In some cases, you may want to have different editor setups in your application, all based on the same build. For that purpose, you need to control the plugins available in the editor at runtime.

Expand Down Expand Up @@ -71,12 +97,12 @@ ClassicEditor
} );
```

However, using this snippet with the official classic build of CKEditor&nbsp;5 will result in an error thrown in the console of the browser:
However, using this snippet with the official classic build of CKEditor 5 will result in an error thrown in the console of the browser:
```
CKEditorError: plugincollection-required {"plugin":"Link","requiredBy":"CKFinder"}`
Read more: [https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html#error-plugincollection-required](https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html#error-plugincollection-required)
```
This is a good time to remind you that some plugins in CKEditor&nbsp;5 depend on each other. In this case, the `CKFinder` plugin requires the `Link` plugin to work. To make the above snippet work, the `CKFinder` plugin must also be deleted:
This is a good time to remind you that some plugins in CKEditor 5 depend on each other. In this case, the `CKFinder` plugin requires the `Link` plugin to work. To make the above snippet work, the `CKFinder` plugin must also be deleted:

```js
// Remove a few plugins from the default setup.
Expand All @@ -94,87 +120,10 @@ ClassicEditor
Be careful when removing plugins from CKEditor builds using {@link module:core/editor/editorconfig~EditorConfig#removePlugins `config.removePlugins`}. If removed plugins were providing toolbar buttons, the default toolbar configuration included in a build will become invalid. In such case you need to provide the {@link features/toolbar updated toolbar configuration} as in the example above or by providing only toolbar items that need to be removed using `config.toolbar.removeItems`.
</info-box>

### List of plugins

Each build has a number of plugins available. You can easily list all plugins available in your build:

```js
ClassicEditor.builtinPlugins.map( plugin => plugin.pluginName );
```

## Adding features

### Adding complex features

As predefined CKEditor&nbsp;5 builds do not include all possible features, the only way to add more features to them is to {@link installation/getting-started/quick-start-other create a custom build}.

### Adding simple (standalone) features

There is an exception to every rule. Although it is impossible to add plugins that have dependencies to {@link api/core `@ckeditor/ckeditor5-core`} or {@link api/engine `@ckeditor/ckeditor5-engine`} (that includes nearly all existing official plugins) without rebuilding the build, it is still possible to add simple, **dependency-free** plugins.

You can do that using the {@link module:core/editor/editorconfig~EditorConfig#extraPlugins `config.extraPlugins`} configuration. The {@link module:core/plugin~PluginInterface plugin interface} allows plugins to be simple functions and you can define them in just a few lines, for instance:

```js
function MyPlugin( editor ) {
// Plugin code.
// ...
}
```

or

```js
class MyPlugin {
constructor( editor ) {
// Constructor code.
// ...
}

init() {
// Initializations code.
// ...
}
}
```

An example plugin that you may want to add this way is a {@link framework/deep-dive/upload-adapter custom upload adapter}.

```js
import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

function MyUploadAdapterPlugin( editor ) {
editor.plugins.get( 'FileRepository' ).createUploadAdapter = function( loader ) {
// Custom upload adapter.
// ...
};
}

// Load the custom upload adapter as a plugin of the editor.
ClassicEditor
.create( document.querySelector( '#editor' ), {
extraPlugins: [ MyUploadAdapterPlugin ],
// More of the editor's configuration.
// ...
} )
.catch( error => {
console.log( error );
} );
```

## Toolbar setup

In the builds that contain toolbars an optimal default configuration is defined for it. You may need a different toolbar arrangement, though, and this can be achieved through configuration. Check the detailed {@link features/toolbar toolbar feature guide} for the available options.

When you create a {@link installation/getting-started/quick-start-other#creating-custom-builds-with-online-builder custom build using CKEditor&nbsp;5 online builder}, setting up your toolbar configuration is one of the steps in the build creation process that uses an intuitive drag and drop interface.

## Other configuration options

See {@link module:core/editor/editorconfig~EditorConfig} to learn about all available configuration options.

Some of the options may require loading plugins which are not available in the build you use. Return to the {@link installation/getting-started/quick-start-other Quick start} guide for instructions on creating a custom build.

<info-box hint>
**What's next?**

You have learned how to configure your own CKEditor&nbsp;5 instance. Awesome! In the next tutorial, you will learn more about extending your editor with plugins. Ready for a ride? {@link installation/plugins/installing-plugins Jump in}!
You have learned how to configure your own CKEditor 5 instance. Awesome! Learn more about CKEditor 5 by moving on to {@link installation/getting-started/editor-lifecycle the editor's lifecycle guide}!

If you would like to integrate your CKEditor 5 installation with the Angular, React, and Vue.js JavaScript frameworks, {@link installation/integrations/overview we have dedicated guides for that}.
</info-box>
Loading

0 comments on commit 94a9771

Please sign in to comment.