SCF Handlebars Helpers

Handlebars Helpers(helpers)는 SCF 구성 요소 작업을 용이하게 하기 위해 Handlebars 스크립트에서 호출할 수 있는 메서드입니다.

구현에는 클라이언트측과 서버측 정의가 포함됩니다. 또한 개발자가 사용자 정의 도움말을 만들 수도 있습니다.

AEM Communities으로 제공된 사용자 지정 SCF 도우미는 클라이언트 라이브러리에 정의됩니다.

• /etc/clientlibs/social/commons/scf/helpers.js

약어

maxWords 및 maxLength 속성을 따르는 축약된 문자열을 반환하는 도우미입니다.

축약할 문자열은 컨텍스트로 제공됩니다. 제공된 컨텍스트가 없으면 빈 문자열이 반환됩니다.

먼저 컨텍스트를 maxLength로 트리밍한 다음, 컨텍스트를 단어로 잘라서 maxWords로 줄입니다.

safeString이 true로 설정된 경우 반환된 문자열은 SafeString입니다.

매개 변수

• 컨텍스트:문자열

  (선택 사항) 기본값은 빈 문자열입니다.

• maxLength:숫자

  (선택 사항) 기본값은 컨텍스트의 길이입니다.

• maxWords:숫자

  (선택 사항) 기본값은 트리밍된 문자열의 단어 수입니다.

• safeString:부울

  (선택 사항) true인 경우 Handlebars.SafeString()을 반환합니다. 기본값은 false입니다.

예

{{abbreviate subject maxWords=2}}

/*
If subject =
    "AEM Communities - Site Creation Wizard"

Then abbreviate would return
    "AEM Communities".
*/

{{{abbreviate message safeString=true maxLength=30}}}

/*
If message =
    "The goal of AEM Communities is to quickly create a community engagement site."

Then abbreviate would return
    "The goal of AEM Communities is"
*/

내용-로더

두 보기 간을 전환할 수 있는 기능을 사용하여 div 아래에 두 범위를 추가하는 도우미, 하나는 전체 텍스트에 대해 하나, 다른 하나는 적은 텍스트에 대해 추가합니다.

매개 변수

• 컨텍스트:문자열

  (선택 사항) 기본값은 빈 문자열입니다.

• numChars:숫자

  (선택 사항) 전체 텍스트를 표시하지 않을 때 표시할 문자 수입니다. 기본값은 100입니다.

• moreText:문자열

  (선택 사항) 표시할 텍스트가 더 있음을 나타내는 텍스트입니다. 기본값은 "more"입니다.

• ellipsesText:문자열

  (선택 사항) 숨겨진 텍스트가 있음을 나타내는 표시할 텍스트입니다. 기본값은 "…"입니다.

• safeString:부울

  (선택 사항) 결과를 반환하기 전에 Handlebars.SafeString()을 적용할지 여부를 나타내는 부울 값입니다. 기본값은 false입니다.

예

{{content-loadmore  context numChars=32  moreText="go on"  ellipsesText="..." }}

/*
If context =
    "Here is the initial less content and this is more content."

Then content-loadmore would return
    "Here is the initial less content<span class="moreelipses">...</span> <span class="scf-morecontent"><span>and this is more content.</span>  <a href="" class="scf-morelink" evt="click=toggleContent">go on</a></span>"
*/

DateUtil

형식이 지정된 날짜 문자열을 반환하는 도우미입니다.

매개 변수

• 컨텍스트:숫자

  (선택 사항) 1970년 1월 1일(epoch)부터 밀리초 값 오프셋입니다. 기본값은 현재 날짜입니다.

• 형식:문자열

  (선택 사항) 적용할 날짜 형식입니다. 기본값은 "YYYY-MM-DDTHH:mm:ss.sssZ"이며 그 결과는 "2015-03-18T18:17:13-07:00"로 표시됩니다.

예

{{dateUtil this.memberSince format="dd MMM yyyy, hh:mm"}}

// returns "18 Mar 2015, 18:17"

{{dateUtil this.birthday format="MM-DD-YYYY"}}

// returns "03-18-2015"

과(와) 같음

동일도 조건에 따라 콘텐츠를 반환하는 도우미입니다.

매개 변수

• lvalue:문자열

  비교할 왼쪽 값입니다.

