AEM as a Cloud Service でのクライアントサイドライブラリの使用 using-client-side-libraries

デジタルエクスペリエンスは、複雑な JavaScript や CSS コードを利用したクライアントサイドの処理に大きく依存しています。AEM クライアントサイドライブラリ（clientlibs）を使用すると、これらのクライアントサイドライブラリをリポジトリー内に整理し、一元的に保存できます。AEM プロジェクトアーキタイプでフロントエンドビルドプロセスと組み合わせると、AEM プロジェクトのフロントエンドコードの管理が簡単になります。

AEM で clientlibs を使用する利点は次のとおりです。

Clientlibs は、AEM から CSS と JavaScript を配信するための組み込みソリューションです。

クライアントサイドライブラリとは what-are-clientlibs

Sites では、JavaScript と CSS、およびクライアントサイドで処理されるアイコンや web フォントなどの静的リソースが必要です。clientlib は、そのようなリソースを（必要に応じてカテゴリ別に）参照し、提供する AEM のメカニズムです。

AEM は、サイトの CSS と JavaScript を 1 つのファイルにまとめて一元的な場所に配置し、HTML 出力にはリソースのコピーが 1 つだけ含まれるようにします。これにより、配信の効率が最大化され、プロキシを介してリポジトリ内でリソースを一元的に管理し、アクセスの安全性を確保できます。

AEM as a Cloud Service 向けフロントエンド開発 fed-for-aemaacs

すべての JavaScript、CSS およびその他のフロントエンドアセットは、AEM プロジェクトアーキタイプの ui.frontend モジュールで管理する必要があります。アーキタイプの柔軟性により、最新の web ツールを使用して、これらのリソースを作成および管理できます。

次に、アーキタイプは、リソースを単一の CSS ファイルと JS ファイルにコンパイルし、自動的にリポジトリーの cq:clientLibraryFolder に埋め込むことができます。

クライアントサイドライブラリフォルダー構造 clientlib-folders

クライアントサイドライブラリフォルダーは、cq:ClientLibraryFolder タイプのリポジトリノードです。その CND 表記での定義は次のとおりです。

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple

各 cq:ClientLibraryFolder には、JS ファイルや CSS ファイルのセットと、いくつかのサポートファイルが入力されます（以下を参照）。cq:ClientLibraryFolder の重要なプロパティは、次のように設定されます。

クライアントライブラリフォルダーに 1 つ以上のソースファイルが含まれている場合は、そのソースファイルが実行時に単一の JS ファイルや CSS ファイルに結合されます。生成されるファイルの名前はノード名で、ファイル名の拡張子は .js または .css です。例えば、cq.jquery という名前のライブラリノードからは、 cq.jquery.js または cq.jquery.css という名前のファイルが生成されます。

クライアントライブラリフォルダーには次の項目が含まれます。

クライアントサイドライブラリフォルダーの作成 creating-clientlib-folders

クライアントライブラリは、/apps に配置する必要があります。このルールは、コードをコンテンツや設定からより適切に分離するために必要です。

/apps にあるクライアントライブラリにアクセスできるようにするために、プロキシサーブレットが使用されます。ACL は依然としてクライアントライブラリフォルダーで適用されますが、サーブレットを使用すると、/etc.clientlibs/ プロパティが allowProxy に設定されている場合、true を介してコンテンツを読み取ることができます。

クライアントサイドライブラリの提供 serving-clientlibs

クライアントライブラリフォルダーを必要に応じて設定したら、clientlibs をプロキシ経由でリクエストできます。次に例を示します。

allowProxy プロパティを使用して、次をリクエストできます。

クライアントライブラリの読み込み（HTL 経由） loading-via-htl

clientlibs がクライアントライブラリフォルダーに正常に保存および管理されると、HTL を介してアクセスできます。

クライアントライブラリは AEM 提供のヘルパーテンプレートを介して読み込まれます。テンプレートには data-sly-use を使用してアクセスできます。このファイルには 3 つのヘルパーテンプレートが含まれ、data-sly-call で呼び出すことができます。

各ヘルパーテンプレートには、必要なクライアントライブラリを参照するための categories オプションを指定できます。このオプションには、文字列値の配列またはコンマ区切り値のリストを含む文字列を指定できます。

HTL を使用した clientlibs の読み込みについて詳しくは、HTL のドキュメントを参照してください。

オーサーのクライアントライブラリ対パブリッシュのクライアントライブラリ clientlibs-author-publish

ほとんどの clientlibs は、AEM パブリッシュインスタンスで必要です。つまり、clientlibs の大半の目的は、コンテンツのエンドユーザーエクスペリエンスを生み出すことです。パブリッシュインスタンスの clientlibs の場合、フロントエンドビルドツールは、前述のように、クライアントライブラリフォルダーを介して使用およびデプロイできます。

ただし、オーサリングエクスペリエンスのカスタマイズにクライアントライブラリが必要な場合があります。例えば、ダイアログのカスタマイズには、AEM オーサリングインスタンスに小さな CSS または JS のデプロイが必要になる場合があります。

オーサークライアントライブラリの管理 clientlibs-on-author

