Class: CKEditor5::Rails::Presets::PresetBuilder

Inherits:
Object
  • Object
show all
Includes:
Editor::Helpers::Config, Concerns::ConfigurationMethods, Concerns::PluginMethods
Defined in:
lib/ckeditor5/rails/presets/preset_builder.rb

Overview

rubocop:disable Metrics/ClassLength

Instance Method Summary collapse

Methods included from Concerns::PluginMethods

#compression, #compression?, #external_plugin, #inline_plugin, #patch_plugin, #plugin, #plugins, #try_compress_inline_plugins!

Methods included from Concerns::ConfigurationMethods

#configure

Methods included from Editor::Helpers::Config

#ckeditor5_element_ref, #ckeditor5_preset, #ckeditor5_translation_ref

Constructor Details

#initialize(&block) ⇒ PresetBuilder

Returns a new instance of PresetBuilder.

Examples:

Basic initialization

PresetBuilder.new do
  version '43.3.1'
  gpl
  type :classic
end


20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 20

def initialize(&block)
  @version = nil
  @premium = false
  @cdn = :jsdelivr
  @translations = [:en]
  @license_key = nil
  @type = :classic
  @ckbox = nil
  @editable_height = nil
  @automatic_upgrades = false
  @disallow_inline_plugin_compression = false
  @custom_translations = {}
  @config = {
    plugins: [],
    toolbar: []
  }

  instance_eval(&block) if block_given?
end

Instance Method Details

#apply_integration_patches(compress: !@disallow_inline_plugin_compression)) ⇒ void

This method returns an undefined value.

Apply integration patches for the current version



198
199
200
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 198

def apply_integration_patches(compress: !@disallow_inline_plugin_compression)
  patch_plugin(Plugins::Patches::FixColorPickerRaceCondition.new(compress: compress))
end

#automatic_upgrades(enabled: true) ⇒ Object

Enable or disable automatic version upgrades

Examples:

Enable automatic upgrades

automatic_upgrades enabled: true

Parameters:

  • enabled (Boolean) (defaults to: true) —

    Enable/disable upgrades



206
207
208
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 206

def automatic_upgrades(enabled: true)
  @automatic_upgrades = enabled
end

#automatic_upgrades? ⇒ Boolean

Check if automatic upgrades are enabled

Returns:

  • (Boolean) 


212
213
214
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 212

def automatic_upgrades?
  @automatic_upgrades
end

#balloon_toolbar(*items, **kwargs) { ... } ⇒ ToolbarBuilder

Configure balloon toolbar items and grouping

Examples:

Configure balloon toolbar items

balloon_toolbar :bold, :italic, :link

Configure with block

balloon_toolbar do
  append :textColor
  remove :italic
end

Parameters:

  • items (Array<Symbol>) —

    Toolbar items to include

  • kwargs (Hash) —

    Additional toolbar configuration options

Options Hash (**kwargs):

  • :should_group_when_full (Boolean) —

    Enable/disable toolbar item grouping

Yields:

  • Optional block for additional toolbar configuration

Returns:



323
324
325
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 323

def balloon_toolbar(*items, **kwargs, &block)
  toolbar(*items, **kwargs, type: :balloonToolbar, &block)
end

#block_toolbar(*items, **kwargs) { ... } ⇒ ToolbarBuilder

Configure block toolbar items and grouping

Examples:

Configure block toolbar items

block_toolbar :heading, :paragraph, :blockQuote

Configure with block

block_toolbar do
  append :table
  remove :paragraph
end

Parameters:

  • items (Array<Symbol>) —

    Toolbar items to include

  • kwargs (Hash) —

    Additional toolbar configuration options

Options Hash (**kwargs):

  • :should_group_when_full (Boolean) —

    Enable/disable toolbar item grouping

Yields:

  • Optional block for additional toolbar configuration

Returns:



306
307
308
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 306

def block_toolbar(*items, **kwargs, &block)
  toolbar(*items, **kwargs, type: :blockToolbar, &block)
end

#cdn(cdn = nil, &block) ⇒ Symbol, Proc

Configure CDN source

Examples:

Use jsDelivr CDN

cdn :jsdelivr

Custom CDN configuration

cdn do |bundle, version, path|
  "https://custom-cdn.com/#{bundle}@#{version}/#{path}"
end

