Getting started¶
About ten minutes. Every snippet here exists in looma-demo, where it is tested.
1. Add it¶
Add the dependency from Installation. That is the only setup: Spring Boot auto-configures the engine and the view resolver.
2. Your first page¶
@Controller
class HelloController {
@GetMapping("/hello")
String hello(Model model) {
model.addAttribute("name", "Ada <script>"); // (1)!
return "hello"; // (2)!
}
}
- Escaped automatically: the page shows
Ada <script>as text, never as a tag. - The view name. Looma renders
templates/hello.looma.html, so there is nothing to configure.
{{ }} always HTML-escapes. Use {!! !!} only for markup you trust.
Develop with live reload: looma.template-dir=src/main/resources/templates. Edit, refresh, done.
3. A shared layout¶
<!DOCTYPE html>
<html>
<head>
<title>@yield('title', 'My app')</title> <!-- (1)! -->
@stack('head') <!-- (2)! -->
</head>
<body>
@include('partials.nav')
<main>@yield('content')</main>
@stack('scripts')
</body>
</html>
- The page's
@section('title', ...), orMy appwhen the page sets none. - Everything pages
@push('head'), for example a stylesheet only one page needs.
@extends('layouts.app')
@section('title', 'Hello')
@section('content')
<h1>Hello, {{ $name }}!</h1>
@push('scripts')<script>console.log('only on this page')</script>@endpush
@endsection
4. Loops and conditions¶
<ul>
@forelse($posts as $post)
<li @class({'first': $loop->first})>
{{ $loop->iteration }}/{{ $loop->count }} {{ $post.title }}
@unless($post.published) (draft) @endunless
</li>
@empty
<li>No posts yet</li>
@endforelse
</ul>
Expressions are SpEL with Blade conveniences: $post->title, $post.title and post.title are the same;
$a ?? 'default' works; &&, ||, ! work. Also @for, @while, @switch, @break, @continue.
5. A form with validation¶
signup.looma.html and
SignupController:
<form method="post" action="/signup">
@csrf
@bind('form')
<input type="email" @field('email') @class({'invalid': $errors.containsKey('email')})>
@error('email')<small class="error">{{ $message }}</small>@enderror
@endbind
<button>Create account</button>
</form>
@bind('form') + @field('email') writes id, name and value from the form object. After a failed submit
the field shows what the user typed, as with Thymeleaf's th:field. See form binding
for checkboxes, radios and selects.
@PostMapping("/signup")
String submit(@Valid @ModelAttribute("form") SignupForm form, BindingResult result) {
return result.hasErrors() ? "signup" : "signup-done"; // (1)!
}
- On a failed submit the form is shown again:
@errorreads the messages from theBindingResultand@fieldkeeps what the user typed. No glue code.
With Spring Security, @csrf renders the token the filter expects (tested in looma-it), and
@auth('ADMIN') ... @endauth / @guest follow the signed-in user.
6. A component¶
<div {{ $attributes->except('type')->merge({'class': 'alert alert-' + $type}) }}>{{ $slot }}</div>
Declare a component's props and their defaults at its top with @props({'type': 'info'}); declared props are
removed from $attributes, so only real HTML attributes are written. Components see only what you pass them. Named slots: <x-slot:title>…</x-slot:title> becomes $title.
7. Your own directive¶
@Component
class MoneyDirective implements Directive {
public String name() { return "money"; }
public Node parse(ParseContext p) {
Expr amount = p.expr();
return ctx -> ctx.writeEscaped(String.format("%.2f €", ((Number) ctx.eval(amount)).doubleValue()));
}
}
Block directives, loops and more: Extending & architecture.
8. Before you ship¶
- Keep
looma.cache=true(the default) and leavelooma.template-dirunset in production. - The app fails at startup, naming template and line, if any template has a syntax error or points at a
missing
@include/@extends/<x-…>. Boot it once in CI and typos never reach users. - Templates are trusted code. Never build template names from request input. See the security model.
Coming from Thymeleaf?¶
| Thymeleaf | Looma |
|---|---|
<p th:text="${user.name}"> |
<p>{{ $user.name }}</p> |
th:utext |
{!! $html !!} |
th:if / th:unless |
@if / @unless |
th:each="p, s : ${posts}" |
@foreach($posts as $p) with $loop |
th:replace / th:insert |
@include('partials.x') |
layout dialect layout:decorate |
@extends + @section / @yield |
th:fragment with parameters |
<x-component :arg="…"> |
#{key} |
@lang('key') |
th:field, #fields.hasErrors |
@error('field') |
The main difference: Looma templates are not valid HTML on their own (no natural templating), which is what lets them read like plain text with directives.