オーサーがクライアントライブラリを使用する必要がある場合は、パブリッシュと同じ方法で /apps にクライアントライブラリを作成できますが、管理するプロジェクト全体を作成する代わりに、直接 /apps/.../clientlibs/foo に書き込むことができます。

その後、作成したクライアントライブラリをすぐに使用できるクライアントライブラリカテゴリに追加することで、オーサリング JS に「接続」できます。

デバッグツール debugging-tools

AEM には、クライアントライブラリフォルダーをデバッグおよびテストするためのツールが用意されています。

クライアントライブラリの確認 discover-client-libraries

/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 などのライブラリ属性の値が含まれます。ページ上の後続のテーブルは、各カテゴリおよびチャネルに含まれるライブラリを示します。

生成される出力の確認 see-generated-output

dumplibs コンポーネントには、ui:includeClientLib タグ用に生成されたソースコードを表示するテストセレクターが含まれています。このページには、js、css およびテーマの属性の異なる組み合わせのためのコードが含まれています。

その他のクライアントライブラリフォルダー機能 additional-features

AEM のクライアントライブラリフォルダーでは、他にもいくつかの機能がサポートされています。ただし、AEM as a Cloud Service ではこれらは必須ではないので、使用しないでください。完全を期すために、以下に示します。

Adobe Granite HTML Library Manager html-library-manager

追加のクライアントライブラリ設定は、システムコンソール（https://<host>:<port>/system/console/configMgr）の Adobe Granite HTML Library Manager パネルで制御できます。

追加のフォルダープロパティ additional-folder-properties

フォルダーのプロパティには、依存関係や埋め込みの制御が許可されているものもありますが、通常は不要になっており、使用はお勧めしません。

依存関係へのリンク linking-to-dependencies

クライアントライブラリフォルダーのコードが他のライブラリを参照する場合、他のライブラリを依存関係として識別します。クライアントライブラリフォルダーを参照する 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">

他のライブラリからのコードの埋め込み embedding-code-from-other-libraries

あるクライアントライブラリから別のクライアントライブラリに、コードを埋め込むことができます。実行時に、埋め込み元のライブラリで生成される JS ファイルおよび CSS ファイルには、埋め込み先のライブラリのコードが含まれます。

コードの埋め込みは、リポジトリーのセキュリティ保護された領域に格納されているライブラリへのアクセスを提供する際に便利です。

アプリ固有のクライアントライブラリフォルダー app-specific-client-library-folders

アプリケーション関連のすべてのファイルは、/apps 内のアプリケーションフォルダーに格納することをお勧めします。Web サイト訪問者の /apps フォルダーに対するアクセスを拒否することもお勧めします。両方のベストプラクティスを満たすには、/etc にクライアントライブラリフォルダーを作成して、 /apps 内のクライアントライブラリを埋め込みます。

埋め込むクライアントライブラリフォルダーを識別するには、categories プロパティを使用します。ライブラリを埋め込むには、次のプロパティ属性を使用して、埋め込み cq:ClientLibraryFolder ノードにプロパティを追加します。

埋め込みを使用したリクエストの最小化 using-embedding-to-minimize-requests

場合によっては、パブリッシュインスタンスによって一般的なページ用に生成される最終的な HTML に、比較的多くの <script> 要素が含まれていることがあります。

このような場合、必要なすべてのクライアントライブラリコードを 1 つのファイルに組み合わせて、ページ読み込み時のリクエストの行き来の数を減らすと便利です。これを行うには、cq:ClientLibraryFolder ノードの embed プロパティを使用して、必要なライブラリをアプリ固有のクライアントライブラリに embed します。

CSS ファイル内のパス paths-in-css-files

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%;
}

HTML 出力の埋め込みファイルの確認 see-embedded-files

埋め込みコードの元をトレースする、または埋め込みクライアントライブラリが期待どおりの結果を得られるようにするには、実行時に埋め込まれているファイルの名前を確認できます。ファイル名を確認するには、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");

プリプロセッサーの使用 using-preprocessors

AEM では、プラグ可能なプリプロセッサーを使用でき、AEM のデフォルトプリプロセッサーとして、CSS および JavaScript 用の YUI Compressor と YUI が定された JavaScript 用の Google Closure Compiler（GCC）をサポートします。

プラグ可能なプリプロセッサーを使用すると、次のような柔軟な使い方ができるようになります。

使用方法 usage

クライアントライブラリごとに、またはシステム全体でプリプロセッサーを設定できます。

clientlib ノードのプリプロセッサー設定は、OSGI 設定よりも優先されます。

形式と例 format-and-examples

形式 format

config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;

CSS 縮小用の YUI Compressor と JS 用の GCC yui-compressor-for-css-minification-and-gcc-for-js

cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]

事前処理のための Typescript と縮小および不明化のための GCC typescript-to-preprocess-and-then-gcc-to-minify-and-obfuscate

jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]

追加の GCC オプション additional-gcc-options

failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

GCC オプションについて詳しくは、GCC ドキュメントを参照してください。

システムのデフォルト縮小ツールの設定 set-system-default-minifier

YUI は、AEM のデフォルトの縮小ツールとして設定されています。これを GCC に変更するには、次の手順に従います。