reference.dj

= Toupee Element Reference

All template elements use the `t-` prefix.

== Template Inheritance

=== `<t-extend>`

Inherit from a parent template. Must be the first non-whitespace content in a template.

```
<t-extend template="base.html">
<t-define name="title">Style Guide</t-define>
<t-define name="">Body content</t-define>
```

The `template` attribute names a template registered in the `Resolver`. Extend chains can be arbitrarily deep (up to 50 levels). Circular references are detected and produce `CircularReference`.

=== `<t-define>`

Fill a named slot when used inside `<t-extend>` or `<t-include>`.

```
<t-define name="sidebar">Sidebar content</t-define>
<t-define name="">Anonymous slot content</t-define>
```

The `name` attribute identifies which slot to fill. An empty name (`name=""`) fills the anonymous/default slot. Duplicate definitions within the same include body produce `DuplicateSlotDefinition`.

=== `<t-slot>`

Mark an insertion point in a parent or included template.

```
<t-slot name="title" />
<t-slot name="footer">Default footer content</t-slot>
<t-slot />
```

Self-closing slots render nothing if unfilled. Block slots render their default content if unfilled. Nameless slots are the anonymous/default slot.

== Variables

=== `<t-var>`

Insert a variable value with HTML escaping.

```
<t-var name="style.name" />
<t-var name="missing">fallback content</t-var>
<t-var name="title" transform="upper" />
```

Produces `UndefinedVariable` if the variable is missing and no default body or `default` transform is provided. Variable names use dot-path resolution --- `style.name` resolves through the data hierarchy (style -> name). All scalar Value types (string, integer, float, boolean) are auto-coerced to strings for rendering.

=== `<t-raw>`

Insert a variable value without HTML escaping.

```
<t-raw name="content" />
<t-raw name="missing"><em>fallback</em></t-raw>
```

Same semantics as `<t-var>` except output is not escaped. Use for pre-rendered HTML content.

=== `<t-let>`

Capture rendered content into a variable for later use.

```
<t-let name="slug" transform="slugify"><t-var name="style.name" /></t-let>
<a href="/<t-var name="slug" />"><t-var name="style.name" /></a>
```

The body is rendered, optionally transformed, and stored in the variable. The variable is available for the remainder of the current template scope.

== Attribute Binding

=== `t-var:attr`

Bind a context variable to an HTML attribute. If the variable is missing, the attribute is omitted entirely.

```
<a t-var:href="style.url" t-var:title="style.label">link</a>
```

Values are HTML-escaped.

=== `t-attr:attr`

Bind an include attribute to an HTML attribute. Same semantics as `t-var:` but reads from `attrs` instead of data.

```
<div t-attr:class="variant">content</div>
```

== Component Inclusion

=== `<t-include>`

Include another template with attribute passing and optional body.

```
<t-include template="nav.html" class="site-nav" />

<t-include template="style-card.html" variant="signature">
  <t-define name="title"><h2>The Marcel Wave</h2></t-define>
  <p>Layered waves with soft texture (anonymous slot)</p>
</t-include>
```

All attributes except `template` are passed as `attrs` to the included template. The body can contain `<t-define>` blocks for named slots and/or plain content for the anonymous slot.

=== `<t-attr>`

Access an include attribute inside an included template.

```
<button class="btn"><t-attr name="label" /></button>
```

Self-closing only. Renders the attribute value with HTML escaping.

== Control Flow

=== `<t-if>`

Conditional rendering based on variable, attribute, or slot existence/value.

```
<t-if var="x">shown when x exists</t-if>
<t-if var="x" equals="hello">exact match</t-if>
<t-if var="x" not-equals="hello">not equal</t-if>
<t-if var="x" not-exists>truly missing (empty string counts as existing)</t-if>
<t-if var="x" truthy>value is truthy</t-if>
<t-if var="x" not-truthy>value is falsy or missing</t-if>
<t-if var="x" contains="needle">substring match</t-if>
<t-if var="x" starts-with="/styles">prefix match</t-if>
<t-if var="x" ends-with=".html">suffix match</t-if>
<t-if var="x" matches="*.html">glob pattern match (* and ?)</t-if>
<t-if attr="variant">has variant attribute</t-if>
<t-if slot="sidebar">sidebar slot was defined</t-if>
```

Existence vs truthiness: `<t-if var="x">` is true if `x` is present, even if its value is an empty string or `false`. `not-exists` is true *only* when the variable is genuinely absent. `truthy` checks the value itself: non-empty strings, `true`, non-zero numbers, and non-empty lists/maps are truthy; empty strings, `false`, zero, empty collections, `nil`, and missing variables are falsy.