Parameters:

  • cdn (Symbol, nil) (defaults to: nil) —

    CDN name or custom block

Returns:

  • (Symbol, Proc) —

    Current CDN configuration



225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 225

def cdn(cdn = nil, &block)
  return @cdn if cdn.nil? && block.nil?

  if block_given?
    unless block.arity == 3
      raise ArgumentError,
            'Block must accept exactly 3 arguments: bundle, version, path'
    end

    @cdn = block
  else
    @cdn = cdn
  end
end

#ckbox(version = nil, theme: :lark) ⇒ Object

Configure CKBox integration

Examples:

Enable CKBox with custom version

ckbox '2.6.0', theme: :lark

Parameters:

  • version (String, nil) (defaults to: nil) —

    CKBox version

  • theme (Symbol) (defaults to: :lark) —

    Theme name (:lark)



118
119
120
121
122
123
124
125
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 118

def ckbox(version = nil, theme: :lark)
  return @ckbox if version.nil?

  @ckbox = {
    version: version,
    theme: theme
  }
end

#custom_translations(lang_code = nil, translations = {}, compress: !@disallow_inline_plugin_compression)) ⇒ void

This method returns an undefined value.

Configure custom translations for the editor

Examples:

Add multiple translations

custom_translations :en, {
  'my.button': 'My Button'
}
custom_translations :pl, {
  'my.button': 'Mój przycisk'
}

Use translations in configuration with ckeditor5_translation_ref

custom_translations :en, {
  'custom.heading': 'Custom Section'
}

configure :heading, {
  options: [
    { model: 'heading1', title: ckeditor5_translation_ref('custom.heading') }
  ]
}

Parameters:

  • lang_code (Symbol) (defaults to: nil) —

    Language code for translations (e.g. :en, :pl)

  • translations (Hash) (defaults to: {}) —

    A hash containing translations in format { key => translation }

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

    Whether to compress the translations



355
356
357
358
359
360
361
362
363
364
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 355

def custom_translations(lang_code = nil, translations = {},
                        compress: !@disallow_inline_plugin_compression)
  return @custom_translations if lang_code.blank?

  @custom_translations[lang_code.to_sym] ||= {}
  @custom_translations[lang_code.to_sym].merge!(translations)

  plugins.remove(:CustomTranslationsLoader)
  plugins.prepend(Plugins::CustomTranslationsLoader.new(@custom_translations, compress: compress))
end

#editable_height(height = nil) ⇒ Integer?

Set or get editable height in pixels

Examples:

Set editor height to 300px

editable_height 300

Parameters:

  • height (Integer, nil) (defaults to: nil) —

    Height in pixels

Returns:

  • (Integer, nil) —

    Current height value



107
108
109
110
111
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 107

def editable_height(height = nil)
  return @editable_height if height.nil?

  @editable_height = height
end

#gpl ⇒ Object

Set GPL license and disable premium features

Examples:

Enable GPL license

gpl


143
144
145
146
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 143

def gpl
  license_key('GPL')
  premium(false)
end

#gpl? ⇒ Boolean

Check if preset is using GPL license

Returns:

  • (Boolean) 


65
66
67
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 65

def gpl?
  license_key == 'GPL'
end

#initialize_copy(source) ⇒ Object

Examples:

Copy preset and modify it

original = PresetBuilder.new
copied = original.initialize_copy(original)


43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 43

def initialize_copy(source)
  super

  @translations = source.translations.dup
  @ckbox = source.ckbox.dup if source.ckbox
  @custom_translations = source.custom_translations.deep_dup
  @config = {
    plugins: source.config[:plugins].map(&:dup),
    toolbar: deep_copy_toolbar(source.config[:toolbar])
  }.merge(
    source.config.except(:plugins, :toolbar).deep_dup
  )
end

#language(ui = nil, content: ui) ⇒ Hash?

Configure editor language

Examples:

Set Polish UI and content language

language :pl

Different UI and content languages

language :pl, content: :en

Parameters:

  • ui (Symbol, nil) (defaults to: nil) —

    UI language code

  • content (Symbol) (defaults to: ui) —

    Content language code

Returns:

  • (Hash, nil) —

    Language configuration



374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 374

def language(ui = nil, content: ui) # rubocop:disable Naming/MethodParameterName
  return config[:language] if ui.nil?

  # Normalize language codes, as the translation packs used to be in lowercase
  ui = ui.to_sym.downcase
  content = content.to_sym.downcase

  @translations << ui unless @translations.map(&:to_sym).include?(ui)

  config[:language] = {
    ui: ui,
    content: content
  }
end

#language? ⇒ Boolean

Check if language is configured

Returns:

  • (Boolean) 


329
330
331
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 329

def language?
  config[:language].present?
end

#license_key(license_key = nil) ⇒ String?

Set or get license key

Examples:

Set commercial license

license_key 'your-license-key'

Parameters:

  • license_key (String, nil) (defaults to: nil) —

    License key

Returns:

  • (String, nil) —

    Current license key



132
133
134
135
136
137
138
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 132

def license_key(license_key = nil)
  return @license_key if license_key.nil?

  @license_key = license_key

  cdn(:cloud) unless gpl?
end

#menubar(visible: true) ⇒ Object

Configure menubar visibility

Examples:

Hide menubar

menubar visible: false

Parameters:

  • visible (Boolean) (defaults to: true) —

    Show/hide menubar



257
258
259
260
261
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 257

def menubar(visible: true)
  config[:menuBar] = {
    isVisible: visible
  }
end

#menubar? ⇒ Boolean

Check if menubar is visible

Returns:

  • (Boolean) 


265
266
267
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 265

def menubar?
  config.dig(:menuBar, :isVisible) || false
end

#merge_with_hash!(**overrides) ⇒ self

Merge preset with configuration hash

Parameters:

  • overrides (Hash) —

    Configuration options to merge

Returns:

  • (self) 


87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 87

def merge_with_hash!(**overrides)
  @version = Semver.new(overrides[:version]) if overrides.key?(: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)
  @editable_height = overrides.fetch(:editable_height, editable_height)
  @automatic_upgrades = overrides.fetch(:automatic_upgrades, automatic_upgrades)
  @ckbox = overrides.fetch(:ckbox, ckbox) if overrides.key?(:ckbox) || ckbox
  @config = config.merge(overrides.fetch(:config, {}))

  self
end

#override(&block) ⇒ PresetBuilder

Create a new preset by overriding current configuration

Examples:

Override existing preset

preset.override do
  menubar visible: false
  toolbar do
    remove :underline, :heading
  end
end

Returns:



78
79
80
81
82
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 78

def override(&block)
  clone.tap do |preset|
    preset.instance_eval(&block)
  end
end

#premium(premium = nil) ⇒ Boolean

Enable or check premium features

Examples:

Enable premium features

premium true

Parameters:

  • premium (Boolean, nil) (defaults to: nil) —

    Enable/disable premium features

Returns:

  • (Boolean) —

    Premium status



153
154
155
156
157
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 153

def premium(premium = nil)
  return @premium if premium.nil?

  @premium = premium
end

#premium? ⇒ Boolean

Check if preset is using premium features

Returns:

  • (Boolean) 


59
60
61
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 59

def premium?
  @premium
end

#simple_upload_adapter(upload_url = '/uploads', compress: !@disallow_inline_plugin_compression)) ⇒ Object

Configure simple upload adapter

Examples:

Enable upload adapter

simple_upload_adapter '/uploads'

Parameters:

  • upload_url (String) (defaults to: '/uploads') —

    Upload endpoint URL

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

    Enable compression



394
395
396
397
398
399
400
401
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 394

def simple_upload_adapter(upload_url = '/uploads', compress: !@disallow_inline_plugin_compression)
  plugins do
    remove(:Base64UploadAdapter)
  end

  plugin(Plugins::SimpleUploadAdapter.new(compress: compress))
  configure(:simpleUpload, { uploadUrl: upload_url })
end

#special_characters(compress: !@disallow_inline_plugin_compression,) { ... } ⇒ Object

Configure special characters plugin

Examples:

Basic configuration with block

special_characters do
  group 'Emoji', label: 'Emoticons' do
    item 'smiley', '😊'
    item 'heart', '❤️'
  end
  order :Text, :Emoji
end

Configuration with direct items array

special_characters do
  group 'Arrows',
        items: [
          { title: 'right', character: '→' },
          { title: 'left', character: '←' }
        ]
end

Mixed configuration

special_characters do
  group 'Mixed',
        items: [{ title: 'star', character: '⭐' }],
        label: 'Mixed Characters' do
    item 'heart', '❤️'
  end
