Class HtmlBuilder

java.lang.Object
dev.jcputney.mjml.util.HtmlBuilder
public final class HtmlBuilder extends Object
Fluent HTML builder that manages indentation automatically. Designed for use in MJML component render() methods to replace manual StringBuilder with hardcoded indentation strings.

Usage: 

HtmlBuilder html = new HtmlBuilder();
html.open("table", attrs("border", "0", "role", "presentation"));
html.open("tbody");
html.open("tr");
html.open("td", attrs("style", buildStyle(styles)));
html.text("content");
html.close("td");
html.close("tr");
html.close("tbody");
html.close("table");
return html.toString();

  • Field Details

    • PRESENTATION_TABLE_ATTRS

      public static final Map<String,String> PRESENTATION_TABLE_ATTRS
      Base attributes shared by presentation-only tables in MJML email rendering: border="0", cellpadding="0", cellspacing="0", role="presentation". Copy this map and add additional attributes as needed (e.g. style, width).

  • Constructor Details

    • HtmlBuilder

      public HtmlBuilder()
      Creates a builder at indent depth 0.

    • HtmlBuilder

      public HtmlBuilder(int startingIndent)
      Creates a builder with the given starting indent depth in spaces.

  • Method Details

    • open

      public HtmlBuilder open(String tag, String attrs)
      Opens a tag with attributes, writes a newline, and increases indent. Produces: {indent}<tag attrs>\n

    • open

      public HtmlBuilder open(String tag)
      Opens a tag with no attributes.

    • close

      public HtmlBuilder close(String tag)
      Closes a tag: decreases indent, writes {indent}</tag>\n.

    • openInline

      public HtmlBuilder openInline(String tag, String attrs)
      Opens a tag on the current line WITHOUT a trailing newline. Used when content follows on the same line. Produces: {indent}<tag attrs>

    • openInline

      public HtmlBuilder openInline(String tag)
      Opens an inline tag with no attributes.

    • closeInline

      public void closeInline(String tag)
      Appends a closing tag for the specified inline element to the internal StringBuilder.
      Parameters:
      tag - the name of the inline element for which the closing tag should be appended

    • closeInlineLn

      public void closeInlineLn(String tag)
      Appends a closing tag with a newline character to the StringBuilder.
      Parameters:
      tag - the name of the tag to be closed

    • text

      public HtmlBuilder text(String content)
      Appends raw text on the current line (no indent, no newline).

    • line

      public HtmlBuilder line(String content)
      Appends indented text followed by a newline.

    • raw

      public HtmlBuilder raw(String html)
      Appends raw HTML at the current indent level, followed by a newline. Only the first line gets the indentation prefix.

    • rawVerbatim

      public HtmlBuilder rawVerbatim(String html)
      Appends raw HTML verbatim with NO indentation or newline added. Used for MSO conditionals, VML, and preformatted content.

    • mso

      public HtmlBuilder mso(Runnable block)
      Wraps the output of a builder block in MSO conditional comments. Everything written by the block appears between <!--[if mso | IE]> and <![endif]-->, followed by a newline.

    • mso

      public HtmlBuilder mso(String content)
      Wraps a string in MSO conditional comments followed by a newline. Shorthand for simple MSO content that doesn't need builder calls.

    • attrs

      public static String attrs(Map<String,String> attributes, String... trailingKeys)
      Builds a sorted attribute string from a map. Keys are sorted alphabetically, with any trailingKeys placed at the end in the order specified. Null or empty values cause the attribute to be omitted, except for attributes in ALWAYS_EMIT which are always emitted. Produces: key1="val1" key2="val2" (note leading space).

      Values are NOT escaped — callers must escape via escapeAttr() before passing.

      Parameters:
      attributes - the attribute map to render
      trailingKeys - attribute names that should appear after all alphabetically-sorted keys

    • unsortedAttrs

      public static String unsortedAttrs(Map<String,String> attributes)
      Builds an unsorted attribute string from a map of key-value pairs. Keys are appended with their corresponding values in the order they are provided in the map. Null or empty values are omitted, except for keys in ALWAYS_EMIT, which are always included even if their values are empty.

      Values are NOT escaped — callers must escape via escapeAttr() before passing.

      Parameters:
      attributes - a map of attribute names and their values; keys represent attribute names and values represent attribute values
      Returns:
      a space-separated string of unsorted attributes in the format key1="value1" key2="value2". An empty string is returned if the input map is null or empty.

    • attrs

      public static String attrs(String... keyValuePairs)
      Builds an attribute string from key/value pairs. Null or empty values cause the attribute to be omitted, except for attributes in ALWAYS_EMIT which are always emitted. Produces: key1="val1" key2="val2" (note leading space).

      Values are NOT escaped — callers must escape via escapeAttr() before passing.

      Note: this overload preserves insertion order. Use attrs(Map, String...) (Map)} for automatic alphabetical sorting.

    • notMso

      public void notMso(Runnable block)
      Wraps the output of a builder block in non-MSO conditional comments (<!--[if !mso]><!-->...<!--<![endif]-->). Content is visible to all clients except Outlook desktop. Followed by a newline.

    • notMsoIE

      public void notMsoIE(Runnable block)
      Wraps the output of a builder block in non-MSO/IE conditional comments (<!--[if !mso | IE]><!-->...<!--<![endif]-->). Content is hidden from both Outlook desktop and IE. Followed by a newline.

    • selfClose

      public void selfClose(String tag, String attrs)
      Creates a self-closing HTML tag with optional attributes. The method appends the tag at the current indentation level, includes the specified attributes if provided, and appends a newline.
      Parameters:
      tag - the HTML tag name to be self-closed
      attrs - the attribute string to include within the tag; if null or empty, no attributes are added

    • wrap

      public HtmlBuilder wrap(String tag, String attrs, Runnable block)
      Opens a tag with attributes, executes the block, and closes the tag. Manages indentation like wrap(String, Runnable).
      Parameters:
      tag - the HTML tag name
      attrs - the attribute string (from attrs(Map, String...))
      block - the block that produces the tag's inner content

    • newline

      public HtmlBuilder newline()
      Appends a newline character to the internal string builder and returns the current instance of the HtmlBuilder.
      Returns:
      this HtmlBuilder instance for method chaining

    • indent

      public void indent()
      Increases the current indentation depth by a predefined size. This method modifies the internal state of the HtmlBuilder to reflect a deeper nesting level for subsequent content. The increase in depth is determined by the constant INDENT_SIZE.

    • outdent

      public void outdent()
      Reduces the current indentation level by decreasing the depth. Ensures that the depth does not fall below zero. The decrease is determined by the constant INDENT_SIZE.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • table

      public HtmlBuilder table(Runnable block)
      Wraps content in a presentation table (border="0" cellpadding="0" cellspacing="0" role="presentation" width="100%").
      Parameters:
      block - the block that produces the table's inner content

    • table

      public HtmlBuilder table(String attrs, Runnable block)
      Creates an HTML table element with the specified attributes and content block.
      Parameters:
      attrs - the attributes to be applied to the table element
      block - a runnable block that defines the content of the table
      Returns:
      an HtmlBuilder instance with the table element wrapped

    • table

      public HtmlBuilder table(Map<String,String> attrs, Runnable block)
      Wraps content in an HTML `<table>` tag, applying attributes and executing the provided block within the table. Adds default presentation table attributes unless overridden by the input.
      Parameters:
      attrs - a map of attributes to be applied to the `` tag; keys represent attribute names and values represent attribute values
      block - the block that produces the table's inner content
      Returns:
      this HtmlBuilder instance for method chaining

    • wrap

      public HtmlBuilder wrap(String tag, Runnable block)
      Wraps the output of a Runnable block with the specified HTML tag. Indents the block's content appropriately and closes the tag after execution of the block.
      Parameters:
      tag - the HTML tag to wrap the block with
      block - the block of content to be wrapped in the specified tag
      Returns:
      this HtmlBuilder instance for method chaining

    • attrIf

      public static String attrIf(String key, String value)
      Conditionally adds a single attribute if the value is non-null and non-empty. Returns key="value" (with leading space) or empty string.

      • Copyright © 2026. All rights reserved.