Templates & controlled pages: two weapons of dynamic content

Overview

19.1 Intro

Not all dynamic content deserves a frontend framework: admin panels, report pages and mail rendering are natural fits for server-side templates. XServer's answer keeps a clean split — xrtTemplate (a compiled template engine, 32 APIs) handles "how to render", the page/ directory (outside wwwroot) handles "whether it is directly reachable": templates and controlled pages never surface in the static layer; they only go out through your routes via LoadPage/rendering.

19.2 Template syntax & rendering

/* 1. prepare data (an xvalue tree, ch18's ownership rules) */
xvalue* pData = xrtValueObject();
xvalue* pList = xrtValueArray();
xrtValueObjectSetNew(pData, XRT_STR_LITERAL("title"),
    xrtValueString(XRT_STR_LITERAL("Template page")));
for ( i = 0; i < N; i++ )
    xrtValueArrayAppendNew(pList,
        xrtValueString(xrtStrView(arrItem[i])));
xrtValueObjectSetNew(pData, XRT_STR_LITERAL("list"), pList);

/* 2. render (LoadTemplate internally: read file → Compile → Render) */
(void)LoadTemplate(pReq, "page.html", pData);

/* 3. release the data tree */
xrtValueRelease(pData);

Template syntax (a real sample from template/page.html):

<h1>{$title}</h1>
<ul>
{#foreach:list}
  <li>{$this}</li>
{/foreach}
</ul>

What just happened: xrtTemplateCompile(xstrview) compiles the source text into an xtemplate* (immutable, reusable); xrtTemplateRender renders it with an xvalue data tree into a str. The demo's LoadTemplate packs "read + compile + render + output" into one call — the full pipeline runs per request (template edits apply immediately, at the cost of recompiling per request), or compile once in ServiceInit and cache (see 19.4).

19.3 Controlled pages & escape protection

Files under page/ are not URL-reachable (the static layer only serves wwwroot). The script's LoadPage reads through an xroot handle, with defenses shared with chapter 10's static layer:

• Root anchoring: reads can only land inside the page/ directory
• Rejecting .., absolute paths and symlink escapes
• Filenames coming from your code rather than request parameters are far safer — a request-supplied filename hands the trust boundary to the user (see the advanced exercise)

19.4 Compilation caching strategies

Two strategies, chosen by scenario:

The caching strategy meshes with chapter 5's "statics isolated per generation": a cached xtemplate* is generation state, rebuilt on swap — the "edited template not taking effect" staleness problem doesn't exist (editing a template is content change; pair it with reload).

19.5 Contract

• Visibility: only wwwroot is URL-reachable; page/template go through script-controlled reads.
• Ownership: the xtemplate* is held by whoever compiles (Release frees it); the str from Render is freed by the caller.
• Caching: cached templates are generation state — rebuilt on swap, never shared across generations by hand.

Common mistakes

LoadPage(pReq, sQueryPage);

/* whitelist mapping: request picks the key, code picks the file */

Exercises