`.
---
## Trigger annotation
```java
@Trigger(type = TriggerType.OnLoad, actionId = "load")
@Trigger(type = TriggerType.OnLoad, actionId = "load", timeoutMillis = 0)
@Trigger(type = TriggerType.OnSuccess, actionId = "poll", calledActionId = "poll", timeoutMillis = 10000)
@Trigger(type = TriggerType.OnEnter) // fire an action when user presses Enter
```
`TriggerType` values: `OnLoad`, `OnSuccess`, `OnEnter`, `OnChange`.
---
## Validation
### Bean validation (automatic)
```java
@NotNull String name;
@NotEmpty String email;
@Min(1) @Max(100) int quantity;
@Pattern(regexp="[A-Z]{2}\\d{6}") String code;
```
### `@Validation` (cross-field, declarative)
```java
@Validation(filter="endDate < startDate", field="endDate", message="End must be after start")
public class BookingForm { ... }
```
### `ValidationSupplier` (cross-field, programmatic)
```java
public class BookingForm implements ValidationSupplier {
@Override
public List
validations() {
return List.of(new Validation("endDate < startDate", "endDate", "End must be after start"));
}
}
```
---
## Rules (conditional visibility / enable)
### `@Rule` (declarative)
```java
@Rule(filter="accountType == 'BUSINESS'", field="vatNumber",
attribute=RuleFieldAttribute.visible, value="true")
```
`RuleFieldAttribute` values: `visible`, `enabled`, `required`, `readonly`, `value`.
### `RuleSupplier` (programmatic)
```java
public class AccountForm implements RuleSupplier {
@Override
public List rules() {
return List.of(Rule.builder()
.filter("accountType == 'BUSINESS'")
.action(RuleAction.set)
.fieldName("vatNumber")
.fieldAttribute(RuleFieldAttribute.visible)
.value("true")
.build());
}
}
```
---
## Action return types
| Return | Effect |
|---|---|
| `void` / `null` | Stay on current page, no visual change |
| `URI.create("/path")` | Browser navigates to that URL |
| `new Message("text")` | Toast notification (bottom of screen) |
| `Message.builder().text("...").build()` | Same, builder form |
| Any Java object (form, listing, etc.) | Mateu navigates to that object as a new view |
| `new State(this)` | Push updated field values to frontend without navigating |
| `PageBanner` | Show banner on current page (replaces previous action banners) |
| `List` | Same, multiple banners |
| `PageBanners.replace(banner...)` | Explicit replace |
| `PageBanners.append(banner...)` | Accumulate banners across action calls |
| `UICommand.markAsClean()` | Clear the unsaved-changes flag (e.g. after a successful save) |
| `UICommand.markAsDirty()` | Flag the form as having unsaved changes |
---
## CRUD patterns
### AutoCrud — zero boilerplate
```java
@UI("/products")
public class Products extends AutoCrud {}
record Product(
@NotEmpty @EditableOnlyWhenCreating String id,
@NotEmpty String name,
double price,
@Status(...) ProductStatus status
) implements Identifiable {}
```
### Custom listing with search
```java
@UI("/orders")
@Title("Orders")
@Trigger(type = TriggerType.OnLoad, actionId = "search")
public class Orders extends Listing {
@Override
public ListingData search(
String searchText, OrderFilters filters,
Pageable pageable, HttpRequest httpRequest) {
return ListingData.of(repo.findAll(searchText, filters, pageable));
}
@Override
public GridLayout gridLayout() { return GridLayout.table; }
}
record OrderFilters(String status, LocalDate from, LocalDate to) {}
record OrderRow(
@ColumnWidth("80px") String id,
String customer,
@ColumnWidth("100px") double total,
String status
) {}
```
`GridLayout` values: `auto`, `table`, `list`, `cards`, `masterDetail`.
### Export support
```java
public class OrdersListing extends Listing {
@Override public boolean csvExportable() { return true; }
@Override public boolean excelExportable() { return true; }
@Override public boolean pdfExportable() { return true; }
}
```
Add `export-excel` and `export-pdf` Maven dependencies to enable those buttons.
### CRUD URL pagination
Mateu syncs page, sort, and filter to the URL automatically:
`/orders?page=2&sort=date:desc&status=PENDING`
No code needed — deep-linking and browser back/forward work out of the box.
---
## Form with load trigger
```java
@UI("/customer/:id")
@Title("Customer")
@Trigger(type = TriggerType.OnLoad, actionId = "load")
public class CustomerForm {
String name;
String email;
Object load(HttpRequest req) {
var c = repo.find(req.pathVariable("id"));
name = c.name(); email = c.email();
return new State(this);
}
@Toolbar
@Action(validationRequired = true)
Object save() {
repo.save(name, email);
return new Message("Saved");
}
}
```
---
## Wizard
Extend `Wizard` and declare one field per step; each field type must implement `WizardStep`.
The **penultimate** step shows the `@WizardCompletionAction` button. The **last** step is a read-only result screen (no nav buttons, progress bar = 100%). The last step is auto-instantiated if `null` when completion runs.
```java
@UI("/signup")
@Title("Create account")
public class SignupWizard extends Wizard {
AccountStep account = new AccountStep();
PlanStep plan = new PlanStep();
ResultStep result; // auto-instantiated or set explicitly
@WizardCompletionAction
@Action(validationRequired = true)
Object finish() {
service.create(account, plan);
return null;
}
}
class AccountStep implements WizardStep {
@NotEmpty String email;
@NotEmpty String password;
}
class PlanStep implements WizardStep {
@NotNull PlanType plan;
}
class ResultStep implements WizardStep {
@PlainText String summary = "Account created successfully!";
}
```
---
## Navigation & menus
```java
@UI("/app")
@App(AppVariant.HAMBURGUER_MENU)
@Logo("/logo.svg")
@FavIcon("/favicon.svg")
public class MyApp {
@Menu Customers customers;
@Menu Orders orders;
@Menu Reports reports;
}
```
---
## Dense multi-zone screen
```java
@UI("/checkin/:id")
@Compact
@Style(StyleConstants.FULL_WIDTH_WITH_PADDING)
@ConfirmOnNavigationIfDirty
@Zones({
@Zone(name = "left", width = "64%"),
@Zone(name = "right", width = "36%")
})
public class CheckInForm {
@Section(value = "Reservation", columns = 4, zone = "left")
@ReadOnly @PlainText String locator;
@ReadOnly @PlainText String hotel;
@Section(value = "Guests", columns = 1, zone = "left")
@Inline @Label("")
GuestSection guests = new GuestSection();
@Section(value = "Amounts", columns = 1, zone = "right")
@PlainText
@Stereotype(FieldStereotype.money) @Label("Credit limit") BigDecimal creditLimit; // → 1.250,00
@Stereotype(FieldStereotype.money) @Label("Balance due") BigDecimal balanceDue;
@Section(value = "Charges", zone = "right")
@Label("") @Stereotype(FieldStereotype.grid)
List charges;
@Toolbar @Action(validationRequired = true)
Object checkIn(HttpRequest req) {
return List.of(new Message("Checked in"), UICommand.markAsClean());
}
}
@PlainText
public class GuestSection {
@Label("") @Stereotype(FieldStereotype.grid)
List guests;
@Toolbar @Label("Print welcome card")
Object printCard(HttpRequest req) { return new Message("Sent to printer"); }
}
```
---
## Banners
### Declarative `@Banner`
```java
@Banner(theme = BannerTheme.WARNING, title = "Notice", closeable = true)
String bannerText() { return degraded ? "Some features may be slow." : null; }
```
### Programmatic `BannerSupplier`
```java
public class MyPage implements BannerSupplier {
@Override
public List banners() {
return List.of(new PageBanner(BannerTheme.INFO, "Info", "Welcome back."));
}
}
```
### Action-returned banners
```java
@Toolbar
Object validate() {
if (hasErrors()) return new PageBanner(BannerTheme.DANGER, "Error", errorSummary());
return new PageBanner(BannerTheme.SUCCESS, "OK", "All checks passed.");
}
// Accumulate banners:
return PageBanners.append(new PageBanner(BannerTheme.WARNING, "Warning", detail));
```
---
## Header badges
### `@BadgeInHeader` (field-level, boolean or String)
```java
@BadgeInHeader(label = "VIP", color = "success") boolean vip;
@BadgeInHeader(color = "warning") String alertCode;
```
### `BadgeSupplier` (programmatic)
```java
public class BookingPage implements BadgeSupplier {
@Override
public List badges() {
return List.of(Badge.builder().text(status).color("success").pill(true).build());
}
}
```
---
## Floating action buttons (FABs)
```java
// App-level FAB (global, visible on all pages)
@UI("/app")
@App(AppVariant.AUTO)
public class MyApp {
@Fab(icon="vaadin:plus", label="New order", order=0)
Object newOrder() { return new CreateOrderForm(); }
}
// Page-level FAB (scoped to this page)
@UI("/customers")
public class CustomerList {
@Fab(icon="vaadin:plus", label="Add customer")
Object add() { return new CreateCustomerForm(); }
}
```
---
## Key interfaces
| Interface | Purpose |
|---|---|
| `Identifiable` | Mark the ID field for CRUD. Return `id()`. |
| `ListingBackend` | Custom searchable/filterable grid |
| `CrudRepository` | Data port for `AutoCrud` |
| `Hydratable` | `hydrate(HttpRequest)` called before each render — load data from DB |
| `ComponentTreeSupplier` | Return a fluent component tree instead of annotated fields |
| `BannerSupplier` | Programmatic page banners |
| `BadgeSupplier` | Programmatic header-strip badges |
| `TitleSupplier` | Dynamic page title |
| `SubtitleSupplier` | Dynamic page subtitle |
| `ValidationSupplier` | Programmatic cross-field validation |
| `RuleSupplier` | Programmatic conditional UI rules |
| `MenuSupplier` | Dynamic navigation menu |
| `ActionHandler` | Programmatic action dispatch |
| `WizardStep` | Marker for wizard step types |
| `PostHydrationHandler` | `onHydrated(HttpRequest)` called after client state is applied |
---
## Useful types
| Type | Use |
|---|---|
| `Message` | Toast notification: `new Message("text")` or `Message.builder().text("...").build()` |
| `State` | Push updated field values to frontend: `new State(this)` |
| `PageBanner` | Dynamic banner: `new PageBanner(BannerTheme, title, description)` |
| `PageBanners` | Banner collection with replace/append: `PageBanners.replace(...)`, `.append(...)` |
| `UICommand` | Frontend command: `UICommand.markAsClean()` / `markAsDirty()` (works with `@ConfirmOnNavigationIfDirty`) |
| `Badge` | Fluent badge component (used in `BadgeSupplier`, grid cells): `Badge.builder()...build()` |
| `ListingData` | Search result: `ListingData.of(list)` or builder |
| `Pageable` | Pagination/sort from the grid: `page`, `size`, `sort` |
| `HttpRequest` | Access path vars, query params, headers, auth |
---
## Common patterns — quick reference
### Dashboard with KPIs
```java
@UI("/dashboard")
public class Dashboard {
@KPI int totalOrders = orderRepo.count();
@KPI String totalRevenue = "€ " + revenueService.total();
@KPI double avgOrderValue = revenueService.average();
}
```
### Detail form with tabs
```java
@UI("/product/:id")
@Tabs
@Trigger(type=TriggerType.OnLoad, actionId="load")
public class ProductDetail {
@Tab("General") @NotEmpty String name;
@Tab("General") String description;
@Tab("Pricing") double price;
@Tab("Stock") int stock;
Object load(HttpRequest req) { /* populate fields */ return new State(this); }
@Toolbar @Action(validationRequired=true)
Object save() { return new Message("Saved"); }
}
```
### AutoSave settings page
```java
@UI("/settings")
@AutoSave(debounceMillis=800, action="save")
public class SettingsPage {
String displayName;
String email;
boolean newsletter;
@Toolbar
Message save() {
settingsService.update(displayName, email, newsletter);
return new Message("Saved");
}
}
```
### Long-running job with SSE progress
```java
@UI("/import")
public class ImportPage {
@Button
@Action(background=true, sse=true)
Object runImport(HttpRequest req) {
return importService.start(); // returns a job that streams progress
}
}
```
### Navigation from action
```java
@Toolbar
Object openDetail() {
return URI.create("/orders/" + orderId); // browser URL navigation
}
// Or navigate to a Java object directly:
@Toolbar
Object openDetail() {
return new OrderDetailForm(orderId); // Mateu builds the view
}
```
---
## What Mateu does NOT support declaratively
- **Complex custom layouts** beyond `@Zones` + `@Compact` — use the Fluent Component API or `ComponentTreeSupplier`.
- **Real-time push without polling** — use `@Action(sse=true)` or the `@AI` chat panel; WebSocket is not a native primitive.
- **Per-cell custom rendering** beyond `@Stereotype` / `@Status` / `@ColumnAction` — implement a custom web component.