OR GPL' %>
<% end %>
```
### Lazy loading ๐
Loading JS and CSS Assets
All JS assets defined by the `ckeditor5_assets` helper method are loaded **asynchronously**. It means that the assets are loaded in the background without blocking the rendering of the page. However, the CSS assets are loaded **synchronously** to prevent the flash of unstyled content and ensure that the editor is styled correctly.
It has been achieved by using web components, together with import maps, which are supported by modern browsers. The web components are used to define the editor and its plugins, while the import maps are used to define the dependencies between the assets.
### GPL usage ๐
If you want to use CKEditor 5 under the GPL license, you can include the assets using the `ckeditor5_assets` without passing any arguments. It'll include the necessary assets for the GPL license from one of the most popular CDNs. In our scenario, we use the `jsdelivr` CDN which is the default one.
Example:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
```
In that scenario it's recommended to add `gpl` method to the initializer along with the version:
```rb
# config/initializers/ckeditor5.rb
CKEditor5::Rails.configure do
gpl
version '43.3.0'
end
```
In order to use `unpkg` CDN, you can extend your initializer with the following configuration:
```rb
# config/initializers/ckeditor5.rb
CKEditor5::Rails.configure do
# ... rest of the configuration
cdn :unpkg
end
```
However, you can also specify the CDN directly in the view:
```erb
<% content_for :head do %>
<%= ckeditor5_assets cdn: :unpkg %>
<% end %>
```
or using helper function:
```erb
<% content_for :head do %>
<%= ckeditor5_jsdelivr_assets %>
<% end %>
```
### Commercial usage ๐ฐ
If you want to use CKEditor 5 under a commercial license, you have to specify license key. It can be done in the initializer:
```rb
# config/initializers/ckeditor5.rb
CKEditor5::Rails.configure do
license_key 'your-license-key'
end
```
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
```
or directly in the view:
```erb
<% content_for :head do %>
<%= ckeditor5_assets license_key: 'your-license-key' %>
<% end %>
```
In this scenario, the assets are included from the official CKEditor 5 CDN which is more reliable and provides better performance, especially for commercial usage.
## Editor placement ๐๏ธ
The `ckeditor5_editor` helper renders CKEditor 5 instances in your views. Before using it, ensure you've included the necessary assets in your page's head section otherwise the editor won't work as there are no CKEditor 5 JavaScript and CSS files loaded.
### Setting Initial Content ๐
You can set the initial content of the editor using the `initial_data` keyword argument or by passing the content directly to the `ckeditor5_editor` helper block.
The example below shows how to set the initial content of the editor using the `initial_data` keyword argument:
```erb
<%= ckeditor5_editor initial_data: "Initial content
" %>
```
The example below shows how to set the initial content of the editor using the `ckeditor5_editor` helper block.
```erb
<%= ckeditor5_editor do %>
Initial content
<% end %>
```
### Watchdog ๐
CKEditor 5 uses a watchdog utility to protect you from data loss in case the editor crashes. It saves your content just before the crash and creates a new instance of the editor with your content intact. It's enabled by default in the gem.
If you want to disable the watchdog, you can pass the `watchdog` keyword argument with the value `false`:
```erb
<%= ckeditor5_editor watchdog: false %>
```
### Classic editor ๐
The classic editor is the most common type of editor. It provides a toolbar with various formatting options like bold, italic, underline, and link.
It looks like this:
The example below shows how to include the classic editor in your view:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor style: 'width: 600px' %>
```
You can pass the `style` keyword argument to the `ckeditor5_editor` helper to define the editor's style. The example above shows how to set the width of the editor to `600px`. However you can pass any HTML attribute you want, such as `class`, `id`, `data-*`, etc.
While example above uses predefined `:default` preset, you can use your custom presets by passing the `preset` keyword argument:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor preset: :custom, style: 'width: 600px' %>
```
If your configuration is even more complex, you can pass the `config` and `type` arguments with the configuration hash:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor type: :classic, config: { plugins: [:Bold, :Italic], toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
```
If you want to override the configuration of the editor specified in default or custom preset, you can pass the `extra_config` keyword argument with the configuration hash:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor extra_config: { toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
```
It's possible to define the height of the editor by passing the `editable_height` keyword argument with the value in pixels:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor editable_height: 300 %>
```
### Multiroot editor ๐ณ
The multiroot editor allows you to create an editor with multiple editable areas. It's useful when you want to create a CMS with multiple editable areas on a single page.
- `ckeditor5_editor`: Defines the editor instance.
- `ckeditor5_editable`: Defines the editable areas within the editor.
- `ckeditor5_toolbar`: Defines the toolbar for the editor.
If you want to use a multiroot editor, you can pass the `type` keyword argument with the value `:multiroot`:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor type: :multiroot, style: 'width: 600px' do %>
<%= ckeditor5_toolbar %>
<%= ckeditor5_editable 'toolbar', style: 'border: 1px solid var(--ck-color-base-border);' do %>
This is a toolbar editable
<% end %>
<%= ckeditor5_editable 'content', style: 'border: 1px solid var(--ck-color-base-border)' %>
<% end %>
```
Roots can be defined later to the editor by simply adding new elements rendered by `ckeditor5_editable` helper.
### Inline editor ๐
Inline editor allows you to create an editor that can be placed inside any element. Keep in mind that inline editor does not work with `textarea` elements so it might be not suitable for all use cases.
If you want to use an inline editor, you can pass the `type` keyword argument with the value `:inline`:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor type: :inline, style: 'width: 600px' %>
```
### Balloon editor ๐
Balloon editor is a floating toolbar editor that provides a minimalistic interface. It's useful when you want to create a simple editor with a floating toolbar.
If you want to use a balloon editor, you can pass the `type` keyword argument with the value `:balloon`:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor type: :balloon, style: 'width: 600px' %>
```
### Decoupled editor ๐
Decoupled editor is a variant of classic editor that allows you to separate the editor from the content area. It's useful when you want to create a custom interface with the editor.
If you want to use a decoupled editor, you can pass the `type` keyword argument with the value `:decoupled`:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor type: :decoupled, style: 'width: 600px' do %>
<%= ckeditor5_toolbar %>
<%= ckeditor5_editable %>
<% end %>
```
## Using Context ๐ฆ
Context CKEditor 5 is a feature that allows multiple editor instances to share a common configuration and state. This is particularly useful in collaborative environments where multiple users are editing different parts of the same document simultaneously. By using a shared context, all editor instances can synchronize their configurations, plugins, and other settings, ensuring a consistent editing experience across all users.
### Using Context in CKEditor 5 ๐
Format of the `ckeditor5_context` helper:
```erb
<%= ckeditor5_context config: { ... }, plugins: [ ... ] do %>
<%= ckeditor5_editor %>
<%= ckeditor5_editor %>
<% end %>
```
The `ckeditor5_context` helper takes the `config` and `plugins` keyword arguments. The `config` keyword argument allows you to define the shared configuration of the editor instances, while the `plugins` keyword argument allows you to define the shared plugins. Format of these arguments is the same as in the `ckeditor5_editor` helper.
### Example usage of `ckeditor5_context` helper ๐
```erb
<% content_for :head do %>
<%= ckeditor5_assets preset: :ultrabasic %>
<% end %>
<%= ckeditor5_context do %>
<%= ckeditor5_editor initial_data: 'Hello World' %>
<%= ckeditor5_editor initial_data: 'Hello World 2' %>
<% end %>
```
## How to access editor instance? ๐ค
You can access the editor instance using plain HTML and JavaScript, as CKEditor 5 is a web component with defined `instance`, `instancePromise` and `editables` properties.
For example:
```erb
<% content_for :head do %>
<%= ckeditor5_assets %>
<% end %>
<%= ckeditor5_editor style: 'width: 600px', id: 'editor' %>
```
โ ๏ธ Direct access of `instance` property of the web component. Keep in mind it's unsafe and may cause issues if the editor is not loaded yet.
```js
document.getElementById('editor').instance
```
๐ Accessing the editor instance using `instancePromise` property. It's a promise that resolves to the editor instance when the editor is ready.
```js
document.getElementById('editor').instancePromise.then(editor => {
console.log(editor);
});
```
โ
Accessing the editor through the `runAfterEditorReady` helper method. It's a safe way to access the editor instance when the editor is ready.
```js
document.getElementById('editor').runAfterEditorReady(editor => {
console.log(editor);
});
```
## Common Tasks and Solutions ๐ก
This section covers frequent questions and scenarios when working with CKEditor 5 in Rails applications.
### Setting Editor Language ๐
You can set the language of the editor using the `language` method in the `config/initializers/ckeditor5.rb` file. The `translations` method fetches the translations files, while the `language` method sets the default language of the editor.
```rb
config.presets.override :default do
translations :pl, :es
language :pl
end
```
### Integrating with Forms ๐
You can integrate CKEditor 5 with Rails form builders like `form_for` or `simple_form`. The example below shows how to integrate CKEditor 5 with a Rails form using the `form_for` helper:
#### Rails form builder integration
```erb
<%= form_for @post do |f| %>
<%= f.label :content %>
<%= f.ckeditor5 :content, required: true, style: 'width: 700px', initial_data: 'Hello World!' %>
<% end %>
```
#### Simple form integration
```erb
<%= simple_form_for :demo, url: '/demos', html: { novalidate: false } do |f| %>
<%= f.input :content, as: :ckeditor5, initial_data: 'Hello, World 12!', input_html: { style: 'width: 600px' }, required: true %>
<%= f.button :submit, 'Save', class: 'btn btn-primary' %>
<% end %>
```
### Custom Styling ๐จ
You can pass the `style`, `class` and `id` keyword arguments to the `ckeditor5_editor` helper to define the styling of the editor. The example below shows how to set the height, margin, and CSS class of the editor:
```erb
<%= ckeditor5_editor style: 'height: 400px; margin: 20px;', class: 'your_css_class', id: 'your_id' %>
```
### Custom plugins ๐งฉ
You can create custom plugins for CKEditor 5 using the `inline_plugin` method. It allows you to define a custom class or function inside your preset configuration.
The example below shows how to define a custom plugin that allows toggling the highlight of the selected text:
```rb
# config/initializers/ckeditor5.rb
CKEditor5::Rails.configure do
# ... other configuration
# 1. You can also use "window_name" option to import plugin from window object:
# plugin :MyPlugin, window_name: 'MyPlugin'
# 2. Create JavaScript file in app/javascript/custom_plugins/highlight.js,
# add it to import map and then load it in initializer:
# plugin :MyCustomPlugin, import_name: 'my-custom-plugin'
# 3 Create JavaScript file in app/javascript/custom_plugins/highlight.js
# and then load it in initializer:
# In Ruby initializer you can also load plugin code directly from file:
inline_plugin :MyCustomPlugin, File.read(
Rails.root.join('app/javascript/custom_plugins/highlight.js')
)
# 4. Or even define it inline:
# inline_plugin :MyCustomPlugin, <<~JS
# import { Plugin } from 'ckeditor5';
#
# export default class MyCustomPlugin extends Plugin {
# // ...
# }
# JS
# Add item to beginning of the toolbar.
toolbar do
prepend :highlight
end
end
```
Example of Custom Highlight Plugin ๐จ
```js
// app/javascript/custom_plugins/highlight.js
import { Plugin, Command, ButtonView } from 'ckeditor5';
export default class MyCustomPlugin extends Plugin {
static get pluginName() {
return 'MyCustomPlugin';
}
init() {
const editor = this.editor;
// Define schema for highlight attribute
editor.model.schema.extend('$text', { allowAttributes: 'highlight' });
// Define conversion between model and view
editor.conversion.attributeToElement({
model: 'highlight',
view: {
name: 'span',
styles: {
'background-color': 'yellow'
}
}
});
// Create command that handles highlighting logic
// Command pattern is used to encapsulate all the logic related to executing an action
const command = new HighlightCommand(editor);
// Register command in editor
editor.commands.add('highlight', command);
// Add UI button
editor.ui.componentFactory.add('highlight', locale => {
const view = new ButtonView(locale);
// Bind button state to command state using bind method
// bind() allows to sync button state with command state automatically
view.bind('isOn').to(command, 'value');
view.set({
label: 'Highlight',
withText: true,
tooltip: true
});
view.on('execute', () => {
editor.execute('highlight');
editor.editing.view.focus();
});
return view;
});
}
}
// Command class that handles the highlight feature
// isEnabled property determines if command can be executed
class HighlightCommand extends Command {
execute() {
const model = this.editor.model;
const selection = model.document.selection;
model.change(writer => {
const ranges = model.schema.getValidRanges(selection.getRanges(), 'highlight');
for (const range of ranges) {
if (this.value) {
writer.removeAttribute('highlight', range);
} else {
writer.setAttribute('highlight', true, range);
}
}
});
}
refresh() {
const model = this.editor.model;
const selection = model.document.selection;
const isAllowed = model.schema.checkAttributeInSelection(selection, 'highlight');
// Set if command is enabled based on schema
this.isEnabled = isAllowed;
this.value = this.#isHighlightedNodeSelected();
}
// Check if the highlighted node is selected.
#isHighlightedNodeSelected() {
const { model } = this.editor
const { schema } = model
const selection = model.document.selection
if (selection.isCollapsed) {
return selection.hasAttribute('highlight')
}
return selection.getRanges().some(range =>
Array
.from(range.getItems())
.some(item =>
schema.checkAttribute(item, 'highlight') &&
item.hasAttribute('highlight')
)
);
}
}
```
## Events fired by the editor ๐
CKEditor 5 provides a set of events that you can listen to in order to react to changes in the editor. You can listen to these events using the `addEventListener` method or by defining event handlers directly in the view.
### `editor-ready` event
The event is fired when the initialization of the editor is completed. You can listen to it using the `editor-ready` event.
```js
document.getElementById('editor').addEventListener('editor-ready', () => {
console.log('Editor is ready');
});
```
### `editor-error` event
The event is fired when the initialization of the editor fails. You can listen to it using the `editor-error` event.
```js
document.getElementById('editor').addEventListener('editor-error', () => {
console.log('Editor has an error');
});
```
### `editor-change` event
The event is fired when the content of the editor changes. You can listen to it using the `editor-change` event.
```js
document.getElementById('editor').addEventListener('editor-change', () => {
console.log('Editor content has changed');
});
```
### Inline event handling
You can also define event handlers directly in the view using the `oneditorchange`, `oneditorerror`, and `oneditorready` attributes.
```erb
<%= ckeditor5_editor id: 'editor',
oneditorchange: 'onEditorChange',
oneditorerror: 'onEditorError',
oneditorready: 'onEditorReady'
%>
```
## Gem Development ๐
If you want to contribute to the gem, you can clone the repository and run the following commands:
```sh
gem install bundler -v 2.5.22
bundle install
bundle exec guard -g rails
```
### Running tests ๐งช
You can run the tests using the following command:
```sh
bundle exec rspec
```
If you want to watch the tests, you can use the following command:
```sh
bundle exec guard -g rspec
```
## Trademarks ๐
CKEditorยฎ is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com/) All rights reserved. For more information about the license of CKEditorยฎ please visit [CKEditor's licensing page](https://ckeditor.com/legal/ckeditor-oss-license/).
This gem is not owned by CKSource and does not use the CKEditorยฎ trademark for commercial purposes. It should not be associated with or considered an official CKSource product.
## License ๐
This project is licensed under the terms of the [GNU General Public License v2.0 or later](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). See the [LICENSE](LICENSE) file for details.
This project uses CKEditor 5 which is licensed under the terms of [GNU General Public License Version 2 or later](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html). For more information about CKEditor 5 licensing, please see their [official documentation](https://ckeditor.com/legal/ckeditor-oss-license/).
