Web Pages

Build websites and webshops in a blueprint. A page is rendered on the server from a template, and its buttons and forms update only the part of the page that changed: one row, one counter, the errors of one form.

A web page is a web_page block with a URL, a flow, and a web_render block that turns a template into the finished HTML. There is no frontend framework and no build step: the visitor's browser receives a complete page, with its title, description, Open Graph tags and structured data already in it. A small script (under 4 KB) makes buttons and forms work in place. When a visitor deletes a row, the server runs your blueprint and answers with "remove row p1", and only that row disappears.

How a web page works

There are two kinds of request, and each starts its own flow in the same blueprint.

The action is posted to the page's own URL, so the page's scopes decide first who may use it. An action can carry scopes of its own; an action without them is allowed only for visitors every page of the blueprint allows, so a public page is never the way in to an action meant for an admin page in the same blueprint. A request from another website is refused.

Your first page

1. Add a web_page block. Its event field is the URL without the leading slash, for example shop or products/:slug; a :name segment arrives on the params out-pin. Give it the scope *public for a page anyone may open.
2. Connect its flow to a web_render block.
3. Write the template on the render block (its template pin, or the template stored on the block), and wire a title and description.
4. Add a custom pin per value the template needs. A custom pin named products is {{products}} in the template.

<main class="shop">
  <h1>{{title}}</h1>
  {{if products}}
    <ul class="grid">
      {{for p in products}}
        <li>
          <a href="/products/{{p.slug}}">
            <img src="{{p.image}}" alt="{{p.name}}" loading="lazy">
            <strong>{{p.name}}</strong>
            <span>{{p.price | money "EUR"}}</span>
          </a>
        </li>
      {{/for}}
    </ul>
  {{else}}
    <p>{{t "shop.empty"}}</p>
  {{/if}}
</main>

Without a layout, the page gets a plain HTML5 document around it. Start the template with <!doctype html> to write the whole document yourself, or name a layout (see below). The head tags are written for you in every case.

Template syntax

Web templates use Mustache, the same syntax as mail templates and page templates, with the platform's additions. A template that does not compile is an error the block reports, not an empty page.

Filters

A filter changes a value before it is written: {{price | money "EUR"}}. Numbers, money and dates follow the page's language, so the same template writes € 1.234,50 on the Dutch page and €1,234.50 on the English one.

Stored templates, layouts and partials

A template you use on more than one page belongs in the templates store, the same place mail templates live. Give it the type web and a name, and every page of the entity can use it by that name.

• A partial is used inside another template: {{> product-card}}.
• A layout wraps the page: set the render block's layout pin to its name. The layout prints the page with {{{body}}} and the generated head tags with {{{head}}}, and it sees the same data as the page. Its stylesheet and script are linked automatically.

<!doctype html>
<html lang="{{language}}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="{{viewport}}">
  {{{head}}}
</head>
<body>
  {{> site-header}}
  {{{body}}}
  {{> site-footer}}
</body>
</html>

Saving a template takes effect on every node at once; there is nothing to deploy.

Lists and tables with web for each

web_foreach repeats a row template for every item of a list, such as the documents of a storage search, and gives every row a data-key: the document's _meta.guid, its id, or the field you name. That key is how a later action replaces or removes exactly that row. Wire its html into a custom pin of the render block and print it with triple braces.

<tr>
  <td>{{name}}</td>
  <td>{{price | money "EUR"}}</td>
  <td>
    <button type="button" data-action="edit">Edit</button>
    <button type="button" data-action="delete" data-confirm="Delete {{name}}?" data-optimistic="remove">Delete</button>
  </td>
</tr>

<table>
  <tbody id="products">{{{rows}}}</tbody>
</table>

Actions update only what changed

A button with data-action="delete" runs the web_action block named delete (its event field) in the page's blueprint. The action receives the form fields on form and the data-key of the row the button sits in on key. It answers with update blocks, applied in the order they ran:

To re-render a row after an edit, render the same row template with web_template (for a stored row template, the template is just {{> product-row}}), pass it the updated document and the key, and hand its html to web_replace.

• Delete: web_action(delete), storage delete by key, web_remove(key).
• Edit: web_action(save), storage update, web_template of the row with the updated document, web_replace(key, html).
• Add: web_action(add), storage create, web_template of the new row with its guid as key, web_insert(target "#products").

