クライアントサイドライブラリの使用

最近の Web サイトは、複雑な JavaScript や CSS コードを利用したクライアント側の処理に大きく依存しています。このコードの提供を編成および最適化することが厄介な問題となることがあります。

この問題への対処に役立つように、AEM では、クライアント側ライブラリフォルダーが提供されています。これにより、クライアント側コードをリポジトリに格納し、カテゴリ別に整理して、それぞれのコードカテゴリをクライアントに保存するタイミングと方法を定義することができます。その後、クライアント側ライブラリシステムにより、最終的な Web ページで、正しいコードを読み込むための正しいリンクが作成されます。

AEM でのクライアント側ライブラリの機能

クライアント側ライブラリ（JSまたはCSSファイル）をページのHTMLに含める標準的な方法は、そのページのJSPに<script>タグまたは<link>タグを含め、該当するファイルへのパスを含めることです。例：

...
<head>
   ...
   <script type="text/javascript" src="/etc/clientlibs/granite/jquery/source/1.8.1/jquery-1.8.1.js"></script>
   ...
</head>
...

この方法は AEM で機能しますが、ページやそれに含まれるコンポーネントが複雑になると、問題につながる可能性があります。そのような場合、同じ JS ライブラリの複数のコピーが最終的な HTML 出力に含まれる危険性があります。これを回避してクライアント側ライブラリを論理的に整理するために、AEM ではクライアント側ライブラリフォルダーを使用します。

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

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

デフォルトでは、cq:ClientLibraryFolderノードは、リポジトリの/apps、/libsおよび/etcサブツリー内の任意の場所に配置できます(これらのデフォルトと、System ConsoleのAdobeGranite HTML Library Managerパネルでその他の設定を制御できます)。

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

categories：cq:ClientLibraryFolder に含まれる JS ファイルや CSS ファイルのセットのカテゴリを特定します。categories プロパティは複数の値を取るため、ライブラリフォルダーを複数のカテゴリーの一部にすることができます（これがどのように役立つかについては以下を参照）。
dependencies：これは、このライブラリカテゴリが依存する他のクライアントライブラリフォルダーのリストです。例えば、F と G の 2 つの cq:ClientLibraryFolder ノードを指定し、F のファイルが正しく機能するために別の G のファイルを必要とする場合、G の中の少なくとも 1 つの categories は、F の dependencies でなければなりません。
embed：他のライブラリからコードを埋め込むために使用します。ノードFがノードG,Hを埋め込むと、結果のHTMLはノードG,Hからのコンテンツの集合となる。
allowProxy:クライアントライブラリがの下にある場合、このプ /appsロパティを使用すると、プロキシサーブレットを介してそのライブラリにアクセスできます。後述の「クライアントライブラリフォルダーの配置とプロキシクライアントライブラリサーブレットの使用」を参照してください。

クライアント側ライブラリの参照

HTL は、AEM のサイト開発での推奨テクノロジーなので、HTL を使用して AEM にクライアント側ライブラリを含める必要があります。ただし、JSP を使用しておこなうこともできます。

HTL の使用

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

css — 参照されるクライアントライブラリのCSSファイルのみを読み込みます。
js — 参照されるクライアントライブラリのJavaScriptファイルのみを読み込みます。
all — 参照されるクライアントライブラリのすべてのファイル（CSSとJavaScriptの両方）を読み込みます。

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

詳細と使用例については、HTMLテンプレート言語使用の手引きを参照してください。

JSP の使用

JSPコードにui:includeClientLibタグを追加して、生成されるHTMLページのクライアントライブラリへのリンクを追加します。ライブラリを参照するには、ui:includeClientLibノードのcategoriesプロパティの値を使用します。

<%@taglib prefix="ui" uri="https://www.adobe.com/taglibs/granite/ui/1.0" %>
<ui:includeClientLib categories="<%= categories %>" />

例えば、/etc/clientlibs/foundation/jqueryノードのタイプはcq:ClientLibraryFolderで、categoriesプロパティは値cq.jqueryです。 JSPファイル内の次のコードは、ライブラリを参照します。

<ui:includeClientLib categories="cq.jquery"/>

生成される HTML ページには次のコードが含まれます。

<script type="text/javascript" src="/etc/clientlibs/foundation/jquery.js"></script>

JS、CSS またはテーマライブラリをフィルタリングするための属性を含めた詳細は、ui:includeClientLib を参照してください。

注意

<cq:includeClientLib>は、以前はクライアントライブラリを含めるために一般的に使用されていたもので、AEM 5.6以降は非推奨（廃止予定）となっていま <ui:includeClientLib> す。この代わりに、上記の説明に従ってを使用する必要があります。

