ckeditor5 1.0.5 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8e40a31c033d3d5cfc96667757993fd4a92614a5e5bedacb93ec20d82419bd2
-  data.tar.gz: fb172fb186502165dd06475a980fd9ccbd21751076cf5a420edc64ace4129734
+  metadata.gz: ad357ef6b45ba35fdea777e70dae559476bd57040b23f49cfefa3581b4b3aafc
+  data.tar.gz: 89da75ef1325766ad4a2f0d81152822f8774b55efdf81bd76b8d9479332cb749
 SHA512:
-  metadata.gz: 64889f53d365c640f498efc484fbab12e05cfe93b80a9ab448c5bc5e3cb45bd24f313bce90ebd04cfd656c7cbd7c9cc60f7c982d7cf0aee8128cbc50633304ac
-  data.tar.gz: 1f9985d8cf29068eb70ecb93bf2c8e85a177750d0241e28075b1ba916a6e3a43cef71bd5598f4f25e25c6d9751cc36639065aa28065d592ff888012dbfd5bde3
+  metadata.gz: f4f599b202ef0c109e14ff12c25f09890808d53e2116b2d3b6e51dfbfc5f389ea1d62651aa1a493fb897838e56ca2f3345addee8eebd55f5c2b7126f55169ce3
+  data.tar.gz: fc254a7f703defae55c901a444329772e177dfbfc8d0ee4ea3864c6c516b1c36f64e21166ec2e787d79ce368e09981ad524f4187842f31b53b8084ab690ed13b

data/README.md

@@ -28,7 +28,7 @@ Usage in your Rails application:
 <%= ckeditor5_editor style: 'width: 600px' %>
 ```
 
-Effect:
+Result:
 
 ![CKEditor 5 Classic Editor in Ruby on Rails application](docs/intro-classic-editor.png)
 
@@ -39,8 +39,14 @@ Effect:
   - [Table of Contents 📚](#table-of-contents-)
   - [Presets 🎨](#presets-)
     - [Available Configuration Methods ⚙️](#available-configuration-methods-️)
-      - [`shape(type)` method](#shapetype-method)
-      - [`plugins(*names)` method](#pluginsnames-method)
+      - [`version(version)` method](#versionversion-method)
+      - [`gpl` method](#gpl-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)
       - [`menubar(visible: true)` method](#menubarvisible-true-method)
       - [`language(ui, content:)` method](#languageui-content-method)
@@ -62,16 +68,16 @@ Effect:
 
 Presets are predefined configurations of CKEditor 5, allowing quick setup with specific features. The gem includes a `:default` preset with common features like bold, italic, underline, and link for the classic editor.
 
-You can override the default preset or create your own by defining a new preset in the `config/initializers/ckeditor5.rb` file using the `config.presets.define` method.
-
-The example below shows how to define a custom preset with a classic editor and a custom toolbar:
+You can create your own by defining it in the `config/initializers/ckeditor5.rb` file using the `config.presets.define` method. The example below illustrates the setup of a custom preset with a classic editor and a custom toolbar:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 CKEditor5::Rails::Engine.configure do |config|
   config.presets.define :custom
-    shape :classic
+    gpl # Use GPL license
+
+    type :classic
 
     menubar
 
@@ -93,7 +99,7 @@ CKEditor5::Rails::Engine.configure do |config|
 end
 ```
 
