⇐ 機能の基本事項 | サーバー側のカスタマイズ ⇒ |
---|---|
クライアント側のカスタマイズ ⇒ |
Handlebars ヘルパーは、SCF コンポーネントの操作を円滑化する目的で Handlebars から呼び出すことができるメソッドです。
実装では、クライアント側定義とサーバー側定義を扱います。開発者は、カスタムヘルパーを作成することもできます。
AEM Communities に付属のカスタム SCF ヘルパーは、次のクライアントライブラリに定義されています。
/etc/clientlibs/social/commons/scf/helpers.js
最新の Communities 機能パックをインストールしてください。
maxWords および maxLength プロパティに準拠した省略形文字列を返すヘルパーです。
省略対象の文字列は context で指定します。コンテキストが指定されない場合、空の文字列が返されます。
context は最初に maxLength にトリミングされ、その後、いくつかの単語に分割されてから maxWords まで縮小されます。
safeString を true に設定した場合は、SafeString が文字列として返されます。
context:文字列
(オプション)デフォルトは空の文字列です
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 の下に 2 つの span を追加するヘルパーです。一方はフルテキスト表示用、もう一方は縮小テキスト表示用で、これらの 2 つのビューを切り替えることができます。
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日(エポック)からのミリ秒オフセットの値。 初期設定は現在の日付です。
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"
等価条件に応じてコンテンツを返すヘルパーです。
lvalue:文字列
比較する左側の値。
rvalue:文字列
比較する右側の値。
{{#equals value "some-value"}}
<div>They are EQUAL!</div>
{{else}}
<div>They are NOT equal!</div>
{{/equals}}
WCM modeの現在値を、モードのリストを区切った文字列と比較してテストするブロックヘルパー。
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
を使用して、現在のコンテキストを渡します。
this.id
を使用して、id
のリソースを取得し、要求されたresourceTypeをレンダリングします。
resourceType:文字列
(オプション)リソースタイプは、デフォルトでコンテキストからリソースタイプに設定されます。
template:文字列
コンポーネントスクリプトへのパス
path:文字列
(必須)リソースへのパスです。 パスが相対パスの場合、context を指定する必要があります。そうしないと、空の文字列が返されます。
authoringDisabled:ブール値
(オプション)デフォルトはfalseです。 内部でのみ使用されます。
{{include this.id path="comments" resourceType="social/commons/components/hbs/comments"}}
これにより、this.id
+ /commentsに新しいコメントコンポーネントが追加されます。
AEM html クライアントライブラリとして js、css、または theme の各ライブラリをインクルードするヘルパーです。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" 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)からのミリ秒単位のオフセットとして表されます。
daysCutofof:数値
実際の日付に切り替わる前の日数。 初期設定は 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 要素コンテンツのソース文字列をエンコードするヘルパーです。
注意:これはバリデーターではなく、属性値の記述には使用されません。
context:object
エンコードするHTMLです。
<p>{{xss-html forum-ugc}}</p>
XSS に対する保護として、HTML 属性値に記述するソース文字列をエンコードするヘルパーです。
注意:これはバリデーターではなく、実用的な属性(href、src、イベントハンドラー)の記述には使用されません。
context:オブジェクト
エンコードするHTMLです。
<div id={{xss-htmlAttr id}} />
XSS に対する保護として、JavaScript 文字列コンテンツに記述するソース文字列をエンコードするヘルパーです。
注意:これはバリデーターではなく、任意の JavaScript への記述には使用されません。
context:オブジェクト
エンコードするHTMLです。
var input = {{xss-jsString topic-title}}
XSS に対する保護として、HTML の href または src 属性値として記述する URL の不要部分を削除するヘルパーです。
注意:空の文字列が返される場合があります。
context:オブジェクト
不要部分を削除するURL。
<a href="{{xss-validHref url}}">my link</a>
Handlebars.jsドキュメントのヘルパー関数の概要を簡単に説明します。
Handlebars ヘルパーを呼び出すには、単純な識別子(ヘルパーの名前**)を使用し、それに続けて 0 個以上のパラメーターをスペースで区切って指定します。
パラメーターには、単純な文字列、数値、ブール値、または JSON オブジェクトを指定し、オプションで最後のパラメーターとして一連のキー/値ペア(ハッシュ引数)を指定します。
ハッシュ引数内のキーは単純な識別子にする必要があります。
ハッシュ引数内の値は Handlebars 式(単純な識別子、パス、または文字列)です。
現在のコンテキストthis
は、常にHandlebarsヘルパーで使用できます。
コンテキストは、文字列、数値、ブール値、またはJSONデータオブジェクトです。
this.url
や this.id
のように、現在のコンテキスト内にネストされているオブジェクトを context として渡すことができます(単純なヘルパーおよびブロックヘルパーを示す後述の例を参照)。
ブロックヘルパーとは、テンプレート内の任意の場所から呼び出すことができる関数です。テンプレートのブロックは、毎回異なるコンテキストで0回以上呼び出すことができます。 {{#name}}と{{/name}}の間のコンテキストが含まれます。
Handlebars では、ヘルパーに対する最後のパラメーターとして「options」を使用します。特別なオブジェクト「options」には、
ヘルパーから返される 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);
レンダリング対象:
<ul>
<li><a href="/posts/hello-world">投稿!</a></li>
</ul>
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);
レンダリング対象:
<ul>
<li><a href="/people/1">アラン</a></li>
<li><a href="/people/2">Yeuda</a></li>
</ul>
カスタムヘルパーは、特にデータを渡す場合に、クライアント側だけでなくサーバー側で実装する必要があります。SCFの場合、ほとんどのテンプレートは、ページが要求されたときに特定のコンポーネントのHTMLがサーバーで生成されるので、サーバー側でコンパイルおよびレンダリングされます。
カスタムSCFヘルパーをサーバー側に実装して登録するには、JavaインターフェイスTemplateHelperを実装し、OSGi Serviceにして、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;
}
}
サーバー側用に作成したヘルパーは、クライアント側用にも作成する必要があります。
このコンポーネントは、ログインしているユーザーのクライアント側で再レンダリングされます。クライアント側ヘルパーが見つからない場合、このコンポーネントは表示されません。
クライアント側ヘルパーは、Handlebars.registerHelper()
() を呼び出すことによって登録する Handlebars スクリプトです。次に例を示します。
function(Handlebars, SCF, $CQ) {
Handlebars.registerHelper('foo-text', function(context, options) {
if (!context) {
return "";
}
return "foo-" + context;
});
})(Handlebars, SCF, $CQ);
カスタムのクライアントサイドヘルパーは、カスタムのクライアントライブラリに追加する必要があります。
clientlib の条件は次のとおりです。
cq.social.scf
に依存関係を含めます。注意:SCFヘルパーは/etc/clientlibs/social/commons/scf/helpers.js
で定義されています。
⇐ 機能の基本事項 | サーバー側のカスタマイズ ⇒ |
---|---|
クライアント側のカスタマイズ ⇒ |