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

HTL Java Use-API를 사용하면 HTL 파일이 사용자 정의 Java 클래스의 도우미 메서드에 액세스할 수 있습니다.

사용 사례 use-case

HTL Java Use-API를 사용하면 HTL 파일이 data-sly-use를 통해 사용자 정의 Java 클래스의 도우미 메서드에 액세스할 수 있습니다. 이 방법을 통해 모든 복잡한 비즈니스 논리를 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 맵에는 Use-API 오브젝트가 처리에 사용할 수 있는 현재 실행된 HTL 스크립트에 컨텍스트를 제공하는 오브젝트가 포함될 수 있습니다.

간단한 예 a-simple-example

이 예제에서는 Use-API의 사용 방법에 대해 설명합니다.

use-class가 없는 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 코드 내에서 현재 리소스의 title 및 description에 액세스하고 이를 표시하기 위해서는 컨텍스트 오브젝트 properties가 사용됩니다. 출력 파일 /content/my-example.html은(는) 다음과 같습니다.

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

Use-Class 추가 adding-a-use-class

info 구성 요소는 간단한 기능을 수행하기 위해 use-class가 필요하지 않습니다. 단, HTL에서 수행할 수 없는 작업을 수행해야 하므로 use-class가 필요한 경우가 있습니다. 하지만 다음 사항에 유의하십시오.

예를 들어 info 구성 요소가 리소스의 title 및 description 속성을 표시하지만 모두 소문자로 표시하기를 원한다고 가정합니다. HTL에는 문자열을 소문자로 변환하는 메서드가 없으므로 Java use-class를 추가하고 /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용 Javadocs를 참조하십시오.

이제 코드의 여러 부분을 살펴보겠습니다.

로컬 및 번들 Java 클래스 비교 local-vs-bundle-java-class

Java use-class는 두 가지 방법으로 설치할 수 있습니다.

언제 어떤 방법을 사용해야 하는지 알기 위해서는 두 가지 사항을 염두에 두어야 합니다.

이 예에서는 로컬 설치를 사용합니다.

Java 패키지는 저장소 경로입니다. java-package-is-repository-path

로컬 설치를 사용하는 경우 use-class의 패키지 이름은 저장소 폴더 위치의 패키지 이름과 일치해야 합니다. 패키지 이름의 밑줄은 경로의 모든 하이픈을 대체합니다.

이 경우 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 클래스를 확장하는 것입니다. 이 /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

use-class가 WCMUsePojo에서 확장되면 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

일반적으로 활성화 메서드는 현재 컨텍스트(예: 현재 요청 및 리소스)를 기반으로 HTL 코드에 필요한 값을 미리 계산하고 (멤버 변수에) 저장하는 데 사용됩니다.

WCMUsePojo 클래스는 HTL 파일 내에서 사용 가능한 것과 동일한 컨텍스트 오브젝트 집합에 대한 액세스를 제공합니다(전역 오브젝트 문서 참조).

WCMUsePojo를 확장하는 클래스에서 컨텍스트 오브젝트에 다음과 같이 이름을 사용하여 액세스할 수 있습니다.

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

또는 이 표에 나열된 것처럼 적절한 편의 메서드를 사용해 일반적으로 사용되는 컨텍스트 오브젝트에 직접 액세스할 수 있습니다.

getter 메서드 getter-methods

use-class가 초기화되면 HTL 파일이 실행됩니다. 이 단계에서 HTL은 일반적으로 use-class의 다양한 멤버 변수의 상태를 가져와 표시하기 위해 렌더링합니다.

HTL 파일 내에서 이러한 값에 대한 액세스를 제공하려면 다음 명명 규칙에 따라 use-class에서 사용자 정의 getter 메서드를 정의해야 합니다.

다음 예제 파일 /apps/my-example/component/info/Info.java에서 getTitle 및 getDescription 메서드는 HTL 파일의 컨텍스트 내에서 액세스할 수 있는 오브젝트 속성 title 및 description를 생성합니다.

...

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-class를 초기화하는 데 사용됩니다. 이 예제에서 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-class에 전달할 수 있습니다.

자세한 내용은 Sling HTL 스크립팅 엔진 설명서를 참조하십시오.

번들 Java 클래스 bundled-java-class

번들 use-class에서 표준 OSGi 번들 배포 메커니즘을 사용하여 AEM에서 클래스를 컴파일하고 패키징하고 배포해야 합니다. 로컬 설치와 달리 use-class 패키지 선언의 이름은 일반적으로 이 /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>