現在表示中:

現代の Web サイトは、JavaScript や CSS の複雑なコードで駆動するクライアント側処理に大きく依存しています。このコードの働きを整理し、最適化しようとすると、複雑な問題が生じる可能性があります。

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

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

クライアント側ライブラリ(JS ファイルまたは CSS ファイル)をページの HTML に含めるための標準的な方法は単純です。<script> タグまたは <link> タグを使用して、そのページの JSP に問題のファイルのパスを含めるだけです。次に例を示します。

...
<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 内であればどこにでも配置できます(これらのデフォルト、およびその他の設定は、システムコンソールの.Day CQ ライブラリマネージャーパネルで制御できます)。

それぞれの cq:ClientLibraryFolder には、一連の JS/CSS ファイル(いずれかまたは両方)と、少数のサポートファイルが格納されます(下記参照)。cq:ClientLibraryFolder のプロパティは以下のように設定されます。

  • categories:この cq:ClientLibraryFolder 内の一連の JS/CSS ファイルのカテゴリを識別します。categories プロパティでは、複数の値を設定できるので、1 つのライブラリフォルダーを複数のカテゴリに所属させることができます(これがどのような場合に便利かについては以下を参照)。
  • dependencies:このライブラリフォルダーが依存している他のクライアントライブラリカテゴリのリストです。例えば、2 つの cq:ClientLibraryFolder ノード FG がある場合に、F 内のあるファイルが適切に機能するために G 内の別のファイルが必要だとすると、Gcategories のうち少なくとも 1 つが、Fdependencies に含まれている必要があります。
  • embed

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

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

例えば、/etc/clientlibs/foundation/jquery ノードはタイプが cq:ClientLibraryFolder で、categories プロパティの値は cq.jquery です。JSP ファイル内で以下のコードによって、ライブラリが参照されます。

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

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

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

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

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

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

ノードには 1 つ以上のソースファイルが含まれており、実行時に単一の JS ファイルと CSS ファイル(いずれかまたは両方)に統合されます。生成されるファイルの名前は、ノード名に .js または .css のファイル名拡張子が付いたものになります。例えば、ライブラリノードの名前が cq.jquery である場合、生成されるファイル名は cq.jquery.js または cq.jquery.css となります。

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

  • 統合対象の JS/CSS ソースファイル(いずれかまたは両方)。
  • 画像ファイルなど、CSS スタイルをサポートするリソース。

    注意:サブフォルダーを使用してソースファイルを整理できます。

  • 生成される JS/CSS ファイルに統合するソースファイルを識別する 1 つの js.txt ファイルと 1 つの css.txt ファイル(いずれかまたは両方)。

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

