Extending Thymeleaf

/** Handles {@code bookshelf:rating="${book.rating}"}: replaces the body with "Rated n of 5". */
public class RatingAttributeTagProcessor extends AbstractAttributeTagProcessor {

    private static final String ATTR_NAME = "rating";
    private static final int PRECEDENCE = 1300;

    public RatingAttributeTagProcessor(final String dialectPrefix) {
        super(
            TemplateMode.HTML, // only HTML templates
            dialectPrefix,     // prefix used to build the attribute name
            null,              // no element name: match any element
            false,             // no prefix on the element name
            ATTR_NAME,         // attribute name, so bookshelf:rating
            true,              // apply the dialect prefix to the attribute name
            PRECEDENCE,        // precedence inside the dialect
            true);             // remove the attribute from the output
    }

    @Override
    protected void doProcess(
            final ITemplateContext context, final IProcessableElementTag tag,
            final AttributeName attributeName, final String attributeValue,
            final IElementTagStructureHandler structureHandler) {

        // Evaluate the attribute value as a Thymeleaf Standard Expression
        final var parser = StandardExpressions.getExpressionParser(context.getConfiguration());
        final IStandardExpression expression = parser.parseExpression(context, attributeValue);
        final Object value = expression.execute(context);

        final int rating = value instanceof Number n ? Math.max(0, Math.min(5, n.intValue())) : 0;
        final String message = context.getMessage(
                RatingAttributeTagProcessor.class, "rating.label", new Object[] {rating}, true);

        // Text set as the body is not escaped for us, and false means "do not process it again"
        structureHandler.setBody(HtmlEscape.escapeHtml5(message), false);
    }
}

rating.label=Rated {0} of 5

rating.label=Valorado con {0} de 5

/** Handles {@code bookshelf:stock="${book.copies}"}: appends a CSS class to the host element. */
public class StockAttributeTagProcessor extends AbstractAttributeTagProcessor {

    public StockAttributeTagProcessor(final String dialectPrefix) {
        super(TemplateMode.HTML, dialectPrefix, null, false, "stock", true, 1200, true);
    }

    @Override
    protected void doProcess(
            final ITemplateContext context, final IProcessableElementTag tag,
            final AttributeName attributeName, final String attributeValue,
            final IElementTagStructureHandler structureHandler) {

        final var parser = StandardExpressions.getExpressionParser(context.getConfiguration());
        final Object value = parser.parseExpression(context, attributeValue).execute(context);
        final int copies = value instanceof Number n ? n.intValue() : 0;

        final String cssClass = copies <= 0 ? "out-of-stock" : copies < 3 ? "low-stock" : "in-stock";

        // The tag is immutable: ask the engine to set the attribute, keeping any existing classes
        final String current = tag.getAttributeValue("class");
        structureHandler.setAttribute("class", current == null ? cssClass : current + " " + cssClass);
    }
}

<li class="book low-stock">x</li>

/** Handles {@code <bookshelf:new-arrivals limit="2"/>}: replaces the element with a list of titles. */
public class NewArrivalsElementTagProcessor extends AbstractElementTagProcessor {

    private static final String TAG_NAME = "new-arrivals";
    private static final int DEFAULT_LIMIT = 3;
    private static final int MAX_LIMIT = 10;

    public NewArrivalsElementTagProcessor(final String dialectPrefix) {
        super(
            TemplateMode.HTML, // only HTML templates
            dialectPrefix,     // prefix used to build the element name
            TAG_NAME,          // element name, so bookshelf:new-arrivals
            true,              // apply the dialect prefix to the element name
            null,              // no attribute name: match by element only
            false,             // no prefix on the attribute name
            1000);             // precedence inside the dialect
    }

