最近の web サイトは、複雑な JavaScript や CSS コードを利用したクライアント側の処理に大きく依存しています。このコードの提供を編成および最適化することが厄介な問題となることがあります。
この問題に対処するために、AEMでは次の機能を提供しています。 クライアント側ライブラリフォルダー:クライアント側コードをリポジトリに保存し、カテゴリに整理し、コードの各カテゴリをクライアントに提供するタイミングと方法を定義できます。 その後、クライアントサイドライブラリシステムは、正しいコードを読み込むための正しいリンクを最終的な Web ページに生成する処理をおこないます。
クライアントサイドライブラリ(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
プロパティは複数の値を取るため、ライブラリフォルダーを複数のカテゴリの一部にすることができます(これがどのように役立つかについては以下を参照)。
dependencies
:これは、このライブラリカテゴリが依存する他のクライアントライブラリフォルダーのリストです。例えば、F
と G
の 2 つの cq:ClientLibraryFolder
ノードを指定し、F
のファイルが正しく機能するために、別の G
にあるファイルが必要な場合、G
のうち 1 つ以上の categories
は、F
の dependencies
に含まれている必要があります。
embed
:他のライブラリからコードを埋め込むために使用します。ノード F がノード G および H を埋め込むと、結果として得られる HTML は、ノード G および H からのコンテンツの合成になります。
allowProxy
:クライアントライブラリが /apps
の下にある場合、このプロパティを使用すると、プロキシサーブレット経由でクライアントライブラリにアクセスできます。後述のクライアントライブラリのフォルダーの配置とプロキシクライアントライブラリのサーブレットの使用を参照してください。
AEMサイトの開発には HTL が推奨されるテクノロジーなので、AEMにクライアント側ライブラリを含めるには HTL を使用する必要があります。 ただし、JSP を使用しておこなうこともできます。
HTL では、クライアントライブラリは AEM 提供のヘルパーテンプレートを介して読み込まれます。テンプレートには data-sly-use
を使用してアクセスできます。このファイルには 3 つのテンプレートが含まれ、data-sly-call
で呼び出すことができます。
各ヘルパーテンプレートには、必要なクライアントライブラリを参照するための categories
オプションを指定できます。このオプションには、文字列値の配列またはコンマ区切り値のリストを含む文字列を指定できます。
詳細および使用例については、HTML テンプレート言語の使用の手引きドキュメントを参照してください。
ui:includeClientLib
タグを JSP コードに追加して、生成した 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.jquery
値の categories プロパティを持つ cq:ClientLibraryFolder
です。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
ファイル(いずれかまたは両方)。
ウィジェット用のクライアントライブラリ特有の要件について詳しくは、ウィジェットの使用および拡張を参照してください。
Web クライアントには、cq:ClientLibraryFolder
ノードにアクセスする許可が必要です。また、リポジトリの保護された領域からライブラリを公開することもできます(以下の「他のライブラリからのコードの埋め込み」を参照)。
以下にあるクライアントライブラリフォルダー /apps
同じ名前のフォルダーよりも、 /libs
. 例えば、/apps/cq/ui/widgets
は /libs/cq/ui/widgets
よりも優先されます。これらのライブラリが同じカテゴリに属する場合、/apps
の下にあるライブラリが使用されます。
以前のバージョンでは、クライアントライブラリフォルダーは、リポジトリの /etc/clientlibs
の下にありました。これは引き続きサポートされますが、クライアントライブラリを /apps
の下に配置することをお勧めします。これは、クライアントライブラリを他のスクリプトの近くに配置するためです。他のスクリプトは、通常、/apps
と /libs
の下にあります。
クライアントライブラリフォルダーの下にある静的リソースは、resources というフォルダーに配置する必要があります。resources フォルダーの下に画像などの静的リソースがない場合、公開インスタンスで参照することはできません。以下に例を示します。https://localhost:4503/etc.clientlibs/geometrixx/components/clientlibs/resources/example.gif
コードをコンテンツと設定からより詳細に分離するには、以下の場所にクライアントライブラリを配置することをお勧めします。 /apps
を介して公開します。 /etc.clientlibs
を使用して、 allowProxy
プロパティ。
/apps
にあるクライアントライブラリにアクセスできるようにするために、プロキシサーブレットが使用されます。ACL は依然としてクライアントライブラリフォルダーで適用されますが、サーブレットを使用すると、/etc.clientlibs/
プロパティが allowProxy
に設定されている場合、true
を介してコンテンツを読み取ることができます。
静的リソースは、クライアントライブラリフォルダーの下のリソースにある場合、プロキシ経由でのみアクセスできます。
次に例を示します。
/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
から画像を参照できますプロキシを使用したクライアントライブラリを使用している場合、拡張子 clientlibs を含む URI を許可するように AEM Dispatcher 設定を更新する必要が生じる場合があります。
アドビでは、クライアントライブラリを /apps
の下に配置し、プロキシサーブレットを使用して利用できるようにすることをお勧めします。ただし、ベストプラクティスとしては、依然として、/apps
または /libs
パスから直接提供されたものを何も含まない公開サイトが必要です。
Web ブラウザーで CRXDE Lite を開きます(https://localhost:4502/crx/de)。
クライアントライブラリフォルダーの配置先のフォルダーを選択して、作成/ノードを作成をクリックします。
ライブラリファイルの名前を入力し、タイプリストで cq:ClientLibraryFolder
を選択します。「OK」をクリックし、「すべて保存」をクリックします。
ライブラリが所属するカテゴリ(1 つまたは複数)を指定するには、cq:ClientLibraryFolder
ノードを選択し、次のプロパティを追加して、「すべて保存」をクリックします。
何らかの方法で、ソースファイルをライブラリフォルダーに追加します。例えば、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
ノードに追加します。
例えば、/ 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 ファイルには、埋め込み先のライブラリのコードが含まれます。
コードの埋め込みは、リポジトリーのセキュリティ保護された領域に格納されているライブラリへのアクセスを提供する際に便利です。
アプリケーション関連のすべてのファイルは、/apps
内のアプリケーションフォルダーに格納することをお勧めします。Web サイト訪問者の /apps
フォルダーに対するアクセスを拒否することもお勧めします。両方のベスト プラクティスを満たすには、/apps
の下にクライアントライブラリフォルダーを作成し、クライアントライブラリフォルダーの配置とプロキシクライアントライブラリサーブレットの使用で説明されているように、プロキシサーブレットを介してアクセスできるようにします。
埋め込むクライアントライブラリフォルダーを識別するには、categories プロパティを使用します。ライブラリを埋め込むには、次のプロパティ属性を使用して、埋め込み cq:ClientLibraryFolder
ノードにプロパティを追加します。
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/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 コードは、埋め込みライブラリに対するリソースへの相対パスを使用します。例えば、公開アクセス可能な /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
ノードに追加します。
例えば、次の表は、cq.widgets
カテゴリの各クライアントライブラリフォルダーの channels
プロパティの値を示しています。
クライアントライブラリフォルダー | チャネルプロパティの値 |
---|---|
/libs/cq/analytics/widgets |
!touch |
/libs/cq/analytics/widgets/themes/default |
!touch |
/libs/cq/cloudserviceconfigs/widgets |
!touch |
/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)をサポートします。
プラガブルプリプロセッサーは、次のように柔軟に使用できます。
デフォルトでは、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;
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 に変更するには、次の手順に従います。
Apache Felix Config Manager(https://localhost:4502/system/console/configMgrr)に移動します。
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
タグを処理してライブラリを生成します。環境、開発または実稼動のタイプによって、サービスの設定方法が決まります。
サービスの設定について詳しくは、 AEMHTMLライブラリマネージャー.