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

#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



31
32
33
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 31

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

#inline_plugin(name, code, compress: true) ⇒ 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: true) —

    Whether to compress the code (default: true)



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 54

def inline_plugin(name, code, compress: true)
  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

  compress = false if @disallow_inline_plugin_compression
  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:



79
80
81
82
83
84
85
86
87
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 79

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



99
100
101
102
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 99

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



116
117
118
119
120
121
122
123
124
 
# File 'lib/ckeditor5/rails/presets/concerns/plugin_methods.rb', line 116

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:



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

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