HTL 快速入门 | Adobe Experience Manager

HTL 的基本概念 fundamental-concepts-of-htl

HTML 模板语言使用表达式语言将内容片段插入到呈现的标记中，并使用 HTML5 数据属性来定义标记块上的语句（如条件或迭代）。在 HTL 编译为 Java Servlet 时，表达式和 HTL 数据属性都完全在服务器端进行计算，不会显示在生成的 HTML 中。
要运行本页面上提供的大多数示例，可以使用称为读取-求值-打印-循环的实时执行环境。
块和表达式 blocks-and-expressions

下面是第一个示例，它可以按原样包含在 template.html 文件中：
<h1 data-sly-test="${properties.jcr:title}">
    ${properties.jcr:title}
                块语句 – 如果你想有条件地显示 <h1> 元素，请使用 data-sly-test HTML5 数据属性。 HTL 提供了多个此类属性，允许将行为附加到任何 HTML 元素，并且所有属性都以 data-sly 为前缀。
                表达式语言 – HTL 表达式通过 ${ 和 } 字符进行分隔。 在运行时，计算这些表达式并将其值注入到传出的 HTML 流中。
        SLY 元素 the-sly-element
        HTL 的一个核心概念是提供重用现有 HTML 元素来定义块语句的可能性。这种重用避免了插入额外的分隔符来定义语句的开始和结束位置的需要。通过不干扰地注释标记，可以将静态 HTML 转换为动态模板，而不会破坏 HTML 有效性，从而确保即使是静态文件也能正确显示。
        但是，有时在必须插入块语句的确切位置上可能没有现有元素。在这种情况下，您可以插入一个特殊的 sly 元素。在运行附加的块语句并相应地显示其内容时，此元素会自动从输出中删除。
        以下示例：
              <sly data-sly-test="${properties.jcr:title && properties.jcr:description}">
    <h1>${properties.jcr:title}</h1>
    <p>${properties.jcr:description}</p>
    <sly data-sly-test="${properties.jcr:title && properties.jcr:description}">
        <h1>${properties.jcr:title}</h1>
        <p>${properties.jcr:description}</p>
              <div data-sly-test="${properties.jcr:title && properties.jcr:description}">
    <h1>${properties.jcr:title}</h1>
    <p>${properties.jcr:description}</p>
        HTL 注释是使用其他类似于 JavaScript 的语法的 HTML 注释。整个 HTL 注释及其中的任何内容都将被处理器完全忽略并从输出中删除。
        不过，将传递标准 HTML 注释的内容，并计算注释中的表达式。
        HTML 注释不能包含 HTL 注释，反之亦然。
        特殊上下文 special-contexts
        为了能够充分利用 HTL，很好地了解它基于 HTML 语法的结果很重要。
        有关详细信息，请参阅 HTL 规范的显示上下文部分。
        元素和属性名称 element-and-attribute-names
        表达式只能放置到 HTML 文本或属性值中，而不能放置到元素名称或属性名称中，否则它就不再是有效的 HTML。 要动态设置元素名称，可以在所需的元素上使用 data-sly-element 语句；要动态设置属性名称，甚至同时设置多个属性，可以使用 data-sly-attribute 语句。
              <h1 data-sly-element="${myElementName}" data-sly-attribute="${myAttributeMap}">...</h1>
        原因是这些上下文的内容是文本而不是 HTML，并且包含的 HTML 元素将被视为简单的字符数据。因此，没有真正的 HTML 元素，也无法执行 data-sly 属性。
        这种方法听起来可能像是一个重大的限制。然而，它是首选，因为 HTML 模板语言应该只生成有效的 HTML 输出。下面的用于访问逻辑的 Use-API 部分介绍了如何从模板调用其他逻辑，可以在需要为这些上下文准备复杂输出时使用它。要将数据从后端发送到前端脚本，请使用组件的逻辑生成 JSON 字符串，并使用简单的 HTL 表达式将其放置在数据属性中。
        以下示例说明了 HTML 注释的行为，但在 script 或 style 元素中，将观察到相同的行为：
    The title is: ${properties.jcr:title}
    <h1 data-sly-test="${properties.jcr:title}">${properties.jcr:title}</h1>
        需要显式上下文 explicit-contexts-required
        如下面的自动上下文感知转义部分中所述，HTL 的一个目标是通过自动将上下文感知转义应用于所有表达式来降低引入跨站点脚本 (XSS) 漏洞的风险。HTL 检测 HTML 标记中表达式的上下文，但不分析内联 JavaScript 或 CSS，因此开发人员必须为这些表达式指定确切的上下文。
        由于没有在 XSS 漏洞中应用正确的转义结果，因此 HTL 会在尚未声明上下文时删除脚本和样式上下文中的所有表达式的输出。
        下面是如何为放置在脚本和样式中的表达式设置上下文的示例：
              <script> var trackingID = "${myTrackingID @ context='scriptString'}"; </script>