    @Override
    protected void doProcess(
            final ITemplateContext context, final IProcessableElementTag tag,
            final IElementTagStructureHandler structureHandler) {

        // A Spring bean, reached through the application context the engine runs in
        final ApplicationContext applicationContext = SpringContextUtils.getApplicationContext(context);
        final List<Book> books = applicationContext.getBean(BookRepository.class).findAll();

        // A plain literal attribute, parsed defensively; it is not evaluated as an expression
        int limit = DEFAULT_LIMIT;
        final String requested = tag.getAttributeValue("limit");
        if (requested != null && requested.matches("\\d{1,2}")) {
            limit = Math.min(Integer.parseInt(requested), MAX_LIMIT);
        }

        // A model is a flat sequence of events, so open and close tags are created one by one
        final IModelFactory modelFactory = context.getModelFactory();
        final IModel model = modelFactory.createModel();
        model.add(modelFactory.createOpenElementTag("ul", "class", "new-arrivals"));
        for (final Book book : books.stream().limit(limit).toList()) {
            model.add(modelFactory.createOpenElementTag("li"));
            model.add(modelFactory.createText(HtmlEscape.escapeHtml5(book.getTitle())));
            model.add(modelFactory.createCloseElementTag("li"));
        }
        model.add(modelFactory.createCloseElementTag("ul"));

        // false: the generated events must not be processed again by the engine
        structureHandler.replaceWith(model, false);
    }
}

/** Handles {@code bookshelf:promoted}: adds a ribbon right after the element, only inside .catalog. */
public class PromotedModelProcessor extends AbstractAttributeModelProcessor {

    private static final String ATTR_NAME = "promoted";

    public PromotedModelProcessor(final String dialectPrefix) {
        super(TemplateMode.HTML, dialectPrefix, null, false, ATTR_NAME, true, 1100, true);
    }

    @Override
    protected void doProcess(
            final ITemplateContext context, final IModel model,
            final AttributeName attributeName, final String attributeValue,
            final IElementModelStructureHandler structureHandler) {

        if (!insideCatalog(context)) {
            throw new TemplateProcessingException(
                    "bookshelf:" + ATTR_NAME + " can only be used inside an element with class \"catalog\"");
        }

        // The model holds the whole element: open tag, body and close tag. Appending puts the
        // new events after the element's own close tag.
        final IModelFactory modelFactory = context.getModelFactory();
        model.add(modelFactory.createOpenElementTag("span", "class", "ribbon"));
        model.add(modelFactory.createText("Promoted"));
        model.add(modelFactory.createCloseElementTag("span"));
    }

    private static boolean insideCatalog(final ITemplateContext context) {
        // The last entry of the element stack is the element being processed
        final List<IProcessableElementTag> stack = context.getElementStack();
        for (int i = stack.size() - 2; i >= 0; i--) {
            final IProcessableElementTag ancestor = stack.get(i);
            if (ancestor instanceof IOpenElementTag) {
                final String css = ancestor.getAttributeValue("class");
                if (css != null && (" " + css + " ").contains(" catalog ")) {
                    return true;
                }
            }
        }
        return false;
    }
}

<div class="catalog"><p>x</p><span class="ribbon">Promoted</span></div>

org.thymeleaf.exceptions.TemplateProcessingException: bookshelf:promoted can only be used inside an element with class "catalog" (template: "<p bookshelf:promoted>x</p>" - line 1, col 4)

/** Removes HTML comments that start with "internal:" from the output. */
public class InternalCommentProcessor extends AbstractCommentProcessor {

    public InternalCommentProcessor() {
        super(TemplateMode.HTML, 900);
    }

    @Override
    protected void doProcess(
            final ITemplateContext context, final IComment comment,
            final ICommentStructureHandler structureHandler) {
        if (comment.getContent().stripLeading().startsWith("internal:")) {
            structureHandler.removeComment();
        }
    }
}

/** Writes a comment at the very end of every HTML template that goes through the engine. */
public class RenderedByBoundariesProcessor extends AbstractTemplateBoundariesProcessor {

    public RenderedByBoundariesProcessor() {
        super(TemplateMode.HTML, 800);
    }

