fragmake

A small templating utility for constructing DocumentFragments from a mix of html, content-to-be-escaped, and already-constructed Nodes. Uses tagged template literals, and all expressions are auto-escaped.

It's useful when you don't want to set up a full "component framework" (eg. react, vue, lit, etc.), or when you want to "inject" already-existing nodes/elements.

Node Injection

Template expressions include any type of Node. Those nodes get injected directly (maintaining event listeners and other properties) into the generated fragment. This makes it easy to use already-constructed DOM Nodes, regardless of what pattern or framework you used to create them.

const button = document.createElement('button')
button.onclick = ...
fragmake`<p>${button}</p>`.firstChild.firstChild == button // true

Note that while you can put placeholders anywhere in your template literal (including tag names, attribute names, attribute values), expressions containing Nodes can ONLY be located where it's legal to have an HTMLTemplateElement.

Basic usage

import {fragmake, FragmakeRenderable} from '@qnc/fragmake';

function profile_controls(username: string, log_out_button: HTMLElement, wrapper_class: string): DocumentFragment {
    return fragmake`
        <div class=${wrapper_class}>
            Logged in as ${username}. ${log_out_button}
        </div>
    `
}

fragmake

Our primary function. Intended for use with tagged template literals.

Produces a DocumentFragment from a template literal.

The template literal must represent BALANCED/COMPLETE html tags. If you give us unbalanced html, our behaviour is UNSPECIFIED.

If you give us invalid html, our behaviour is unspecified.

Template expressions can be strings, numbers, Nodes, or arrays (potentially nested) thereof. Strings and numbers will be escaped. Nodes will be injected directly into the resultant fragment.

A "simple" expression is one which contains only strings, numbers, or arrays (potentially nested) thereof. Ie, they contain no Nodes. Simple expressions can be placed anywhere in your template literal, including:

• within tag names
• within attribute names
• within attribute values
• as top-level or element content

Expressions containing Nodes, however, can only be placed where it's legal to have an HTMLTemplateElement (they will be replaced with a string representing a template element before we have the browser parse the html).

html_to_fragment

export function html_to_fragment(html: string): DocumentFragment

This is used internally by fragmake, but users might find it useful when "trusting" known-safe html.

Examples

import {fragmake, FragmakeRenderable} from '@qnc/fragmake';

// Static parts aren't escaped
console.log(fragmake`<i></i>`) // <i></i>

// You can insert regular characters
console.log(fragmake`<i>${"apple"}</i>`) // <i>apple</i>

// You can insert numbers
console.log(fragmake`<i>${1}</i>`)  // <i>1</i>

// You can insert arrays
console.log(fragmake`<i>${[1, 2, 3]}</i>`)  // <i>123</i>

// Special characters are escaped
console.log(
    fragmake`<i data-foo="${`'"`}">${"<>&"}</i>`
) // "<i>&lt;&gt;&quot;&#039;&amp;</i>",

// it's composable
const inner = fragmake`<i>${3}</i>`;
console.log(fragmake`<b>${inner}</b>`)  // <b><i>3</i></b>

// You can put expressions in attributes
console.log(
    fragmake`<a href="mailto:${'"John Doe" <[email protected]>'}">email John Doe</a>`
)   // <a href="mailto:&quot;John Doe&quot; &lt;[email protected]&gt;">email John Doe</a>

// You can inject existing nodes
const button: HTMLButtonElement = make_custom_button()
fragmake`<p>Hello! ${button}</p>`.firstChild.lastChild == button    // true

// Slightly more complex case
const users = [
    { first_name: "Alex", last_name: "Fischer" },
    { first_name: "John", last_name: "Doe" },
    { first_name: "Jane", last_name: "Doe" },
];
console.log(
    fragmake`
        <ul>
            ${users.map((u) => fragmake`<li>${u.first_name} ${u.last_name}</li>`)}
        </ul>
    `
)   
/*
    <ul>
        <li>Alex Fischer</li><li>John Doe</li><li>Jane Doe</li>
    </ul>
*/