What the markup can ask for

These attributes work on any element. Everything marked "no request" happens in the browser alone.

Forms and validation

A form with data-action checks itself before it is sent: required, type="email", pattern, minlength, min and max are judged in the browser, and the message appears next to the field without a request. A visitor fixing a field sees its message disappear while typing. Only a form that passes reaches your action.

The action checks what only the server can know (is this email already registered, is this product still in stock) and answers with web_errors: an object of field name to message, plus an optional message for the whole form. Those messages also disappear as soon as the visitor edits the field.

<form data-action="subscribe">
  <label>Email <input name="email" type="email" required data-msg-required="{{t "form.email_required"}}"></label>
  <div data-error-for="email"></div>
  <div data-error-for="_form"></div>
  <button type="submit" data-loading-text="{{t "form.sending"}}">{{t "form.subscribe"}}</button>
</form>

Forms keep working without JavaScript. A plain form with a hidden _action field posts the same way; the visitor is then sent back to the page, or to the URL of a web_redirect. A web_render in an action answers with a whole page instead, for example an order confirmation.

SEO, Open Graph and languages

Every page is complete HTML when it leaves the server, so search engines and link previews see exactly what visitors see. From the render block's pins the head gets:

• <title>, the meta description and a canonical link (the page URL without its query, unless you set canonical);
• og:title, og:description, og:url, og:image, og:locale and the Twitter card, larger when there is an image;
• a hreflang link for every language version of the page, from the page's l10n URLs, with the main URL as x-default;
• structured data from the json_ld pin;
• anything else from the meta pin, for example {"robots": "noindex", "og:type": "product"}.

A tag your layout already writes is not written twice. A localized URL (an l10n entry) always renders in its own language.

Why it is fast

• Templates compile once. A compiled template renders a 50-row product table in about 16 microseconds, more than twice as fast as the Mustache engine mail templates used and seven times faster than Go's own HTML templates.
• An action renders only its answer. Editing a row renders that row, not the page, and sends only that row back.
• Unchanged pages are not sent again. Every page carries an ETag; a browser that already has the page gets a 304.
• Pages can be cached. Set cache seconds on the render block and shared caches may keep a public page; a page rendered for a signed-in visitor is never cached publicly.
• Links load before the click. Links a visitor hovers are prefetched. Links that run an action, and links marked rel="nofollow" or data-no-prefetch, never are.
• Typing costs nothing. Validation, loading states, toggles and clearing errors happen in the browser.

Escaping and security

Where a value lands decides how it is escaped, and that is read from your template's own markup, so data can never escape its place.

Some templates cannot be escaped safely, and those do not compile, with a message that says why: a partial inside a tag, attribute or script; an {{if}} whose branches end in different places (one inside a tag the other is not: open and close tags inside each branch); and a link whose scheme would come from data (write https://{{host}}, not {{scheme}}://{{host}}).

Every page has a Content Security Policy with a fresh nonce: inline scripts need nonce="{{nonce}}", and onclick-style attributes are blocked, which is what data-action replaces. Actions are refused when another website sends them. A visitor who reaches a broken page reads that it failed; why it failed is shown only to the entity's blueprint developers.

Letting AI build your pages

Web pages are designed to be written by an AI agent as easily as by hand: a page is a template plus a short flow, and every web block carries a precise description of what it does in the block catalog. Ask for the result you want ("a product page for every product in the products storage, with a reviews list and an add-to-cart form") and the agent can create the stored templates through the API and the blueprint with the web blocks. The agent does not call your backend from the page: the page's own request is the backend and the frontend at once.

• Keep shared pieces (header, footer, product card, row) as stored web templates, so a page and its actions render them identically.
• Give every element an action can change a data-key or an id.
• Prefer one action per user intent (add, save, delete) over one action with a switch.

Limits

• Actions take form fields and JSON. Upload files through the upload endpoints and pass the result to the action.
• HTML an action returns is inserted without running its scripts.
• An action belongs to the page's blueprint: a page cannot run another blueprint's actions directly. Call a shared function from the action instead.
• When a blueprint has pages with different scopes, give each action the scopes it needs: an action without scopes requires what every page of the blueprint requires.

Next steps

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem