Stampino is a fast and flexible HTML template system, where you write dynamic templates using real HTML `<template>` tags:
npm install stampinoStampino is a fast and flexible HTML template system, where you write dynamic templates using real HTML tags:
``html`
Hello {{ name }}
Stampino uses HTML tags to define templates, lit-html for the underlying template rendering, and jexpr for binding expressions.
Stampino is based on the idea that a template defines a function from data to DOM, so it transforms elements into lit-html render functions. Control flow, template composition, and extensibility are built on top of function composition.
This approach leads to a low-cost for features like conditionals and repeating, which are just s themselves:
`html
Messages
These messages are important
{{ item.text }}
`
and are not hard-coded into the core of Stampino. Instead they are just default _template handlers_ that are matched against the "type" attribute. Users can implement their own template handlers just like if and repeat.
Stampino does not currently automatically enable templates within HTML. JavaScript is required to find and make elements available as renderable lit-html templates, and requries lit-html render() calls to render them. Stampino also does not autoamtically wire up super templates, or sub tempalte calls.
The low-level nature of Stampino is intended to allow frameworks and components to define how and what data, control flow handlers, and super- and sub-templates are available.
Stampino is very useful for custom elements that want to allow custom rendering or user-extensibility.
Consider the example of an element that fetches a list of npm packages and renders it, letting users override a default shadow-DOM template. The element may accept a template as a child and render it with Stampino and the package data:
` Version: {{ package.version }}html`
{{ package.name }}
{{ package.description }}
When Stampino processes a template, it creates a lit-html template function.
To render this template:
`html`
Hello {{ name }}
Pass it to prepareTemplate() and use lit-html to render the returned function:`ts
import {prepareTemplate} from 'stampino';
import {render} from 'lit';
const templateElement = document.querySelector('#my-template');
// Returns a lit-html template function that accepts data and
// returns a renderable TemplateResult
const myTemplate = prepareTemplate(templateElement);
render(myTemplate({name: 'World'}), document.body);
`
prepareTemplate() takes options for _template handlers_ (to handle >), _renderers_ (to handle ), and a super template.
_Note: this API is known to have some flaws and will definitely change!_
Expressions are delimted by double braces - {{ }}. They can appear in attribute values and as text/children of elements.
Expressions are interpreted by jexpr, which provides a fast and expressive expression evaluator and supports a subset of JavaScript expressions.
Expressions can include variables, property access, arithmetic, function and method calls, lists, maps and filters.
` What's the answer to life, the universe and everything? {{ 6 * 7 }}html`
See the jexpr README for more expression features.
Stampino uses lit-html's syntax for binding to properties, events, and boolean attributes.
| Binding Type | Prefix | Example |
|-------------------|--------|-------------------------|
| Attribute | none | class=${c} |.
| Property | | .foo=${bar} |@
| Event | | @click=${handleClick} |?
| Boolean Attribute | | ?disabled=${disabled} |
Stampino control flow is based on nested elements with a type attribute. Stampino comes with two built-in template handlers, if and repeat
#### if templates
For conditional rendering, use type="if" and an if attribute.
`html`
Render when condition is true.
#### repeat templates
For repeated templates use type="repeat" and a repeat attribute. The repeat handler automatically adds an item loop variable to the template's scope.
`html`
A template can call another template, either by name or by referece.
The call is written as a with call and optionally data
attributes:
`html`
#### Calling by name
If the call attribute is a plain string, the sub template is looked up in the
renderers configuration.
`html
This the main template
foo is {{ foo }}
`
JavaScript is required to wire this together:
`ts
const main = document.querySelector('#main');
const templateA = document.querySelector('#a');
const mainTemplate = prepareTemplate(
main,
undefined,
{
// A sub-template is a Renderer:
A: (model, handlers, renderers) => {
evaluateTemplate(templateA, model, handlers, renderers);
}
});
`
#### Calling by reference
If the call attribute is an expression, then the sub-template is looked upcall
from the calling template's model by the reference:
`html
This the main template
foo is {{ foo }}
`
JavaScript:
`ts
const main = document.querySelector('#main');
const templateA = document.querySelector('#a');
const mainTemplate = prepareTemplate(
main,
undefined,
undefined);
const aRenderer = (model, handlers, renderers) =>
evaluateTemplate(templateA, model, handlers, renderers);
render(mainTemplate({a: {b: aRenderer}}), container);
`
A template with a name attribute is a "named block". A named block is similar
to a template call with fallback content that can be overriden by renderers.
Named blocks are usually used with inheritance, where the sub-template can
override the named blocks of the base template. They can also be used outside
of inheritance by configuring the main template with renderers for the blocks
that should be overridden.
Besides fallback content, a difference between named blocks is template calls is
that named blocks do not have a data attribute. They inherit the scope of the
callsite.
Stampino supports template inheritance similar to how the popular Jinja library does.
Because Stampino does not automatically find templates in the DOM, even for simple rendering, specifying inheritance is done entirely out-of-band. Set up code must find the template and it's super template, then pass both to prepareTemplate().
`html
This the base template, that defines a "block"
This is a block with fallback content.
This is a sub-template providing new content for a block.
`
`javascript
import {render} from 'lit-html';
import {prepareTemplate} from 'stampino';
const baseEl = document.querySelector('#base-template');
const templateEl = document.querySelector('#my-template');
const myTemplate = prepareTemplate(
templateEl,
undefined, // use default handlers
undefined, // use default (empty) renderers
baseEl); // super template
// Note: the above API isn't great. It'll change
// Use lit-html to render:
render(myTemplate(data), container);
`
Templates can explicitly include a call to the super template with . This lets the sub-template render content before and after the super template:
`html`
This is before the super-template
This is a sub-template providing new content for a block.
This is after the super-template
Most template systems have built-in control-flow constructs like 'if' and 'repeat'. Stampino includes these too, but they are implemented as extensions called template handlers, just like user-provided handlers.
Handlers are functions that implement this signature:
`typescript`
function handler
template: HTMLTemplateElement,
model: Model,
handlers: Handlers,
renderers: renderers,
): TemplateResult|Directive|string|number|((string|number)[]);
They can return any lit-html rendereable object, including strings, numbers, arrays, TemplateResults, or directives.
Handlers are passed to prepareTemplate():
`javascript
import {prepareTemplate, evaluateTemplate} from 'stampino';
const myTemplate = prepareTemplate(
element,
{
// Renders a template twice
'echo': (template, model, handlers, renderers) => {
return [
evaluateTemplate(template, model, handlers, renderers),
evaluateTemplate(template, model, handlers, renderers)];
},
}
);
`
Handlers are referenced inside templates via the type attribute:
`html`
Do I hear an echo?
Yes, I hear an echo!
You can think of this very much like is syntax for a function call. Here's the entire implementation of the 'if' handler:
`javascript`
handlers: {
'if': (template, model, handlers, renderers) => {
const ifAttribute = template.getAttribute('if');
if (ifAttribute !== null && getSingleValue(ifAttribute, model)) {
return evaluateTemplate(template, model, handlers, renderers);
}
return undefined;
},
},
Note: getSingleValue()` evaluates an expression against a model. It's provided by the Stampino library.
Stampino is a side-project and development typically happens in bursts. Things are changing quickly, so be careful. If you find a problem or are intested in contributing please reach out in the issues.