クライアントライブラリフォルダーの作成

cq:ClientLibraryFolderノードを作成して、JavaScriptおよびカスケーディングスタイルシートライブラリを定義し、HTMLページで使用できるようにします。ノードの categories プロパティを使用して、ノードが属するライブラリカテゴリを特定します。

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

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

JS／CSS ソースファイル（いずれかまたは両方）をマージします。
画像ファイルなど、CSS スタイルをサポートするリソース。

注意：サブフォルダーを使用してソースファイルを整理できます。
生成される JS／CSS ファイルに統合するソースファイルを識別する 1 つの js.txt ファイルと 1 つの css.txt ファイル（いずれかまたは両方）。

clientlibarch

ウィジェット用のクライアントライブラリ特有の要件について詳しくは、ウィジェットの使用および拡張を参照してください。

Webクライアントには、cq:ClientLibraryFolderノードにアクセスする権限が必要です。また、リポジトリの保護された領域からライブラリを公開することもできます（後述の「他のライブラリからのコードの埋め込み」を参照）。

/lib でのライブラリの上書き

/appsの下にあるクライアントライブラリフォルダーは、/libs内にある同じ名前のフォルダーよりも優先されます。例えば、/apps/cq/ui/widgetsが/libs/cq/ui/widgetsよりも優先されます。これらのライブラリが同じカテゴリに属する場合は、/appsの下のライブラリが使用されます。

クライアントライブラリフォルダーの配置とプロキシクライアントライブラリサーブレットの使用

以前のバージョンでは、クライアントライブラリフォルダーはリポジトリの/etc/clientlibsの下にありました。これは引き続きサポートされますが、クライアントライブラリは/appsの下に配置することをお勧めします。これは、他のスクリプトの近くにクライアントライブラリを配置するためのものです。通常は、/appsと/libsの下にあります。

メモ

クライアントライブラリフォルダーの下の静的リソースは、resourcesというフォルダーに存在する必要があります。フォルダーresourcesの下に画像などの静的リソースがない場合、パブリッシュインスタンスで参照できません。次に例を示します。http://localhost:4503/etc.clientlibs/geometrixx/components/clientlibs/resources/example.gif

メモ

コードをコンテンツと設定からより詳細に分離するには、/appsの下にクライアントライブラリを配置し、allowProxyプロパティを利用して/etc.clientlibsを介して公開することをお勧めします。

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

静的リソースは、クライアントライブラリフォルダーの下のリソースにある場合、プロキシ経由でのみアクセスできます。

次に例を示します。

clientlib は /apps/myproject/clientlibs/foo にあります。
静的画像は /apps/myprojects/clientlibs/foo/resources/icon.png にあります。

次に、fooのallowProxyプロパティをtrueに設定します。

次に、/etc.clientlibs/myprojects/clientlibs/foo.jsをリクエストできます。
次に、/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.pngを使用して画像を参照できます。

注意

プロキシ化されたクライアントライブラリを使用する場合、AEM Dispatcher設定で、拡張機能clientlibsを持つURIが許可されるように更新が必要になる場合があります。

注意

Adobeは、/appsの下にクライアントライブラリを配置し、プロキシサーブレットを使用して使用できるようにすることをお勧めします。ただし、ベストプラクティスとしては、/appsパスまたは/libsパスを介して直接提供されるものをパブリックサイトに含めないことが必要です。

クライアントライブラリフォルダーの作成

Web ブラウザーで CRXDE Lite を開きます（http://localhost:4502/crx/de）。
クライアントライブラリフォルダーの配置先のフォルダーを選択して、作成／ノードを作成をクリックします。
ライブラリファイルの名前を入力し、タイプリストで cq:ClientLibraryFolder を選択します。「OK」をクリックし、「すべて保存」をクリックします。
ライブラリが所属するカテゴリ（1 つまたは複数）を指定するには、cq:ClientLibraryFolder ノードを選択し、次のプロパティを追加して、「すべて保存」をクリックします。
- 名前：categories
- タイプ：String
- 値：カテゴリ名
- 複数：選択
何らかの方法で、ソースファイルをライブラリフォルダーに追加します。例えば、WebDav クライアントを使用してファイルをコピーする、ファイルを作成してコンテンツを手動で作成する、などの方法があります。

注意：必要に応じて、サブフォルダーを使用してソースファイルを整理できます。
クライアントライブラリフォルダーを選択して、作成／ファイルを作成をクリックします。
ファイル名ボックスに、次のいずれかのファイル名を入力して、「OK」をクリックします。
- js.txt： JavaScript ファイルを生成する場合はこのファイル名を使用します。
- css.txt： カスケーディングスタイルシート（CSS）を生成する場合はこのファイル名を使用します。
ファイルを開き、ソースファイルのパスのルートを識別する次のテキストを入力します。

