hmpl-dom
v0.0.2
Published
A module for using HMPL syntax directly in HTML, without the need for compilation on the JavaScript side
Maintainers
anthonymaxReadme
hmpl-dom
hmpl-dom is a library for integrating HMPL templates directly into the DOM. It allows you to use templates written with hmpl-js right in your HTML documents using the <template> tag, and automatically mounts them into the DOM.
Requires
hmpl-jsversion 3.0.0 or higher.
Installation
npm install hmpl-domUsage
Add a template to your HTML file using the <template> tag and the data-hmpl or hmpl attribute:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Example</title>
</head>
<body>
<main>
<template data-hmpl data-config-id="my-component-config">
<div>
{{#request src="/api/my-component.html"}}
{{#indicator trigger="pending"}}
Loading...
{{/indicator}}
{{/request}}
</div>
</template>
</main>
<script src="https://unpkg.com/json5/dist/index.min.js"></script>
<script src="https://unpkg.com/dompurify/dist/purify.min.js"></script>
<script src="https://unpkg.com/hmpl-js/dist/hmpl.min.js"></script>
<script src="https://unpkg.com/hmpl-dom/dist/hmpl-dom.min.js"></script>
</body>
</html>This HTML example demonstrates how to use the hmpl-dom library to mount HMPL templates directly in your page:
- The
<template data-hmpl data-config-id="my-component-config">tag defines a template that will not be rendered immediately. It contains HMPL syntax for dynamic content loading. - Inside the template, the
{{#request src="/api/my-component.html"}} ... {{/request}}block will fetch content from the server. While the request is pending, the{{#indicator trigger="pending"}} Loading... {{/indicator}}block will show a loading message. - The scripts at the bottom load all required dependencies from CDN:
json5,dompurify,hmpl-js, andhmpl-dom. - When the page loads,
hmpl-domwill automatically find all<template data-hmpl ...>elements, compile them using HMPL, and replace the template with the rendered result in the DOM.
This approach allows you to declaratively define dynamic, server-driven components in your HTML, and have them automatically rendered and updated by the HMPL engine.
Configs
Each config object for init can contain:
- id: (string) — Unique identifier for the template, must match the
data-config-idin HTML. - value: (object)
- compile: (object) — Compile options for HMPL (e.g.,
{ memo: true }). - templateFunction: (object) — Data or parameters to be passed to the template function.
- compile: (object) — Compile options for HMPL (e.g.,
Example:
init([
{
id: "1",
value: {
compile: { memo: true },
templateFunction: { credentials: "include" }
}
}
]);Important Notes
- Each
<template>must contain exactly one root element. - The
data-config-idattribute is not required and cannot be empty. - For every
configId, a corresponding option must be defined in theinitcall.
Example
<template data-hmpl data-config-id="clicker-config">
<div>
<button data-action="increment" id="btn">Click!</button>
<div>
Clicks: {{#request src="/api/clicks" after="click:#btn"}}{{/request}}
</div>
</div>
</template>import { init } from "hmpl-dom";
init([
{
id: "clicker-config",
value: {
compile: { memo: true },
templateFunction: ({ request: { event } }) => ({
body: JSON.stringify({
action: event.target.getAttribute("data-action")
})
})
}
}
]);Changelog
See the GitHub releases page for changes.
Contributing
We have a Contributing Guide that describes the main steps for contributing to the project.
Thank you to all the people who have already contributed to HMPL, or related projects!
License
This project is licensed under the MIT License.