• rvalue:문자열

  비교할 오른쪽 값입니다.

예

{{#equals  value "some-value"}}
  <div>They are EQUAL!</div>
{{else}}
  <div>They are NOT equal!</div>
{{/equals}}

If-wcm-mode

문자열 구분 모드 목록을 기준으로 WCM 모드의 현재 값을 테스트하는 블록 도우미입니다.

매개 변수

• 컨텍스트:문자열

  (선택 사항) 변환할 문자열입니다. 기본값이 제공되지 않을 경우 필요합니다.

• 모드:문자열

  (선택 사항) 설정되면 테스트할 WCM 모드의 쉼표로 구분된 목록입니다.

예

{{#if-wcm-mode mode="DESIGN, EDIT"}}
 ...
{{else}}
 ...
{{/if-wcm-mode}}

i18n

이 도우미는 Handlebars 도우미 'i18n'을 무시합니다.

JavaScript 코드에서 문자열 국제화를 참조하십시오.

매개 변수

• 컨텍스트:문자열

  (선택 사항) 변환할 문자열입니다. 기본값이 제공되지 않을 경우 필요합니다.

• 기본값:문자열

  (선택 사항) 변환할 기본 문자열입니다. 제공된 컨텍스트가 없는 경우 필요합니다.

• 주석:문자열

  (선택 사항) 번역 힌트

예

{{i18n "hello"}}
{{i18n "hello" comment="greeting" default="bonjour"}}

포함

템플릿에 구성 요소를 존재하지 않는 리소스로 포함하는 도우미입니다.

따라서 JCR 노드로 추가된 리소스에 대해 가능한 것보다 프로그래밍 방식으로 보다 쉽게 리소스를 사용자 지정할 수 있습니다. 커뮤니티 구성 요소 추가 또는 포함을 참조하십시오.

일부 커뮤니티 구성 요소만 포함할 수 있습니다. AEM 6.1의 경우, 포함할 수 있는 사람은 댓글, 등급, 평가 및 투표입니다.

이 도우미는 서버측에만 적합하며 JSP 스크립트용 cq:include와 유사한 기능을 제공합니다.

매개 변수

• 컨텍스트:문자열 또는 개체

  (선택 사항으로, 상대 경로를 제공하지 않는 경우)

  현재 컨텍스트를 전달하려면 this을 사용합니다.

  this.id을(를) 사용하여 요청된 resourceType을 렌더링하기 위해 id에서 리소스를 가져옵니다.

• resourceType:문자열

  (선택 사항) 리소스 유형은 기본적으로 컨텍스트의 리소스 유형으로 설정됩니다.

• 템플릿:문자열

  구성 요소 스크립트 경로.

• 경로:문자열

  (필수) 리소스의 경로입니다. 경로가 상대적이면 컨텍스트를 제공해야 하며 그렇지 않으면 빈 문자열이 반환됩니다.

• authoringDisabled:부울

  (선택 사항) 기본값은 false입니다. 내부 용도로만 사용하십시오.

예

{{include this.id path="comments" resourceType="social/commons/components/hbs/comments"}}

여기에는 this.id + /comments에 새 주석 구성 요소가 포함됩니다.

IncludeClientLib

js, css 또는 테마 라이브러리가 될 수 있는 AEM html 클라이언트 라이브러리를 포함하는 도우미. js 및 css와 같이 다양한 유형의 여러 포함을 사용하려면 이 태그를 Handlebars 스크립트에서 여러 번 사용해야 합니다.

이 도우미는 서버측에만 적합하며 JSP 스크립트용 ui:includeClientLib와 유사한 기능을 제공합니다.

매개 변수

• 카테고리:문자열

  (선택 사항) 쉼표로 구분된 클라이언트 라이브러리 카테고리 목록입니다. 지정된 범주에 대한 모든 Javascript 및 CSS 라이브러리가 포함됩니다. 테마 이름이 요청에서 추출됩니다.

• 테마:문자열

  (선택 사항) 쉼표로 구분된 클라이언트 라이브러리 카테고리 목록입니다. 지정된 범주에 대한 모든 테마 관련 라이브러리(CSS 및 JS 모두)가 포함됩니다. 테마 이름이 요청에서 추출됩니다.

• js:문자열

  (선택 사항) 쉼표로 구분된 클라이언트 라이브러리 카테고리 목록입니다. 지정된 범주에 대한 모든 Javascript 라이브러리가 포함됩니다.

• css:문자열

  (선택 사항) 쉼표로 구분된 클라이언트 라이브러리 카테고리 목록입니다. 지정된 범주에 대한 모든 CSS 라이브러리가 포함됩니다.

예

// all: js + theme (theme-js + css)
{{includeClientLib categories="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css?lang=ko" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css?lang=ko" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=ko" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=ko" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js?lang=ko" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=ko" type="text/javascript"></script>

// only js libs
{{includeClientLib js="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=ko" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js?lang=ko" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=ko" type="text/javascript"></script>

// theme only (theme-js + css)
{{includeClientLib theme="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css?lang=ko" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=ko" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=ko" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=ko" type="text/javascript"></script>

// css only
{{includeClientLib css="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css?lang=ko" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css?lang=ko" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=ko" rel="stylesheet" type="text/css">

Pretty-time

일반 날짜 형식이 표시된 이후 마감 지점까지 경과된 시간을 표시하는 도우미입니다.

예:

• 12시간 전
• 7일 전

매개 변수

• 컨텍스트:숫자

  '지금'과 비교할 과거의 시간. 시간은 1970년 1월 1일(epoch)부터 밀리 값 오프셋으로 표현됩니다.

• daysCutar:숫자

  실제 날짜로 전환하기 전 일 수입니다. 기본값은 60입니다.

예

{{pretty-time this.published daysCutoff=7}}

/*
Depending on how long in the past, may return

  "3 minutes ago"

  "3 hours ago"

  "3 days ago"
*/

Xss-html

XSS를 방지하는 데 도움이 되도록 HTML 요소 내용의 소스 문자열을 인코딩하는 도우미.

참고:유효성 검사기가 아니며 특성 값을 쓰는 데 사용할 수 없습니다.

매개 변수

• 컨텍스트:개체

  인코딩할 HTML입니다.

예

<p>{{xss-html forum-ugc}}</p>

Xss-htmlAttr

XSS를 보호하는 데 도움이 되도록 HTML 속성 값에 쓸 소스 문자열을 인코딩하는 도우미.

참고:이것은 유효성 검사기가 아니며 실행 가능한 특성(href, src, 이벤트 핸들러)을 쓰는 데 사용할 수 없습니다.

매개 변수

• 컨텍스트:개체

  인코딩할 HTML입니다.

예

<div id={{xss-htmlAttr id}} />

Xss-jsString

XSS에 대한 경계를 지원하기 위해 JavaScript 문자열 컨텐츠에 쓸 소스 문자열을 인코딩하는 도우미.

참고:이것은 유효성 검사기가 아니며 임의의 JavaScript에 쓰는 데 사용되지 않습니다.

매개 변수

• 컨텍스트:개체

  인코딩할 HTML입니다.

예

var input = {{xss-jsString topic-title}}

Xss-validHref

XSS를 막기 위해 HTML href 또는 srce 속성 값으로 쓸 수 있도록 URL을 정리하는 도우미.

참고:빈 문자열을 반환할 수 있습니다.

매개 변수

• 컨텍스트:개체

  문서의 기밀 정보 가리기 URL입니다.

예

<a href="{{xss-validHref url}}">my link</a>

Handlebars.js 기본 개요

Handlebars.js 설명서의 도우미 기능에 대한 빠른 개요:

• Handlebars 도우미 호출은 0개 이상의 공간 구분 매개 변수가 있는 간단한 식별자(도우미의 name)입니다.

• 매개 변수는 간단한 문자열, 숫자, 부울 또는 JSON 개체일 뿐만 아니라 마지막 매개 변수로서 키-값 쌍(해시 인수)의 선택적 시퀀스일 수 있습니다.

• 해시 인수의 키는 단순 식별자여야 합니다.

• 해시 인수의 값은 Handlebars 표현식입니다.단순 식별자, 경로 또는 문자열.

• 현재 컨텍스트인 this은 항상 Handlebars 도우미에게 사용할 수 있습니다.

• 컨텍스트는 문자열, 숫자, 부울 또는 JSON 데이터 개체일 수 있습니다.

• 현재 컨텍스트 내에 중첩된 개체를 컨텍스트로 전달할 수 있습니다(예: this.url 또는 this.id)(단순 및 블록 도움말의 다음 예 참조).

• 블록 도우미는 템플릿의 모든 위치에서 호출할 수 있는 함수입니다. 매번 다른 컨텍스트에서 템플릿 블록을 0회 이상 호출할 수 있습니다. 여기에는 {{#name}}과(와) {{/name}} 사이의 컨텍스트가 포함됩니다.

• handlebars는 'options'라는 이름의 도우미에게 최종 매개 변수를 제공합니다. 특수 객체 'options'에 포함된

  • 선택적 개인 데이터(options.data)
  • 호출의 선택적 키 값 속성(options.hash)
  • 자체 호출 기능(options.fn())
  • 자체 반전(options.inverse())을 호출하는 기능

• 도우미에서 반환된 HTML 문자열 내용은 SafeString이 좋습니다.

Handlebars.js 문서에서 제공하는 간단한 도우미 예:

Handlebars.registerHelper('link_to', function(title, options) {
    return new Handlebars.SafeString('<a href="/posts'%20+%20this.url%20+%20'?lang=ko">' + title + "!</a>");
});

var context = {posts: [
    {url: "/hello-world",
      body: "Hello World!"}
  ] };

// when link_to is called, posts is the current context
var source = '<ul>{{#posts}}<li>{{{link_to "Post"}}}</li>{{/posts}}</ul>'

var template = Handlebars.compile(source);

template(context);

렌더링:

<ul>
<li><a href="/posts/hello-world">포스트!</a></li>
</ul>

Handlebars.js 설명서의 블록 도우미의 예:

Handlebars.registerHelper('link', function(options) {
    return new Handlebars.SafeString('<a href="/people/'%20+%20this.id%20+%20'?lang=ko">' + options.fn(this) + '</a>');
});

var data = { "people": [
  { "name": "Alan", "id": 1 },
  { "name": "Yehuda", "id": 2 }
]};

// when link is called, people is the current context
var source = "<ul>{{#people}}<li>{{#link}}{{name}}{{/link}}</li>{{/people}}</ul>";

var template = Handlebars.compile(source);

template(data);

렌더링:
<ul>
<li><a href="/people/1">Alan</a></li>
<li><a href="/people/2">Yhuda</a></li>
</ul>

사용자 지정 SCF 도움말

사용자 지정 도움말은 특히 데이터를 전달할 때 서버측 및 클라이언트측에서 구현되어야 합니다. SCF의 경우 페이지가 요청될 때 서버가 지정된 구성 요소에 대한 HTML을 생성하므로 대부분의 템플릿이 서버측에서 컴파일되고 렌더링됩니다.

서버측 사용자 지정 도움말 도우미

서버측에서 사용자 지정 SCF 도우미를 구현하고 등록하려면 Java 인터페이스 TemplateHelper을 구현하고 OSGi 서비스로 만들고 OSGi 번들의 일부로 설치합니다.

예:

FooTextHelper.java

/** Custom Handlebars Helper */

package com.my.helpers;

import java.io.IOException;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;

import com.adobe.cq.social.handlebars.api.TemplateHelper;
import com.github.jknack.handlebars.Options;

@Service
@Component
public class FooTextHelper implements TemplateHelper<String>{

    @Override
    public CharSequence apply(String context, Options options) throws IOException {
        return "foo-" + context;
    }

    @Override
    public String getHelperName() {
        return "foo-text";
    }

    @Override
    public Class<String> getContextType() {
        return String.class;
    }
}

클라이언트측 사용자 지정 도움말

클라이언트측 도움말은 Handlebars.registerHelper()을(를) 호출하여 등록된 Handlebars 스크립트입니다.
예:

custom-helpers.js

function(Handlebars, SCF, $CQ) {

    Handlebars.registerHelper('foo-text', function(context, options) {
        if (!context) {
            return "";
        }
        return "foo-" + context;
    });

})(Handlebars, SCF, $CQ);

사용자 지정 클라이언트측 도움말을 사용자 지정 클라이언트 라이브러리에 추가해야 합니다.
clientlib은 다음을 수행해야 합니다.

• cq.social.scf에 대한 종속성을 포함합니다.
• Handlebars가 로드된 후 로드합니다.
• included이어야 합니다.

참고:SCF 도우미는 /etc/clientlibs/social/commons/scf/helpers.js에 정의됩니다.