Class VaadinCKEditorBuilder

java.lang.Object
com.wontlost.ckeditor.VaadinCKEditorBuilder
public class VaadinCKEditorBuilder extends Object
Builder for creating VaadinCKEditor instances.

This builder provides a fluent API for configuring CKEditor 5 instances with support for presets, custom plugins, dependency resolution, and more.

Quick Start

// Simplest usage - use a preset
VaadinCKEditor editor = VaadinCKEditor.withPreset(CKEditorPreset.STANDARD);

// Or use the builder directly
VaadinCKEditor editor = VaadinCKEditorBuilder.create()
    .withPreset(CKEditorPreset.STANDARD)
    .build();

Custom Plugins

Plugin dependencies are automatically resolved by default:

// IMAGE_CAPTION requires IMAGE - it will be added automatically
VaadinCKEditor editor = VaadinCKEditorBuilder.create()
    .withPlugins(CKEditorPlugin.BOLD, CKEditorPlugin.IMAGE_CAPTION)
    .withToolbar("bold", "|", "insertImage")
    .build();

Customizing Presets

VaadinCKEditor editor = VaadinCKEditorBuilder.create()
    .withPreset(CKEditorPreset.BASIC)
    .addPlugin(CKEditorPlugin.TABLE)           // Add table support
    .removePlugin(CKEditorPlugin.MEDIA_EMBED)  // Remove media embed
    .withLanguage("zh-cn")                     // Chinese UI
    .withTheme(CKEditorTheme.DARK)             // Dark theme
    .build();

View-Only Mode

// For displaying content without editing
VaadinCKEditor viewer = VaadinCKEditorBuilder.create()
    .withPreset(CKEditorPreset.BASIC)
    .withValue("<p>Content to display</p>")
    .withViewOnly()  // Read-only + hidden toolbar
    .build();

Enterprise Features

VaadinCKEditor editor = VaadinCKEditorBuilder.create()
    .withPreset(CKEditorPreset.FULL)
    .withErrorHandler(error -> {
        // Custom error handling
        logger.error("Editor error: " + error.getMessage());
        return false; // Let event propagate
    })
    .withHtmlSanitizer(HtmlSanitizer.withPolicy(SanitizationPolicy.STRICT))
    .withUploadHandler((context, stream) -> {
        // Handle file uploads
        String url = saveFile(context.getFileName(), stream);
        return CompletableFuture.completedFuture(new UploadResult(url));
    })
    .withFallbackMode(FallbackMode.TEXTAREA)
    .build();

Thread Safety

Builder instances are not thread-safe. Create a new builder for each editor.

