新しいブロックの作成
この章では、ユニバーサルエディターを使用して、Edge Delivery Services web サイト用の新しい編集できるティーザーブロックを作成するプロセスについて説明します。
teaser という名前のブロックでは、次の要素を示します。
-
画像：視覚的に魅力的な画像。
-
テキストコンテンツ：
- タイトル：注目を集める説得力のある見出し。
- 本文：オプションの利用条件を含む、コンテキストや詳細を提供する説明的なコンテンツ。
- コールトゥアクション（CTA）ボタン：ユーザーのインタラクションを促し、さらなるエンゲージメントを促すように設計されたリンク。
teaser ブロックのコンテンツはユニバーサルエディターで編集できるので、web サイト全体での使いやすさと再利用性が確保されます。
teaser ブロックはボイラープレートの hero ブロックに似ています。したがって、teaser ブロックは開発の概念を説明する簡単な例としてのみ使用されることを目的としています。
新しい Git 分岐の作成
クリーンで組織化されたワークフローを維持するには、特定の開発タスクごとに新しい分岐を作成します。これにより、不完全なコードやテストされていないコードを実稼動環境にデプロイする際に発生する問題を回避できます。
- メイン分岐から開始：最新の実稼動コードから作業することで、強固な基盤が確保されます。
- リモート変更を取得：GitHub から最新の更新を取得すると、開発を開始する前に最新のコードが使用できます。
- 例：
wknd-styles分岐からの変更をmainに結合した後、最新の更新を取得します。
- 例：
- 新しい分岐を作成：
# ~/Code/aem-wknd-eds-ue
$ git fetch origin
$ git checkout -b teaser origin/main
teaser 分岐を作成すると、ティーザーブロックの開発を開始する準備が整います。
ブロックのフォルダー
プロジェクトの blocks ディレクトリに teaser という名前の新しいフォルダーを作成します。このフォルダーには、ブロックの JSON、CSS、JavaScript ファイルが含まれており、ブロックのファイルが 1 つの場所に整理されます。
# ~/Code/aem-wknd-eds-ue
/blocks/teaser
ブロックフォルダー名は、ブロックの ID として機能し、開発全体を通じてブロックを参照するのに使用されます。
ブロックの JSON
ブロックの JSON は、ブロックの次の 3 つの主要な側面を定義します。
- 定義：ブロックをユニバーサルエディターで編集できるコンポーネントとして登録し、ブロックモデルおよびオプションでフィルターにリンクします。
- モデル：ブロックのオーサリングフィールドと、これらのフィールドがセマンティック Edge Delivery Services HTML としてレンダリングされる方法を指定します。
- フィルター：ユニバーサルエディター経由でブロックを追加できるコンテナを制限するフィルタリングルールを設定します。ほとんどのブロックはコンテナではありませんが、その ID は他のコンテナブロックのフィルターに追加されます。
次の初期構造を正確な順序で使用して、/blocks/teaser/_teaser.json に新しいファイルを作成します。キーの順序が正しくない場合、正しく作成されない場合があります。
[/blocks/teaser/_teaser.json]{class="badge neutral" title="以下のコードサンプルのファイル名。"}
{
"definitions": [],
"models": [],
"filters": []
}
ブロックモデル
ブロックモデルは、以下を定義するので、ブロックの設定の重要な部分です。
-
編集できるフィールドを定義することによるオーサリングエクスペリエンス。
-
フィールドの値を Edge Delivery Services HTML にレンダリングする方法。
モデルには、ブロックの定義に対応する id が割り当てられ、編集できるフィールドを指定する fields 配列が含まれます。
fields 配列の各フィールドには、次の必須プロパティを含む JSON オブジェクトがあります。
componentnamelabelオプションを含むプロパティの包括的なリストについて詳しくは、ユニバーサルエディターのフィールドのドキュメントを参照してください。
ブロックデザイン
ティーザーブロックには、次の編集できる要素が含まれます。
-
画像：ティーザーの視覚的なコンテンツを表します。
-
テキストコンテンツ：タイトル、本文、コールトゥアクションボタンが含まれ、白色の長方形内に配置されます。
- タイトル と 本文 は、同じリッチテキストエディターを使用して作成できます。
- CTA は、ラベル の「
text」フィールドと リンク の「aem-content」フィールドを使用して作成できます。
ティーザーブロックのデザインは、これら 2 つの論理コンポーネント（画像とテキストコンテンツ）に分割され、構造化された直感的なオーサリングエクスペリエンスをユーザーに提供します。
ブロックのフィールド
ブロックに必要なフィールド（画像、画像の代替テキスト、テキスト、CTA ラベル、CTA リンク）を定義します。
このタブでは、ティーザーブロックをモデル化する正しい方法について説明します。
ティーザーは、画像とテキストという 2 つの論理領域で構成されます。Edge Delivery Services HTML を目的の web エクスペリエンスとして表示するのに必要なコードを簡素化するには、ブロックモデルでこの構造を反映する必要があります。
- フィールドの折りたたみを使用して、画像 と 画像の代替テキスト をグループ化します。
- 要素のグループ化と CTA のフィールドの折りたたみを使用して、テキストコンテンツフィールドをグループ化します。
フィールドの折りたたみ、要素のグループ化、または型推論に慣れていない場合は、適切に構造化されたブロックモデルを作成するのに不可欠であるので、続行する前にリンクされているドキュメントを確認します。
以下に例を示します。
- 型推論は、「
image」フィールドから<img>HTML 要素を自動的に作成するのに使用されます。フィールドの折りたたみは、「image」フィールドと「imageAlt」フィールドで使用され、<img>HTML 要素を作成します。src属性は「image」フィールドの値に設定され、alt属性は「imageAlt」フィールドの値に設定されます。 textContentは、フィールドを分類するのに使用されるグループ名です。セマンティックにする必要がありますが、このブロックに固有のものであれば何でも構いません。これにより、ユニバーサルエディターに、このプレフィックスを持つすべてのフィールドを最終的な HTML 出力の同じ<div>要素内にレンダリングするように通知されます。- フィールドの折りたたみは、コールトゥアクション（CTA）の
textContentグループ内でも適用されます。CTA は、型推論を通じて<a>として作成されます。「cta」フィールドは<a>要素のhref属性を設定するのに使用され、「ctaText」フィールドは<a ...>タグ内のリンクのテキストコンテンツを提供します。
[/blocks/teaser/_teaser.json]{class="badge neutral" title="以下のコードサンプルのファイル名。"}
| code language-json |
|---|
|
このモデルは、ブロックのユニバーサルエディターでのオーサリング入力を定義します。
このブロックの結果として得られる Edge Delivery Services HTML では、最初の div に画像が配置され、2 番目の div に要素グループの「textContent」フィールドが配置されます。
| code language-html |
|---|
|
次の章で説明するように、この HTML 構造により、ブロックをまとまりのある単位としてスタイル設定することが簡素化されます。
フィールドの折りたたみと要素のグループ化を使用しない場合の結果を理解するには、上記の「間違った方法」タブを参照してください。
このタブでは、ティーザーブロックをモデル化する次善策としての方法について説明しますが、正しい方法との比較にすぎません。
フィールドの折りたたみや要素のグループ化を使用せずに、各フィールドをブロックモデル内のスタンドアロンフィールドとして定義することは魅力的に思える場合があります。ただし、この見落としにより、ブロックをまとまりのある単位としてスタイル設定することが複雑になります。
例えば、ティーザーモデルは、フィールドの折りたたみや要素のグループ化を 行わず に次のように定義できます。
[/blocks/teaser/_teaser.json]{class="badge neutral" title="以下のコードサンプルのファイル名。"}
| code language-json |
|---|
|
ブロックの Edge Delivery Services HTML では、各フィールドの値を個別の div にレンダリングするので、目的のデザインを実現するコンテンツの理解、スタイルの適用、HTML 構造の調整が複雑になります。
| code language-html |
|---|
|
各フィールドは独自の div に分離されているので、画像とテキストコンテンツをまとまりのある単位としてスタイル設定することが困難です。労力と創造性で目的のデザインを実現することは可能ですが、要素のグループ化を使用してテキストコンテンツフィールドをグループ化し、フィールドの折りたたみを使用して、作成された値を要素属性として追加する方が、よりシンプルで簡単であり、セマンティクス的にも適切です。
ティーザーブロックをより適切にモデル化する方法について詳しくは、上記の「正しい方法」タブを参照してください。
ブロックの定義
ブロックの定義では、ユニバーサルエディターにブロックを登録します。ブロックの定義で使用される JSON プロパティの分類を以下に示します。
definition.titledefinition.idfilters での使用を制御するのに使用される、ブロックの一意の ID。definition.plugins.xwalk.page.resourceTypecore/franklin/components/block/v#/block リソースタイプを使用します。definition.plugins.xwalk.page.template.namedefinition.plugins.xwalk.page.template.modelmodel 定義にこの定義をリンクします。ここの値は、model.id 値と一致する必要があります。definition.plugins.xwalk.page.template.classesclass 属性に追加される、オプションのプロパティ。これにより、同じブロックのバリアントが可能になります。ブロックのモデルにクラスフィールドを追加して、classes 値を編集可能にすることができます。ブロック定義の JSON の例を次に示します。
[/blocks/teaser/_teaser.json]{class="badge neutral" title="以下のコードサンプルのファイル名。"}
{
"definitions": [{
"title": "Teaser",
"id": "teaser",
"plugins": {
"xwalk": {
"page": {
"resourceType": "core/franklin/components/block/v1/block",
"template": {
"name": "Teaser",
"model": "teaser",
"textContent_text": "<h2>Enter a title</h2><p>...and body text here!</p>",
"textContent_cta": "/",
"textContent_ctaText": "Click me!"
}
}
}
}
}],
"models": [... from previous section ...],
"filters": []
}
この例では、次のようになります。
- このブロックの名前は「ティーザー」で、ユニバーサルエディターで編集できるフィールドを決定する
teaserモデルを使用します。 - ブロックには、タイトルと本文のリッチテキスト領域である「
textContent_text」フィールドのデフォルトコンテンツと、CTA（コールトゥアクション）リンクとラベルのtextContent_ctaとtextContent_ctaTextが含まれます。初期コンテンツを含むテンプレートのフィールド名は、コンテンツモデルのフィールド配列で定義されたフィールド名と一致します。
この構造により、レンダリング用の適切なフィールド、コンテンツモデル、リソースタイプを使用して、ブロックがユニバーサルエディターで設定されます。
ブロックのフィルター
ブロックの filters 配列は、コンテナブロックの場合、コンテナに追加できる他のブロックを定義します。フィルターは、コンテナに追加できるブロック ID（model.id）のリストを定義します。
[/blocks/teaser/_teaser.json]{class="badge neutral" title="以下のコードサンプルのファイル名。"}
{
"definitions": [... populated from previous section ...],
"models": [... populated from previous section ...],
"filters": []
}
ティーザーコンポーネントはコンテナブロックではないので、他のブロックを追加できません。その結果、filters 配列は空のままになります。代わりに、ティーザーの ID をセクションブロックのフィルターリストに追加して、ティーザーをセクションに追加できるようにします。
アドビが提供するブロック（セクションブロックなど）は、プロジェクトの models フォルダーにフィルターを保存します。調整するには、アドビが提供するブロックの JSON ファイル（/models/_section.json など）を見つけて、ティーザーの ID（teaser）をフィルターリストに追加します。この設定により、ティーザーコンポーネントをセクションコンテナブロックに追加できることがユニバーサルエディターに通知されます。
[/models/_section.json]{class="badge neutral" title="以下のコードサンプルのファイル名。"}
{
"definitions": [],
"models": [],
"filters": [
{
"id": "section",
"components": [
"text",
"image",
"button",
"title",
"hero",
"cards",
"columns",
"fragment",
"teaser"
]
}
]
}
teaser のティーザーブロック定義 ID が components 配列に追加されます。
JSON ファイルのリント
変更がクリーンで一貫性のあることを確認するには、頻繁にリントします。頻繁にリンティングを行うと、問題を早期に発見し、全体的な開発時間を短縮できます。npm run lint:js コマンドも JSON ファイルをリントし、構文エラーを検出します。
# ~/Code/aem-wknd-eds-ue
$ npm run lint:js
プロジェクトの JSON のビルド
ブロックの JSON ファイル（blocks/teaser/_teaser.json、models/_section.json など）を設定したら、プロジェクトの component-models.json、component-definitions.json、component-filters.json ファイルに自動的にコンパイルされます。このコンパイルは、AEM ボイラープレート XWalk プロジェクトテンプレートに含まれる Husky pre-commit フックによって自動的に処理されます。
また、プロジェクトのビルド JSON NPM スクリプトを使用して、ビルドを手動またはプログラムでトリガーすることもできます。
ブロック JSON のデプロイ
ユニバーサルエディターでブロックを使用できるようにするには、プロジェクトをコミットして GitHub リポジトリの分岐（この場合は、teaser 分岐）にプッシュする必要があります。
ユニバーサルエディターが使用する正確な分岐名は、ユニバーサルエディターの URL を通じてユーザー別に調整できます。
# ~/Code/aem-wknd-eds-ue
$ git add .
$ git commit -m "Add teaser block JSON files so it is available in Universal Editor"
# JSON files are compiled automatically and added to the commit via a husky precommit hook
$ git push origin teaser
クエリパラメーター ?ref=teaser を使用してユニバーサルエディターを開くと、新しい teaser ブロックがブロックパレットに表示されます。ブロックにはスタイル設定がないので、ブロックのフィールドはセマンティック HTML としてレンダリングされ、グローバル CSS を通じてのみスタイル設定されます。