Template

A lightweight Handlebars-inspired template engine with support for conditionals, loops, partials, HTML escaping, raw output, and automatic i18n DOM translation. Templates are loaded from HTML files, cached in memory, and compiled with a simple data-binding syntax.

Quick Start

Configure the template base path, register a route, and render a template into the container element with a single call.

js
import Aura from 'aurajs';

// Configure template paths
Aura.template.configure({
  basePath: '/templates',
  container: '#app',
  loadingHTML: '<div class="spinner">Loading...</div>'
});

// Render a template into the container
await Aura.template.renderTo('home', {
  title: 'Welcome',
  items: ['Alpha', 'Beta', 'Gamma']
});

// Or compile an inline string
const html = Aura.template.renderString(
  '<h1>{{title}}</h1>',
  { title: 'Hello Aura' }
);

Types

TemplateConfig

Configuration object accepted by configure(). All fields are optional (partial).

Property	Type	Description
basePath	string	Root URL path for loading template HTML files. Default: `'/templates'`.
container	string	CSS selector for the DOM element that `renderTo()` writes into. Default: `'#flxy-app'`.
loadingHTML	string	HTML string shown while a template is being fetched. Default: `'<div class="aura-loading">Loading...</div>'`.

configure() core

Merge partial configuration into the current template settings. Any provided fields override the existing values.

Aura.template.configure(config: Partial<TemplateConfig>): void

Param	Type	Description
config	Partial<TemplateConfig>	Object with optional `basePath`, `container`, and `loadingHTML` fields.

js
Aura.template.configure({
  basePath: '/views',
  container: '#main-content'
});

renderString() core

