hmpl-js

v3.2.1

Published

2 months ago

🐜 HMPL.js is a lightweight server-oriented template language for JavaScript. Fetch HTML, render it safely, and keep apps dynamic, modern, and small.

Downloads

201

Introduction

HMPL.js provides the flexibility to build server-driven templates with minimal JavaScript. With its block-based syntax, customizable fetch requests, and built-in support for forms, events, and time-based syncing you can deliver dynamic user interfaces without relying on a heavy framework. HMPL integrates with JSON5 for expressive object syntax and DOMPurify for safe HTML rendering, all in just a few kilobytes.

Example

<div>
  {{#request src="/api/my-component.html"}}
    {{#indicator trigger="pending"}}
      <p>Loading...</p>
    {{/indicator}}
  {{/request}}
</div>

Try HMPL online at: hmpl-playground

Basic usage

import hmpl from "hmpl-js";

const templateFn = hmpl.compile(
  `<div>
      <button data-action="increment" id="btn">Click!</button>
      <div>Clicks: {{#request src="/api/clicks" after="click:#btn"}}{{/request}}</div>
  </div>`
);

const clicker = templateFn(({ request: { event } }) => ({
  body: JSON.stringify({ action: event.target.getAttribute("data-action") })
})).response;

document.querySelector("#app").append(clicker);

import hmpl from "hmpl-js"; // Import the HMPL library

// Compile an HMPL template with dynamic behavior
const templateFn = hmpl.compile(
  `<div>
      <button data-action="increment" id="btn">Click!</button>
      <!-- This div will update with the click count from /api/clicks -->
      <div>Clicks: {{#request src="/api/clicks" after="click:#btn"}}{{/request}}</div>
      <!-- Also, you can write in short: {{#r src="..."}}{{/r}} -->
  </div>`
);

// Generate a response handler for the template
// In the original object, we will have the following: { response: div, status: 200 }
const clicker = templateFn(({ request: { event } }) => ({
  // Send a JSON payload with the action from the button's data attribute
  body: JSON.stringify({ action: event.target.getAttribute("data-action") })
})).response;

// Append the dynamically generated element to the #app container
document.querySelector("#app").append(clicker);

In this example, we create a dynamic clicker component in which, when a button is pressed, we will receive the value of the current clicks that will come from the server. The advantage of this approach is that we can take out not only data in the form of Text, but also entire components and even pages!

Usage with DOM

If you need an option without using js, then by connecting the additional hmpl-dom module you can do this.

<!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 hmpl>
        <div>
          {{#request src="/api/my-component.html"}}
            {{#indicator trigger="pending"}}
              <p>Loading...</p>
            {{/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 way, components from the server are mounted into the DOM without having to add them manually.

Why HMPL?

Using template language capabilities, you can multiply reduce the size of the application bundle. Full customization of the request based on the modern fetch standard, as well as support for all the functionality necessary for modern work in applications (request indicator, sending by event, automatic generation of body for the form, caching) and the syntax of the object in the markup, which requires a minimum number of characters, will help to build interaction with the server and client as efficiently as possible. App size comparison (bytes):

Also, HMPL can be a great alternative to popular tools such as HTMX and Alpine.js.

Features

Customizable: Send a custom request to the server when receiving the UI
Memory Preserving: Reduce file sizes on the client by several times
Based on Fetch API: Use a modern standard instead of XMLHTTPRequest
Server-oriented: Work with the server directly through markup and with a little js
Generate thousands of DOM nodes from a single template: Work with large components not only on the server but also on the client
Simple: Get ready-made UI from the server by writing a couple of lines of familiar object syntax
Protected from XSS attacks: Enable incoming server HTML sanitization with DOMPurify and work with it safely
Flexible: Can be used in almost any project due to not only working through a script, but also working in files with the .hmpl extension
Integrated with JSON5: Flexible writing of objects by docs as in vanilla js, as well as the reliability of the parser used by millions of people
Small bundle size: Lots of functionality in a couple of kilobytes

Installation

hmpl can be installed in several ways, which are described in this section. This tool is a simple javascript file that is connected in the usual way through a script, or using the import construct in an environment that supports this (webpack build, parcel build etc.).

[!NOTE] Starting with version 2.2.0, the JSON5 module needs to be connected, and starting with version 2.2.5, the DOMPurify module also needs to be connected. The first and easiest way is to install using a CDN.

Package Manager

This method involves downloading through npm or other package managers.

npm i hmpl-js

Along the path node_modules/hmpl/dist you can find two files that contain a regular js file and a minified one.

CDN

This method involves connecting the file through a third-party resource, which provides the ability to obtain a javascript file from npm via a link.

<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>
<!--   
  integrity="..."
  crossorigin="anonymous"
-->

This resource could be unpkg, skypack or other resources. The examples include unpkg simply because it is one of the most popular and its url by characters is not so long.

Through the starter template project

There is a starter project on Vite.

npx degit hmpl-language/hello-hmpl-starter hello-hmpl

Based on it, you can make web applications.

Official Tools

But we will be glad if you make your own :)

Community support

The documentation contains main information on how the HMPL template language works. If you have any questions about how HMPL works, you can use the following resources:

GitHub - In the discussion and issues sections you can ask any question you are interested in
Discord - You can ask your question in the thematic channel "support"
𝕏 (Twitter) - There is a lot of interesting stuff there, concerning the template language and not only :)

You can also ask your question on Stack Overflow and address it in the resources described above.

Contribution

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!

Star History

Roadmap

The project has a roadmap where you can see the plans for future development.

License

Released under the MIT

💎 Star this repo • 💻 Try HMPL.js • 💬 Join Discord

This project has been developed with contributions from many amazing community developers!