    @Override
    public void doProcessTemplateStart(
            final ITemplateContext context, final ITemplateStart templateStart,
            final ITemplateBoundariesStructureHandler structureHandler) {
        // nothing to do at the start
    }

    @Override
    public void doProcessTemplateEnd(
            final ITemplateContext context, final ITemplateEnd templateEnd,
            final ITemplateBoundariesStructureHandler structureHandler) {
        structureHandler.insert("<!-- rendered with the bookshelf dialect -->", false);
    }
}

final var parser = StandardExpressions.getExpressionParser(context.getConfiguration());
final IStandardExpression expression = parser.parseExpression(context, attributeValue);
final Object value = expression.execute(context);

class WriteProcessor extends AbstractAttributeTagProcessor {

    private final boolean escape;

    WriteProcessor(String prefix, String name, boolean escape) {
        super(TemplateMode.HTML, prefix, null, false, name, true, 1000, true);
        this.escape = escape;
    }

    @Override
    protected void doProcess(ITemplateContext context, IProcessableElementTag tag,
            AttributeName attributeName, String attributeValue, IElementTagStructureHandler handler) {
        final Object result = StandardExpressions.getExpressionParser(context.getConfiguration())
                .parseExpression(context, attributeValue).execute(context);
        final String text = String.valueOf(result);
        handler.setBody(escape ? HtmlEscape.escapeHtml5(text) : text, false);
    }
}

<p>Tom & <b>Jerry</b></p>
<p>Tom &amp; &lt;b&gt;Jerry&lt;/b&gt;</p>

/** The object behind the {@code #bookshelf} expression object. */
public class BookshelfExpressions {

    private static final int RECENT_DAYS = 30;

    private final Clock clock;

    public BookshelfExpressions(final Clock clock) {
        this.clock = clock;
    }

    /** 9780134685991 becomes 978-0-13-468599-1; anything that is not 13 digits is returned as is. */
    public String isbn(final String digits) {
        if (digits == null || !digits.matches("\\d{13}")) {
            return digits;
        }
        return digits.substring(0, 3) + "-" + digits.charAt(3) + "-" + digits.substring(4, 6) + "-"
                + digits.substring(6, 12) + "-" + digits.charAt(12);
    }

    /** True when the date is no more than 30 days before today, as told by the configured clock. */
    public boolean isRecent(final LocalDate published) {
        if (published == null) {
            return false;
        }
        final long days = ChronoUnit.DAYS.between(published, LocalDate.now(this.clock));
        return days >= 0 && days <= RECENT_DAYS;
    }
}

public class BookshelfExpressionObjectFactory implements IExpressionObjectFactory {

    static final String NAME = "bookshelf";

    @Override
    public Set<String> getAllExpressionObjectNames() {
        return Set.of(NAME);
    }

    @Override
    public Object buildObject(final IExpressionContext context, final String expressionObjectName) {
        if (!NAME.equals(expressionObjectName)) {
            return null;
        }
        // Execution attributes are shared by every processor and expression object of the engine
        final Clock clock = (Clock) context.getConfiguration()
                .getExecutionAttributes().get(BookshelfDialect.CLOCK_ATTRIBUTE);
        return new BookshelfExpressions(clock);
    }

    @Override
    public boolean isCacheable(final String expressionObjectName) {
        // The object has no per-evaluation state, so one instance can serve the whole execution
        return true;
    }
}

<code th:text="${#bookshelf.isbn(b.isbn)}">978-0-00-000000-0</code>
<em th:if="${#bookshelf.isRecent(b.published)}">New</em>

final Clock clock = (Clock) context.getConfiguration()
        .getExecutionAttributes().get(BookshelfDialect.CLOCK_ATTRIBUTE);

/** Post-processing handler: collapses every whitespace-only text event into a single newline. */
public class TidyWhitespaceHandler extends AbstractTemplateHandler {

    @Override
    public void handleText(final IText text) {
        final String content = text.getText();
        if (content.length() > 1 && content.isBlank()) {
            super.handleText(getContext().getModelFactory().createText("\n"));
        } else {
            super.handleText(text);
        }
    }
}