-In order to override existing presets, you can use the `config.presets.override` method. The method takes the name of the preset you want to override and a block with the new configuration. In example below, we override the `:default` preset to hide the menubar.
+In order to override existing presets, you can use the `config.presets.override` method. The method takes the name of the preset you want to override and a block with the old configuration. The example below shows how to hide the menubar in the default preset:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -105,14 +111,98 @@ CKEditor5::Rails::Engine.configure do |config|
 end
 ```
 
-You can generate your preset using the CKEditor 5 [online builder](https://ckeditor.com/ckeditor-5/online-builder/). After generating the configuration, you can copy it to the `config/initializers/ckeditor5.rb` file.
+Configuration of the editor can be complex, and it's recommended to use the CKEditor 5 [online builder](https://ckeditor.com/ckeditor-5/online-builder/) to generate the configuration. It allows you to select the features you want to include and generate the configuration code in JavaScript format.  Keep in mind that you need to convert the JavaScript configuration to Ruby format before using it in this gem.
 
 ### Available Configuration Methods ⚙️
 
 <details>
   <summary>Expand to show available methods 📖</summary>
 
-#### `shape(type)` method
+#### `version(version)` method
+
+Defines the version of CKEditor 5 to be used. The example below shows how to set the version to `43.2.0`:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  version '43.2.0'
+end
+```
+
+#### `gpl` method
+
+Defines the license of CKEditor 5. The example below shows how to set the license to GPL:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  gpl
+end
+```
+
+#### `premium` method
+
+Defines if premium package (`ckeditor5-premium-features`) should be used.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  premium
+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:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  translations :pl, :es
+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
+```
+
+#### `ckbox` method
+
+Defines the CKBox plugin to be included in the editor. The example below shows how to include the CKBox plugin:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  ckbox '2.5.4', theme: :lark
+end
+```
+
+#### `type(type)` method
 
 Defines the type of editor. Available options:
 
@@ -122,24 +212,28 @@ Defines the type of editor. Available options:
 - `:balloon` - balloon editor
 - `:multiroot` - editor with multiple editing areas
 
-The example below shows how to define a multiroot editor:
+The example below sets the editor type to `multiroot` in the custom preset:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 config.presets.define :custom do
-  shape :multiroot
+  # ... other configuration
+
+  type :multiroot
 end
 ```
 
-#### `plugins(*names)` method
+#### `plugins(*names, **kwargs)` method
 
-Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments.
+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
 ```
@@ -257,16 +351,16 @@ end
 
 ## Including CKEditor 5 assets 📦
 
-To include CKEditor 5 assets in your application, you can use the `ckeditor5_assets` helper method. This method takes the version of CKEditor 5 as an argument and includes the necessary assets. It allows you to specify custom translations to be included.
+To include CKEditor 5 assets in your application, you can use the `ckeditor5_assets` helper method. This method takes the version of CKEditor 5 as an argument and includes the necessary resources of the editor. Depending on the specified configuration, it includes the JS and CSS assets from the official CKEditor 5 CDN or one of the popular CDNs.
 
-Keep in mind that you need to include the assets in the `head` section of your layout. In examples below, we use `content_for` to include the assets in the `head` section.
+Keep in mind that you need to include the helper result in the `head` section of your layout. In examples below, we use `content_for` helper to include the assets in the `head` section of the view.
 
 ### Lazy loading 🚀
 
 <details>
   <summary>Loading JS and CSS Assets</summary>
 
-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.
+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.
 
@@ -286,6 +380,28 @@ If you want to use CKEditor 5 under the GPL license, you can include the assets
 
 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.
 
+Version is optional as long as you defined it in the `config/initializers/ckeditor5.rb` file. If you want to use the default version, you can omit the `version` keyword argument:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets %>
+<% end %>
+```
+
+Set the version in the `config/initializers/ckeditor5.rb` file:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails::Engine.configure do
+  presets.override :default do
+    version '43.3.0'
+  end
+end
+```
+
 In order to use `unpkg` CDN, you can pass the `cdn` keyword argument with the value `:unpkg`:
 
 ```erb
@@ -349,7 +465,7 @@ In this scenario, the assets are included from the official CKEditor 5 CDN which
 
 ## 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.
+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.
 
 ### Classic editor 📝
 
