ckeditor5 1.0.6 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad357ef6b45ba35fdea777e70dae559476bd57040b23f49cfefa3581b4b3aafc
-  data.tar.gz: 89da75ef1325766ad4a2f0d81152822f8774b55efdf81bd76b8d9479332cb749
+  metadata.gz: ba0f56261f0c699d67fce659fe6cd4cbc3fc2f288ebedf0fd908f4f6d9555001
+  data.tar.gz: 9c5b41693f3858a94841b7e6392bbd573a3bc83c3a936c7dd2fbdcfff42fda63
 SHA512:
-  metadata.gz: f4f599b202ef0c109e14ff12c25f09890808d53e2116b2d3b6e51dfbfc5f389ea1d62651aa1a493fb897838e56ca2f3345addee8eebd55f5c2b7126f55169ce3
-  data.tar.gz: fc254a7f703defae55c901a444329772e177dfbfc8d0ee4ea3864c6c516b1c36f64e21166ec2e787d79ce368e09981ad524f4187842f31b53b8084ab690ed13b
+  metadata.gz: e12b59365223eeeee6cccef5e771ae2df9e17e9500275a871c8f7b41b6a39abe0cec725848f887ead1a3235d2d50447fdb8b99ead940d1dc50c5f795369d9354
+  data.tar.gz: b163824d28f9867b0bee31e273e5b0be6ad380891d43a1e48ed1fb4df0c38460a4cfddc5fcb7fdf1fa1430950b6cd3d47a6c4cbcf8c4067f5178660f6c991d15

data/README.md

@@ -8,6 +8,10 @@
 
 Unofficial CKEditor 5 Ruby on Rails integration gem. Provides seamless integration of CKEditor 5 with Rails applications through web components and helper methods.
 
+<p align="center">
+  <img src="docs/intro-classic-editor.png" alt="CKEditor 5 Classic Editor in Ruby on Rails application">
+</p>
+
 ## Installation 🛠️
 
 Add this line to your application's Gemfile:
@@ -16,21 +20,33 @@ Add this line to your application's Gemfile:
 gem 'ckeditor5'
 ```
 
-Usage in your Rails application:
+In your config:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails::Engine.configure do |config|
+  config.presets.override :default do
+    version '43.3.0'
+  end
+end
+```
+
+In your view:
 
 ```erb
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+  <%= ckeditor5_assets %>
+  <!-- or using inline config: ckeditor5_assets version: '43.3.0', premium: false -->
 <% end %>
 
-<%= ckeditor5_editor style: 'width: 600px' %>
+<%= ckeditor5_editor style: 'width: 600px', initial_data: '<YOUR DATA>' %>
+<!-- or using inline config: ckeditor5_editor type: :classic, config: { toolbar: [:Bold, :Italic] }, ... -->
 ```
 
-Result:
-
-![CKEditor 5 Classic Editor in Ruby on Rails application](docs/intro-classic-editor.png)
+Voilà! You have CKEditor 5 integrated with your Rails application. 🎉
 
 ## Table of Contents 📚
 