/** Pre-processing handler: sees every event before the processors do. Here it only logs. */
public class TemplateNameHandler extends AbstractTemplateHandler {

    private static final Logger LOGGER = LoggerFactory.getLogger(TemplateNameHandler.class);

    @Override
    public void handleTemplateStart(final ITemplateStart templateStart) {
        LOGGER.debug("Processing template {}", getContext().getTemplateData().getTemplate());
        super.handleTemplateStart(templateStart);
    }
}

public class BookshelfDialect extends AbstractProcessorDialect
        implements IPreProcessorDialect, IPostProcessorDialect,
                   IExpressionObjectDialect, IExecutionAttributeDialect {

    public static final String DIALECT_NAME = "Bookshelf Dialect";
    public static final String DEFAULT_PREFIX = "bookshelf";
    static final String CLOCK_ATTRIBUTE = "bookshelf.clock";

    private final Clock clock;

    public BookshelfDialect() {
        this(Clock.systemDefaultZone());
    }

    public BookshelfDialect(final Clock clock) {
        // The same processor precedence as the Standard Dialect lets the executions interleave
        super(DIALECT_NAME, DEFAULT_PREFIX, StandardDialect.PROCESSOR_PRECEDENCE);
        this.clock = clock;
    }

    @Override
    public Set<IProcessor> getProcessors(final String dialectPrefix) {
        return Set.of(
                new RatingAttributeTagProcessor(dialectPrefix),
                new StockAttributeTagProcessor(dialectPrefix),
                new NewArrivalsElementTagProcessor(dialectPrefix),
                new PromotedModelProcessor(dialectPrefix),
                new InternalCommentProcessor(),
                new RenderedByBoundariesProcessor(),
                // removes the xmlns:bookshelf declaration we add so that IDEs stop complaining
                new StandardXmlNsTagProcessor(TemplateMode.HTML, dialectPrefix));
    }

    @Override
    public int getDialectPreProcessorPrecedence() {
        return StandardDialect.PROCESSOR_PRECEDENCE;
    }

    @Override
    public Set<IPreProcessor> getPreProcessors() {
        return Set.of(new PreProcessor(TemplateMode.HTML, TemplateNameHandler.class, 1000));
    }

    @Override
    public int getDialectPostProcessorPrecedence() {
        return StandardDialect.PROCESSOR_PRECEDENCE;
    }

    @Override
    public Set<IPostProcessor> getPostProcessors() {
        return Set.of(new PostProcessor(TemplateMode.HTML, TidyWhitespaceHandler.class, 1000));
    }

    @Override
    public IExpressionObjectFactory getExpressionObjectFactory() {
        return new BookshelfExpressionObjectFactory();
    }

    @Override
    public Map<String, Object> getExecutionAttributes() {
        return Map.of(CLOCK_ATTRIBUTE, this.clock);
    }
}

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" xmlns:bookshelf="http://www.example.com/bookshelf">
<body>
<!--internal: remove before publishing -->
<!-- visible comment -->
<section class="catalog">
  <h1>Catalog</h1>
  <bookshelf:new-arrivals limit="2"/>
  <ul>
    <li th:each="b : ${books}" class="book" bookshelf:stock="${b.copies}">
      <span th:text="${b.title}">Title</span>
      <span bookshelf:rating="${b.rating}">Rated 5 of 5</span>
      <code th:text="${#bookshelf.isbn(b.isbn)}">978-0-00-000000-0</code>
      <em th:if="${#bookshelf.isRecent(b.published)}">New</em>
    </li>
  </ul>
  <p bookshelf:promoted>Featured this week</p>
</section>
</body>
</html>

@Controller
public class ShelfController {

    public record Shelved(String title, int rating, int copies, String isbn, LocalDate published) { }

