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 に定義されています。