クライアントライブラリとフロントエンドワークフロー client-side-libraries
このチュートリアルでは、クライアントサイドライブラリ(clientlib)を使用して、Adobe Experience Manager (AEM) Sites 実装の CSS と JavaScript をデプロイおよび管理する方法について説明します。このチュートリアルでは、ui.frontend モジュール、非結合 webpack プロジェクトを、エンドツーエンドのビルドプロセスに統合する方法についても説明します。
前提条件 prerequisites
ローカル開発環境を設定するために必要なツールや説明を確認します。
コンポーネントの基本チュートリアルを確認して、クライアントサイドライブラリと AEM の基礎を理解することもお勧めします。
スタータープロジェクト
チュートリアルの作成元となるベースラインコードをチェックアウトします。
-
GitHubの
tutorial/client-side-libraries-start
ブランチをチェックアウトします。code language-shell $ cd aem-guides-wknd $ git checkout tutorial/client-side-libraries-start
-
Maven スキルを使用して、ローカル AEM インスタンスにコードベースをデプロイします。
code language-shell $ mvn clean install -PautoInstallSinglePackage
note note NOTE AEM 6.5 または 6.4 を使用している場合は、任意の Maven コマンドに classic
プロファイルを追加します。code language-shell $ mvn clean install -PautoInstallSinglePackage -Pclassic
いつでも、完成したコードを GitHub で確認したり、ブランチ tutorial/client-side-libraries-solution
に切り替えてコードをローカルにチェックアウトしたりできます。
目的
- 編集可能なテンプレートを使用してクライアントサイドライブラリをページに組み込む方法を理解する。
- 専用のフロントエンド開発用の webpack 開発サーバーと
ui.frontend
モジュールの使用方法を確認する。 - コンパイル済みの CSS と JavaScript を Sites 実装に配信するエンドツーエンドのワークフローについて理解する
作ろうとしているもの what-build
この章では、WKND サイトと記事ページテンプレートのベースラインスタイルを追加して、実装を UI デザインモックアップに近づけます。高度なフロントエンドワークフローを使用して、webpack プロジェクトを AEM クライアントライブラリに統合します。
ベースラインスタイルが適用された記事ページ
背景 background
クライアントサイドライブラリは、AEM Sites の実装に必要な CSS と JavaScript ファイルの編成および管理のための仕組みを提供します。クライアントライブラリ(clientlib)の基本的な目的は、以下のとおりです。
- CSS/JS を、開発および管理が簡単な個別の小さなファイルに保存する
- 組織的な方法で、サードパーティのフレームワークへの依存関係を管理する
- CSS/JS を 1~2 個の要求に連結することで、クライアント側の要求数を最小限にする.
クライアントサイドライブラリの使用の詳細については、こちらを参照してください。
クライアントサイドライブラリにはいくつかの制限があります。 中でも注目すべきは、Sass、LESS、TypeScript などの一般的なフロントエンド言語のサポートが制限されていることです。 このチュートリアルでは、ui.frontend モジュールがこの問題の解決にどう役立つのかを見ていきます。
スターターコードベースをローカルの AEMインスタンスにデプロイし、http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html に移動します。このページのスタイルは設定されていません。 WKND ブランドのクライアントサイドライブラリを実装して、ページに CSS と JavaScript を追加しましょう。
クライアントサイドライブラリの組織 organization
次に、 AEM プロジェクトアーキタイプで生成された clientlib の組織を見ていきます。
クライアントサイドライブラリの組織とページを含む概要図
-
VSCode または他の IDE を使用して、ui.apps モジュールを開きます。
-
パス
/apps/wknd/clientlibs
を展開して、アーキタイプで生成された clientlib を表示します。以下のセクションでは、これらの clientlib の詳細について説明します。
-
次の表に、クライアントライブラリの概要を示します。クライアントライブラリを含める方法については、こちらを参照してください。
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 名前 説明 備考 clientlib-base
WKND サイトが機能するために必要となる CSS および JavaScript の基本レベルを構成します コアコンポーネントのクライアントライブラリを埋め込みます clientlib-grid
レイアウトモードが機能するのに必要な CSS を生成します モバイルとタブレットのブレークポイントは、ここで設定できます clientlib-site
WKND サイト固有のテーマを含みます ui.frontend
モジュールによって生成されますclientlib-dependencies
サードパーティの依存関係を埋め込みます ui.frontend
モジュールによって生成されます -
その
clientlib-site
を確認します。clientlib-dependencies
はソース管理から無視されます。 これは意図的なもので、ビルド時にui.frontend
モジュールによって生成されます。
基本スタイルの更新 base-styles
次に、 ui.frontend モジュールで定義された基本スタイルを更新します。 ui.frontend
モジュールのファイル は、サイトテーマとサードパーティの依存関係を含む clientlib-site
および clientlib-dependecies
のライブラリを生成します。
クライアントサイドライブラリは、Sass または TypeScript などのより高度な言語をサポートしていません。フロントエンド開発を加速させて最適化する NPM や webpack などのオープンソースツールがいくつかあります。 ui.frontend モジュールの目標は、これらのツールを使用して、ほとんどのフロントエンドソースファイルを管理できるようにすることです。
-
ui.frontend モジュールを開き、
src/main/webpack/site
に移動します。 -
ファイル
main.scss
を開きますmain.scss
は、ui.frontend
モジュールの Sass ファイルへのエントリポイントです。 これには、プロジェクト内の様々な Sass ファイル全体で使用される一連のブランド変数を含む_variables.scss
ファイルが含まれます。 また、_base.scss
ファイルも含まれ、HTML 要素の基本スタイルを定義します。 正規表現には、src/main/webpack/components
にあるの個々のコンポーネントのスタイルが含まれます。別の正規表現には、src/main/webpack/site/styles
にあるファイルが含まれます。 -
main.ts
ファイルを調べます。これにはmain.scss
のほか、プロジェクトで.js
または.ts
ファイルを収集するための正規表現が含まれます。 このエントリポイントは、ui.frontend
モジュール全体で webpack 設定ファイルによって使用されます。 -
src/main/webpack/site/styles
の下にあるファイルを調べます。これらのファイルは、ヘッダー、フッター、メインコンテンツコンテナなど、テンプレート内のグローバル要素のスタイルを設定します。 これらのファイルの CSS ルールは、様々な HTML 要素(
header
、main
、およびfooter
)をターゲットにします。 これらの HTML 要素は、前の章のページとテンプレートのポリシーによって定義されています。 -
src/main/webpack
の下のcomponents
フォルダーを展開してファイルを調べます。各ファイルは、アコーディオンコンポーネントといったコアコンポーネントにマッピングされます。スタイルルールを使用して特定の CSS クラスを容易にターゲット設定できるよう、各コアコンポーネントはブロック要素修飾子または BEM 表記で作成されます。
/components
の下にあるファイルは、コンポーネントごとに異なる BEM ルールを使用して、AEM プロジェクトアーキタイプによってスタブ化されています。 -
WKND の基本スタイル wknd-base-styles-src-v3.zip をダウンロードし、ファイルを 解凍 します。
チュートリアルの進行を促進するために、コアコンポーネントと記事ページテンプレートの構造に基づく WKND ブランドを実装する Sass ファイルがいくつか用意されています。
-
ui.frontend/src
の内容を前の手順からのファイルで上書きします。ZIP された内容で、次のフォルダーを上書きします。code language-plain /src/main/webpack /components /resources /site /static
WKND スタイルの実装の詳細を確認するために、変更されたファイルを検査します。
ui.frontend 統合の検査 ui-frontend-integration
ui.frontend モジュールに組み込まれた主要な統合要素である aem-clientlib-generator は、コンパイル済みの CSS および JS アーティファクトを webpack/npm プロジェクトから取得し、AEM クライアントサイドライブラリに変換します。
AEM プロジェクトアーキタイプは、この統合を自動的に設定します。次に、その仕組みを見てみましょう。
-
コマンドラインターミナルを開き、ui.frontend モジュールを
npm install
コマンドを使用してインストールします。code language-shell $ cd ~/code/aem-guides-wknd/ui.frontend $ npm install
note note NOTE 新しいクローンやプロジェクトの生成の後と同様に、 npm install
の実行は 1 回だけ必要です。 -
ui.frontend/package.json
を開き、スクリプト****開始 コマンドに--env writeToDisk=true
を追加します。code language-json { "scripts": { "start": "webpack-dev-server --open --config ./webpack.dev.js --env writeToDisk=true", } }
-
監視 モードで webpack 開発サーバーを起動するには、次のコマンドを実行します。
code language-shell $ npm run watch
-
これは
ui.frontend
モジュールからソースファイルをコンパイルし、http://localhost:4502 で AEM と変更を同期します。code language-shell + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js + jcr_root/apps/wknd/clientlibs/clientlib-site/js + jcr_root/apps/wknd/clientlibs/clientlib-site + jcr_root/apps/wknd/clientlibs/clientlib-dependencies/css.txt + jcr_root/apps/wknd/clientlibs/clientlib-dependencies/js.txt + jcr_root/apps/wknd/clientlibs/clientlib-dependencies http://admin:admin@localhost:4502 > OK + jcr_root/apps/wknd/clientlibs/clientlib-site/css + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js http://admin:admin@localhost:4502 > OK
-
コマンド
npm run watch
で最終的に clientlib-site および clientlib-dependencies を AEM と自動的に同期される ui.apps モジュールで入力します。note note NOTE また、JS と CSS を縮小する npm run prod
プロファイルがあります。Maven 経由で webpack ビルドがトリガーされるたびに行われる標準的なコンパイルです。ui.frontend モジュールについて詳しくは、こちらを参照してください。 -
ファイル
site.css
をui.frontend/dist/clientlib-site/site.css
下で検査します。これは、Sass ソースファイルに基づくコンパイル済み CSS です。 -
ui.frontend/clientlib.config.js
ファイルを調べます。これは aem-clientlib-generator という npm プラグインの設定ファイルで、/dist
の内容をクライアントライブラリに変換し、ui.apps
モジュールに移動させます。 -
ui.apps/src/main/content/jcr_root/apps/wknd/clientlibs/clientlib-site/css/site.css
でファイルsite.css
を ui.apps モジュールで検査します。これは、ui.frontend モジュールからのsite.css
ファイルと同一コピーである必要があります。ui.apps モジュールで AEM にデプロイできるようになりました。note note NOTE clientlib-site は、npm または maven を使用してビルド時にコンパイルされているため、ui.apps モジュールでソース管理から安全に無視できます。ui.apps 下の .gitignore
ファイルを検査します。 -
AEM の LA スケートパークに関する記事を http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html で開きます。
これで、記事の更新されたスタイルが表示されます。ブラウザーでキャッシュされた CSS ファイルをクリアするには、ハード更新が必要な場合があります。
外観がモックアップにかなり近づいてきました。
note note NOTE ui.frontend コードをビルドして AEM にデプロイするための上記の手順は、Maven ビルドが mvn clean install -PautoInstallSinglePackage
プロジェクトのルートからトリガーされたときに自動的に実行されます。
スタイルの変更
次に、ui.frontend
モジュールで小規模な変更を加えて、npm run watch
がローカルの AEM インスタンスにスタイルを自動的にデプロイする様子を確認します。
-
ui.frontend
モジュールからファイルui.frontend/src/main/webpack/site/_variables.scss
を開きます。 -
$brand-primary
カラー変数を更新します。code language-scsss //== variables.css //== Brand Colors $brand-primary: $pink;
変更を保存します。
-
ブラウザーに戻り、AEM ページを更新して更新内容を確認します。
-
$brand-primary
カラーの変更を元に戻し、コマンドCTRL+C
を使用して webpack ビルドを停止します。
ページとテンプレートの組み込み page-inclusion
次に、clientlib が AEM ページでどのように参照されているかを確認します。Web 開発の一般的なベストプラクティスは、CSS を HTML ヘッダー <head>
に含め、JavaScript を終了タグ </body>
の直前で組み込むことです。
-
Article Page テンプレート(http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page/structure.html)を参照してください。
-
ページ情報 アイコンをクリックし、メニューで「ページポリシー」を選択して ページポリシー ダイアログを開きます。
ページ情報/ページポリシー
-
ここには
wknd.dependencies
とwknd.site
のカテゴリが一覧表示されていることに注目してください。デフォルトでは、ページポリシーを通じて設定される clientlib は分割されて、CSS がページヘッダーに含まれ、JavaScript が本体の末尾に含まれます。ページヘッダーで読み込まれる clientlib JavaScript を明示的にリストすることができます。以下はwknd.dependencies
の場合です。note note NOTE customheaderlibs.html
またはcustomfooterlibs.html
スクリプトを使用して、ページコンポーネントから直接wknd.site
またはwknd.dependencies
を参照することもできます。テンプレートを使用すると、テンプレートごとに使用する clientlib を柔軟に選択できます。例えば、選択したテンプレートでのみ使用される大きな JavaScript ライブラリがある場合です。 -
Article Page テンプレート を使用して作成した LA Skateparks ページ(http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html)に移動します。
-
ページ情報 アイコンをクリックし、メニューで「公開済みとして表示」を選択して AEM エディターの外部で記事ページを開きます。
-
http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled のページソースを表示すると、
<head>
に次の clientlib 参照が含まれていることがわかります。code language-html <head> ... <script src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.js"></script> <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.css" type="text/css"> <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-78fb9cea4c3a2cc17edce2c2b32631e2-lc.min.css" type="text/css"> ... </head>
なお、これらの clientlibs はプロキシ
/etc.clientlibs
エンドポイントを使用しています。また、次の clientlib がページの下部に含まれていることもわかります。code language-html ... <script src="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-7157cf8cb32ed66d50e4e49cdc50780a-lc.min.js"></script> <script src="/etc.clientlibs/wknd/clientlibs/clientlib-base.lc-53e6f96eb92561a1bdcc1cb196e9d9ca-lc.min.js"></script> ... </body>
note note NOTE AEM 6.5/6.4 の場合、クライアントサイドライブラリは自動的には縮小されません。HTML ライブラリマネージャーによる縮小の有効化(推奨)に関するドキュメントを参照してください。 note warning WARNING セキュリティ上の理由から、/apps パスは**** Dispatcher の filter セクション にのみ使用すべきなので、パブリッシュ側では、クライアントライブラリを /apps から提供 しないことが重要となります。クライアントライブラリの allowProxy プロパティにより、CSS と JavaScript が /etc.clientlibs から提供されるようになります。
次の手順 next-steps
個々のスタイルを実装し、Experience Manager のスタイルシステムを使用してコアコンポーネントを再利用する方法について説明します。 スタイルシステムを使った開発では、スタイルシステムを使用してブランド固有の CSS とテンプレートエディターの高度なポリシー設定でコアコンポーネントを拡張する方法について説明します。
完成したコードを GitHub で確認したり、Git ブランチ tutorial/client-side-libraries-solution
でレビューしてローカルにデプロイしたりできます。
- github.com/adobe/aem-wknd-guides リポジトリのクローンを作成します。
tutorial/client-side-libraries-solution
ブランチをチェックアウトします。
その他のツールとリソース additional-resources
Webpack DevServer - 静的マークアップ webpack-dev-static
前の演習では、ui.frontend モジュールのいくつかの Sass ファイルが更新され、ビルドプロセスを通じて最終的にこれらの変更が AEM に反映されることを確認しました。次は、webpack-dev-server を使用して 静的 HTML に対するフロントエンドスタイルを迅速に開発する手法を見ていきます。
この手法は、AEM 環境に容易にアクセスできない専任のフロントエンド開発者(FED)によって、ほとんどのスタイルとフロントエンドコードが実行される場合に便利です。また、この手法を使用すると、FED が HTML に直接変更を加え、それを AEM 開発者に渡してコンポーネントとして実装してもらうこともできます。
-
http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled で LA スケートパークの記事ページのページソースをコピーします。
-
IDE を再度開きます。 AEM からコピーしたマークアップを
src/main/webpack/static
の下にある ui.frontend モジュールのindex.html
に貼り付けます。 -
コピーしたマークアップを編集して、clientlib-site および clientlib-dependencies への参照をすべて削除します。
code language-html <!-- remove --> <script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.js"></script> <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.css" type="text/css"> <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.css" type="text/css"> ... <script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site.js"></script>
webpack 開発サーバーがこれらのアーティファクトを自動的に生成するので、これらの参照を削除します。
-
ui.frontend モジュール内から次のコマンドを実行して、新しいターミナルから webpack サーバーを起動します。
code language-shell $ cd ~/code/aem-guides-wknd/ui.frontend/ $ npm start > aem-maven-archetype@1.0.0 start code/aem-guides-wknd/ui.frontend > webpack-dev-server --open --config ./webpack.dev.js
-
これにより、http://localhost:8080/ で新しいブラウザーウィンドウが開き、静的マークアップが表示されます。
-
src/main/webpack/site/_variables.scss
ファイルを編集します。$text-color
ルールを次のように置き換えます。code language-diff - $text-color: $black; + $text-color: $pink;
変更を保存します。
-
ブラウザーで http://localhost:8080 に自動的に反映された変更が表示されるはずです。
-
/aem-guides-wknd.ui.frontend/webpack.dev.js
ファイルを確認します。webpack-dev-server の起動に使用する Webpack 設定が含まれます。 ローカルで実行されている AEM のインスタンスからパス/content
と/etc.clientlibs
をプロキシします。これにより、画像や他の clientlib(ui.frontend コードによって管理されていない)が使用可能になります。note caution CAUTION 静的マークアップの画像ソースは、ローカル AEM インスタンス上のライブ画像コンポーネントを指しています。 画像のパスが変更された場合、AEM が起動されていない場合、ブラウザーがローカルの AEM インスタンスにログインしていない場合は、画像が壊れて表示されます。 外部リソースに渡す場合は、画像を静的な参照で置き換えることもできます。 -
コマンドラインに
CTRL+C
と入力すると、webpack サーバーを 停止 できます。
aemfed develop-aemfed
aemfed は、フロントエンド開発の高速化に使用できるオープンソースのコマンドラインツールです。 aemsync、Browsersync、Sling ログトレーサーを備えています。
大まかに言うと、aemfed
は ui.apps モジュール内のファイルの変更をリッスンし、それらを実行中の AEM インスタンスに直接自動的に同期するように設計されています。変更に基づき、ローカルブラウザーが自動更新されるので、フロントエンド開発がスピードアップします。aemfed は Sling ログトレーサーとも連携し、サーバーサイドのすべてのエラーを直接ターミナルに自動表示します。
ui.apps モジュール内で多くの作業を行い、HTL スクリプトを修正し、カスタムコンポーネントを作成する場合、aemfed は強力なツールとして使用できます。完全なドキュメントについては、こちらを参照してください。
クライアントサイドライブラリのデバッグ debugging-clientlibs
複数のクライアントライブラリを組み込むために、カテゴリ および 埋め込み の様々な方法を使用すると、トラブルシューティングが面倒になることがあります。AEM はそのためにいくつかのツールを公開しています。最も重要なツールの 1 つは、クライアントライブラリの再ビルド です。これにより、AEM はすべての LESS ファイルを強制的に再コンパイルし、CSS を生成します。
-
ライブラリのダンプ - AEM インスタンスに登録されているすべてのクライアントライブラリを一覧表示します。
<host>/libs/granite/ui/content/dumplibs.html
-
出力テスト - カテゴリ別を含む、clientlib の予想される HTML 出力を確認します。
<host>/libs/granite/ui/content/dumplibs.test.html
-
ライブラリの依存関係の検証 - 見つからないすべての依存関係または埋め込みカテゴリを強調表示します。
<host>/libs/granite/ui/content/dumplibs.validate.html
-
クライアントライブラリの再ビルド - AEM ですべてのクライアントライブラリを強制的に再ビルドするか、クライアントライブラリのキャッシュを無効にできます。このツールでは、AEM が生成された CSS を強制的に再コンパイルするので、LESS を使用した開発において特に効果的です。一般的に、キャッシュを無効化した後にページを更新する方が、すべてのライブラリを再ビルドするよりも効果的です。
<host>/libs/granite/ui/content/dumplibs.rebuild.html