HTL Java Use-API htl-java-use-api

HTL Java Use-API 让 HTL 文件可以访问自定义 Java 类中的 Helper 方法。

用例 use-case

HTL Java Use-API 让 HTL 文件可以通过 data-sly-use 访问自定义 Java 类中的 Helper 方法。 这样可以将所有复杂的业务逻辑封装在 Java 代码中，而 HTL 代码只处理直接标记生成。

Java Use-API 对象可以是一个简单的 POJO，由特定的实现通过 POJO 的默认构造器实例化。

Use-API POJO 也可以使用以下签名公开名为 init 的公共方法：

    /**
     * Initializes the Use bean.
     *
     * @param bindings All bindings available to the HTL scripts.
     **/
    public void init(javax.script.Bindings bindings);

bindings 映射可以包含一些对象，这些对象向当前执行的 HTL 脚本提供上下文，以便 Use-API 对象可使用这些上下文进行处理。

简单示例 a-simple-example

此示例说明了 Use-API 的用法。

我们先来看一个没有 use 类的 HTL 组件，名为 info。 它由单个文件 /apps/my-example/components/info.html 组成

<div>
    <h1>${properties.title}</h1>
    <p>${properties.description}</p>
</div>

我们还为该组件添加了一些内容，以便在 /content/my-example/ 上呈现：

{
    "sling:resourceType": "my-example/component/info",
    "title": "My Example",
    "description": "This Is Some Example Content."
}

当用户访问此内容时，系统会执行 HTL 文件。在 HTL 代码内，我们使用上下文对象 properties 来访问当前资源的 title 和 description，并显示它们。 输出的文件 /content/my-example.html 会是这样：

<div>
    <h1>My Example</h1>
    <p>This Is Some Example Content.</p>
</div>

添加一个 use 类 adding-a-use-class

目前 info 组件不需要 use 类来执行其（非常简单的）功能。 有些情况下，您需要做的事情无法在 HTL 中完成，因此需要 use 类。但请记住：

例如，假设您想让 info 组件显示资源的 title 和 description 属性且必须全部小写。由于 HTL 没有将字符串转换为小写的方法，所以您需要 use 类。我们的解决办法是，添加一个 Java use 类并更改 /apps/my-example/component/info/info.html，如下所示：

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

此外，我们还创建了 /apps/my-example/component/info/Info.java。

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    private String lowerCaseTitle;
    private String lowerCaseDescription;

    @Override
    public void activate() throws Exception {
        lowerCaseTitle = getProperties().get("title", "").toLowerCase();
        lowerCaseDescription = getProperties().get("description", "").toLowerCase();
    }

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

有关详细信息，请参见com.adobe.cq.sightly.WCMUsePojo](https://developer.adobe.com/experience-manager/reference-materials/6-5/javadoc/com/adobe/cq/sightly/WCMUsePojo.html) 的 [Javadocs。

现在让我们浏览代码的不同部分。

局部与捆绑 Java 类 local-vs-bundle-java-class

Java use 类有以下两种安装方式：

要知道何时使用哪种方法，请记住以下两点：

本例使用局部安装。

Java 包是存储库路径 java-package-is-repository-path

使用局部安装时，use 类的包名称必须与存储库文件夹位置的名称匹配，在包名称中将路径中的所有连字符替换为下划线。

在此情形中，Info.java 位于 /apps/my-example/components/info，因此包名称为 apps.my_example.components.info：

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {

   ...

}

扩展 WCMUsePojo extending-wcmusepojo

尽管 Java 类与 HTL 结合的方法很多（请参阅 WCMUsePojo 的替代项部分），但更简单的方法是扩展 WCMUsePojo 类。 以我们为例/apps/my-example/component/info/Info.java：

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo

    ...
}

初始化类 initializing-the-class

从 WCMUsePojo 扩展 use 类时，通过覆盖 activate 方法来执行初始化，在本例中为 /apps/my-example/component/info/Info.java

...

public class Info extends WCMUsePojo {
    private String lowerCaseTitle;
    private String lowerCaseDescription;

    @Override
    public void activate() throws Exception {
        lowerCaseTitle = getProperties().get("title", "").toLowerCase();
        lowerCaseDescription = getProperties().get("description", "").toLowerCase();
    }

...

}

上下文 context

通常，activate 方法用于根据当前上下文（例如当前请求和资源）预先计算和存储（在成员变量中）HTL 代码中所需的值。

WCMUsePojo 类提供对 HTL 文件中同样的上下文对象集的访问（请参阅全局对象文档）。

在扩展 WCMUsePojo 的类中，可以使用名称访问对象

<T> T get(String name, Class<T> type)

或者，可以通过本表中列出的适当方便方法直接访问常用的上下文对象。

Getter 方法 getter-methods

一旦 use 类初始化，HTL 文件即会运行。在此阶段，HTL 通常会拉入 use 类的各种成员变量的状态，并渲染它们以便呈现。

要提供从 HTL 文件内访问这些值的权限，您必须根据以下命名惯例在 use 类中定义自定义 getter 方法：

在以下示例文件/apps/my-example/component/info/Info.java中，方法 getTitle 和 getDescription 使对象属性 title 和 description 在 HTL 文件上下文内变为可访问。

...

public class Info extends WCMUsePojo {

    ...

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

data-sly-use 属性 data-sly-use-attribute

data-sly-use 属性用于初始化 HTL 代码中的 use 类。在我们的示例中，data-sly-use 属性声明我们需要使用类 Info：我们可以只使用该类的局部名称，因为我们使用的是局部安装（Java 源文件与 HTL 文件放在同一文件夹中）。如果我们使用捆绑安装，则须指定完全限定的类名称。

注意本 /apps/my-example/component/info/info.html 示例中的用法。

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

局部标识符 local-identifier

标识符 info（位于 data-sly-use.info 中的点后）用于在 HTL 文件中标识类。声明该标识符后，其作用范围是整个文件。这不限于包含 data-sly-use 语句的元素。

注意本 /apps/my-example/component/info/info.html 示例中的用法。

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

获取属性 getting-properties

标识符 info 然后用于访问通过 getter 方法 Info.getTitle 和 Info.getDescription 公开的对象属性 title 和 description。

注意本 /apps/my-example/component/info/info.html 示例中的用法。

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

输出 output

现在，当我们访问 /content/my-example.html 时，它会返回以下 /content/my-example.html 文件：

<div>
    <h1>my example</h1>
    <p>this is some example content.</p>
</div>

基本功能拓展 beyond-the-basics

本节介绍了一些超出前述简单示例的其他功能。

传递参数 passing-parameters

初始化时，可将参数传递给 use 类。

有关详细信息，请参阅 Sling HTL 脚本引擎文档。

捆绑的 Java 类 bundled-java-class

对于捆绑的 use 类，必须使用标准 OSGi 捆绑包部署机制在 AEM 中编译、打包和部署类。 与局部安装相反，use 类包声明应按照该 /apps/my-example/component/info/Info.java 示例中的方式正常命名。

package org.example.app.components;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    ...
}

同时，data-sly-use 语句必须引用完全限定的类名称，而非该 /apps/my-example/component/info/info.html 示例中仅引用局部类名称：

<div data-sly-use.info="org.example.app.components.info.Info">
  <h1>${info.title}</h1>
  <p>${info.description}</p>
</div>