# Template
Bialet renders pages using Inline HTML Strings — HTML written directly inside
your Wren `.wren` files. No template engine, no separate files, no build step.
Write a `.wren` file, return an HTML string, and that's your page.
---
## View: Inline HTML Strings
Inline HTML Strings are delimited by angle brackets `<` and `>`. The string
must begin and end with the same tag. Tag names must be lowercase, start with a
letter, and contain only letters and numbers.
```wren
// A simple HTML string assigned to a variable
var str =
Hello World
```
### Interpolation
Use `{{ }}` to embed any Wren expression inside HTML. The expression is
evaluated and its result is inserted into the string.
```wren
var name = "John"
var greeting =
Hello, {{ name }}!
// Output:
Hello, John!
var sum =
{{ 5 + 3 }}
// Output:
8
```
### `return` sends the response
Inside a `.wren` file, `return` sends the value as the HTTP response body
and **stops execution immediately**. Nothing after `return` runs. This is how
every page in Bialet works — the last statement is a `return` with the HTML.
```wren
// index.wren
return
My Page
Hello World
```
### Attributes
Attributes follow the same rules as regular HTML — lowercase names, quoted
values. You can interpolate values with `{{ }}`.
```wren
var url = "/about"
var label = "Learn more"
var link = {{ label }}
```
### Self-Closing Tags
Certain HTML tags are self-closing. In Bialet, these must include a space
before the closing slash. The final output omits the slash.
- Correct: ``, ` `, ``, ``
- Incorrect: ``, ` `
```wren
var inputField =
// Renders:
```
### Multi-line Inline HTML
An inline HTML string can span as many lines as you need. The newlines inside
the tags become part of the HTML output.
```wren
var card =
Title
{{ description.safe }}
```
### Pitfalls
**Same-tag nesting is a parse error.** A tag cannot directly contain another
tag with the same name:
```wren
// Wrong — parse error
var bad =
Hello
var alsoBad = Nested
// Correct — use a different tag
var good =
Hello
```
**Mismatched tags fail.** Opening and closing tags must match:
```wren
// Wrong
var bad =
Hello
// Correct
var good =
Hello
```
**Invalid tag names.** Only lowercase letters and numbers are allowed. No
hyphens, underscores, or uppercase:
```wren
// Wrong
var bad1 = Invalid
var bad2 = Invalid
// Correct
var good = Valid
```
**Interpolation depth** is limited to 9 nested levels.
**Forgetting `return`.** Without `return`, the response body is empty. The page
renders as blank.
**Files starting with `_` or `.` are private** — they return 403 if accessed
directly. Use them for imports and internal logic only.
---
## Conditional Rendering with `&&`
Wren's `&&` operator is the primary tool for conditional rendering. When the
left side is truthy, the right side is returned; otherwise the expression
evaluates empty.
### Class toggling
```wren
// filter is a query parameter string
var filter = Request.get("filter") || "all"
AllActiveCompleted
```
When `filter == "all"` is true, `"active"` is inserted as the class value.
When false, nothing is inserted.
### Conditional HTML blocks
You can conditionally render entire chunks of HTML. The right side of `&&` can
be an inline HTML string. The `{{ }}` interpolation must always appear inside
an HTML tag (`{{ }}` outside an HTML tag is parsed as Wren map syntax).
```wren
return
{{ showClear && }}
```
```wren
return
{{ tasks.count == 0 && 🎉
Nothing here yet.
}}
```
```wren
// Conditional text
{{ activeCount }}
task{{ activeCount != 1 && "s" }} remaining
```
### Pitfall
**Newlines outside HTML tags produce unexpected output.** The Wren code
inside `{{ }}` must start on the same line as `{{`. Newlines belong inside
the HTML string (between `` and ``), not in the surrounding Wren
code. Breaking the Wren expression with newlines can cause parsing
ambiguities and empty output.
```wren
// Wrong — Wren code spans lines outside the HTML tags
return
{{
showClear &&
}}
// Correct — Wren code starts on the same line as {{
return
{{ showClear && }}
```
The same rule applies to ternary expressions and `map` — keep the Wren
expression on the same line as `{{`, let only the HTML string span lines.
---
## Ternary Expressions
Ternary operators are essential for switching attributes, classes, and entire
blocks of HTML based on a condition.
### Attribute switching
```wren
```
### Nested ternaries for multi-value decisions
```wren
```
### Ternary with HTML operands
Each branch of a ternary can be an inline HTML string that spans multiple
lines. The `{{ }}` must be inside an HTML tag context:
```wren
return {{ task.finished ?
{{ task.description.safe }}
:
{{ task.description.safe }}
}}
```
### Pitfall
**Deeply nested ternaries hurt readability.** For complex logic, compute the
value above the template and use a simple variable instead:
```wren
// Compute before the template
var taskClass = "task-text"
if (task.finished) {
taskClass = "task-text completed"
}
// Clean template
{{ task.description.safe }}
```
**Newlines outside HTML tags** — same rule as `&&`:
```wren
// Wrong — Wren code broken across lines outside the HTML string
return
{{
task.finished ?
Done :
Pending
}}
// Correct — one expression, newlines inside the HTML strings
return
{{ task.finished ?
Done
:
Pending
}}
```
---
## Iteration with `map`
Wren's `map` function transforms each element of a list into an HTML string.
The callback body is a single Wren expression — but the inline HTML string
inside it can span many visual lines.
### Simple list
```wren
var items = ["Apple", "Banana", "Cherry"]
var html =
{{ items.map { |item|
{{ item }}
} }}
// Output:
Apple
Banana
Cherry
```
### Multiline items
The callback is one expression (`|task|
...
`), but the `
` inline
HTML string spans multiple lines. The Wren code stays on one line of Wren, but
the HTML inside the tags has newlines.
```wren
```
### Pitfalls
**The callback must be a single expression.** You cannot have multiple Wren
statements or variable declarations inside a `map` callback:
```wren
// Wrong — multiple statements inside map
{{ tasks.map { |task|
var icon = task.finished ? "✓" : "○"
{{ icon }} {{ task.description }}
} }}
```
If you need pre-computed values, prepare them before `map` (e.g. add computed
properties to your model class, or pre-process the list).
**Empty lists produce empty output.** Pair `map` with `&&` to show an empty
state:
```wren
return
{{ tasks.map{ |task|
{{ task.description.safe }}
} }}
{{ tasks.count == 0 &&
No tasks yet. Add your first one above.
}}
```
**Large lists hurt performance.** Paginate or limit results in the controller —
`map` iterates everything you give it.
**Newlines outside HTML tags** — same rule:
```wren
// Wrong — Wren code broken across lines outside the HTML string
return
{{
tasks.map { |task|
{{ task.description }}
} }}
// Correct — the expression starts on the {{ line
return
{{ tasks.map{ |task|
{{ task.description }}
} }}
```
---
## Bialet MVC: File Structure
Now that you know how to write HTML, here's how a complete `.wren` file is
organized. Bialet follows an MVC-like pattern within a single file:
- **Model** — Wren classes in separate files (e.g. `_domain.wren`), imported at
the top
- **Controller** — the logic at the top of the `.wren` file: routing decisions,
POST handling, data fetching, redirects
- **View** — the inline HTML at the bottom, passed to `return` to send the
response and end the script
```wren
// === Controller ===
import "_template" for Template
import "_domain" for Post
if (Request.isPost) {
var post = Post.new()
post.title = Request.post("title")
post.save()
return Response.redirect("/")
}
var posts = Post.list()
// === View ===
return Template.new().layout(
)
```
### Pitfall
**`return` terminates immediately.** Code after `return` never executes.
This means you cannot `return` and then run more logic. Put all controller
logic before the view.
---
## Model: Wren Classes
Wren classes serve as the Model layer. They encapsulate data, database queries,
and domain logic — keeping it out of your template code.
```wren
// _domain.wren
class Post {
construct new(row) {
_id = row["id"]
_title = row["title"]
_body = row["body"]
_createdAt = row["createdAt"] || Date.now
}
static new() { Post.new({}) }
id { _id }
title { _title }
title=(val) { _title = val.toString.trim() }
body { _body }
body=(val) { _body = val.toString() }
createdAt { Date.new(_createdAt) }
save() { `Post`.save(this) }
static list() { `
SELECT * FROM Post ORDER BY createdAt DESC
`.fetch.to(Post) }
static find(id) { `
SELECT * FROM Post WHERE id = ?
`.first(id).to(Post) }
}
```
Now the controller imports this class and the view iterates over `Post`
instances — clean, testable, and separated from presentation.
### Pitfall
**Database values come back as strings.** Always convert before numeric
operations:
```wren
var count = Num.fromString(row["cnt"])
// Wrong: row["cnt"] + 1 — this concatenates strings
```
---
## Controller: Logic at the Top
The top of each `.wren` file handles the request. This is where you:
1. Check the HTTP method (`Request.isPost`)
2. Read form data (`Request.post("field")`)
3. Read query parameters (`Request.get("key")`)
4. Call model methods
5. Redirect or prepare data for the view
```wren
import "_template" for Template
import "_domain" for Post
if (Request.isPost) {
var post = Post.new()
post.title = Request.post("title")
post.body = Request.post("body")
post.save()
return Response.redirect("/posts/" + post.id.toString)
}
var postId = Request.route(1)
var post = Post.find(postId)
```
Use `return Response.redirect(path)` to redirect after POST — this follows
the Post/Redirect/Get pattern and prevents duplicate form submissions.
### Pitfall
**Forgetting `return` before `Response.redirect()`** causes a double-response
error. The redirect sends headers, then the code below still executes and
tries to send a body. Always `return Response.redirect(...)`.
```wren
// Wrong — missing return
if (Request.isPost) {
task.save()
Response.redirect("/") // redirect sends headers...
}
// ...then this still runs, trying to send a second response
return Template.new().layout(...)
```
---
## Template Classes / Components
Extract shared HTML into Wren classes. Each method returns an inline HTML
string, turning your class into a library of reusable components.
### Layout template
Create `_template.wren` and import it from your pages:
```wren
class Template {
construct new() {
_title = "My App"
_subtitle = "A Bialet application"
}
layout(content) {
{{ head(_title) }}
{{ _title }}
{{ _subtitle }}
{{ content }}
{{ footer }}
}
head(title) {
{{ title }}
}
footer { }
}
```
### Using the template
```wren
// index.wren
import "_template" for Template
return Template.new().layout(
Welcome
This content goes into {{ content }}.
)
```
A Wren block that contains a single expression implicitly returns that
expression — no `return` keyword needed in the method body.
### Pitfalls
**Instance methods need `new()`.** If your methods are not `static`, you
must instantiate the class:
```wren
// Wrong — calls static layout, doesn't exist
return Template.layout(...)
// Correct — creates an instance first
return Template.new().layout(...)
```
**Don't over-engineer.** A template class with a handful of methods (`layout`,
`head`, `footer`, plus one or two component helpers) covers most needs.
Nested class hierarchies and deep abstraction layers work against Bialet's
simplicity.
---
## Semantic HTML
Prefer semantic elements that describe their purpose. Bialet's inline HTML is
plain HTML — the browser treats it exactly as if you'd written an `.html` file.
Use the right element for the job.
| Instead of `