<style> a { font-family: "${myFont @ context='styleString'}"; } </style>
        有关如何控制转义的更多详细信息，请参阅 HTL 规范中的表达式语言显示上下文部分。
        HTL 的常规功能 general-capabilities-of-htl
        此部分快速介绍 HTML 模板语言的常规功能。
        用于访问逻辑的 Use-API use-api-for-accessing-logic
        利用 HTML 模板语言 (HTL) Java Use-API，HTL 文件可以通过 data-sly-use 访问自定义 Java 类中的 helper 方法。这样可以将所有复杂的业务逻辑封装在 Java 代码中，而 HTL 代码只处理直接标记生成。
        有关更多详细信息，请参阅 HTL Java Use-API 文档。
        自动上下文感知转义 automatic-context-aware-escaping
        请仔细研究下面的示例：
              <p data-sly-use.logic="logic.js">
    <a href="${logic.link}" title="${logic.title}">
        ${logic.text}
        在大多数模板语言中，此示例可能会造成跨站点脚本 (XSS) 漏洞，因为即使所有变量都会自动进行 HTML 转义，href 属性仍必须经过专门的 URL 转义。这种遗漏是常见的错误之一，因为它容易被遗忘，并且很难自动发现。
        为帮助解决这个问题，HTML 模板语言会根据每个变量所在的上下文自动对每个变量进行转义。此功能的实现得益于 HTL 对 HTML 语法的理解。
        假设以下 logic.js 文件：
              use(function () {
    return {
        link:  "#my link's safe",
        title: "my title's safe",
        text:  "my text's safe"
        请注意两个属性如何以不同的方式进行转义，因为 HTL 知道 href 和 src 属性必须针对 URI 上下文进行转义。 此外，如果 URI 以 javascript: 开头，则除非上下文已显式更改为其他内容，否则将完全删除该属性。
        有关如何控制转义的更多详细信息，请参阅 HTL 规范中的表达式语言显示上下文部分。
        自动删除空属性 automatic-removal-of-empty-attributes
        请仔细研究下面的示例：
              <p class="${properties.class}">some text</p>
        如果 class 属性的值碰巧为空，则 HTML 模板语言将自动从输出中删除整个 class 属性。
        此功能的实现同样得益于 HTL 对 HTML 语法的理解，因此只有当属性的值不为空时，才能有条件地显示具有动态值的属性。 这十分方便，因为它避免了在属性周围添加条件块，这会使标记无效和不可读。
        此外，放置在表达式中的变量的类型很重要：
        使用 HTL 的常见模式 common-patterns-with-htl
        本节介绍几种常见的场景。它解释了如何使用 HTML 模板语言最好地解决这些情况。
        加载客户端库 loading-client-libraries
        在 HTL 中，通过 AEM 提供的帮助程序模板来加载客户端库，可通过 data-sly-use 访问模板。此文件中提供了三个模板，可通过 data-sly-call 来调用它们：
              <!doctype html>
<html data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html">
        <!-- HTML meta-data -->
        <sly data-sly-call="${clientlib.css @ categories='myCategory'}"/>
    </head>
        <!-- page content -->
        <sly data-sly-call="${clientlib.js @ categories='myCategory'}"/>
    </body>
</html>
        在此示例中，如果 HTML head 和 body 元素位于单独的文件中，则必须在每个需要它的文件中加载 clientlib.html 模板。
        HTL 规范中有关 template 和 call 语句的部分提供了有关声明和调用此类模板的工作原理的更多详细信息。
        将数据传递给客户端 passing-data-to-the-client
        一般来说，将数据传递给客户端的更方便、更轻松的方式是使用 data 属性，对于 HTL 来说更是如此。
        下面的示例说明如何将对象序列化为 JSON（在 Java 中也可以）以传递给客户端。然后可以轻松地将其放入 data 属性中：
              <!--/* template.html file: */-->
<div data-sly-use.logic="logic.js" data-json="${logic.json}">...</div>
              var elements = document.querySelectorAll("[data-json]");
for (var i = 0; i < elements.length; i++) {
    var obj = JSON.parse(elements[i].dataset.json);
    //console.log(obj);
              <!--/* template.html file: */-->
<script id="entry-section" type="text/template"
    data-sly-include="entry-section.html"></script>
<!--/* entry-section.html file: */-->
<div class="entry-section">
    <h2 data-sly-test="${properties.entrySectionTitle}">
        ${properties.entrySectionTitle}
    {{#each entry}}<h3><a href="{{link}}">{{title}}</a></h3>{{/each}}
        script 元素的标记可以包含没有明确上下文的 HTL 块语句，因为 Handlebars 模板内容被隔离在其自己的文件中。此外，此示例显示了如何将服务器端执行的 HTL（例如在 h2 元素上）与 Handlebars 之类的客户端执行的模板语言（显示在 h3 元素上）混合。
        不过，一种更现代的技术是改用 HTML template 元素，因为这样做的好处是无需将模板的内容隔离到单独的文件中。
        解除特殊上下文的限制 lifting-limitations-of-special-contexts
        在需要绕过脚本、样式和注释上下文的限制的特殊情况下，可以将它们的内容隔离在单独的 HTL 文件中。 HTL 将其文件中的所有内容解释为标准 HTML 片段，忽略包含它的任何限制上下文。
        请参阅下面的使用客户端模板部分来获取示例。
            CAUTION
            该技术可能引入跨站点脚本（XSS）漏洞。如果使用这种方法，应该仔细研究安全性方面。通常有比依赖这种做法更好的方法来实施同样的目的。