#base=[root]

[root] を、ソースファイルが格納されているフォルダーの TXT ファイルに対する相対パスに置き換えます。例えば、ソースファイルが TXT ファイルと同じフォルダーにある場合は、次のテキストを使用します。

#base=.

次のコードで、cq:ClientLibraryFolder ノードの下の mobile という名前のフォルダーをルートに設定します。

#base=mobile
#base=[root] の下の行に、ソースファイルのルートに対する相対パスを入力します。各ファイル名を別々の行に配置します。
「すべて保存」をクリックします。

依存関係へのリンク

クライアントライブラリフォルダーのコードが他のライブラリを参照する場合、他のライブラリを依存関係として識別します。JSP では、クライアントライブラリフォルダーを参照する ui:includeClientLib タグが原因で、HTML コードに生成したライブラリファイルへのリンクおよび依存関係が含まれます。

依存関係は別の cq:ClientLibraryFolder でなければなりません。依存関係を識別するには、次の属性を持つプロパティを cq:ClientLibraryFolder ノードに追加します。

名前： dependencies
タイプ： String[]
値：現在のライブラリフォルダーの依存先である cq:ClientLibraryFolder ノードの categories プロパティの値。

例えば、 / etc/clientlibs/myclientlibs/publicmainはcq.jqueryライブラリに依存しています。メインのクライアントライブラリを参照するJSPは、次のコードを含む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 ノードにプロパティを追加します。

名前： embed
タイプ： String[]
値：埋め込む cq:ClientLibraryFolder ノードの categories プロパティの値。

埋め込みを使用したリクエストの最小化

場合によっては、パブリッシュインスタンスによって一般的なページ用に生成される最終的なHTMLに、比較的多くの<script>要素が含まれていることがあります。特に、サイトで分析やターゲティングにClientContext情報を使用している場合は、例えば、最適化されていないプロジェクトでは、ページのHTMLに次の一連の<script>要素が表示されます。

<script type="text/javascript" src="/etc/clientlibs/granite/jquery.js"></script>
<script type="text/javascript" src="/etc/clientlibs/granite/utils.js"></script>
<script type="text/javascript" src="/etc/clientlibs/granite/jquery/granite.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/jquery.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/shared.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/personalization/kernel.js"></script>

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

次のクライアントライブラリカテゴリが AEM に含まれています。特定のサイトを機能させるために必要なもののみを埋め込んでください。ただし、このリストの順序は保持する必要があります。

browsermap.standard
browsermap
jquery-ui
cq.jquery.ui
personalization
personalization.core
personalization.core.kernel
personalization.clientcontext.kernel
personalization.stores.kernel
personalization.kernel
personalization.clientcontext
personalization.stores
cq.collab.comments
cq.collab.feedlink
cq.collab.ratings
cq.collab.toggle
cq.collab.forum
cq.cleditor

CSS ファイル内のパス

CSS ファイルを埋め込むと、生成される CSS コードは、埋め込みライブラリに対するリソースへの相対パスを使用します。例えば、公開アクセス可能な /etc/client/libraries/myclientlibs/publicmain ライブラリによって /apps/myapp/clientlib クライアントライブラリが埋め込まれるとします。

screen_shot_2012-05-29at20122pm

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

特定のモバイルグループ用のライブラリの使用

クライアントライブラリフォルダーのchannelsプロパティを使用して、ライブラリを使用するモバイルグループを特定します。 channelsプロパティは、同じカテゴリのライブラリが異なるデバイス機能用に設計されている場合に役立ちます。

クライアントライブラリフォルダーをデバイスグループに関連付けるには、次の属性を持つプロパティをcq:ClientLibraryFolderノードに追加します。

名前： channels
タイプ： String[]
値：モバイルグループの名前。グループからライブラリフォルダーを除外するには、名前の前に感嘆符(「!」)を付けます。

例えば、次の表は、channels カテゴリの各クライアントライブラリフォルダーの cq.widgets プロパティの値を示しています。

クライアントライブラリフォルダー	channels プロパティの値
`/libs/cq/analytics/widgets`	`!touch`
`/libs/cq/analytics/widgets/themes/default`	`!touch`
`/libs/cq/cloudserviceconfigs/widgets`	`!touch`
`/libs/cq/searchpromote/widgets`	`!touch`
`/libs/cq/searchpromote/widgets/themes/default`	`[`値なし`]`
`/libs/cq/touch/widgets`	`touch`
`/libs/cq/touch/widgets/themes/default`	`touch`
`/libs/cq/ui/widgets`	`!touch`
`/libs/cq/ui/widgets/themes/default`	`!touch`

