Architecture¶
Looma is built so that the common change, adding or fixing a directive, touches one file.
The pipeline¶
| Package | Role | May depend on |
|---|---|---|
io.github.djamelkorei.looma.spi |
The public contract: Directive, Node, ParseContext, RenderContext, Expr, Syntax. |
nothing of ours |
io.github.djamelkorei.looma.internal |
Lexer, parser, renderer, expression evaluation + sandbox, components. Knows no directive by name. | spi |
io.github.djamelkorei.looma.directive |
Every built-in directive, one class (or one small family) each. | spi only |
io.github.djamelkorei.looma |
LoomaEngine, loaders, Template, LoomaException. |
all of the above |
looma-spring-boot-starter |
Auto-configuration, ViewResolver, looma.*, startup check. |
core |
ArchitectureTest fails the build if these arrows are broken. The rule that matters most: built-in
directives use only the public SPI. If one ever needs more, the SPI is missing something, so fix the SPI
instead of reaching around it. That is also why a directive you write is never second class.
How a directive works¶
A Directive has two jobs, mirrored by the two SPI interfaces:
- Parse time:
parse(ParseContext)reads the arguments (p.expr(),p.splitArgs(), ...) and, for block directives, the body (p.block("endfoo")), and returns aNode. - Render time: the
Nodewrites output throughRenderContext(ctx.eval,ctx.write,ctx.render(body),ctx.child(), ...).
Nodes are immutable and shared between concurrent requests. Never keep per-render data in a node field;
use ctx.state(Type.class, Type::new) (see Sections, StackDirectives).
Add a directive (the whole procedure)¶
Say you want @money($amount).
public final class MoneyDirective implements Directive {
@Override public String name() { return "money"; }
@Override
public Node parse(ParseContext p) {
Expr amount = p.expr(); // parse-time work happens once per template
return ctx -> ctx.writeEscaped( // render-time work happens per request
String.format("%.2f €", ((Number) ctx.eval(amount)).doubleValue()));
}
}
- Spring Boot: declare it as a
@Bean/@Component. Nothing else. - Plain Java:
LoomaEngine.builder(loader).directive(new MoneyDirective()).build(). - Built-in: add it to
BuiltinDirectives.all()and put a test next to the others.
A block directive declares its closing tags and reads its body:
@Override public Map<String, Syntax> tags() { return Map.of("endrepeat", Syntax.NONE); }
@Override public Node parse(ParseContext p) {
Expr times = p.expr();
List<Node> body = p.block("endrepeat").nodes(); // consumes @endrepeat
return ctx -> { for (int i = 0; i < n(ctx, times); i++) ctx.render(body); };
}
Things the SPI gives you for free: error messages with template name and line, escaping
(writeEscaped), isolated variable scopes (child()), loops with @break/@continue support
(runLoopBody), per-render state, an end-of-render hook (onFinish), and a parse-time marker mechanism
(within / isWithin) so a directive can insist on being used inside another one.
If your directive names another template by a fixed name, call p.references(name) (use p.literalOrNull(arg)
to tell a fixed name from an expression) and the startup check will report it when it is missing.
Names must be letters only; verbatim is reserved by the lexer; clashes fail when the engine is built.
Template helpers¶
When templates need functions rather than new syntax (formatting money, building URLs, date helpers),
a helper is simpler than a directive. Any public class implementing TemplateHelper is callable as
Name.method(...):
@Component
public class PriceHelper implements TemplateHelper {
public String name() { return "Price"; }
public String eur(Number amount) { return String.format("%.2f €", amount.doubleValue()); }
}
Without Spring: LoomaEngine.builder(loader).helper(new PriceHelper()).build(). Helpers are visible in every
template, including includes and components, below the model in lookup order. Their output is escaped like any
other value. The built-in String and Math helpers are written the same way (looma-core/.../helper); a helper
of yours with the same name replaces them.
Only expose methods you would be happy for any template to call; helpers are the deliberate, reviewed way to
give templates access to Java code, as opposed to T(...), which stays blocked.
Testing conventions¶
- Behaviour tests render a template string and compare the output (
LoomaEngineTest). They know nothing about internals, so refactors don't break them. Prefer these. - Custom-directive tests (
CustomDirectiveTest) show the SPI from the outside. - Starter tests use
WebApplicationContextRunner; demo tests go through MockMvc. - Every directive needs a test for its error path (unclosed, misplaced, malformed args) as well as its happy path.
Design decisions worth knowing¶
- Expressions are SpEL in a
SimpleEvaluationContextplus a sandbox (internal/Sandbox). Blade conveniences ($x,->,??) are a text translation inExpressions.translate, not a new language. - Layouts are core, not a directive detail:
@extendsrecords the layout on theTemplate; a child's top-levelLayoutContributions (sections) are registered, then the layout renders. - Output is buffered per render, so an error never sends half a page.
@stackuses placeholders resolved in anonFinishhook for the same reason it can be declared before it is filled. - Everything is bounded: nesting depth (100) and
@for/@whilepasses (100,000).