Templater

Simple templating engine using html's built-in template element with JavaScript variables and functions.

Features

• Use JavaScript varables within the ${ ... } syntax.
  • ${ ... } is used for simple variable interpolation.
• Input sanitization for untrusted data.
• Support for custom syntax

Future Plans (not yet implemented)

• Support for function calls within templates.
• Support for nested data access (e.g., ${ user.name }).

Usage Example

Simple

<template id="my-template">
	<!-- Display simple variables -->
	<h1>${ title }</h1>
	<p>${ description }</p>
</template>

import { Templater } from 'litmpl';
const template = Templater.fromId('my-template');
const data = {
	title: 'My List',
	description: 'This is a list of items:',
};
const result = template.render(data); // <h1>My List</h1><p>This is a list of items:</p>
document.body.appendChild(result);

With custom syntax

<template id="custom-template">
	<!-- Using custom syntax for variable interpolation -->
	<h1><% title %></h1>
	<p>${ description }</p>
</template>

import { Templater, replacePatterns } from 'litmpl';
replacePatterns["capital"] = {
	pattern: /<%\s*([\w.]+)\s*%>/g,
	variableGetter: (matches) => ({var: matches[1]}),
	replacer: (content, matches, variableNames, data) =>
		content.replace(matches[0], data[variableNames.var as string].toString().toUpperCase()),
};
const template = Templater.fromId('custom-template');
const data = {
	title: 'my list',
	description: 'This is a list of items:',
};
const result = template.render(data); // <h1>MY LIST</h1><p>This is a list of items:</p>
document.body.appendChild(result);

API

Parse Template

• Templater.fromId(templateId: string): ParsedTemplater
  Parses a template from an HTML element with the specified ID.
• Templater.fromElement(htmlTemplate: HTMLTemplateElement): ParsedTemplater
  Parses a template from a given HTMLTemplateElement.
• Templater.fromString(templateString: string): ParsedTemplater
  Parses a template from a string containing HTML.

Render Template

• render(data: Record<string, any>): RenderedTemplateElement
  Renders the template with the provided data and returns a DocumentFragment.
• renderToString(data: Record<string, any>): string
  Renders the template with the provided data and returns the resulting HTML as a string.

Custom Syntax

note: ReplacePattern is defined as:\

{
	pattern: RegExp;
	variableGetter: (matches: RegExpExecArray) => Record<string, string|string[]>;
	customDataGetter?: (matches: RegExpExecArray) => Record<string, unknown>;
	replacer: (content: string, matches: RegExpExecArray, variableNames: Record<string, string|string[]>, data: Record<string, { toString(): String }>, customData: Record<string, unknown>) => string;
}

where the replacer.variableNames is the output of variableGetter and replacer.customData is the output of customDataGetter (if provided).

• replacePatterns: Record<string, ReplacePattern>
  The list of all syntax patterns used when parsing and rendering templates
• setReplacePattern(replacePattern: Record<string, ReplacePattern>): void
  Overwrites all existing replace patterns with the provided ones.

License

This project is licensed under the GPL-3.0-or-later license.