プリプロセッサーの使用

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

プラグ可能なプリプロセッサーは、次のように柔軟な使用が可能です。

スクリプトソースを処理できる ScriptProcessors を定義する
プロセッサーはオプションを使用して設定できる
プロセッサーは縮小用に使用できるが、縮小以外の場合にも使用できる
clientlib はどのプロセッサーを使用するかを定義できる

メモ

デフォルトでは、AEM は YUI Compressor を使用します。既知の問題のリストについては、YUI Compressor GitHub ドキュメントを参照してください。特定の clientlibs 用の GCC コンプレッサーに切り替えると、YUI を使用しているときに発生していたいくつかの問題が解決することがあります。

注意

縮小化したライブラリをクライアントライブラリに配置しないでください。代わりに、生のライブラリを提供し、縮小が必要な場合は、プリプロセッサーのオプションを使用します。

使用方法

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

クライアントライブラリノードで、複数値プロパティ cssProcessor および jsProcessor を追加します。
または、HTML ライブラリマネージャーの OSGi 設定で、システムのデフォルト設定を定義します。

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

形式と例

形式

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

CSS 縮小用の YUI Compressor と JS 用の GCC

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

事前処理のための Typescript と縮小および不明化のための GCC

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

追加の GCC オプション

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 に変更するには、次の手順に従います。

Apache Felix Config Manager（http://localhost:4502/system/console/configMgr）に移動します。
Adobe Granite HTML ライブラリマネージャーを検索して編集します。
「Minify」オプションを有効にします（まだ有効でない場合）。
JS Processor Default Configs の値を min:gcc に設定します。

セミコロンで区切られている場合、オプションを渡すことができます（例：min:gcc;obfuscate=true）。
「保存」をクリックして、変更を保存します。

デバッグツール

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

埋め込みファイルの確認

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

Web ブラウザーのアドレスボックスで、HTML の URL に次のテキストを付加します。

?debugClientLibs=true
ページが読み込まれたら、ページソースを表示します。
リンク要素の href として指定されているリンクをクリックしてファイルを開き、ソースコードを表示します。

クライアントライブラリの確認

/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 ページから、「こちらをクリックして出力テスト」テキストのリンクをクリックします。
- Web ブラウザーで次の URL を開きます（必要に応じて別のホストおよびポートを使用）。
  - http://<host>:<port>/libs/granite/ui/content/dumplibs.html
デフォルトページに、categories 属性の値がないタグの出力が表示されます。
特定のカテゴリの出力を確認するには、クライアントライブラリの categories プロパティの値を入力して、「クエリを送信」をクリックします。

開発および本番用のライブラリ処理の設定

HTML ライブラリマネージャーサービスは、実行時に cq:ClientLibraryFolder タグを処理し、ライブラリを生成します。環境、開発または本番のタイプが、サービスの設定方法を決定します。

セキュリティを強化：デバッグを無効化
パフォーマンスを向上：空白を削除してライブラリを圧縮
読みやすさを改善：空白を含めて圧縮しない

サービスの設定について詳しくは、AEM HTML ライブラリマネージャーを参照してください。

adobe.com 上のリソース

Multichannel Communication Customer Communications Theme Editor Document Generation Version History Digital Asset Management

クライアントサイドライブラリの使用

AEM でのクライアント側ライブラリの機能

クライアント側ライブラリの参照

HTL の使用

JSP の使用

クライアントライブラリフォルダーの作成

/lib でのライブラリの上書き

クライアントライブラリフォルダーの配置とプロキシクライアントライブラリサーブレットの使用

クライアントライブラリフォルダーの作成

依存関係へのリンク

他のライブラリからのコードの埋め込み

アプリケーション専用のクライアントライブラリフォルダー

埋め込みを使用したリクエストの最小化

CSS ファイル内のパス

特定のモバイルグループ用のライブラリの使用

プリプロセッサーの使用

使用方法

形式と例

形式

CSS 縮小用の YUI Compressor と JS 用の GCC

事前処理のための Typescript と縮小および不明化のための GCC

追加の GCC オプション

システムのデフォルト縮小ツールの設定

デバッグツール

埋め込みファイルの確認

クライアントライブラリの確認

生成される出力の確認

開発および本番用のライブラリ処理の設定

adobe.com 上のリソース

このページ

次を表示：

トレーニング

ドキュメント

コミュニティ

サポート

リソース

アドビアカウント

Adobe