htl-template-loader

Webpack loader for HTL/Sightly data-sly-template templates. Based on @adobe/htlengine.

Installation

npm install --save htl-template-loader @adobe/htlengine

Usage

Entire files

1. Add loader to webpack.config.js:

{
  module: {
    rules: [
      {
        test: /\.htl$/,
        use: ["htl-template-loader"],
      },
    ];
  }
}

2. Create a template file template.htl:

<h1>Hello World</h1>

3. Import render method

import renderMain from './demo.html';

// Render the entire file
console.log(await renderMain());

Templates

1. Add loader to webpack.config.js:

{
  module: {
    rules: [
      {
        test: /\.htl$/,
        use: ["htl-template-loader"],
      },
    ];
  }
}

2. Create a template file template.htl:

<template data-sly-template.greeter="${@ name}">
  <h1>Hello ${name}!</h1>
</template>

3. Import render method

import { render } from './demo.html';

// If no template name is given use the first exported data-sly-template
console.log(await render({ name: 'Alex' }));

// To call a specific template pass the name as first parameter
console.log(await render('greeter', { name: 'Alex' }));

Loader options

templateRoot

The @adobe/htl-engine ships with a scriptResolver to align with the AEM template resolution logic.
The templateRoot option allows to specify a base folder to lookup relative template paths like example/headline.htl.

The following example would look up example/headline.htl in /my-project/templates/example/headline.htl:

<sly
  data-sly-use.headline="example/headline.htl"
  data-sly-call="${headline.headline @ text=text}"
/>

{
  module: {
    rules: [
      {
        test: /\.htl$/,
        use: {
          loader: "htl-template-loader",
          options: {
            templateRoot: "/my-project/templates",
          },
        },
      },
    ];
  }
}

Typescript Typings

htl-template-loader provides optional typescript typings. If you would like to define that all *.htl files export the htl-template-loader functions you can use:

declare module "*.htl" {
  export const {
    render,
    renderMain,
    getTemplate,
    getTemplates,
    getTemplateNames,
  }: typeof import("htl-template-loader/types");
  export default renderMain;
}

This will give you autocomplete and type detection:

import { render } from "./demo.html";
console.log(await render({ name: "Alex" }));

Unfortunately the htl-template-loader is not able to extract the typings for a specific template.
However you can define the template parameters by hand:

import { getTemplate } from "./demo.html";
const greetTemplate = getTemplate<{ name: string }>("greet");

console.log(await greetTemplate({ name: "Alex" }));

Runtime Models

htl-template-loader allows to define models which can be used inside a template

<template data-sly-template.headline="${@ text}">
  <sly data-sly-use.myModel="com.foo.core.models.myModel" />
  <h1>${myModel.salutation} ${text}</h1>
</template>

Define the model for com.foo.core.models.myModel and execute the template:

import { render } from "./demo.html";
render(
  { text: "Alex" },
  {
    models: { "com.foo.core.models.myModel": { salutation: "hi" } },
  }
);

Runtime Globals

htl-template-loader allows to define global variables which can be used inside a template

<template data-sly-template.editMode="${@ text}">
  <h1>${text}</h1>
  <div data-sly-test="${wcmmode.edit}">Edit mode</div>
  <div data-sly-test="${!wcmmode.edit}">Live mode</div>
</template>

Define the data for wcmmode.edit and execute the template:

import { render } from "./demo.html";
render(
  { text: "Alex" },
  {
    globals: { wcmmode: { edit: true } },
  }
);

Changelog

Since 5.0 the changelog can be found here https://github.com/jantimon/htl-template-loader/releases
Old changelog entries can be found here https://github.com/jantimon/htl-template-loader/blob/b47c6d242903f5ab75c2f7f0935a4e2431dafd1d/CHANGELOG.md

License

MIT