Skip to content
HMPL Documentation
...
TwitterDiscordGitHub

Getting Started

HMPL is a fully documented module 📚 with a wide range of usage methods. This guide will help you quickly start working on a new project or connect it to an existing one.

Working with a document directly

Section titled “Working with a document directly”

You can start using it in your project right away without any JavaScript initializations. Just add 4 script tags.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Example</title>
  </head>
  <body>
    <template hmpl>{{#request src="/api/my-component"}}{{/request}}</template>
    <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>

When loading the page, your component will be installed immediately as soon as it comes from the server. You can also try the module in Sanbox online.

Creating a project via a template

Section titled “Creating a project via a template”

You can also use the Vite project template. It is cloned from the GitHub repository using npx degit.

  1. Clone the template:

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

  2. Go to the project directory:

    Terminal window
    cd hello-hmpl

  3. Install dependencies and run the project:

    Terminal window
    npm install
    npm run dev

Once server is running, open your browser at Vite’s server URL (printed in the terminal). Now, let’s create our first web application 🌱!

Project structure

Section titled “Project structure”

The template consists of several files and a couple of folders. Made for the fastest and most flexible start, since using other templates, you constantly have to delete a bunch of unnecessary components.

  • Directorymock
    • api.js
  • Directorypublic
    • hmpl.png
  • Directorysrc
    • Directoryhmpl
      • HelloWorld.hmpl
    • main.js
  • .gitignore
  • README.md
  • index.html
  • package.json
  • vite.config.mjs

Here, everything is modest, but practical.

First component

Section titled “First component”

1. Creating a file

Section titled “1. Creating a file”

To get started, let’s say we have a file called HelloWorld.hmpl in the /src/hmpl directory, it will store the first component of your future application.

HelloWorld.hmpl
<div>
  <div>
    {{#request
      src="/api/hello"
      after="submit:#form"
      repeat=false
      indicators=[
        {
          trigger: "pending",
          content: "<p>Loading...</p>"
        },
        {
          trigger: "rejected",
          content: "<p>Error!</p>;"
        }
      ]
    }}
    {{/request}}
  </div>
</div>

We added indicators here, since we are working with a server. They will be just text, but we could have added a gif with a loader.

2. Mounting a component into the DOM

Section titled “2. Mounting a component into the DOM”

Now, you need to make your component appear on the server. To compile the syntax of the template language into computer-readable js code, we use hmpl-vite-plugin, which allows you to work with files of this extension. There is the same for Webpack.

But, this is connected in the project config, now let’s go to main.js:

main.js
import helloWorld from "./hmpl/HelloWorld.hmpl";


const { response } = helloWorld();


document.body.appendChild(response);

We import HelloWorld as a HMPL template function. To make the request to server we invoke this template function. It returns a HMPL instance object and the response property holds the components received from server and the request state indicator components.

Saving the files will render the component received from the server.

Working with dynamic components

Section titled “Working with dynamic components”

1. Create a Form Component

Section titled “1. Create a Form Component”

Similar to HelloWorld, let’s create a simple registration form component where we only have a name. Let’s call the file Form.hmpl.

<div>
  <form id="form" onsubmit="event.preventDefault()">
    <input type="text" name="name" placeholder="Enter your name" />
    <input type="submit" value="Submit" />
  </form>


  {{#request
    src="/api/hello"
    after="submit:#form"
    repeat=false
    autoBody={
      formData: true
    }
    indicators=[
      {
        trigger: "pending",
        content: "<p>Loading...</p>"
      },
      {
        trigger: "rejected",
        content: "<p>Error!</p>;"
      }
    ]
  }}
  {{/request}}
</div>

Here, we will send FormData with our string to the server.

2. Load the Form Component to DOM

Section titled “2. Load the Form Component to DOM”

And also, you need to import this file into your main.js.

import helloWorldTemplate from './hmpl/HelloWorld.hmpl';
import formTemplate from './hmpl/Form.hmpl';


const { response: response as helloWorld } = helloWorldTemplate();
const { response: response as formEl } = helloWorldTemplate();


document.body.appendChild(helloWorld);
document.body.appendChild(formEl);

3. Submit the form

Section titled “3. Submit the form”

Now you can run the application and try to enter the name value. On the server, you can make a suggestion like "${name} successfully registered!" and do something similar if such a name already exists in the database.

Or use as npm module

Section titled “Or use as npm module”

If you also, for example, use a framework and the connection methods are not very convenient, then you can connect it as a regular npm module and use it purely in javascript.

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);

It is worth noting that the assembly does not include hmpl-dom, it must be installed together with hmpl-js.

Next Steps

Section titled “Next Steps”

Now that you’ve set up your first components, here’s what you can explore next: