デジタルエクスペリエンスは、複雑な JavaScript や CSS コードを利用したクライアントサイドの処理に大きく依存しています。AEM クライアントサイドライブラリ(clientlibs)を使用すると、これらのクライアントサイドライブラリをリポジトリー内に整理し、一元的に保存できます。AEM プロジェクトアーキタイプでフロントエンドビルドプロセスと組み合わせると、AEM プロジェクトのフロントエンドコードの管理が簡単になります。
AEM で clientlibs を使用する利点は次のとおりです。
clientlibs は、AEM から CSS と JavaScript を配信するための組み込みソリューションです。
AEM プロジェクト用に CSS と JavaScript を作成するフロントエンドデベロッパーは、 AEM プロジェクトアーキタイプと、自動化されたフロントエンドビルドプロセスにも慣れている必要があります。
サイトを処理するには、JavaScript と CSS に加えて、アイコンや Web フォントなどの静的リソースがクライアントサイドで必要です。clientlib は、そのようなリソースを(必要に応じてカテゴリ別に)参照し、提供する AEM のメカニズムです。
AEM は、サイトの CSS と JavaScript を 1 つのファイルに 1 つの中央の場所に収集し、1 つのリソースのコピーのみが HTML 出力に含まれるようにします。これにより、配信の効率が最大化され、プロキシを介してリポジトリー内でリソースを一元的に管理でき、アクセスの安全性を確保できます。
すべての JavaScript、CSS、およびその他のフロントエンドアセットは、AEM プロジェクトアーキタイプの ui.frontend モジュールで管理する必要があります。 アーキタイプの柔軟性により、最新の Web ツールを使用して、これらのリソースを作成および管理できます。
次に、アーキタイプは、リソースを単一の CSS ファイルと JS ファイルにコンパイルし、自動的にリポジトリーの cq:clientLibraryFolder
に埋め込むことができます。
クライアントサイドライブラリフォルダーは、タイプが cq:ClientLibraryFolder
のリポジトリーノードです。CND 注釈での定義は次のとおりです。
[cq:ClientLibraryFolder] > sling:Folder
- dependencies (string) multiple
- categories (string) multiple
- embed (string) multiple
- channels (string) multiple
cq:ClientLibraryFolder
ノードは、リポジトリーの /apps
サブツリー内の任意の場所に配置できます。categories
プロパティを使用して、ノードが属するライブラリカテゴリを特定します。各 cq:ClientLibraryFolder
には、JS ファイルや CSS ファイルのセットと、いくつかのサポートファイルが入力されます(以下を参照)。cq:ClientLibraryFolder
の重要なプロパティは、次のように設定されます。
allowProxy
:すべての clientlibs は apps
に保存する必要があるため、このプロパティを使用すると、プロキシサーブレットを介してクライアントライブラリにアクセスできます。後述の「クライアントライブラリフォルダーの配置とプロキシクライアントライブラリサーブレットの使用」を参照してください。categories
:cq:ClientLibraryFolder
に含まれる JS ファイルや CSS ファイルのセットのカテゴリを特定します。categories
プロパティは複数の値を取るため、ライブラリフォルダーを複数のカテゴリーの一部にすることができます(これがどのように役立つかについては以下を参照)。クライアントライブラリフォルダーに 1 つ以上のソースファイルが含まれている場合は、そのソースファイルが実行時に単一の JS ファイルや CSS ファイルに結合されます。生成されるファイルの名前はノード名で、ファイル名の拡張子は .js
または .css
です。例えば、cq.jquery
という名前のライブラリノードからは、 cq.jquery.js
または cq.jquery.css
という名前のファイルが生成されます。
クライアントライブラリフォルダーには次の項目が含まれます。
js.txt
ファイルと 1 つの css.txt
ファイル(いずれかまたは両方)クライアントライブラリは、/apps
に配置する必要があります。これは、コードをコンテンツと設定からより詳細に分離するためです。
/apps
にあるクライアントライブラリにアクセスできるようにするために、プロキシサーブレットが使用されます。ACL は依然としてクライアントライブラリフォルダーで適用されますが、サーブレットを使用すると、/etc.clientlibs/
プロパティが allowProxy
に設定されている場合、true
を介してコンテンツを読み取ることができます。
https://<host>:<port>/crx/de
)。/apps
フォルダーを右クリックして、作成/ノードを作成をクリックします。cq:ClientLibraryFolder
を選択します。「OK」をクリックし、「すべて保存」をクリックします。cq:ClientLibraryFolder
ノードを選択し、次のプロパティを追加して、「すべて保存」をクリックします。
categories
/etc.clientlibs
のプロキシ経由でアクセスできるようにするには、 cq:ClientLibraryFolder
ノードを選択し、次のプロパティを追加して、「すべて保存」をクリックします。
allowProxy
true
resources
の下にサブフォルダーを作成します。
resources
フォルダーの下に静的リソースを格納した場合、静的リソースはパブリッシュインスタンスで参照できません。js.txt
: JavaScript ファイルを生成する場合はこのファイル名を使用します。css.txt
: カスケーディングスタイルシート(CSS)を生成する場合はこのファイル名を使用します。#base=*[root]*
[root]
を、ソースファイルが格納されているフォルダーの TXT ファイルに対する相対パスに置き換えます。例えば、ソースファイルが TXT ファイルと同じフォルダーにある場合は、次のテキストを使用します。
#base=.
cq:ClientLibraryFolder
ノードの下の mobile という名前のフォルダーをルートに設定します。
#base=mobile
#base=[root]
の下の行に、ソースファイルのルートに対する相対パスを入力します。各ファイル名を別々の行に配置します。クライアントライブラリフォルダーを必要に応じて設定したら、clientlibs をプロキシ経由でリクエストできます。次に例を示します。
/apps/myproject/clientlibs/foo
にあります。/apps/myprojects/clientlibs/foo/resources/icon.png
にあります。allowProxy
プロパティを使用して、次をリクエストできます。
/etc.clientlibs/myprojects/clientlibs/foo.js
を介す)/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png
を介す)clientlibs がクライアントライブラリフォルダーに正常に保存および管理されると、HTL を介してアクセスできます。
クライアントライブラリは AEM 提供のヘルパーテンプレートを介して読み込まれます。テンプレートには data-sly-use
を使用してアクセスできます。このファイルには 3 つのヘルパーテンプレートが含まれ、data-sly-call
で呼び出すことができます。
各ヘルパーテンプレートには、必要なクライアントライブラリを参照するための categories
オプションを指定できます。このオプションには、文字列値の配列またはコンマ区切り値のリストを含む文字列を指定できます。
HTL を使用した clientlibs の読み込みについて詳しくは、HTL のドキュメントを参照してください。
ほとんどの clientlibs は、AEM パブリッシュインスタンスで必要です。つまり、clientlibs の大半の目的は、コンテンツのエンドユーザーエクスペリエンスを生み出すことです。パブリッシュインスタンスの clientlibs の場合、フロントエンドビルドツールは、前述のように、クライアントライブラリフォルダーを介して使用およびデプロイできます。
ただし、オーサリングエクスペリエンスのカスタマイズにクライアントライブラリが必要な場合があります。例えば、ダイアログのカスタマイズには、AEM オーサリングインスタンスに小さな CSS または JS のデプロイが必要になる場合があります。
オーサーがクライアントライブラリを使用する必要がある場合は、パブリッシュと同じ方法で /apps
にクライアントライブラリを作成できますが、管理するプロジェクト全体を作成する代わりに、直接 /apps/.../clientlibs/foo
に書き込むことができます。
その後、作成したクライアントライブラリをすぐに使用できるクライアントライブラリカテゴリに追加することで、オーサリング JS に「接続」できます。
AEM には、クライアントライブラリフォルダーをデバッグおよびテストするためのツールが用意されています。
/libs/cq/granite/components/dumplibs/dumplibs
コンポーネントは、システム上のすべてのクライアントライブラリフォルダーに関する情報のページを生成します。/libs/granite/ui/content/dumplibs
ノードは、コンポーネントをリソースタイプとして持ちます。ページを開くには、次の URL を使用します(必要に応じてホストとポートを変更)。
https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html
情報には、ライブラリのパスおよびタイプ(CSS または JS)と、categories や dependencies などのライブラリ属性の値が含まれます。ページ上の後続のテーブルは、各カテゴリおよびチャネルに含まれるライブラリを示します。
dumplibs
コンポーネントには、ui:includeClientLib
タグ用に生成されたソースコードを表示するテストセレクターが含まれています。このページには、js、css およびテーマの属性の異なる組み合わせのためのコードが含まれています。
dumplibs.html
ページから、「こちらをクリックして出力テスト」テキストのリンクをクリックします。http://<host>:<port>/libs/granite/ui/content/dumplibs.html
categories
プロパティの値を入力して、「クエリを送信」をクリックします。AEM のクライアントライブラリフォルダーでは、他にも多数の機能がサポートされています。ただし、AEM as a Cloud Service ではこれらは必須ではないので、使用しないでください。完全性を考慮して、以下に示します。
クライアントライブラリフォルダーのこれらの追加機能は、AEM as a Cloud Service では必要ないので、使用しないでください。完全性を考慮して、以下に示します。
追加のクライアントライブラリ設定は、システムコンソール(https://<host>:<port>/system/console/configMgr
)の Adobe Granite HTML Library Manager パネルで制御できます。
フォルダーのプロパティには、依存関係や埋め込みの制御が許可されているものもありますが、通常は不要になっており、使用はお勧めしません。
dependencies
:これは、このライブラリカテゴリが依存する他のクライアントライブラリフォルダーのリストです。例えば、F
と G
の 2 つの cq:ClientLibraryFolder
ノードを指定し、F
のファイルが正しく機能するために別の G
のファイルを必要とする場合、G
の中の少なくとも 1 つの categories
は、F
の dependencies
でなければなりません。embed
:他のライブラリからコードを埋め込むために使用します。ノード F
がノード G
およびノード H
を埋め込むと、結果として得られる HTML は、ノード G
およびノード H
からのコンテンツの合成になります。クライアントライブラリフォルダーのコードが他のライブラリを参照する場合、他のライブラリを依存関係として識別します。クライアントライブラリフォルダーを参照する ui:includeClientLib
タグが原因で、HTML コードに生成したライブラリファイルへのリンクおよび依存関係が含まれます。
依存関係は別の cq:ClientLibraryFolder
でなければなりません。依存関係を識別するには、次の属性を持つプロパティを cq:ClientLibraryFolder
ノードに追加します。
例えば、/etc/clientlibs/myclientlibs/publicmain
は cq.jquery
ライブラリに依存しています。メインのクライアントライブラリを参照するページは、次のコードを含む HTML を生成します。
<script src="/etc/clientlibs/foundation/cq.jquery.js" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js" type="text/javascript">
あるクライアントライブラリから別のクライアントライブラリに、コードを埋め込むことができます。実行時に、埋め込み元のライブラリで生成される JS ファイルおよび CSS ファイルには、埋め込み先のライブラリのコードが含まれます。
コードの埋め込みは、リポジトリのセキュリティ保護された領域に格納されているライブラリへのアクセスを提供する際に便利です。
アプリケーション関連のすべてのファイルは、/app
内のアプリケーションフォルダーに格納することをお勧めします。Web サイト訪問者の /app
フォルダーに対するアクセスを拒否することもお勧めします。両方のベストプラクティスを満たすには、/etc
にクライアントライブラリフォルダーを作成して、 /app
内のクライアントライブラリを埋め込みます。
埋め込むクライアントライブラリフォルダーを識別するには、categories プロパティを使用します。ライブラリを埋め込むには、次のプロパティ属性を使用して、埋め込み cq:ClientLibraryFolder
ノードにプロパティを追加します。
cq:ClientLibraryFolder
ノードの categories プロパティの値。場合によっては、パブリッシュインスタンスによって一般的なページ用に生成される最終的な HTML に、比較的多くの <script>
要素が含まれていることがあります。
このような場合、必要なすべてのクライアントライブラリコードを 1 つのファイルに組み合わせて、ページ読み込み時のリクエストの行き来の数を減らすと便利です。これをおこなうには、cq:ClientLibraryFolder
ノードの embed プロパティを使用して、必要なライブラリをアプリ固有のクライアントライブラリに embed
します。
CSS ファイルを埋め込むと、生成される CSS コードは、埋め込みライブラリに対するリソースへの相対パスを使用します。例えば、公開アクセス可能な /etc/client/libraries/myclientlibs/publicmain
ライブラリによって /apps/myapp/clientlib
クライアントライブラリが埋め込まれるとします。
main.css
ファイルには次のスタイルが含まれます。
body {
padding: 0;
margin: 0;
background: url(images/bg-full.jpg) no-repeat center top;
width: 100%;
}
publicmain
ノードが生成する CSS ファイルには、元の画像の URL を使用した、次のスタイルが含まれます。
body {
padding: 0;
margin: 0;
background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
width: 100%;
}
埋め込みコードの元をトレースする、または埋め込みクライアントライブラリが期待どおりの結果を得られるようにするには、実行時に埋め込まれているファイルの名前を確認できます。ファイル名を確認するには、Web ページの URL に debugClientLibs=true
パラメーターを追加します。生成されるライブラリには、埋め込みコードの代わりに @import
ステートメントが含まれています。
前の「他のライブラリからのコードの埋め込み」節の例では、クライアントライブラリフォルダーに/etc/client/libraries/myclientlibs/publicmain
クライアントライブラリフォルダーが埋め込まれています/apps/myapp/clientlib
。Web ページにパラメーターを追加すると、Web ページのソースコードに次のリンクが作成されます。
<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css">
publicmain.css
ファイルを開くと、次のコードが表示されます。
@import url("/apps/myapp/clientlib/styles/main.css");
?debugClientLibs=true
AEM では、プラグ可能なプリプロセッサーを使用でき、AEM のデフォルトプリプロセッサーとして、CSS および JavaScript 用の YUI Compressor と YUI が定された JavaScript 用の Google Closure Compiler(GCC)をサポートします。
プラグ可能なプリプロセッサーは、次のように柔軟な使用が可能です。
デフォルトでは、AEM は YUI Compressor を使用します。既知の問題のリストについては、YUI Compressor GitHub ドキュメントを参照してください。特定の clientlibs 用の GCC コンプレッサーに切り替えると、YUI を使用しているときに発生していたいくつかの問題が解決することがあります。
縮小化したライブラリをクライアントライブラリに配置しないでください。代わりに、生のライブラリを提供し、縮小が必要な場合は、プリプロセッサーのオプションを使用します。
クライアントライブラリごとに、またはシステム全体でプリプロセッサーを設定できます。
cssProcessor
および jsProcessor
を追加します。clientlib ノードのプリプロセッサー設定は、OSGI 設定よりも優先されます。
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
jsProcessor: [
"default:typescript",
"min:typescript",
"min:gcc;obfuscate=true"
]
failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")
GCC オプションについて詳しくは、GCC ドキュメントを参照してください。
YUI は、AEM のデフォルト縮小ツールとして設定されています。これを GCC に変更するには、次の手順に従います。
http://<host>:<portY/system/console/configMgr
)に移動します。min:gcc
に設定します。
min:gcc;obfuscate=true
)。