Skip to main content

Templates

Templates are versioned Handlebars HTML files (templates/<doc_type>/<version>/template.html) that render a validated dataset into the document a guest or agent sees. One template per document type renders every variant of that type: the reference proposal template renders escorted touring, FIT, cruising, and hybrid trade documents — and all four create-action variants — from one file. Variation is expressed through data and display flags, not template forks.

Templates are fully editable HTML — there are no locked sections or reserved markup. The only contract is the section id registry below (which the QA harness asserts) and the helper registry (which constrains what Handlebars helpers exist). Everything else — structure, layout, copy, imagery — is yours to change.

The canonical section id registry​

Every top-level section in a template carries a registered id. These ids are a contract: the QA harness asserts the presence or absence of each section per dataset and per action, the blueprint's section toggles map onto them, and PDF page-break rules target their CSS classes. Templates must use these exact ids:

Document groupSection ids
Guest documents (proposal)hero, personal-message, highlights, journey-overview, itinerary, services, flights, accommodations, stay-units, arrival-logistics, inclusions, pricing, price-lines, payment-cta, hold-banner, agent-banner, travel-protection, terms, specialist, trust-pillars, footer, action-dock
Finance documents (invoice family)invoice-header, bill-to, line-items, totals, payment-schedule, agent-card, commission-summary, distribution-guard
Booking confirmationconfirmation-header, what-happens-next, trip-summary, financial-summary, how-to-pay
Final travel documentstrip-summary, travelers, service-confirmations, important-info, emergency-contacts

Regulatory certificates (supporting_document_example) sit outside this registry — their layouts are prescribed per scheme.

The _display flag convention​