Compile an inline HTML string with the template engine. Processes all directives (#if, #each, #unless, variables, raw output) and returns the resulting HTML. Does not touch the DOM.

Aura.template.renderString(html: string, data?: Record<string, unknown>): string

Param	Type	Description
html	string	Template string containing Aura template syntax.
data	Record<string, unknown>	Optional data object whose keys are available as template variables. Defaults to `{}`.

js
const result = Aura.template.renderString(
  '<p>Hello, {{name}}!</p>',
  { name: 'World' }
);
// => "<p>Hello, World!</p>"

// With conditionals
const card = Aura.template.renderString(`
  <div class="card">
    {{#if premium}}<span class="badge">PRO</span>{{/if}}
    <h2>{{name}}</h2>
  </div>
`, { name: 'Alice', premium: true });

renderTo() core

Load a template file by name, resolve any partials, compile it with the given data, and inject the result into the configured container element. Also runs i18n.translateDOM() on the container afterwards.

Aura.template.renderTo(name: string, data?: Record<string, unknown>): Promise<void>

Param	Type	Description
name	string	Template file name (without `.html`). Loaded from `basePath/name.html`.
data	Record<string, unknown>	Optional data object for template variables. Defaults to `{}`.

js
// Loads /templates/profile.html, compiles, and injects
await Aura.template.renderTo('profile', {
  user: { name: 'Alice', role: 'Admin' },
  posts: [
    { title: 'First Post', date: '2026-01-15' },
    { title: 'Second Post', date: '2026-02-20' }
  ]
});

render() core

Load a template file, resolve partials, and compile it with data, returning the final HTML string without injecting it into the DOM. Useful when you need the HTML for further processing.

Aura.template.render(name: string, data?: Record<string, unknown>): Promise<string>

Param	Type	Description
name	string	Template file name (without `.html`).
data	Record<string, unknown>	Optional data object for template variables. Defaults to `{}`.

js
const html = await Aura.template.render('card', {
  title: 'My Card',
  description: 'A nice card component.'
});
// Use the HTML string elsewhere
document.querySelector('.sidebar').innerHTML += html;

resolvePartials() utility

Scan an HTML string for partial includes ({{> name}}) and recursively replace them with the loaded partial content. Partials are loaded from the configured basePath and cached.

Aura.template.resolvePartials(html: string): Promise<string>

Param	Type	Description
html	string	Template string potentially containing `{{> partialName}}` directives.

js
const raw = '<div>{{> header}}<main>Content</main>{{> footer}}</div>';
const resolved = await Aura.template.resolvePartials(raw);
// header.html and footer.html are fetched and inlined

setDefaultData() utility

Set global default data that is automatically merged into every template compilation. Template-specific data takes precedence over defaults when keys conflict.

Aura.template.setDefaultData(data: Record<string, unknown>): void

Param	Type	Description
data	Record<string, unknown>	Key-value pairs available in all templates. Merged with `Object.assign` (shallow).

js
// These values are available in every template
Aura.template.setDefaultData({
  appName: 'My App',
  year: 2026,
  version: '1.0.0'
});

// In any template: <footer>© {{year}} {{appName}}</footer>

preload() utility

Pre-fetch and cache multiple templates in parallel. Useful during app initialization to avoid loading delays on first navigation.

Aura.template.preload(names: string[]): Promise<void>

Param	Type	Description
names	string[]	Array of template names to fetch and cache (without `.html`).

js
// Preload critical templates at startup
await Aura.template.preload(['home', 'header', 'footer', 'nav']);

addToCache() utility

Manually insert an HTML string into the template cache under a given name. Useful for injecting dynamically generated templates or templates received from an API.

Aura.template.addToCache(name: string, html: string): void

Param	Type	Description
name	string	Cache key (same as the name used with `render()` and `renderTo()`).
html	string	Raw HTML template string to store in the cache.

js
// Register a partial manually
Aura.template.addToCache('alert',
  '<div class="alert alert-{{type}}">{{message}}</div>'
);

// Now it can be used as a partial: {{> alert}}

clearCache() cache

Remove all cached templates. The next call to render() or renderTo() will re-fetch templates from the server.

Aura.template.clearCache(): void

This method takes no parameters.

js
// Clear all cached templates
Aura.template.clearCache();

// Or refresh a single template
await Aura.template.refreshCache('home');

removeFromCache() cache

Remove a single template from the cache by name.

Aura.template.removeFromCache(name: string): void

Param	Type	Description
name	string	The cache key of the template to remove.

js
Aura.template.removeFromCache('profile');

refreshCache() cache

Delete a template from the cache and immediately re-fetch it from the server. Returns the fresh HTML string.

Aura.template.refreshCache(name: string): Promise<string>

Param	Type	Description
name	string	Template name to invalidate and reload.

js
// Force-reload a template after server-side update
const fresh = await Aura.template.refreshCache('dashboard');

Template Syntax

Aura templates use a Handlebars-inspired syntax. All expressions are enclosed in double or triple curly braces.

Variable Output — `{{var}}`

Output an HTML-escaped value. Supports dot notation for nested properties.

html
<!-- Simple variable -->
<h1>{{title}}</h1>

<!-- Nested property -->
<p>Author: {{user.name}}</p>

<!-- HTML entities are escaped automatically -->
<!-- data: { tag: "<script>" } => "&lt;script&gt;" -->

Raw Output — `{{{raw}}}`

Output a value without HTML escaping. Use this for trusted HTML content.

html
<!-- Renders HTML without escaping -->
<div class="content">{{{bodyHTML}}}</div>

<!-- data: { bodyHTML: "<strong>Bold</strong>" } -->
<!-- => <div class="content"><strong>Bold</strong></div> -->

Conditionals — `{{#if}}`

Render a block only if the value is truthy. Supports an optional {{else}} branch.

html
{{#if isLoggedIn}}
  <p>Welcome back, {{user.name}}!</p>
{{else}}
  <p>Please <a href="/login">sign in</a>.</p>
{{/if}}

<!-- Nested property conditions -->
{{#if user.isAdmin}}
  <button>Admin Panel</button>
{{/if}}

Unless — `{{#unless}}`

Render a block only if the value is falsy. The inverse of #if.

html
{{#unless hasItems}}
  <p class="empty">No items found.</p>
{{/unless}}

Loops — `{{#each}}`

Iterate over an array. Inside the loop, object properties are available directly. Special variables @index, @first, and @last are provided.

html
<ul>
{{#each items}}
  <li class="{{#if @first}}first{{/if}}">
    {{@index}}. {{title}} &mdash; {{author}}
  </li>
{{/each}}
</ul>

<!-- data: { items: [
  { title: "Post A", author: "Alice" },
  { title: "Post B", author: "Bob" }
]} -->

Partials — `{{> name}}`

Include another template file by name. Partials are loaded from the same basePath and resolved recursively (partials can include other partials).

html
<!-- main.html -->
<div class="page">
  {{> header}}
  <main>{{content}}</main>
  {{> footer}}
</div>

<!-- header.html -->
<header><h1>{{appName}}</h1></header>

<!-- Or register partials manually -->

js
// Register a partial from a string
Aura.template.addToCache('header',
  '<header><h1>{{appName}}</h1></header>'
);