Handlebars ヘルパーは、SCF コンポーネントの操作を円滑化する目的で Handlebars から呼び出すことができるメソッドです。
実装では、クライアント側定義とサーバー側定義を扱います。開発者がカスタムヘルパーを作成することもできます。
AEM Communities に付属のカスタム SCF ヘルパーは、次のクライアントライブラリに定義されています。
- /etc/clientlibs/social/commons/scf/helpers.js
注意：
最新の Communities 機能パックをインストールしてください。
maxWords および maxLength プロパティに準拠した省略形文字列を返すヘルパーです。
省略対象の文字列は context で指定します。context を指定しなかった場合、空の文字列が返されます。
context は最初に maxLength にトリミングされ、その後、いくつかの単語に分割されてから maxWords まで縮小されます。
safeString を true に設定した場合は、SafeString が文字列として返されます。
- context：文字列
（オプション）デフォルト値は空の文字列です。 - maxLength：数値
（オプション）デフォルト値は context の長さです。 - 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"
*/
- context：文字列
（オプション）デフォルト値は空の文字列です。 - 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>"
*/
- context：数値
（オプション）1970 年 1 月 1 日（epoch）からのミリ秒単位のオフセットです。デフォルト値は現在の日付です。 - format：文字列
（オプション）適用する日付書式です。デフォルト値は「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"
{{#equals value "some-value"}}
<div>They are EQUAL!</div>
{{else}}
<div>They are NOT equal!</div>
{{/equals}}
WCM モードの現在の値をモードの文字列区切りリストと比較してテストするブロックヘルパーです。
- context：文字列
（オプション）翻訳対象文字列です。default を指定しない場合は必須です。 - mode：文字列
（オプション）テスト対象の WCM モードをコンマ区切りリストとして設定します。
{{#if-wcm-mode mode="DESIGN, EDIT"}}
...
{{else}}
...
{{/if-wcm-mode}}
このヘルパーは、Handlebars ヘルパー「i18n」をオーバーライドします。
JavaScript コードの文字列の国際化も参照してください。
- context：文字列
（オプション）翻訳対象文字列です。default を指定しない場合は必須です。 - default：文字列
（オプション）デフォルトの翻訳対象文字列です。context を指定しない場合は必須です。 - comment：文字列
（オプション）翻訳に関するヒントです。
{{i18n "hello"}}
{{i18n "hello" comment="greeting" default="bonjour"}}
コンポーネントを存在しないリソースとしてテンプレートにインクルードするヘルパーです。
このようにすると、JCR ノードとして追加したリソースよりも、プログラムによるカスタマイズがはるかに容易になります。コミュニティコンポーネントの追加またはインクルードを参照してください。
コミュニティコンポーネントの中でも、インクルードできるのはごく一部です。AEM 6.1 の場合、インクルードできるコンポーネントは、コメント、評価、レビュー、および投票です。
このヘルパーは、サーバー側にのみ該当し、JSP スクリプト用の cq:include と同じ機能を備えています。
- context：文字列またはオブジェクト
（相対パスを指定する場合以外はオプション）
現在のコンテキストを渡すには、this を使用します。
id のリソースを取得して、要求した resourceType をレンダリングするには、this.id を使用します。 - resourceType：文字列
（オプション）デフォルトでは、context の対象リソースタイプが使用されます。 - template：文字列
コンポーネントスクリプトのパスです。 - path：文字列
（必須）リソースのパスです。パスが相対パスの場合、context を指定する必要があります。そうしないと、空の文字列が返されます。 - authoringDisabled：ブール値
（オプション）デフォルト値は false です。内部でのみ使用されます。
{{include this.id path="comments" resourceType="social/commons/components/hbs/comments"}}
AEM html クライアントライブラリとして js、css、または theme の各ライブラリをインクルードするヘルパーです。js と css など、異なるタイプを複数インクルードする場合、このタグを Handlebars スクリプトで複数回使用する必要があります。
このヘルパーは、サーバー側にのみ該当し、JSP スクリプト用の ui:includeClientLib と同じ機能を備えています。
- categories：文字列
（オプション）クライアントライブラリカテゴリのコンマ区切りリストです。指定したカテゴリの JavaScript ライブラリと CSS ライブラリがすべてインクルードされます。テーマ名は要求から抽出されます。 - theme：文字列
（オプション）クライアントライブラリカテゴリのコンマ区切りリストです。指定したカテゴリのテーマに関連するライブラリ（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" rel="stylesheet" type="text/css">
<link href="/etc/clientlibs/social/hbs/socialgraph.css" rel="stylesheet" type="text/css">
<link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
<script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
<script src="/etc/clientlibs/social/hbs/socialgraph.js" type="text/javascript"></script>
<script src="/etc/clientlibs/social/hbs/comments.js" 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" type="text/javascript"></script>
<script src="/etc/clientlibs/social/hbs/socialgraph.js" type="text/javascript"></script>
<script src="/etc/clientlibs/social/hbs/comments.js" 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" rel="stylesheet" type="text/css">
<link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
<script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
<script src="/etc/clientlibs/social/hbs/comments.js" 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" rel="stylesheet" type="text/css">
<link href="/etc/clientlibs/social/hbs/socialgraph.css" rel="stylesheet" type="text/css">
<link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
- context：数値
現在と比較する過去の時間です。時間は 1970 年 1 月 1 日（epoch）からのミリ秒単位のオフセットとして表されます。 - daysCutoff：数値
実際の日付に切り替えるまでの日数です。デフォルト値は 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"
*/
<p>{{xss-html forum-ugc}}</p>
XSS に対する保護として、HTML 属性値に記述するソース文字列をエンコードするヘルパーです。
注意：これはバリデーターではなく、実用的な属性（href、src、イベントハンドラー）の記述には使用されません。
<div id={{xss-htmlAttr id}} />
XSS に対する保護として、JavaScript 文字列コンテンツに記述するソース文字列をエンコードするヘルパーです。
注意：これはバリデーターではなく、任意の JavaScript への記述には使用されません。
var input = {{xss-jsString topic-title}}
<a href="{{xss-validHref url}}">my link</a>
Handlebars.js ドキュメントで取り上げられているヘルパー関数の概要は次のとおりです。
- Handlebars ヘルパーを呼び出すには、単純な識別子（ヘルパーの名前）を使用し、それに続けて 0 個以上のパラメーターをスペースで区切って指定します。
- パラメーターには、単純な文字列、数値、ブール値、または JSON オブジェクトを指定し、オプションで最後のパラメーターとして一連のキー／値ペア（ハッシュ引数）を指定します。
- ハッシュ引数内のキーは単純な識別子にする必要があります。
- ハッシュ引数内の値は Handlebars 式（単純な識別子、パス、または文字列）です。
- 現在のコンテキストを表す this は常に Handlebars ヘルパーで使用できます。
- context には、文字列、数値、ブール値、または JSON データオブジェクトを指定します。
- this.url や this.id のように、現在のコンテキスト内にネストされているオブジェクトを context として渡すことができます（単純なヘルパーおよびブロックヘルパーを示す後述の例を参照）。
- ブロックヘルパーとは、テンプレート内の任意の場所から呼び出すことができる関数です。これらを使用すると、テンプレートのブロックを毎回異なるコンテキストで 0 回以上呼び出すことができます。{{#name}} から {{/name}} までのコンテキストが対象となります。
- Handlebars では、ヘルパーに対する最後のパラメーターとして「options」を使用します。特別なオブジェクト「options」の内容は次のとおりです。
- オプションの非公開データ（options.data）
- 呼び出しにおけるオプションのキー／値プロパティ（options.hash）
- それ自体を呼び出すための機能（options.fn()）
- それ自体の反対を呼び出すための機能（options.inverse()）
- ヘルパーから返される HTML 文字列コンテンツは SafeString になるようにすることをお勧めします。
Handlebars.registerHelper('link_to', function(title, options) {
return new Handlebars.SafeString('<a href="/posts' + this.url + '">' + 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);
Handlebars.registerHelper('link', function(options) {
return new Handlebars.SafeString('<a href="/people/' + this.id + '">' + 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);
カスタムヘルパーは、特にデータを渡す場合に、クライアント側だけでなくサーバー側で実装する必要があります。SCF では、ページ要求に応じてサーバーにより特定のコンポーネントに対して HTML が生成されるので、ほとんどのテンプレートはサーバー側でコンパイルおよびレンダリングされます。
カスタム SCF ヘルパーをサーバー側に実装して登録するには、Java インターフェイス TemplateHelper を実装し、それを OSGi サービスとして使用し、OSGi バンドルの一部としてインストールします。
次に例を示します。
/** 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;
}
}
注意：
サーバー側用に作成したヘルパーは、クライアント側用にも作成する必要があります。
このコンポーネントは、ログインしているユーザーのクライアント側で再レンダリングされます。クライアント側ヘルパーが見つからない場合、このコンポーネントは表示されません。
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 のロード後にロードされる。
- インクルードされる。
注意：SCF ヘルパーは /etc/clientlibs/social/commons/scf/helpers.js に定義されています。
Twitter™ および Facebook の投稿には、Creative Commons の規約内容は適用されません。