    @GetMapping("/extension/shelf")
    String shelf(Model model) {
        model.addAttribute("books", List.of(
                new Shelved("Dune", 5, 4, "9780441013593", LocalDate.of(2026, 9, 20)),
                new Shelved("Tom & Jerry <b>", 3, 1, "9780134685991", LocalDate.of(1999, 1, 1)),
                new Shelved("Ubik", 9, 0, "not-an-isbn", null)));
        return "extension/shelf";
    }
}

<!DOCTYPE html>
<html>
<body>

<!-- visible comment -->
<section class="catalog">
<h1>Catalog</h1>
<ul class="new-arrivals"><li>Dune</li><li>Emma &lt;i&gt;</li></ul>
<ul>
<li class="book in-stock">
<span>Dune</span>
<span>Rated 5 of 5</span>
<code>978-0-44-101359-3</code>
<em>New</em>
</li>
<li class="book low-stock">
<span>Tom &amp; Jerry &lt;b&gt;</span>
<span>Rated 3 of 5</span>
<code>978-0-13-468599-1</code>

</li>
<li class="book out-of-stock">
<span>Ubik</span>
<span>Rated 5 of 5</span>
<code>not-an-isbn</code>

</li>
</ul>
<p>Featured this week</p><span class="ribbon">Promoted</span>
</section>
</body>
</html>
<!-- rendered with the bookshelf dialect -->

<span>Valorado con 5 de 5</span>
<span>Valorado con 3 de 5</span>
<span>Valorado con 5 de 5</span>

class BookshelfDialectTest {

    private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-10-08T10:00:00Z"), ZoneOffset.UTC);

    private TemplateEngine engine() {
        final TemplateEngine engine = new TemplateEngine();
        engine.setTemplateResolver(new StringTemplateResolver());
        engine.addDialect(new BookshelfDialect(CLOCK));
        return engine;
    }

    @Test
    void ratingIsLimitedToFive() {
        final Context ctx = new Context(Locale.ENGLISH);
        ctx.setVariable("rating", 9);
        final String html = engine().process("<p bookshelf:rating=\"${rating}\">x</p>", ctx);
        assertThat(html).contains("<p>Rated 5 of 5</p>");
    }

    @Test
    void expressionObjectUsesTheClock() {
        final Context ctx = new Context(Locale.ENGLISH);
        ctx.setVariable("d", LocalDate.of(2026, 10, 1));
        final String html = engine().process(
                "<p th:text=\"${#bookshelf.isbn('9780134685991')} + ' ' + ${#bookshelf.isRecent(d)}\"></p>", ctx);
        assertThat(html).contains("978-0-13-468599-1 true");
    }

    @Test
    void promotedOutsideCatalogFails() {
        assertThatThrownBy(() -> engine().process("<p bookshelf:promoted>x</p>", new Context()))
                .hasRootCauseInstanceOf(TemplateProcessingException.class)
                .rootCause().hasMessageContaining("catalog");
    }
}

@SpringBootTest
@AutoConfigureMockMvc
@WithMockUser
@Import(ShelfPageTest.FixedClockConfig.class)
class ShelfPageTest {

    @TestConfiguration(proxyBeanMethods = false)
    static class FixedClockConfig {
        @Bean
        BookshelfDialect bookshelfDialect() {
            return new BookshelfDialect(Clock.fixed(Instant.parse("2026-10-08T10:00:00Z"), ZoneOffset.UTC));
        }
    }

    @Autowired MockMvc mvc;
    @Autowired SpringTemplateEngine engine;

    @Test
    void dialectIsRegisteredByBoot() {
        assertThat(engine.getDialects()).anyMatch(d -> d instanceof BookshelfDialect);
    }

    @Test
    void rendersTheShelf() throws Exception {
        mvc.perform(get("/extension/shelf").locale(Locale.ENGLISH))
                .andExpect(status().isOk())
                .andExpect(content().string(containsString("<span>Rated 5 of 5</span>")))
                .andExpect(content().string(not(containsString("internal:"))));
    }
}