Dynamic pages

A .chtml file is an HTML page that can use your recipes. Recipes always run on the server.

Overview

There are three ways to use a recipe from a page:

The name is the one you saved the recipe under in the editor. Names can use letters, numbers, _ and -, and can't start with a number or -.

Results in the page

A %{ }% tag is replaced by what the recipe returns, before the page reaches the browser:

<p>%{ with_tax(10) }%</p>

A page can have many tags, and they run together. The result is kept until you change the page or one of its recipes, so a popular page doesn't run its recipes for every visitor. Saved changes show up immediately. The exception is a page where a recipe uses randomness or storage: that one runs again on every view.

Live values

Add | poll(seconds) to a tag, and the page keeps that value up to date without reloading:

<p>Price: %{ with_tax(10) | poll(5) }%</p>

The value is in the page straight away, and a small script asks the server for a new one every 5 seconds. For a value that changes, like one from storage, that's all it takes to show something like a live visitor count on every open page.

• Between 1 and 3600 seconds. Everyone polling the same recipe with the same arguments shares one result per interval, so a popular page doesn't use more of your limits.
• Only in the page's text. Not in a <script>, an attribute, <title>, <style> or <textarea>: those show an error page with the line number. The value goes in a <span> of its own.
• Reading only. A recipe that stores something can't be polled, since it would run at times you don't control.
• Exactly these arguments. Unlike %recipe%(, polling doesn't let visitors call the recipe with other values.
• Background tabs wait. They catch up when someone comes back. If a request fails, the last value stays, and it tries again after a while.

To do something when a value changes, listen for the nh:update event, which bubbles up from the element:

<div id="stats">Visitors: %{ with_tax(1) | poll(10) }%</div>
<script>
  document.getElementById("stats").addEventListener("nh:update", event => {
    console.log("New value:", event.detail.value);
  });
</script>

Arguments

Arguments are plain values. Calculations and variables aren't allowed: compute those in the recipe.

Arguments without a name follow the order of the recipe's parameters. You can also name them, and leave out any that have a default:

%{ add_two(3, 4) }%|%{ add_two(x=3, y=4) }%|%{ add_two(3) }%

This uses a recipe with an optional parameter, from the recipes guide. An argument can't contain the text }%, because that ends the tag.

Where results can go

Results are made safe for the place they end up in, so a < in a result can't break your page:

So inside a script, don't put quotes around the tag:

<script>
  const price = %{ with_tax(10) }%;
</script>

A result can't produce HTML, and tags inside a result don't run. To build markup, return data and create the elements in JavaScript.

Calling from JavaScript

%recipe%(args) turns into a call to a generated function that sends the arguments to the server, runs the recipe there, and returns the result, like any other function. The function is added to your page automatically, before your own scripts. Use it anywhere in the page, including attributes like onclick:

<input id="net" type="number" value="10">
<button onclick="update()">Calculate</button>
<p id="out"></p>

<script>
  function update() {
    const net = Number(document.getElementById("net").value);
    const out = document.getElementById("out");
    try {
      out.textContent = %with_tax%(net);
    } catch (error) {
      out.textContent = error.message;
    }
  }
</script>

• If the recipe fails, the function throws an Error whose message says why.
• Arguments are positional only, in the order of the recipe's parameters.
• The ( is required: %with_tax% on its own stays as plain text, and so does %name%( when there's no such recipe. So you can't pass the function around by name, like list.map(%with_tax%): write list.map(x => %with_tax%(x)).

Without blocking the page

The browser freezes the page while it waits for the answer, usually for a fraction of a second, but longer on a slow connection. Browsers also warn about this in the console. So for anything that runs while someone is typing or scrolling, in a loop, or as the page loads, put a # before the name. %#recipe%(args) doesn't block, and returns a Promise of the result instead:

<script type="module">
  const price = await %#with_tax%(10);
  document.body.append(price);
</script>

<button onclick="%#with_tax%(20).then(alert).catch(e => alert(e.message))">Price</button>

If the recipe fails, the Promise rejects with the same Error. Use await inside an async function or a <script type="module">, or .then() anywhere else.

Handling visitor input

Anyone can call a recipe that a page offers to JavaScript, with any arguments. Two habits keep that safe:

• Declare your parameter types. A "numeric[0..100]" parameter is checked before the recipe runs. Use any only when you really mean it.
• Show results with textContent, not innerHTML. If a recipe returns something a visitor typed, innerHTML would let them run scripts on your page.

Don't count on a calculation in the browser being honest either: if a price matters, work it out in a recipe, from values in the recipe.

When something goes wrong

A mistake in a page, or a recipe that fails during rendering, shows an error page with the line number, so you'll notice it straight away:

Calls from JavaScript report the same messages through the thrown Error or rejected Promise. Their HTTP status codes, if you look in the browser's network tab:

Limits

These keep one site from slowing down the others.

A "run" is one page render, however many tags it has, or one JavaScript call. All the %{ }% tags of a page share one run. Page views that are served from the saved result don't use any.