end

Parameters:

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

    Enable compression

Yields:

  • Block for configuring special characters



447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 447

def special_characters(compress: !@disallow_inline_plugin_compression, &block)
  builder = SpecialCharactersBuilder.new
  builder.instance_eval(&block) if block_given?

  plugins do
    append(:SpecialCharacters)
    builder.packs_plugins.each { |pack| append(pack) }
    prepend(Plugins::SpecialCharactersBootstrap.new(compress: compress))
  end

  configure(:specialCharactersBootstrap, builder.to_h)
end

#toolbar(*items, should_group_when_full: true, type: :toolbar, &block) ⇒ ToolbarBuilder

Configure toolbar items and grouping

Examples:

Configure toolbar items

toolbar :bold, :italic, :|, :link

Configure with block

toolbar do
  append :selectAll
  remove :heading
end

Parameters:

  • items (Array<Symbol>) —

    Toolbar items

  • should_group_when_full (Boolean) (defaults to: true) —

    Enable grouping

Returns:



280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 280

def toolbar(*items, should_group_when_full: true, type: :toolbar, &block)
  if @config[type].blank? || !items.empty?
    @config[type] = {
      items: items,
      shouldNotGroupWhenFull: !should_group_when_full
    }
  end

  builder = ToolbarBuilder.new(@config[type][:items])
  builder.instance_eval(&block) if block_given?
  builder
end

#translations(*translations) ⇒ Array<Symbol>

Set or get translations

Examples:

Add Polish and Spanish translations

translations :pl, :es

Parameters:

  • translations (Array<Symbol>) —

    Language codes

Returns:

  • (Array<Symbol>) —

    Current translations



164
165
166
167
168
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 164

def translations(*translations)
  return @translations if translations.empty?

  @translations = translations.map { |t| t.to_sym.downcase }
end

#type(type = nil) ⇒ Symbol

Set or get editor type

Examples:

Set editor type to inline

type :inline

Parameters:

  • type (Symbol, nil) (defaults to: nil) —

    Editor type (:classic, :inline, :balloon, :decoupled)

Returns:

  • (Symbol) —

    Current editor type

Raises:

  • (ArgumentError) —

    If invalid type provided



246
247
248
249
250
251
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 246

def type(type = nil)
  return @type if type.nil?
  raise ArgumentError, "Invalid editor type: #{type}" unless Editor::Props.valid_editor_type?(type)

  @type = type
end

#version(version = nil, apply_patches: true) ⇒ String?

Set or get editor version

Examples:

Set specific version

version '43.3.1'

Set version without applying patches

version '43.3.1', apply_patches: false

Get current version

version # => "43.3.1"

Parameters:

  • version (String, nil) (defaults to: nil) —

    Editor version to set

  • apply_patches (Boolean) (defaults to: true) —

    Whether to apply integration patches after setting version

Returns:

  • (String, nil) —

    Current version string or nil if not set



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 180

def version(version = nil, apply_patches: true)
  return @version&.to_s if version.nil?

  if @automatic_upgrades && version
    detected = VersionDetector.latest_safe_version(version)
    @version = Semver.new(detected || version)
  else
    @version = Semver.new(version)
  end

  # If there is no license key set, and the version if newer than 44.0.0, switch to GPL
  # as the license key is now required in all versions
  gpl if license_key.nil? && @version.major >= 44
  apply_integration_patches if apply_patches
end

#wproofreader(version: nil, cdn: nil, compress: !@disallow_inline_plugin_compression,, **config) ⇒ Object

Configure WProofreader plugin

Examples:

Basic configuration

wproofreader serviceId: 'your-service-ID',
           srcUrl: 'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js'

Parameters:

  • version (String, nil) (defaults to: nil) —

    Plugin version

  • cdn (String, nil) (defaults to: nil) —

    CDN URL

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

    Enable compression

  • config (Hash) —

    Plugin configuration



411
412
413
414
415
416
417
 
# File 'lib/ckeditor5/rails/presets/preset_builder.rb', line 411

def wproofreader(version: nil, cdn: nil, compress: !@disallow_inline_plugin_compression, **config)
  configure :wproofreader, config
  plugins do
    prepend(Plugins::WProofreaderSync.new(compress: compress))
    append(Plugins::WProofreader.new(version: version, cdn: cdn))
  end
end