See Also:

  • Method Details

    • create

      public static VaadinCKEditorBuilder create()
      Create a new builder instance.
      Returns:
      a new builder

    • withPreset

      public VaadinCKEditorBuilder withPreset(CKEditorPreset preset)
      Use preset configuration
      Parameters:
      preset - the preset to use
      Returns:
      this builder for chaining

    • withPlugins

      public VaadinCKEditorBuilder withPlugins(CKEditorPlugin... plugins)
      Set plugin list (override preset)
      Parameters:
      plugins - the plugins to use
      Returns:
      this builder for chaining

    • addPlugin

      public VaadinCKEditorBuilder addPlugin(CKEditorPlugin plugin)
      Add plugin
      Parameters:
      plugin - the plugin to add
      Returns:
      this builder for chaining

    • addPlugins

      public VaadinCKEditorBuilder addPlugins(CKEditorPlugin... plugins)
      Add multiple plugins
      Parameters:
      plugins - the plugins to add
      Returns:
      this builder for chaining

    • removePlugin

      public VaadinCKEditorBuilder removePlugin(CKEditorPlugin plugin)
      Remove plugin
      Parameters:
      plugin - the plugin to remove
      Returns:
      this builder for chaining

    • addCustomPlugin

      public VaadinCKEditorBuilder addCustomPlugin(CustomPlugin plugin)
      Add custom plugin
      Parameters:
      plugin - the custom plugin to add
      Returns:
      this builder for chaining

    • withToolbar

      public VaadinCKEditorBuilder withToolbar(String... items)
      Set toolbar items.

      Toolbar items can include:

      • Plugin command names (e.g., "bold", "italic", "insertTable")
      • Separator "|" to create visual groupings
      • Line break "-" to wrap to next line
      Parameters:
      items - the toolbar items (must not be null or empty)
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if items is null or empty

    • withType

      public VaadinCKEditorBuilder withType(CKEditorType type)
      Set editor type
      Parameters:
      type - the editor type
      Returns:
      this builder for chaining

    • withTheme

      public VaadinCKEditorBuilder withTheme(CKEditorTheme theme)
      Set theme mode.

      Available modes:

      • CKEditorTheme.AUTO (default) - Automatically syncs with Vaadin's Lumo theme. When Vaadin switches between light/dark mode, CKEditor follows automatically. Also respects OS-level dark mode preference if Vaadin doesn't have an explicit theme.
      • CKEditorTheme.LIGHT - Forces light theme regardless of Vaadin/OS settings.
      • CKEditorTheme.DARK - Forces dark theme regardless of Vaadin/OS settings.
      Parameters:
      theme - the theme mode to use
      Returns:
      this builder for chaining

    • withLanguage

      public VaadinCKEditorBuilder withLanguage(String language)
      Set language for editor UI and spell checking.

      Supported formats:

      • ISO 639-1 two-letter code: "en", "zh", "ja", "ko"
      • With region: "en-us", "zh-cn", "pt-br"
      Parameters:
      language - the language code (e.g., "en", "zh-cn")
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if language format is invalid

    • withFallbackMode

      public VaadinCKEditorBuilder withFallbackMode(FallbackEvent.FallbackMode mode)
      Set fallback mode for graceful degradation.
      Parameters:
      mode - the fallback mode
      Returns:
      this builder for chaining

    • withErrorHandler

      public VaadinCKEditorBuilder withErrorHandler(ErrorHandler handler)
      Set error handler for custom error handling.
      Parameters:
      handler - the error handler
      Returns:
      this builder for chaining

    • withHtmlSanitizer

      public VaadinCKEditorBuilder withHtmlSanitizer(HtmlSanitizer sanitizer)
      Set HTML sanitizer for content cleaning.
      Parameters:
      sanitizer - the HTML sanitizer
      Returns:
      this builder for chaining

    • withUploadHandler

      public VaadinCKEditorBuilder withUploadHandler(UploadHandler handler)
      Set upload handler for file uploads.
      Parameters:
      handler - the upload handler
      Returns:
      this builder for chaining

    • withUploadConfig

      public VaadinCKEditorBuilder withUploadConfig(UploadHandler.UploadConfig config)
      Set upload configuration for file uploads. Configures file size limits and allowed MIME types.

      Example:

      VaadinCKEditor editor = VaadinCKEditor.create()
    .withUploadHandler(myHandler)
    .withUploadConfig(new UploadHandler.UploadConfig()
        .setMaxFileSize(5 * 1024 * 1024) // 5MB
        .setAllowedMimeTypes("image/jpeg", "image/png", "image/gif"))
    .build();
      Parameters:
      config - the upload configuration
      Returns:
      this builder for chaining

    • withValue

      public VaadinCKEditorBuilder withValue(String value)
      Set initial content
      Parameters:
      value - the initial HTML content
      Returns:
      this builder for chaining

    • readOnly

      public VaadinCKEditorBuilder readOnly(boolean readOnly)
      Set read-only mode.
      Parameters:
      readOnly - whether the editor should be read-only
      Returns:
      this builder for chaining

    • withReadOnly

      public VaadinCKEditorBuilder withReadOnly(boolean readOnly)
      Convenience method for setting read-only mode. Alias for readOnly(boolean).
      Parameters:
      readOnly - whether the editor should be read-only
      Returns:
      this builder for chaining

    • withViewOnly

      public VaadinCKEditorBuilder withViewOnly()
      Configure editor for view-only mode.

      This is a convenience method that sets:

      • Read-only mode enabled
      • Toolbar hidden
      • Fallback mode to READ_ONLY

      Use this for displaying content without editing capabilities.

      Returns:
      this builder for chaining

    • withHideToolbar

      public VaadinCKEditorBuilder withHideToolbar(boolean hide)
      Set whether to hide the toolbar.
      Parameters:
      hide - true to hide toolbar, false to show
      Returns:
      this builder for chaining

    • withAutosave

      public VaadinCKEditorBuilder withAutosave(Consumer<String> callback, int waitingTime)
      Enable autosave with callback and waiting time.
      Parameters:
      callback - the callback to invoke when autosave triggers
      waitingTime - waiting time in milliseconds (100-60000)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if waitingTime is out of range

    • withConfig

      public VaadinCKEditorBuilder withConfig(CKEditorConfig config)
      Set configuration
      Parameters:
      config - the editor configuration
      Returns:
      this builder for chaining

    • withWidth

      public VaadinCKEditorBuilder withWidth(String width)
      Set width
      Parameters:
      width - the width (e.g., "100%", "500px")
      Returns:
      this builder for chaining

    • withHeight

      public VaadinCKEditorBuilder withHeight(String height)
      Set height
      Parameters:
      height - the height (e.g., "400px", "100%")
      Returns:
      this builder for chaining

    • withDependencyMode

      public VaadinCKEditorBuilder withDependencyMode(VaadinCKEditorBuilder.DependencyMode mode)
      Set dependency resolution mode.

      Available modes:

      Parameters:
      mode - the dependency resolution mode
      Returns:
      this builder

    • withLicenseKey

      public VaadinCKEditorBuilder withLicenseKey(String licenseKey)
      Set CKEditor license key for premium features.

      Premium features require a valid license key from CKEditor. Get your license key at: https://ckeditor.com/pricing

      Usage example:

      VaadinCKEditor editor = VaadinCKEditorBuilder.create()
    .withPreset(CKEditorPreset.STANDARD)
    .withLicenseKey("your-license-key-here")
    .addCustomPlugin(CustomPlugin.fromPremium("ExportPdf"))
    .build();

      Note: You must also install the premium features package in your frontend:

      npm install ckeditor5-premium-features
      Parameters:
      licenseKey - the CKEditor license key
      Returns:
      this builder for chaining
      See Also:

    • build

      public VaadinCKEditor build()
      Build and initialize the configured VaadinCKEditor instance.

      This method performs the following steps:

      1. Collects plugins from preset and additional plugins
      2. Removes any plugins marked for removal
      3. Resolves plugin dependencies based on VaadinCKEditorBuilder.DependencyMode
      4. Configures toolbar (custom or from preset)
      5. Applies configuration settings
      6. Initializes the editor component

      Note: The builder can only be used once. After calling build(), create a new builder for additional editors.

      Returns:
      the fully configured and initialized VaadinCKEditor instance
      Throws:
      IllegalStateException - if VaadinCKEditorBuilder.DependencyMode.STRICT is used and plugin dependencies are not satisfied

    • getResolvedPlugins

      public Set<CKEditorPlugin> getResolvedPlugins()
      Get the resolved plugins that would be used with current configuration. Useful for debugging or inspection before building.
      Returns:
      set of plugins that would be included

    • getMissingDependencies

      public Map<CKEditorPlugin, Set<CKEditorPlugin>> getMissingDependencies()
      Get missing dependencies for current plugin configuration. Useful for understanding what dependencies would be auto-resolved.
      Returns:
      map of plugins to their missing dependencies

    • getMissingPremiumDependencies

      public Map<String, Set<CKEditorPlugin>> getMissingPremiumDependencies()
      Get missing dependencies for premium plugins in current configuration. Useful for understanding what premium plugin dependencies would be auto-resolved.
      Returns:
      map of premium plugin names to their missing dependencies