現在表示中:

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

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

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

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

<%@taglib prefix="ui" uri="http://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 およびカスケーディングスタイルシート(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 ファイル(いずれかまたは両方)。
clientlibarch

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

Web クライアントは、cq:ClientLibraryFolder ノードへのアクセス権を持っている必要があります。また、リポジトリの安全な領域からライブラリを公開できます(後述の「他のライブラリからのコードの埋め込み」を参照)。

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

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

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

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

注意:

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

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

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

次に例を示します。

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

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

  • /etc.clientlibs/myprojects/clientlibs/foo.js をリクエストできます
  • /etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png から画像を参照できます

警告:

プロキシを使用したクライアントライブラリを使用している場合、拡張子 clientlibs を含む URI を許可するように AEM ディスパッチャー設定を更新する必要がある可能性があります。

警告:

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

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

  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.txtJavaScript ファイルを生成するには、このファイル名を使用します。
    • css.txtカスケーディングスタイルシート(CSS)を生成するには、このファイル名を使用します。

     

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

    #base=[root]

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

    #base=.

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

    #base=mobile

     

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

     

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

     

依存関係へのリンク

クライアントライブラリフォルダーのコードが他のライブラリを参照する場合、他のライブラリを依存関係として識別します。JSP では、クライアントライブラリフォルダーを参照する ui: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 の下のアプリケーションフォルダーに保持することです。また、/app フォルダーへの Web サイト訪問者のアクセスを拒否することも、ベストプラクティスです。両方のベストプラクティスを満たすには、/app の下にあるクライアントライブラリを埋め込むクライアントライブラリフォルダーを、/etc フォルダーの下に作成します。

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

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

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

場合によっては(特にサイトで分析およびターゲット設定用に ClientContext 情報を使用している場合)、通常のページ用にパブリッシュインスタンスで生成した最終 HTML に比較的多くの <script> 要素が含まれていることがわかることがあります。例えば、最適化されていないプロジェクトで、ページの 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 クライアントライブラリを埋め込む場合、

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

例えば、次の表は、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 では、プラグ可能なプリプロセッサーを使用でき、AEMの デフォルトプリプロセッサーとして、CSS および JavaScript 用の YUI Compressor と YUI が 定された JavaScript 用の Google Closure Compiler(GCC)をサポートします。

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

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

注意:

デフォルトでは、AEM は YUI Compressor を使用します。既知の問題のリストについては、YUI Compressor GitHub ドキュメントを参照してください。特定の clientlib 用の 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 に変更するには、次の手順に従います。

  1. Apache Felix Config Manager(http://localhost:4502/system/console/configMgr)に移動します。

  2. Adobe Granite HTML ライブラリマネージャーを検索して編集します。

  3. Minify」オプションを有効にします(まだ有効でない場合)。

  4. JS Processor Default Configs の値を min:gcc に設定します。

    セミコロンで区切られている場合、オプションを渡すことができます(例:min:gcc;obfuscate=true)。

  5. 保存」をクリックして変更を保存します。

デバッグツール

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

  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 の規約内容は適用されません。

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