hmpl-dom

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 22 Open GitHub ↗

A module for using HMPL syntax directly in HTML, without the need for compilation on the JS side

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hmpl-dom

[![npm-version](https://img.shields.io/npm/v/hmpl-dom?logo=npm&color=fff)](https://www.npmjs.com/package/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](https://www.npmjs.com/package/hmpl-js) right in your HTML documents using the `<template>` tag, and automatically mounts them into the DOM.

> Requires `hmpl-js` version 3.0.0 or higher.

## Installation

```bash
npm install hmpl-dom
```

## Usage

Add a template to your HTML file using the `<template>` tag and the `data-hmpl` or `hmpl` attribute:

```html
<!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>
```

<details>
<summary>Explain this HTML</summary>

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`, and `hmpl-dom`.
- When the page loads, `hmpl-dom` will 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.

</details>

## Configs

Each config object for `init` can contain:

- **id**: (string) — Unique identifier for the template, must match the `data-config-id` in 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.

Example:

```javascript
init([
  {
    id: "1",
    value: {
      compile: { memo: true },
      templateFunction: { credentials: "include" }
    }
  }
]);
```

## Important Notes

- Each `<template>` must contain exactly one root element.
- The `data-config-id` attribute is not required and cannot be empty.
- For every `configId`, a corresponding option must be defined in the `init` call.

## Example

```html
<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>
```

```javascript
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](https://github.com/hmpl-language/hmpl-dom/releases) for changes.

## Contributing

We have a [Contributing Guide](https://github.com/hmpl-language/hmpl/blob/main/CONTRIBUTING.md) 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](https://github.com/hmpl-language/hmpl-dom/blob/main/LICENSE).

hmpl-dom

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README