@@ -41,17 +57,18 @@ Result:
     - [Available Configuration Methods ⚙️](#available-configuration-methods-️)
       - [`version(version)` method](#versionversion-method)
       - [`gpl` method](#gpl-method)
+      - [`license_key(key)` method](#license_keykey-method)
       - [`premium` method](#premium-method)
       - [`translations(*languages)` method](#translationslanguages-method)
-      - [`license_key(key)` method](#license_keykey-method)
       - [`ckbox` method](#ckbox-method)
       - [`type(type)` method](#typetype-method)
-      - [`plugins(*names, **kwargs)` method](#pluginsnames-kwargs-method)
-      - [`toolbar(*items, should_group_when_full: true)` method](#toolbaritems-should_group_when_full-true-method)
+      - [`toolbar(*items, should_group_when_full: true, &block)` method](#toolbaritems-should_group_when_full-true-block-method)
       - [`menubar(visible: true)` method](#menubarvisible-true-method)
       - [`language(ui, content:)` method](#languageui-content-method)
       - [`configure(name, value)` method](#configurename-value-method)
       - [`plugin(name, premium:, import_name:)` method](#pluginname-premium-import_name-method)
+      - [`plugins(*names, **kwargs)` method](#pluginsnames-kwargs-method)
+      - [`inline_plugin(name, code)` method](#inline_pluginname-code-method)
   - [Including CKEditor 5 assets 📦](#including-ckeditor-5-assets-)
     - [Lazy loading 🚀](#lazy-loading-)
     - [GPL usage 🆓](#gpl-usage-)
@@ -62,6 +79,18 @@ Result:
     - [Inline editor 📝](#inline-editor-)
     - [Balloon editor 🎈](#balloon-editor-)
     - [Decoupled editor 🌐](#decoupled-editor-)
+  - [How to access editor instance? 🤔](#how-to-access-editor-instance-)
+  - [Events fired by the editor 🔊](#events-fired-by-the-editor-)
+    - [`editor-ready` event](#editor-ready-event)
+    - [`editor-error` event](#editor-error-event)
+  - [Common Tasks and Solutions 💡](#common-tasks-and-solutions-)
+    - [Setting Initial Content 📝](#setting-initial-content-)
+    - [Setting Editor Language 🌐](#setting-editor-language-)
+    - [Integrating with Forms 📋](#integrating-with-forms-)
+      - [Rails form builder integration](#rails-form-builder-integration)
+      - [Simple form integration](#simple-form-integration)
+    - [Custom Styling 🎨](#custom-styling-)
+    - [Custom plugins 🧩](#custom-plugins-)
   - [License 📜](#license-)
 
 ## Presets 🎨
@@ -75,18 +104,16 @@ You can create your own by defining it in the `config/initializers/ckeditor5.rb`
 
 CKEditor5::Rails::Engine.configure do |config|
   config.presets.define :custom
-    gpl # Use GPL license
-
+    gpl
     type :classic
 
     menubar
-
     toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
-            :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
+            :link, :insertImage, :mediaEmbed, :insertTable, :blockQuote, :|,
             :bulletedList, :numberedList, :todoList, :outdent, :indent
 
     plugins :AccessibilityHelp, :Autoformat, :AutoImage, :Autosave,
-            :BlockQuote, :Bold, :CKBox, :CKBoxImageEdit, :CloudServices,
+            :BlockQuote, :Bold, :CloudServices,
             :Essentials, :Heading, :ImageBlock, :ImageCaption, :ImageInline,
             :ImageInsert, :ImageInsertViaUrl, :ImageResize, :ImageStyle,
             :ImageTextAlternative, :ImageToolbar, :ImageUpload, :Indent,
@@ -95,6 +122,10 @@ CKEditor5::Rails::Engine.configure do |config|
             :SelectAll, :Table, :TableCaption, :TableCellProperties,
             :TableColumnResize, :TableProperties, :TableToolbar,
             :TextTransformation, :TodoList, :Underline, :Undo, :Base64UploadAdapter
+
+    configure :image, {
+      toolbar: ['imageTextAlternative', 'imageStyle:inline', 'imageStyle:block', 'imageStyle:side']
+    }
   end
 end
 ```
@@ -107,6 +138,13 @@ In order to override existing presets, you can use the `config.presets.override`
 CKEditor5::Rails::Engine.configure do |config|
   config.presets.override :default do
     menubar visible: false
+
+    toolbar do
+      remove :underline, :heading
+
+      # prepend :underline
+      # append :heading
+    end
   end
 end
 ```
@@ -146,9 +184,23 @@ config.presets.define :custom do
 end
 ```
 
+#### `license_key(key)` method
+
+Defines the license key of CKEditor 5. It calls `premium` method internally. The example below shows how to set the license key:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  license_key 'your-license-key'
+end
+```
+
 #### `premium` method
 
-Defines if premium package (`ckeditor5-premium-features`) should be used.
+Defines if premium package should be included in JS assets. The example below shows how to add `ckeditor5-premium-features` to import maps:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -162,7 +214,7 @@ end
 
 #### `translations(*languages)` method
 
-Defines the translations of CKEditor 5. You can pass the language codes as arguments. The example below shows how to set the Polish and Spanish translations:
+Defines the translations of CKEditor 5. You can pass the language codes as arguments. The example below shows how tell integration to fetch Polish and Spanish translations:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -174,17 +226,15 @@ config.presets.define :custom do
 end
 ```
 
-#### `license_key(key)` method
-
-Defines the license key of CKEditor 5. It calls `premium` method internally. The example below shows how to set the license key:
+⚠️ You need to use `language` method to set the default language of the editor, as the `translations` only fetch the translations files and makes them available to later use.
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 config.presets.define :custom do
-  # ... other configuration
+  translations :pl
 
-  license_key 'your-license-key'
+  language :pl
 end
 ```
 
@@ -224,9 +274,14 @@ config.presets.define :custom do
 end
 ```
 
-#### `plugins(*names, **kwargs)` method
+#### `toolbar(*items, should_group_when_full: true, &block)` method
 
-Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments. The keyword arguments are identical to the configuration of the `plugin` method defined below.
+Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are a few special items:
+
+- `:_` - breakpoint
+- `:|` - separator
+
+The `should_group_when_full` keyword argument determines whether the toolbar should group items when there is not enough space. It's set to `true` by default.
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -234,33 +289,43 @@ Defines the plugins to be included in the editor. You can specify multiple plugi
 config.presets.define :custom do
   # ... other configuration
 
-  plugins :Bold, :Italic, :Underline, :Link
+  toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
+          :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
+          :bulletedList, :numberedList, :todoList, :outdent, :indent
 end
 ```
 
-#### `toolbar(*items, should_group_when_full: true)` method
+Keep in mind that the order of items is important, and you should install the corresponding plugins. You can find the list of available plugins in the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/plugins.html).
 
-Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are a few special items:
+If you want to add or prepend items to the existing toolbar, you can use the block syntax:
 
-- `:_` - breakpoint
-- `:|` - separator
+```rb
+# config/initializers/ckeditor5.rb
 
-The `should_group_when_full` keyword argument determines whether the toolbar should group items when there is not enough space. It's set to `true` by default.
+config.presets.override :default do
+  # ... other configuration
+
+  toolbar do
+    append :selectAll, :|, :selectAll, :selectAll
+    # Or prepend: prepend :selectAll, :|, :selectAll, :selectAll
+  end
+end
+```
+
+If you want to remove items from the toolbar, you can use the `remove` method:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
-config.presets.define :custom do
+config.presets.override :default do
   # ... other configuration
 
-  toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
-          :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
-          :bulletedList, :numberedList, :todoList, :outdent, :indent
+  toolbar do
+    remove :selectAll, :heading #, ...
+  end
 end
 ```
 
-Keep in mind that the order of items is important, and you should install the corresponding plugins. You can find the list of available plugins in the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/plugins.html).
-
 #### `menubar(visible: true)` method
 
 Defines the visibility of the menubar. By default, it's set to `true`.
@@ -335,7 +400,7 @@ config.presets.define :custom do
 end
 ```
 
-In order to import a plugin from a custom package, you can pass the `import_name` keyword argument:
+In order to import a plugin from a custom ESM package, you can pass the `import_name` keyword argument:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -347,6 +412,57 @@ config.presets.define :custom do
 end
 ```
 
+In order to import a plugin from a custom Window entry, you can pass the `window_name` keyword argument:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugin :YourPlugin, window_name: 'YourPlugin'
+end
+```
+
+#### `plugins(*names, **kwargs)` method
+
+Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments. The keyword arguments are identical to the configuration of the `plugin` method defined below.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugins :Bold, :Italic, :Underline, :Link
+end
+```
+
+#### `inline_plugin(name, code)` method
+
+Use with caution as this is an inline definition of the plugin code, and you can define a custom class or function for the plugin here. The example below shows how to define a custom plugin that highlights the text:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  inline_plugin :MyCustomPlugin, <<~JS
+    import { Plugin } from 'ckeditor5';
+
+    export default class MyCustomPlugin extends Plugin {
+      static get pluginName() {
+        return 'MyCustomPlugin';
+      }
+
+      init() {
+        // ... Your plugin code
+      }
+    }
+  JS
+end
+```
 </details>
 
 ## Including CKEditor 5 assets 📦
@@ -368,7 +484,7 @@ It has been achieved by using web components, together with import maps, which a
 
 ### GPL usage 🆓
 
-If you want to use CKEditor 5 under the GPL license, you can include the assets using the `ckeditor5_assets` helper method with the `version` keyword argument. The example below shows how to include the assets for version `43.3.0`:
+If you want to use CKEditor 5 under the GPL license, you can include the assets using the `ckeditor5_assets` without passing any arguments. However you can pass the `version` keyword argument with the version of CKEditor 5 you want to use:
 
 ```erb
 <!-- app/views/demos/index.html.erb -->
@@ -607,57 +723,301 @@ If you want to use a decoupled editor, you can pass the `type` keyword argument
   <%= ckeditor5_assets %>
 <% end %>
 
-<style>
-  .menubar-container,
-  .editable-container,
-  .toolbar-container {
-    position: relative;
-    border: 1px solid red;
-  }
+<%= ckeditor5_editor type: :decoupled, style: 'width: 600px' do %>
+  <div class="menubar-container">
+    <%= ckeditor5_menubar %>
+  </div>
 
-  .menubar-container::after,
-  .editable-container::after,
-  .toolbar-container::after {
-    content: attr(class);
-    position: absolute;
-    background: red;
-    color: #fff;
-    top: 0;
-    right: 0;
-    font: 10px/2 monospace;
-    padding: .1em .3em;
-  }
+  <div class="toolbar-container">
+    <%= ckeditor5_toolbar %>
+  </div>
+
+  <div class="editable-container">
+    <%= ckeditor5_editable %>
+  </div>
+<% 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
+<!-- app/views/demos/index.html.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);
+});
+```
+
+## Events fired by the editor 🔊
+
+### `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');
+});
+```
+
+## Common Tasks and Solutions 💡
+
+This section covers frequent questions and scenarios when working with CKEditor 5 in Rails applications.
+
+### Setting Initial Content 📝
+
+```erb
+<%= ckeditor5_editor initial_data: "<p>Initial content</p>" %>
+```
+
+### Setting Editor Language 🌐
+
+```rb
+config.presets.override :default do
+  translations :pl, :es
+  language :pl
+end
+```
+
+### Integrating with Forms 📋
+
+#### 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| %>
+  <div class="form-group">
+    <%= f.input :content, as: :ckeditor5, initial_data: 'Hello, World 12!', input_html: { style: 'width: 600px' }, required: true %>
+  </div>
+
+  <div class="form-group mt-3">
+    <%= f.button :submit, 'Save', class: 'btn btn-primary' %>
+  </div>
+<% end %>
+```
+
+### Custom Styling 🎨
+
+```erb
+<%= ckeditor5_editor style: 'height: 400px; margin: 20px;' %>
+```
+
+### 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:
+
+![CKEditor 5 Custom Highlight Plugin in Ruby on Rails application](docs/custom-highlight-plugin.png)
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
 
-  .menubar-container,
-  .toolbar-container {
-    padding: 1em;
+  # 1. You can define it inline like below or in a separate file.
+
+  # In case if plugin is located in external file (recommended), you can simply import it:
+
+  # inline_plugin :MyCustomPlugin, <<~JS
+  #  import MyPlugin from 'app/javascript/custom_plugins/highlight.js';
+  #  export default MyPlugin;
+  # JS
+
+  # 2. You can also use "window_name" option to import plugin from window object:
+
+  # plugin :MyPlugin, window_name: 'MyPlugin'
+
+  # 3. Create JavaScript file in app/javascript/custom_plugins/highlight.js:
+  # You can also use "plugin" to import plugin from file using 'import_name' option.
+  # Your `my-custom-plugin` must be present in import map.
+
+  # plugin :MyCustomPlugin, import_name: 'my-custom-plugin'
+
+  # 4 Create JavaScript file in app/javascript/custom_plugins/highlight.js:
+
+  # In Ruby initializer you can also load plugin code directly from file:
+  plugin :MyCustomPlugin, File.read(
+    Rails.root.join('app/javascript/custom_plugins/highlight.js')
+  )
+
+  # 5. Or even define it 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
+```
+
+<details>
+  <summary>Example of Custom Highlight Plugin 🎨</summary>
+
+```js
+// app/javascript/custom_plugins/highlight.js
+import { Plugin, Command, ButtonView } from 'ckeditor5';
+
+export default class MyCustomPlugin extends Plugin {
+  static get pluginName() {
+    return 'MyCustomPlugin';
   }
 
-  .editable-container {
-    padding: 3em;
-    overflow-y: scroll;
-    max-height: 300px;
+  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');
 
-  .editable-container .ck-editor__editable {
-    min-height: 21cm;
-    padding: 2em;
-    border: 1px #D3D3D3 solid;
-    border-radius: var(--ck-border-radius);
-    background: white;
-    box-shadow: 0 0 5px rgba(0, 0, 0, 0.1);
+    // Set if command is enabled based on schema
+    this.isEnabled = isAllowed;
+    this.value = this.#isHighlightedNodeSelected();
   }
-</style>
 
-<%= ckeditor5_editor type: :decoupled, style: 'width: 600px' do %>
-  <div class="menubar-container"><%= ckeditor5_menubar %></div>
-  <br>
-  <div class="toolbar-container"><%= ckeditor5_toolbar %></div>
-  <br>
-  <div class="editable-container"><%= ckeditor5_editable %></div>
-<% end %>
+  // 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')
+        )
+    );
+  }
+}
 ```
 
+</details>
+
 ## License 📜
 
 The MIT License (MIT)

data/lib/ckeditor5/rails/assets/assets_bundle.rb

@@ -41,7 +41,7 @@ module CKEditor5::Rails::Assets
   class JSExportsMeta
     attr_reader :url, :import_meta
 
-    delegate :esm?, :window?, :import_name, :window_name, :import_as, to: :import_meta
+    delegate :esm?, :window?, :import_name, :window_name, :import_as, :to_h, to: :import_meta
 
     def initialize(url, translation: false, **import_options)
       @url = url

data/lib/ckeditor5/rails/assets/assets_bundle_html_serializer.rb

@@ -63,13 +63,14 @@ module CKEditor5::Rails::Assets
 
     def styles_tags
       @styles_tags ||= safe_join(bundle.stylesheets.map do |url|
-        tag.link(href: url, rel: 'stylesheet')
+        tag.link(href: url, rel: 'stylesheet', crossorigin: 'anonymous')
       end)
     end
 
     def preload_tags
       @preload_tags ||= safe_join(bundle.preloads.map do |url|
-        tag.link(href: url, rel: 'preload', as: self.class.url_resource_preload_type(url))
+        tag.link(href: url, rel: 'preload', as: self.class.url_resource_preload_type(url),
+                 crossorigin: 'anonymous')
       end)
     end
   end

data/lib/ckeditor5/rails/assets/webcomponent.mjs

@@ -23,7 +23,8 @@
  */
 class CKEditorComponent extends HTMLElement {
   /**
-   * List of attributes that trigger updates when changed
+   * List of attributes that trigger updates when changed.
+   *
    * @static
    * @returns {string[]} Array of attribute names to observe
    */
@@ -31,6 +32,16 @@ class CKEditorComponent extends HTMLElement {
     return ['config', 'plugins', 'translations', 'type'];
   }
 
+  /**
+   * List of input attributes that trigger updates when changed.
+   *
+   * @static
+   * @returns {string[]} Array of input attribute names to observe
+   */
+  static get inputAttributes() {
+    return ['name', 'required', 'value'];
+  }
+
   /** @type {Promise<import('ckeditor5').Editor>|null} Promise to initialize editor instance */
   instancePromise = Promise.withResolvers();
 
@@ -134,16 +145,17 @@ class CKEditorComponent extends HTMLElement {
       content = editablesOrContent.main;
     }
 
-    const instance = await Editor.create(
-      content,
-      {
-        ...this.#getConfig(),
-        ...translations.length && {
-          translations
-        },
-        plugins,
-      }
-    );
+    const config = {
+      ...this.#getConfig(),
+      ...translations.length && {
+        translations
+      },
+      plugins,
+    };
+
+    console.warn('Initializing CKEditor with config:', config);
+
+    const instance = await Editor.create(content, config);
 
     this.dispatchEvent(new CustomEvent('editor-ready', { detail: instance }));
 
@@ -168,6 +180,7 @@ class CKEditorComponent extends HTMLElement {
 
     if (!this.isMultiroot() && !this.isDecoupled()) {
       this.innerHTML = `<${this.#editorElementTag}></${this.#editorElementTag}>`;
+      this.#assignInputAttributes();
     }
 
     // Let's track changes in editables if it's a multiroot editor.
@@ -181,6 +194,8 @@ class CKEditorComponent extends HTMLElement {
 
     try {
       this.instance = await this.#initializeEditor(this.editables || this.#getConfig().initialData || '');
+      this.#setupContentSync();
+
       this.instancePromise.resolve(this.instance);
     } catch (err) {
       this.instancePromise.reject(err);
@@ -251,6 +266,74 @@ class CKEditorComponent extends HTMLElement {
     return { main: mainEditable };
   }
 
+  /**
+   * Copies input-related attributes from component to the main editable element
+   *
+   * @private
+   */
+  #assignInputAttributes() {
+    const textarea = this.querySelector('textarea');
+
+    if (!textarea) {
+      return;
+    }
+
+    for (const attr of CKEditorComponent.inputAttributes) {
+      if (this.hasAttribute(attr)) {
+        textarea.setAttribute(attr, this.getAttribute(attr));
+      }
+    }
+  }
+
+  /**
+   * Sets up content sync between editor and textarea element.
+   *
+   * @private
+   */
+  #setupContentSync() {
+    if (!this.instance) {
+      return;
+    }
+
+    const textarea = this.querySelector('textarea');
+
+    if (!textarea) {
+      return;
+    }
+
+    // Initial sync
+    const syncInput = () => {
+      this.style.position = 'relative';
+
+      textarea.value = this.instance.getData();
+      textarea.tabIndex = -1;
+
+      Object.assign(textarea.style, {
+        display: 'flex',
+        position: 'absolute',
+        bottom: '0',
+        left: '50%',
+        width: '1px',
+        height: '1px',
+        opacity: '0',
+        pointerEvents: 'none',
+        margin: '0',
+        padding: '0',
+        border: 'none'
+      });
+    };
+
+    syncInput();
+
+    // Listen for changes
+    this.instance.model.document.on('change:data', () => {
+      textarea.dispatchEvent(new Event('input', { bubbles: true }));
+      textarea.dispatchEvent(new Event('change', { bubbles: true }));
+
+      syncInput();
+    });
+  }
+
   /**
    * Loads translation modules
    *
@@ -624,16 +707,48 @@ function execIfDOMReady(callback) {
  * @returns {Promise<Array<any>>} Loaded modules
  */
 function loadAsyncImports(imports = []) {
-  return Promise.all(
-    imports.map(async ({ import_name, import_as, window_name }) => {
-      if (window_name && Object.prototype.hasOwnProperty.call(window, window_name)) {
-        return window[window_name];
+  const loadInlinePlugin = async ({ name, code }) => {
+    const module = await import(`data:text/javascript,${encodeURIComponent(code)}`);
+
+    if (!module.default) {
+      throw new Error(`Inline plugin "${name}" must export a default class/function!`);
+    }
+
+    return module.default;
+  };
+
+  const loadExternalPlugin = async ({ import_name, import_as, window_name }) => {
+    if (window_name) {
+      if (!Object.prototype.hasOwnProperty.call(window, window_name)) {
+        throw new Error(
+          `Plugin window['${window_name}'] not found in global scope. ` +
+          'Please ensure the plugin is loaded before CKEditor initialization.'
+        );
       }
 
-      const module = await import(import_name);
-      return import_as ? module[import_as] : module.default;
-    })
-  );
+      return window[window_name];
+    }
+
+    const module = await import(import_name);
+    const imported = module[import_as || 'default'];
+
+    if (!imported) {
+      throw new Error(`Plugin "${import_as}" not found in the ESM module "${import_name}"!`);
+    }
+
+    return imported;
+  };
+
+  return Promise.all(imports.map(item => {
+    switch(item.type) {
+      case 'inline':
+        return loadInlinePlugin(item);
+
+      case 'external':
+      default:
+        return loadExternalPlugin(item);
+    }
+  }));
 }
 
 customElements.define('ckeditor-component', CKEditorComponent);

data/lib/ckeditor5/rails/editor/helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'props_plugin'
+require_relative 'props_inline_plugin'
 require_relative 'props'
 
 module CKEditor5::Rails
@@ -11,6 +12,7 @@ module CKEditor5::Rails
     def ckeditor5_editor(
       config: nil, extra_config: {},
       type: nil, preset: :default,
+      initial_data: nil,
       **html_attributes, &block
     )
       context = validate_and_get_editor_context!
@@ -19,8 +21,11 @@ module CKEditor5::Rails
       config ||= preset.config
       type ||= preset.type
 
+      config = config.deep_merge(extra_config)
+      config[:initialData] = initial_data if initial_data
+
       editor_props = build_editor_props(
-        config: config.deep_merge(extra_config),
+        config: config,
         type: type,
         context: context
       )

data/lib/ckeditor5/rails/editor/props.rb

@@ -44,7 +44,7 @@ module CKEditor5::Rails::Editor
     end
 
     def serialize_translations
-      context[:bundle].translations_scripts.map { |script| script.import_meta.to_h }.to_json
+      context[:bundle].translations_scripts.map(&:to_h).to_json
     end
 
     def serialize_plugins

data/lib/ckeditor5/rails/editor/props_inline_plugin.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails::Editor
+  class PropsInlinePlugin
+    def initialize(name, code)
+      @name = name
+      @code = code
+      validate_code!
+    end
+
+    def to_h
+      {
+        type: :inline,
+        name: name,
+        code: code
+      }
+    end
+
+    private
+
+    attr_reader :name, :code
+
+    def validate_code!
+      raise ArgumentError, 'Code must be a String' unless code.is_a?(String)
+
+      return if code.include?('export default')
+
+      raise ArgumentError,
+            'Code must include `export default` that exports plugin definition!'
+    end
+  end
+end

data/lib/ckeditor5/rails/editor/props_plugin.rb

@@ -4,30 +4,35 @@ module CKEditor5::Rails::Editor
   class PropsPlugin
     delegate :to_h, to: :import_meta
 
-    def initialize(name, premium: false, import_name: nil)
+    def initialize(name, premium: false, **js_import_meta)
       @name = name
-      @premium = premium
-      @import_name = import_name
-      @import_name ||= premium ? 'ckeditor5-premium-features' : 'ckeditor5'
+      @js_import_meta = if js_import_meta.empty?
+                          { import_name: premium ? 'ckeditor5-premium-features' : 'ckeditor5' }
+                        else
+                          js_import_meta
+                        end
     end
 
     def self.normalize(plugin)
       case plugin
       when String, Symbol then new(plugin)
-      when PropsPlugin then plugin
+      when PropsPlugin, PropsInlinePlugin then plugin
       else raise ArgumentError, "Invalid plugin: #{plugin}"
       end
     end
 
-    private
-
-    attr_reader :name, :premium, :import_name
+    def to_h
+      meta = ::CKEditor5::Rails::Assets::JSImportMeta.new(
+        import_as: js_import_meta[:window_name] ? nil : name,
+        **js_import_meta
+      ).to_h
 
-    def import_meta
-      ::CKEditor5::Rails::Assets::JSImportMeta.new(
-        import_as: name,
-        import_name: import_name
-      )
+      meta.merge!({ type: :external })
+      meta
     end
+
+    private
+
+    attr_reader :name, :js_import_meta
   end
 end

data/lib/ckeditor5/rails/engine.rb

@@ -2,6 +2,7 @@
 
 require 'rails/engine'
 require_relative 'presets'
+require_relative 'hooks/form'
 
 module CKEditor5::Rails
   class Engine < ::Rails::Engine
@@ -16,6 +17,22 @@ module CKEditor5::Rails
       end
     end
 
+    initializer 'ckeditor5.simple_form' do
+      next unless defined?(::SimpleForm)
+
+      require_relative 'hooks/simple_form'
+
+      ::SimpleForm::FormBuilder.map_type :ckeditor5, to: Hooks::SimpleForm::CKEditor5Input
+    end
+
+    initializer 'ckeditor5.form_builder' do
+      require_relative 'hooks/form'
+
+      ActionView::Helpers::FormBuilder.include(
+        Hooks::Form::FormBuilderExtension
+      )
+    end
+
     def self.base
       config.ckeditor5
     end

data/lib/ckeditor5/rails/hooks/form.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails::Hooks
+  module Form
+    module FormBuilderExtension
+      def ckeditor5(method, options = {})
+        value = if object.respond_to?(method)
+                  object.send(method)
+                else
+                  options[:initial_data]
+                end
+
+        html_options = options.merge(
+          name: object_name,
+          required: options.delete(:required),
+          initial_data: value
+        )
+
+        @template.ckeditor5_editor(**html_options)
+      end
+    end
+  end
+end

data/lib/ckeditor5/rails/hooks/simple_form.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CKEditor5::Rails::Hooks
+  module SimpleForm
+    class CKEditor5Input < ::SimpleForm::Inputs::Base
+      def input(wrapper_options = nil)
+        merged_input_options = merge_wrapper_options(input_html_options, wrapper_options)
+        @builder.template.ckeditor5_editor(**editor_options(merged_input_options))
+      end
+
+      private
+
+      def editor_options(merged_input_options)
+        {
+          preset: input_options.fetch(:preset, :default),
+          type: input_options.fetch(:type, :classic),
+          config: input_options[:config],
+          initial_data: object.try(attribute_name) || input_options[:initial_data],
+          name: "#{object_name}[#{attribute_name}]",
+          **merged_input_options
+        }
+      end
+    end
+  end
+end

data/lib/ckeditor5/rails/presets.rb

@@ -29,7 +29,7 @@ module CKEditor5::Rails
 
     private
 
-    def define_default_preset
+    def define_default_preset # rubocop:disable Metrics/MethodLength
       define :default do
         gpl
 
@@ -38,11 +38,11 @@ module CKEditor5::Rails
         menubar
 
         toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
-                :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
+                :link, :insertImage, :mediaEmbed, :insertTable, :blockQuote, :|,
                 :bulletedList, :numberedList, :todoList, :outdent, :indent
 
         plugins :AccessibilityHelp, :Autoformat, :AutoImage, :Autosave,
-                :BlockQuote, :Bold, :CKBox, :CKBoxImageEdit, :CloudServices,
+                :BlockQuote, :Bold, :CloudServices,
                 :Essentials, :Heading, :ImageBlock, :ImageCaption, :ImageInline,
                 :ImageInsert, :ImageInsertViaUrl, :ImageResize, :ImageStyle,
                 :ImageTextAlternative, :ImageToolbar, :ImageUpload, :Indent,
@@ -51,6 +51,10 @@ module CKEditor5::Rails
                 :SelectAll, :Table, :TableCaption, :TableCellProperties,
                 :TableColumnResize, :TableProperties, :TableToolbar,
                 :TextTransformation, :TodoList, :Underline, :Undo, :Base64UploadAdapter
+
+        configure :image, {
+          toolbar: ['imageTextAlternative', 'imageStyle:inline', 'imageStyle:block', 'imageStyle:side']
+        }
       end
     end
   end
@@ -144,11 +148,22 @@ module CKEditor5::Rails
       }
     end
 
-    def toolbar(*items, should_group_when_full: true)
-      @config[:toolbar] = {
-        items: items,
-        shouldNotGroupWhenFull: !should_group_when_full
-      }
+    def toolbar(*items, should_group_when_full: true, &block)
+      if @config[:toolbar].blank? || !items.empty?
+        @config[:toolbar] = {
+          items: items,
+          shouldNotGroupWhenFull: !should_group_when_full
+        }
+      end
+
+      return unless block
+
+      builder = ToolbarBuilder.new(@config[:toolbar])
+      builder.instance_eval(&block)
+    end
+
+    def inline_plugin(name, code)
+      @config[:plugins] << Editor::PropsInlinePlugin.new(name, code)
     end
 
     def plugin(name, **kwargs)
@@ -166,4 +181,40 @@ module CKEditor5::Rails
       }
     end
   end
+
+  class ToolbarBuilder
+    def initialize(toolbar_config)
+      @toolbar_config = toolbar_config
+    end
+
+    def items
+      @toolbar_config[:items]
+    end
+
+    def remove(*removed_items)
+      removed_items.each { |item| items.delete(item) }
+    end
+
+    def prepend(*prepended_items, before: nil)
+      if before
+        index = items.index(before)
+        raise ArgumentError, "Item '#{before}' not found in toolbar" unless index
+
+        items.insert(index, *prepended_items)
+      else
+        items.insert(0, *prepended_items)
+      end
+    end
+
+    def append(*appended_items, after: nil)
+      if after
+        index = items.index(after)
+        raise ArgumentError, "Item '#{after}' not found in toolbar" unless index
+
+        items.insert(index + 1, *appended_items)
+      else
+        items.push(*appended_items)
+      end
+    end
+  end
 end

data/lib/ckeditor5/rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CKEditor5::Rails
-  VERSION = '1.0.6'
+  VERSION = '1.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.1.1
 platform: ruby
 authors:
 - Mateusz Bagiński
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-31 00:00:00.000000000 Z
+date: 2024-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -53,9 +53,12 @@ files:
 - lib/ckeditor5/rails/cloud/helpers.rb
 - lib/ckeditor5/rails/editor/helpers.rb
 - lib/ckeditor5/rails/editor/props.rb
+- lib/ckeditor5/rails/editor/props_inline_plugin.rb
 - lib/ckeditor5/rails/editor/props_plugin.rb
 - lib/ckeditor5/rails/engine.rb
 - lib/ckeditor5/rails/helpers.rb
+- lib/ckeditor5/rails/hooks/form.rb
+- lib/ckeditor5/rails/hooks/simple_form.rb
 - lib/ckeditor5/rails/presets.rb
 - lib/ckeditor5/rails/semver.rb
 - lib/ckeditor5/rails/version.rb