{{ post.title | upper }}
{{ v }}
` | HTML-escaped | | Attribute | `` | Escaped for attributes. Quotes are optional; an unquoted value is quoted for you | | URL | ``, `{{ post.title }}
Nothing yet.
About us
Thank you, {{ form.name }}
| {{ it.title }} | {{ it.qty }} |
Delivery is free.
```
The tag stands alone: the words are in the file. It works in an action, in a job, and with `for` and `max` for many rows (`{{ b.title }}` is then a column of the row). Everything said about text mail holds: the same recipients, the same values (declared form fields, results of earlier steps, `config.app.url` and `config.app.name`), the same cleaning (one line, 100 characters, a stranger's link replaced), the same footer, the same limits. What is added:
- **Values go in the text.** Not in a tag, an attribute name, `style`, `alt` or an event. The one exception is the address of a link or an image, which must start with `{{ config.app.url }}` followed by `/` (or `?` or `#`) and may go on with values: `href="{{ config.app.url }}/orders/{{ order.code }}"`. So a mail cannot link to a place you did not write. Values are escaped like a page's: `` typed by a visitor is shown as text. Two values side by side are refused, and so is a value that finishes a link you began (`https://{{ x }}`).
- **A short list of tags and attributes.** Tags: `h1`-`h4`, `p`, `div`, `span`, `ul`, `ol`, `li`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `a`, `b`, `strong`, `i`, `em`, `img`, `hr`, `br`. Attributes: `href` (on `a`), `src` and `alt` (on `img`), `width`, `height`, `colspan`, `rowspan`, `align` and a short `style` (colours, font size and weight, alignment, padding, margin, border, width, line height). Values are in double quotes. No script, form, embed, class or id; the error names what it found. `Copy it now: {{ k.key }}
{{ errors.name }}
{{ post.summary }}
Shown when open.
Total:
Hello
{{ answer }}
` and `JSON.parse(el.dataset.post)`. The `` form above still escapes correctly; it only runs if you loosen the CSP yourself.
## Accounts
dhtml keeps accounts, sessions and the one-time links for you (decision D19). Nothing here is written in SQL, and no password or token ever appears in your templates. The tables (`_dhtml_users`, `_dhtml_sessions`, `_dhtml_tokens`) are made by the migrations; your queries may read them but not the password hash or token columns.
**Showing things to the right visitor** is done with `` and ``, in pages, layouts, partials and responses. Both take an `` like ``, and `` is for admins only:
```html
Hello {{ user.name | default user.email }}
Sign in
Admin
```
`user` is what these read. A page that never uses `user` does not look at the session at all.
**Account steps** go in an action, like ``. Each reads form fields by name; the names default to the ones shown, and an attribute names another declared field. All of them need `method="POST"` (the default), a `ratelimit`, and `` for each field they read.
```html
```
| Step | Does | Fields it reads |
|---|---|---|
| `` is drawn with the message in `errors.form`. Too many attempts answer `429` with `Retry-After`. A password field is always empty in `form`, so a form can be drawn again without it, and a step of your own cannot read it (that is a compile error).
An action may do one account step on any path, and it counts as a write: it runs in the action's transaction, so a model call after it is refused like one after ``.
**Going back to where the visitor was heading.** `
```
### Magic links
With `[auth] magic_login = on` (it needs `[mail]` and `url` in `[app]`), a visitor can sign in without a password: they type their address, get an email, and press a button. It follows the same rules as "forgot password", because whoever controls the mailbox can already do that.
```html
```
- **The same answer for every address.** `Continue with Google
```
- **What is checked.** The code flow with PKCE and a random state kept in a signed, short-lived cookie. A callback without the cookie, with another state, with a changed cookie or a second time does nothing. Google's own words are never shown or logged.
- **Who gets in.** Only an address Google has verified. A person already linked signs in as that account; an account with the same address is linked; with `[auth] registration = on` a new account is made (without a password anyone could know: "forgot password" lets them choose one). A suspended account is refused.
- **After it.** A new session starts and the old one ends, like `
```
The table `_dhtml_users` has the columns `banned_at` (a time, empty when not banned) and `ban_reason`, which a page can list.
**The account log.** `_dhtml_auth_log` has one row for every account event: `at` (a Unix time), `kind` (`login`, `login_failed`, `login_banned`, `logout`, `register`, `confirm`, `confirm_failed`, `forgot`, `reset`, `reset_failed`, `password`, `password_failed`, `magic_asked`, `magic_login`, `magic_failed`, `oauth_login`, `oauth_register`, `oauth_failed`, `oauth_banned`, `ban`, `unban`), `user_id` (when the account is known), `email` (the address typed), `addr` (the client address) and `detail` (who banned, and why). A page can list it for an admin, as with the users table; an action cannot write it. It is written after the response, so failed sign-ins are in it, throttled attempts are not, and rows older than 90 days are removed. It holds personal data: say so in your privacy text.
**Protecting pages.** Name them in `[protect]` in `dhtml.config` instead of checking in every page (see [config](config.md)).
## Languages
An app in more than one language keeps the words in one file per language and the pages once (decision D58). A page is the same page in every language: the same markup, the same forms, the same behaviour.
```ini
[lang]
default = en
available = en, nl
detect = path, cookie, accept
```
`server/lang/en.lang` and `server/lang/nl.lang`: one text per line, `key = text`. A key is lower-case letters, digits, dots, hyphens and underscores. `#` starts a comment line. A long text is a key with nothing after `=`, then lines indented by two spaces. `{1}` to `{4}` are places for values, a literal opening brace is written `{{`, and the reserved key `@name` is the language's own name.
```text
@name = Nederlands
nav.home = Home
cart.items = Je hebt {1} artikelen
terms =
## Voorwaarden
Tekst met **opmaak**.
```
```html
{{ alt.name }}
```
- **Escaping**: the result of `t` is text, escaped like every value, and so is a value placed in `{1}`. A language file cannot put markup into a page; the one door is `| markdown`, which is sanitized (it cannot output a script).
- **Keys built by a page** work: ``, where it is written out and takes the language of the recipient ([Mail in the recipient's language](#mail-in-the-recipients-language)). Not in the other steps of an action or a job.
- **The check on every upload** reads every language file and every `t` in the templates: a key a template names that the default language lacks is an error with the line and a "did you mean"; a key another language lacks is a warning (an error with `missing = error`); a key with different `{n}` places in two languages is an error; a key no template uses and a file for a language that is not in `available` are warnings; `t` without `[lang]` is an error.
## Errors
Every error names the file and line of what you wrote, never generated code:
```text
server/pages/blog.dhtml line 7
unknown variable "pots". Did you mean "post"?
```
Errors in a layout or partial name that file. At most 20 are reported per upload.
## Limits
| Limit | Value |
|---|---|
| Template file size | 1 MiB |
| Tag nesting depth | 100 |
| Layout and partial nesting | 20 |
| Output of one page | 16 MiB |
| Markdown input | 256 KiB |
## Fast navigation
Set `navigation = fast` under `[app]` in `dhtml.config` and links and forms stop reloading the page. Clicking a link fetches the next page and swaps only what changed, the way a single-page app does, but every page is still a plain server-rendered page with its own URL. Without JavaScript, or with the setting off (the default), the site works exactly as before.
It works for pages that use one ``. When the next page has the same layout, only the part that comes from the page itself (the slot) is swapped and the layout stays. When it has another layout, or the visitor has just signed in or out, the whole page is swapped in, still without a reload. Only when the new page needs a script the current one lacks, or the server cannot be sure, does the browser do an ordinary page load.
Parts of the layout that depend on the page, such as a menu that marks the current item or the flash message, are marked with `data-dhtml-region`. They are replaced with each navigation:
```html
` of the new content, and announces the new title to screen readers.
- Starts loading a page when the pointer rests on a link for 65 ms, or on touch (not with the browser's data saver on; `data-prefetch="off"` on a link turns it off). This is safe because a dhtml page cannot change anything when it is read (`GET` actions cannot write), but a page's own `
{{ errors.form }}
We sent a link to {{ form.email }}. Open it to finish.
If that address has an account, we sent a link.
If that address has an account, we sent a sign-in link.
{{ "cart.items" | t cart.count }}
{{ "terms" | t | markdown }}{{ flash }}