Class MjmlConfiguration.Builder

java.lang.Object
dev.jcputney.mjml.MjmlConfiguration.Builder
Enclosing class:
MjmlConfiguration
public static class MjmlConfiguration.Builder extends Object
Builder for constructing MjmlConfiguration instances. Use MjmlConfiguration.builder() to obtain an instance.

  • Method Details

    • language

      public MjmlConfiguration.Builder language(String language)
      Sets the language code for the HTML document (e.g., "en"). Defaults to "und" (undetermined).
      Parameters:
      language - the language code
      Returns:
      this builder

    • direction

      public MjmlConfiguration.Builder direction(Direction direction)
      Sets the text direction using a Direction enum value.
      Parameters:
      direction - the text direction
      Returns:
      this builder

    • direction

      public MjmlConfiguration.Builder direction(String direction)
      Sets the text direction from a string ("ltr", "rtl", or "auto", case-insensitive).
      Parameters:
      direction - the direction string
      Returns:
      this builder

    • includeResolver

      public MjmlConfiguration.Builder includeResolver(IncludeResolver resolver)
      Sets the include resolver used to resolve mj-include paths.

      Caching note: The renderer caches component registries keyed by configuration. Because Java lambdas do not support structural equality, each distinct lambda instance produces a cache miss. For best cache effectiveness, store the resolver in a field and reuse the same MjmlConfiguration instance, or use the instance API via MjmlRenderer.create(MjmlConfiguration).

      Parameters:
      resolver - the include resolver
      Returns:
      this builder

    • registerComponent

      public MjmlConfiguration.Builder registerComponent(String tagName, ComponentFactory factory)
      Registers a custom component factory for the given MJML tag name.
      Parameters:
      tagName - the MJML tag name (e.g., "mj-custom")
      factory - the factory that creates component instances
      Returns:
      this builder

    • registerContainerComponent

      public MjmlConfiguration.Builder registerContainerComponent(String tagName, ContainerComponentFactory factory)
      Registers a custom container component factory for the given tag name. Container components receive a ComponentRegistry as a fourth argument, allowing them to instantiate and render child MJML components.

      Container component registrations are applied after standard custom components, so they can override both built-in and previously registered tags.

      Parameters:
      tagName - the MJML tag name (e.g., "mj-card")
      factory - the factory that creates component instances
      Returns:
      this builder

    • sanitizeOutput

      public MjmlConfiguration.Builder sanitizeOutput(boolean sanitize)
      Controls whether HTML special characters in attribute values are escaped in rendered output. When enabled (the default), characters like ", <, >, and & are escaped to prevent cross-site scripting (XSS) attacks.

      WARNING: Disabling output sanitization (sanitizeOutput(false)) allows raw, unescaped attribute values in the generated HTML. This creates a significant XSS risk if any MJML attribute values originate from user input or untrusted sources.

      Only disable sanitization when all attribute values in the MJML template come from trusted, developer-controlled sources (e.g., static templates with no dynamic content).

      Parameters:
      sanitize - true to escape attribute values (default), false to output raw attribute values
      Returns:
      this builder

    • maxInputSize

      public MjmlConfiguration.Builder maxInputSize(int maxInputSize)
      Sets the maximum allowed input size in characters (not bytes). Inputs exceeding this limit are rejected before processing. Default is 1048576 (approximately 1 MB for ASCII).
      Parameters:
      maxInputSize - maximum number of characters allowed
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if maxInputSize is not positive (validated at build time)

    • maxNestingDepth

      public MjmlConfiguration.Builder maxNestingDepth(int maxNestingDepth)
      Sets the maximum allowed nesting depth for MJML elements. Exceeding this depth during parsing or rendering throws an exception. Default is 100.
      Parameters:
      maxNestingDepth - the maximum nesting depth
      Returns:
      this builder

    • maxIncludeDepth

      public MjmlConfiguration.Builder maxIncludeDepth(int maxIncludeDepth)
      Sets the maximum allowed include nesting depth for mj-include.
      Parameters:
      maxIncludeDepth - the maximum include nesting depth
      Returns:
      this builder

    • contentSanitizer

      public MjmlConfiguration.Builder contentSanitizer(ContentSanitizer contentSanitizer)
      Sets an optional content sanitizer that is applied to the inner HTML of <mj-text>, <mj-button>, and <mj-raw> elements. Pass null to disable (the default).

      Caching note: The renderer caches component registries keyed by configuration. Because Java lambdas do not support structural equality, each distinct lambda instance produces a cache miss. For best cache effectiveness, store the sanitizer in a field and reuse the same MjmlConfiguration instance, or use the instance API via MjmlRenderer.create(MjmlConfiguration).

      Parameters:
      contentSanitizer - the content sanitizer, or null to disable
      Returns:
      this builder

    • build

      public MjmlConfiguration build()
      Builds and returns a new MjmlConfiguration with the current builder settings.
      Returns:
      the constructed configuration
      Throws:
      NullPointerException - if language or direction is null
      IllegalArgumentException - if maxInputSize, maxNestingDepth, or maxIncludeDepth is not positive