Web クライアントには、cq:ClientLibraryFolder ノードにアクセスするための権限が必要です。通常、このノードはリポジトリの /etc/clientlibs の下にあります。ただし、リポジトリのセキュリティ保護された領域にあるライブラリへのアクセスを許可することもできます(下記の「他のライブラリからのコードの埋め込み」を参照)。

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

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

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

  1. Web ブラウザーで CRXDE Lite を開きます(http://localhost:4502/crx/de)。

  2. クライアントライブラリフォルダーの配置先のフォルダーを選択して、作成/ノードを作成をクリックします。

  3. ライブラリファイルの名前を入力し、タイプリストで cq:ClientLibraryFolder を選択します。「OK」をクリックし、「すべて保存」をクリックします。

  4. ライブラリの所属先のカテゴリ(1 つまたは複数)を指定するには、cq:ClientLibraryFolder ノードを選択し、以下のプロパティを追加して、「すべて保存」をクリックします。

    • 名前:categories
    • タイプ:String
    • 値:カテゴリ名
    • 複数:選択
  5. 何らかの方法で、ソースファイルをライブラリフォルダーに追加します。例えば、WebDav クライアントを使用してファイルをコピーする、ファイルを作成してコンテンツを手動で作成する、などの方法があります。

    注意:必要に応じて、サブフォルダーを使用してソースファイルを整理できます。

  6. コンテンツライブラリフォルダーを選択して、作成/ファイルを作成をクリックします。

  7. ファイル名ボックスに、以下のいずれかのファイル名を入力して、「OK」をクリックします。

    • js.txt: JavaScript ファイルを生成する場合はこのファイル名を使用します。
    • css.txt: カスケーディングスタイルシート(CSS)を生成する場合はこのファイル名を使用します。

  8. ファイルを開き、ソースファイルのパスのルートを識別する以下のテキストを入力します。

    #base=[root]

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

    #base=.

    以下のコードでは、cq:ClientLibraryFolder ノードの下の mobile という名前のフォルダーがルートに設定されます。

    #base=mobile

  9. #base=[root] の下の行に、ルートに対するソースファイルの相対パスを入力します。ファイル名はそれぞれ別々の行に配置します。

  10. 「すべて保存」をクリックします。

依存関係へのリンク

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

依存関係は、もう 1 つの 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 フォルダーへのアクセスを拒否することも、ベストプラクティスです。両方のベストプラクティスを満たすには、/app の下にあるクライアントライブラリを埋め込むクライアントライブラリフォルダーを、/etc フォルダーの下に作成します。

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

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

埋め込みを使用した要求の最小化

発行インスタンスによって典型的なページ用に生成された最終的な HTML に、<script> 要素が比較的多数含まれている場合があります。分析やターゲット設定のためにクライアントコンテキスト情報を使用しているサイトで特に多く見られます。例えば、最適化されていないプロジェクトでは、1 つのページの 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/granite/underscore.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/personalization/kernel.js"></script>

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

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

  1. browsermap.standard
  2. browsermap
  3. jquery-ui
  4. cq.jquery.ui
  5. personalization
  6. personalization.core
  7. personalization.core.kernel
  8. personalization.clientcontext.kernel
  9. personalization.stores.kernel
  10. personalization.kernel
  11. personalization.clientcontext
  12. personalization.stores
  13. cq.collab.comments
  14. cq.collab.feedlink
  15. cq.collab.ratings
  16. cq.collab.toggle
  17. cq.collab.forum
  18. cq.cleditor

CSS ファイル内のパス

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

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

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

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

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

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

クライアントライブラリフォルダー 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 には、クライアントライブラリフォルダーをデバッグおよびテストするためのツールがいくつか備えられています。

埋め込みファイルの確認

埋め込みコードの起源をトレースする場合や、埋め込みクライアントライブラリが期待通りの結果を出していることを確認する場合は、実行時に埋め込まれるファイルの名前を確認できます。ファイル名を確認するには、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");

<p">埋め込みファイルの名前を確認するには、以下の手順を使用します。</p">

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

    ?debugClientLibs=true

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

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

/libs/cq/ui/components/dumplibs/dumplibs コンポーネントは、システム上のすべてのクライアントライブラリフォルダーに関する情報のページを生成します。/libs/cq/ui/content/dumplibs ノードには、リソースタイプとしてコンポーネントが含まれています。ページを開くには、以下の URL を使用します(必要に応じて別のホストおよびポートを使用してください)。

http://localhost:4502/libs/cq/ui/content/dumplibs.test.html

情報には、ライブラリのパスおよびタイプ(CSS または JS)と、categories や dependencies などのライブラリ属性の値が含まれます。ページ上の後続のテーブルは、各カテゴリおよびチャネルに含まれるライブラリを示します。

生成される出力の確認

dumplibs コンポーネントには、cq:includeClientLib タグ用に生成されるソースコードを表示するテストセレクターが含まれます。ページには、jscssthemed の各属性を様々に組み合わせたコードが含まれます。

  1. 次のいずれかの方法で、テスト出力ページを開きます。
    • dumplibs.html ページから、「Click here for output testing」テキストのリンクをクリックします。
    • Web ブラウザーで以下の URL を開きます(必要に応じて別のホストおよびポートを使用してください)。

      http://localhost:4502/libs/cq/ui/content/dumplibs.html

    デフォルトページに、categories 属性の値がないタグの出力が表示されます。

  2. 特定のカテゴリの出力を確認するには、クライアントライブラリの categories プロパティの値を入力して「クエリーを送信」をクリックします。

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

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

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

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

本作品は Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License によってライセンス許可を受けています。  Twitter™ および Facebook の投稿には、Creative Commons の規約内容は適用されません。

法律上の注意   |   プライバシーポリシー