Document actions control section visibility by injecting boolean flags into the dataset's _display object at generation time (see the blueprint mapping). Templates honour two guard patterns, depending on the section's default:

  • Default-hidden sections (hold-banner, agent-banner, price-lines) render only when a flag is explicitly true:
{{#if _display.showHoldBanner}}
  ...
{{/if}}
  • Default-shown content sections (pricing, inclusions, terms, and so on) render unless a flag is explicitly false. Because an absent flag must mean "shown", the guard tests for explicit false rather than truthiness:
{{#unless (eq _display.showTerms false)}}
  ...
{{/unless}}

The flags are visible in the rendered output. These are sections of the same proposal template rendered under different actions:

Hold banner strip reading: Option held — held for you until 30 June 2026
hold-banner — hidden by default, switched on by the option-hold action
Agent banner identifying the trade partner on an agent proposal
agent-banner — hidden by default, switched on by the trade action
Standard pricing panel with package price and payment call to action
pricing on a standard proposal — package price with payment call to action
Line-level price breakdown table shown on trade proposals
price-lines on an agent proposal — the line-level breakdown trade partners see

Here is a real default-hidden section from the reference proposal template — note the registered id, the _display guard, and the inner data guard:

{{!-- HOLD BANNER (default hidden; shown by create_option) --}}
{{#if _display.showHoldBanner}}
{{#if pricing.holdUntil}}
<section class="hold-banner" id="hold-banner">
  <div class="container">
    <div class="hold-banner__inner">
      <div class="hold-banner__main">
        <div class="hold-banner__eyebrow">Option held</div>
        <div class="hold-banner__label">Held for you until
          <strong class="hold-banner__date">{{> localeDate value=pricing.holdUntil}}</strong></div>
      </div>
      <span class="hold-banner__note">Your places and this price are reserved while you decide.</span>
    </div>
  </div>
</section>
{{/if}}
{{/if}}

Itinerary mode: which sections render​

The proposal template selects its itinerary presentation from meta.itineraryMode together with data presence:

  • #itinerary renders when itinerary.days[] is non-empty and the mode is not services — covering days, both, and the absent-mode fallback.
  • #services renders whenever services[] is non-empty. Cruise documents carry the cruise service entry alongside port-call days, so both sections can appear together.
  • #journey-overview renders only when the mode is services and serviceDates[] is non-empty.

This is why the mode is explicit in the data rather than inferred: a hybrid document that happens to carry both arrays renders predictably, and the QA harness can assert exactly which sections appear for each dataset.

Empty-section collapse​

Independently of display flags, a section with no backing data never renders — header included. The hold banner above collapses without pricing.holdUntil even when its flag is true; the pricing section renders only when the pricing object carries a renderable headline figure; an inclusions section without included or excluded items produces no output at all. This is why schema optionals are nullable by design: a sparse dataset yields a shorter document, never an empty band with a heading over nothing.

The two-layer CSS token system​

Templates are styled exclusively through CSS custom properties, organised in two layers in assets/css/variables.css:

  • Layer 1 — brand primitives. The raw brand values (palette, shadows). This is the only layer a rebrand replaces.
  • Layer 2 — semantic API. The names templates and main.css actually consume. These names are identical across tenants, so templates stay brand-agnostic.
:root {
  /* Layer 1 · brand primitives */
  --flux-primary-600: #034955;
  --flux-yellow-400: #FFBC42;
  --flux-background: #F9FAF8;
  --flux-black: #212121;

  /* Layer 2 · semantic API — consumed by templates; do NOT rename */
  --color-primary: var(--flux-primary-600);
  --color-accent: var(--flux-yellow-400);
  --color-canvas: var(--flux-background);
  --color-ink: var(--flux-black);    /* inverted bands: trust pillars, footer */
  --color-text: var(--flux-black);
}

Templates never contain raw hex values; they reference Layer 2 tokens only (var(--color-accent)). When you rebrand, you replace Layer 1 values and the font definitions — every template picks up the new brand with zero template edits. See the rebranding guide.

Handlebars helpers: what templates may use​

Templates may only use helpers that are available in all of the platform's render registries — the document renderer, the PDF renderer, and the QA harness all execute your template, and a helper missing from any one of them breaks that path. The QA suite includes a helper parity gate for exactly this reason.

The two patterns that matter most:

  • formatCurrency — the one sanctioned way to render money. Takes the raw numeric value and the ISO currency code:
{{formatCurrency pricing.grandTotal pricing.currency}}
  • The localeDate inline-partial pattern — locale-aware dates are implemented as inline partials declared once at the top of the template, taking the date through an explicit value hash argument and resolving the locale from @root so they work at any block depth:
{{#*inline "localeDate"}}{{#if (eq @root.meta.locale "en-US")}}{{date value "MMMM D, YYYY"}}{{else}}{{date value "D MMMM YYYY"}}{{/if}}{{/inline}}

{{!-- usage --}}
due {{> localeDate value=pricing.deposit.dueDate}}

One constraint catches almost everyone once: there are no and / or / not helpers. A condition like "A and B" is expressed by nesting blocks:

{{#if _display.showHoldBanner}}{{#if pricing.holdUntil}}
  ...
{{/if}}{{/if}}

Comparison helpers such as eq are available in subexpressions ({{#if (eq tour.departureType "Fixed")}}), which combined with nesting covers the practical cases.

Quality gates on rendered output​

Every template change runs through the QA harness, which renders each dataset (and each action's display-flag set) at desktop and mobile viewports, asserts the expected and absent section ids, and scans the output for forbidden strings — undefined, [object Object], NaN, unrendered {{ braces, and invalid dates. A binding typo therefore fails CI rather than reaching a guest. Keep this in mind when adding bindings: every field a template references should exist in the schema, and every guard should tolerate null.

Locale-driven rendering​

meta.locale selects more than date formats. Templates branch on it for spelling and phrasing conventions as well — for example, the reference pricing panel renders "per person, double occupancy" for en-US and "per person, twin share" otherwise. Currency formatting via formatCurrency is likewise locale-aware. The dataset never carries pre-formatted display strings for money (the one exception is tour.dates, a display date range, which the schema explicitly documents as such).