=== `<t-elif>` and `<t-else>`

Conditional branches. Must appear inside a `<t-if>` block. Self-closing separators.

```
<t-if var="a">A
<t-elif var="b" />B
<t-else />C
</t-if>
```

`<t-elif>` accepts the same attributes as `<t-if>`.

=== `<t-for>`

Iterate over a collection.

```
<t-for style in styles sort="date" order="desc" limit="5" offset="1" as loop>
  <h2><t-var name="style.name" /></h2>
  <span>#<t-var name="loop.number" /></span>
</t-for>
```

Attributes:

- `sort="field"` --- sort entries by the named field (ascending by default)
- `order="desc"` --- descending sort
- `limit="N"` --- limit to N entries after sorting
- `offset="N"` --- skip first N entries after sorting
- `as alias` --- expose loop metadata via `alias.*`

Loop metadata (available when `as` is used):

- `alias.index` --- 0-based position
- `alias.number` --- 1-based position
- `alias.length` --- total number of items (after limit/offset)
- `alias.first` --- `"true"` on the first iteration (absent otherwise)
- `alias.last` --- `"true"` on the last iteration (absent otherwise)

Entry fields are accessed as `prefix.field` where `prefix` is the loop variable name. Variables use dot-path resolution through the data hierarchy.

Empty or missing collections render nothing (no error).

=== For-else

`<t-else />` inside `<t-for>` provides fallback content when the collection is empty or missing:

```
<t-for style in styles>
  <article><t-var name="style.name" /></article>
<t-else />
  <p>No styles yet.</p>
</t-for>
```

== Other Elements

=== `<t-comment>`

Template-only comment. Content is stripped from output.

```
<t-comment>This will not appear in the rendered HTML</t-comment>
<t-comment />
```

Both block and self-closing forms are supported.

=== `<t-debug />`

Debug element. When `Options.debug` is `true`, renders a table of the current template context (all variables and their values). When debug is `false`, the element is silently stripped from output.

```
<t-debug />
```

Self-closing only.

== Transforms

Applied via `transform="name"` on `<t-var>`, `<t-raw>`, and `<t-let>`. Multiple transforms are pipe-chained: `transform="trim|lower|slugify"`.

=== String transforms

- `upper` --- convert to uppercase
- `lower` --- convert to lowercase
- `capitalize` --- title case (capitalise first letter of each word)
- `trim` --- strip leading and trailing whitespace
- `slugify` --- lowercase, replace non-alphanumeric with hyphens, collapse/strip hyphens
- `truncate:N` --- truncate to N characters (no ellipsis)
- `replace:from:to` --- replace all occurrences of `from` with `to`
- `default:value` --- use `value` if the variable is empty or missing
- `escape` --- HTML-escape (`&`, `<`, `>`, `"`, `'`)
- `url_encode` --- percent-encode for URLs
- `url_decode` --- decode percent-encoded strings

=== Collection transforms

- `join:separator` --- join a newline-separated list with `separator` (default: `, `)
- `split:delimiter` --- split a string on `delimiter` (default: `,`) into newline-separated output
- `first` --- first element (splits on newline or uses separator argument)
- `last` --- last element (splits on newline or uses separator argument)

=== Numeric transforms

- `length` --- string length as a number
- `abs` --- absolute value (best-effort coercion)
- `floor` --- floor/round down (best-effort coercion)
- `ceil` --- ceiling/round up (best-effort coercion)

=== Type-casting transforms

- `int` --- parse as number and truncate to integer
- `float` --- parse as number with minimal representation
- `decimal:N` --- format with exactly N decimal places
- `bool` --- convert to `"true"` or `"false"`

=== Date transforms

- `date:format` --- format ISO date with strftime-style specifiers (`%Y`, `%m`, `%d`, `%e`, `%B`, `%b`, `%H`, `%M`, `%S`, `%%`)

== Errors

| Error | Cause |
| --- | --- |
| `MalformedElement` | Unclosed tag, missing required attribute, unknown transform |
| `TemplateNotFound` | Referenced template not registered in Resolver |
| `CircularReference` | Extend chain cycle or render depth exceeded |
| `DuplicateSlotDefinition` | Same slot defined twice in one include body |
| `UndefinedVariable` | Variable missing with no default body or default transform |
| `OutOfMemory` | Allocator exhausted |