@@ -365,7 +481,7 @@ The example below shows how to include the classic editor in your view:
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor style: 'width: 600px' %>
@@ -379,7 +495,7 @@ While example above uses predefined `:default` preset, you can use your custom p
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor preset: :custom, style: 'width: 600px' %>
@@ -391,7 +507,7 @@ If your configuration is even more complex, you can pass the `config` and `type`
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :classic, config: { plugins: [:Bold, :Italic], toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
@@ -403,7 +519,7 @@ If you want to override the configuration of the editor specified in default or
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor extra_config: { toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
@@ -425,7 +541,7 @@ If you want to use a multiroot editor, you can pass the `type` keyword argument
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :multiroot, style: 'width: 600px' do %>
@@ -454,7 +570,7 @@ If you want to use an inline editor, you can pass the `type` keyword argument wi
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :inline, style: 'width: 600px' %>
@@ -472,7 +588,7 @@ If you want to use a balloon editor, you can pass the `type` keyword argument wi
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :balloon, style: 'width: 600px' %>
@@ -488,7 +604,7 @@ If you want to use a decoupled editor, you can pass the `type` keyword argument
 
 ```erb
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <style>

data/lib/ckeditor5/rails/cdn/ckbox_bundle.rb

@@ -7,7 +7,7 @@ module CKEditor5::Rails
 
       attr_reader :cdn, :version, :theme, :translations
 
-      def initialize(version, theme: :lark, cdn: Engine.base.default_cdn, translations: [])
+      def initialize(version, theme: :lark, cdn: Engine.default_preset.cdn, translations: [])
         raise ArgumentError, 'version must be semver' unless version.is_a?(Semver)
         raise ArgumentError, 'theme must be a string' unless theme.is_a?(String)
         raise ArgumentError, 'translations must be an array' unless translations.is_a?(Array)

data/lib/ckeditor5/rails/cdn/ckeditor_bundle.rb

@@ -7,7 +7,7 @@ module CKEditor5::Rails
 
       attr_reader :version, :translations, :import_name
 
-      def initialize(version, import_name, cdn: Engine.base.default_cdn, translations: [])
+      def initialize(version, import_name, cdn: Engine.default_preset.cdn, translations: [])
         raise ArgumentError, 'version must be semver' unless version.is_a?(Semver)
         raise ArgumentError, 'import_name must be a string' unless import_name.is_a?(String)
         raise ArgumentError, 'translations must be an array' unless translations.is_a?(Array)

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

@@ -6,7 +6,17 @@ require_relative 'ckbox_bundle'
 
 module CKEditor5::Rails
   module Cdn::Helpers
-    def ckeditor5_cdn_assets(version:, cdn:, license_key: 'GPL', premium: false, translations: [], ckbox: nil)
+    def ckeditor5_cdn_assets(preset: :default, **kwargs)
+      merge_with_editor_preset(preset, **kwargs) => {
+        cdn:,
+        version:,
+        translations:,
+        ckbox:,
+        license_key:,
+        premium:,
+        **kwargs
+      }
+
       bundle = build_base_cdn_bundle(cdn, version, translations)
       bundle << build_premium_cdn_bundle(cdn, version, translations) if premium
       bundle << build_ckbox_cdn_bundle(ckbox) if ckbox
@@ -29,12 +39,34 @@ module CKEditor5::Rails
       if kwargs[:license_key] && kwargs[:license_key] != 'GPL'
         ckeditor5_cloud_assets(**kwargs)
       else
-        ckeditor5_cdn_assets(**kwargs.merge(cdn: Engine.base.default_cdn))
+        ckeditor5_cdn_assets(**kwargs.merge(cdn: Engine.default_preset.cdn))
       end
     end
 
     private
 
+    def merge_with_editor_preset(preset, **kwargs)
+      found_preset = Engine.base.presets[preset]
+
+      if found_preset.blank?
+        raise ArgumentError,
+              "Poor thing. You forgot to define your #{preset} preset. " \
+              'Please define it in initializer. Thank you!'
+      end
+
+      hash = found_preset.to_h_with_overrides(**kwargs)
+
+      %i[version type].each do |key|
+        next if hash[key].present?
+
+        raise ArgumentError,
+              "Poor thing. You forgot to define #{key}. Make sure you passed `#{key}:` parameter to " \
+              "`ckeditor5_cdn_assets` or defined default one in your `#{preset}` preset!"
+      end
+
+      hash
+    end
+
     def build_base_cdn_bundle(cdn, version, translations)
       Cdn::CKEditorBundle.new(
         Semver.new(version),

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

@@ -54,7 +54,7 @@ module CKEditor5::Rails::Editor
     def serialize_config
       config
         .except(:plugins)
-        .merge(licenseKey: context[:license_key] || 'GPL')
+        .tap { |cfg| cfg[:licenseKey] = context[:license_key] if context[:license_key] }
         .to_json
     end
   end

data/lib/ckeditor5/rails/engine.rb

@@ -7,12 +7,6 @@ module CKEditor5::Rails
   class Engine < ::Rails::Engine
     config.ckeditor5 = ActiveSupport::OrderedOptions.new
 
-    # Specifies which CDN should be used to load CKEditor 5 using the ckeditor5_assets helper.
-    # It is possible to use the following CDNs:
-    # - :unpkg
-    # - :jsdelivr (default)
-    config.ckeditor5.default_cdn = :jsdelivr
-
     # Specifies configuration of editors generated by gem.
     config.ckeditor5.presets = PresetsManager.new
 
@@ -26,6 +20,10 @@ module CKEditor5::Rails
       config.ckeditor5
     end
 
+    def self.default_preset
+      config.ckeditor5.presets.default
+    end
+
     def self.configure
       yield config.ckeditor5
     end

data/lib/ckeditor5/rails/presets.rb

@@ -31,7 +31,9 @@ module CKEditor5::Rails
 
     def define_default_preset
       define :default do
-        shape :classic
+        gpl
+
+        type :classic
 
         menubar
 
@@ -54,17 +56,79 @@ module CKEditor5::Rails
   end
 
   class PresetBuilder
-    attr_reader :type, :config
+    attr_reader :config
 
     def initialize
+      @version = nil
+      @premium = false
+      @cdn = :jsdelivr
+      @translations = []
+      @license_key = nil
       @type = :classic
+      @ckbox = nil
       @config = {
         plugins: [],
         toolbar: []
       }
     end
 
-    def shape(type)
+    def to_h_with_overrides(**overrides)
+      {
+        version: overrides.fetch(:version, version),
+        premium: overrides.fetch(:premium, premium),
+        cdn: overrides.fetch(:cdn, cdn),
+        translations: overrides.fetch(:translations, translations),
+        license_key: overrides.fetch(:license_key, license_key),
+        type: overrides.fetch(:type, type),
+        ckbox: overrides.fetch(:ckbox, ckbox),
+        config: config.merge(overrides.fetch(:config, {}))
+      }
+    end
+
+    def ckbox(version = nil, theme: :lark)
+      return @ckbox if version.nil?
+
+      @ckbox = { version: version, theme: theme }
+    end
+
+    def license_key(license_key = nil)
+      return @license_key if license_key.nil?
+
+      @license_key = license_key
+    end
+
+    def gpl
+      license_key('GPL')
+      premium(false)
+    end
+
+    def premium(premium = nil)
+      return @premium if premium.nil?
+
+      @premium = premium
+    end
+
+    def translations(*translations)
+      return @translations if translations.empty?
+
+      @translations = translations
+    end
+
+    def version(version = nil)
+      return @version.to_s if version.nil?
+
+      @version = Semver.new(version)
+    end
+
+    def cdn(cdn = nil)
+      return @cdn if cdn.nil?
+
+      @cdn = cdn
+    end
+
+    def type(type = nil)
+      return @type if type.nil?
+
       raise ArgumentError, "Invalid editor type: #{type}" unless Editor::Props.valid_editor_type?(type)
 
       @type = type

data/lib/ckeditor5/rails/semver.rb

@@ -6,7 +6,7 @@ class CKEditor5::Rails::Semver
   alias to_s :version
 
   def initialize(version)
-    @version = version
+    @version = version.to_s
     validate!
   end
 

data/lib/ckeditor5/rails/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ckeditor5
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.6
 platform: ruby
 authors:
 - Mateusz Bagiński