Module: CKEditor5::Rails::Presets::Concerns::PluginMethods

Extended by:
ActiveSupport::Concern
Included in:
Context::PresetBuilder, PresetBuilder
Defined in:
lib/ckeditor5/rails/presets/concerns/plugin_methods.rb

Defined Under Namespace

Classes: CompressionDisabledError, InvalidPatchPluginError, MissingInlinePluginError, UnsupportedESModuleError

Instance Method Summary collapse

Instance Method Details

#compression(enabled: false) ⇒ void

Note:

This method is useful for debugging purposes, as it allows you to see the uncompressed code.

This method returns an undefined value.

Sets compression of inline plugin code. Make sure that it is called before setting the version or adding plugins.

Examples:

Disable compression

compression(enabled: false)


27
28
29
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 27

def compression(enabled: false)
  @disallow_inline_plugin_compression = !enabled
end

#compression? ⇒ Boolean

Check if compression is enabled

Examples:

Check if compression is enabled

compression? # => true

Returns:

  • (Boolean) —

    True if compression is enabled, false otherwise



35
36
37
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 35

def compression?
  !@disallow_inline_plugin_compression
end

#external_plugin(name, **kwargs) ⇒ Object

Registers an external plugin loaded from a URL

Examples:

Load plugin from URL

external_plugin :MyPlugin, script: 'https://example.com/plugin.js'

Load with import alias

external_plugin :MyPlugin,
  script: 'https://example.com/plugin.js',
  import_as: 'Plugin'

Parameters:

  • name (Symbol) —

    Plugin name

  • kwargs (Hash) —

    Plugin options like :script, :import_as, :window_name, :stylesheets



49
50
51
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 49

def external_plugin(name, **kwargs)
  register_plugin(Editor::PropsExternalPlugin.new(name, **kwargs))
end

#inline_plugin(name, code, compress: !@disallow_inline_plugin_compression)) ⇒ Object

Registers an inline plugin with raw JavaScript code

Examples:

Define custom highlight plugin

inline_plugin :MyCustomPlugin, <<~JS
  const { Plugin } = await import( 'ckeditor5' );

  return class MyCustomPlugin extends Plugin {
    static get pluginName() {
      return 'MyCustomPlugin';
    }

    init() {
      // Plugin initialization code
    }
  }
JS

Parameters:

  • name (Symbol) —

    Plugin name

  • code (String) —

    JavaScript code defining the plugin

  • compress (Boolean) (defaults to: !@disallow_inline_plugin_compression)) —

    Whether to compress the code (default: true)



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 72

def inline_plugin(name, code, compress: !@disallow_inline_plugin_compression)
  if code.match?(/export default/)
    raise UnsupportedESModuleError,
          'Inline plugins must not use ES module syntax!' \
          'Use async async imports instead!'
  end

  unless code.match?(/return class(\s+\w+)?\s+extends\s+Plugin/)
    raise MissingInlinePluginError,
          'Plugin code must return a class that extends Plugin!'
  end

  plugin = Editor::PropsInlinePlugin.new(name, code, compress: compress)

  register_plugin(plugin)
end

#patch_plugin(plugin) ⇒ Editor::PropsPatchPlugin?

Registers a patch plugin that modifies CKEditor behavior for specific versions

Examples:

Apply patch for specific CKEditor versions

patch_plugin PropsPatchPlugin.new(:PatchName, code, min_version: '35.0.0', max_version: '36.0.0')

Parameters:

Returns:

Raises:



96
97
98
99
100
101
102
103
104
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 96

def patch_plugin(plugin)
  unless plugin.is_a?(Editor::PropsPatchPlugin)
    raise InvalidPatchPluginError, 'Provided plugin must be a PropsPatchPlugin instance'
  end

  return unless !@version || plugin.applicable_for_version?(@version)

  register_plugin(plugin)
end

#plugin(name, **kwargs) ⇒ Object

Register a single plugin by name

Examples:

Register standard plugin

plugin :Bold

Register premium plugin

plugin :RealTimeCollaboration, premium: true

Register custom plugin

plugin :MyPlugin, import_name: 'my-custom-plugin'

Parameters:

  • name (Symbol, Editor::PropsBasePlugin) —

    Plugin name or instance

  • kwargs (Hash) —

    Plugin configuration options



116
117
118
119
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 116

def plugin(name, **kwargs)
  premium(true) if kwargs[:premium] && respond_to?(:premium)
  register_plugin(PluginsBuilder.create_plugin(name, **kwargs))
end

#plugins(*names, **kwargs, &block) ⇒ Object

Register multiple plugins and configure plugin settings

Examples:

Register multiple plugins

plugins :Bold, :Italic, :Underline

Configure plugins with block

plugins do
  remove :Heading
  append :SelectAll, :RemoveFormat
  prepend :SourceEditing
end

Parameters:

  • names (Array<Symbol>) —

    Plugin names to register

  • kwargs (Hash) —

    Shared plugin configuration



133
134
135
136
137
138
139
140
141
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 133

def plugins(*names, **kwargs, &block)
  config[:plugins] ||= []

  names.each { |name| plugin(name, **kwargs) } unless names.empty?

  builder = PluginsBuilder.new(config[:plugins])
  builder.instance_eval(&block) if block_given?
  builder
end

#try_compress_inline_plugins! ⇒ void

Note:

This method is called automatically when defining a preset

This method returns an undefined value.

Compresses inline plugins to reduce bundle size

Examples:

Compress inline plugins

try_compress_inline_plugins!

Raises:



150
151
152
153
154
155
156
157
158
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 150

def try_compress_inline_plugins!
  raise CompressionDisabledError if @disallow_inline_plugin_compression

  config[:plugins].each do |plugin|
    next unless plugin.is_a?(Editor::PropsInlinePlugin)

    plugin.try_compress!
  end
end