マークアップ、セクション、ブロック、自動ブロック

開発者は、web サイトをデザインし、機能を作成するために、コンテンツから動的にレンダリングされるマークアップと DOM を使用します。マークアップと DOM は、柔軟な操作とスタイル設定が可能な方法で構築されています。同時に、標準搭載の機能を提供するので、開発者は最新の web サイトの要素について気にする必要がありません。

ドキュメントの構造

ドキュメントを構築する際の最も重要な側面の 1 つは、コンテンツを提供する作成者にとってドキュメントをシンプルで直感的なものにすることです。

つまり、プロセスの非常に早い段階で作成者を関与させることを強くお勧めします。 多くの場合、作成者は、ブロックやセクションという概念を持たずに、ページに移動する必要があるコンテンツをGoogle ドキュメントまたは Word ドキュメントに配置し、必要な場合にのみ、セクションやブロックを導入して小さな構造変更を加えることをお勧めします。

ドキュメントは、抽象内で次の構造に従います。

Word またはGoogle ドキュメントで作成されたページでは、見出し、本文、リスト、画像、リンクなど、よく理解されたセマンティックモデルが使用されます。 これは、HTML、markdown およびGoogle Doc/Word で共有されます。 これを デフォルトコンテンツ と呼びます。 理想的な状況では、作成者ができるだけ多くのコンテンツをデフォルトのコンテンツのままにしておきます。これは、作成者がドキュメントを扱う自然な方法であるためです。

デフォルトコンテンツに加えて、ページ セクション の概念があり、水平ルールまたは --- で区切られて、ページの特定の要素をグループ化します。 コンテンツをグループ化するには、セマンティック上の理由とデザイン上の理由の両方が必要になる場合があります。 単純なケースとしては、ページの一部の背景色が異なる場合があります。

さらに、blocks という概念があります。これは、ブロックのタイプを識別する最初の行として見出しを持つテーブルとして作成されます。 この概念は、コードをコンポーネント化する最も簡単なアプローチです。

セクションには複数のブロックを含めることができます。 作成者がブロックを使用すると非常に困難になるので、ブロックはネストしないでください。

DOM とマークアップ

AEMは、提供されるコンテンツから、クリーンで読みやすいセマンティックマークアップを生成します。 ソースを表示 機能を使用して簡単にアクセスでき、現在読んでいるページのマークアップを確認できます。

scripts.js で使用されるJavaScript ライブラリは、マークアップを取得して DOM に拡張し、ほとんどの開発タスク（特にブロックの構築）で使用されます。 カスタムプロジェクトコード用に操作しやすい DOM を作成するには、を 2 つの手順から成るプロセスとして表示することをお勧めします。

最初の手順では、セクション、ブロック、これと類似したデフォルトコンテンツでマークアップを作成します。

2 番目の手順では、上記のマークアップを次のサンプル DOM に拡張して、スタイル設定と機能の追加に使用できます。 サーバーから配信されるマークアップと、ほとんどの開発タスクで使用される拡張 DOM の違いを以下に示します。

主に、ブロックとデフォルトコンテンツのラッパー <div> を導入し、AEM ブロックローダーで使用される、有用な CSS クラスとデータ属性を動的に追加する作業で構成されます。

セクション

セクションを使用すると、作成者はデフォルトのコンテンツとブロックをグループ化することができます。 ほとんどの時間セクション区切りは、ページの一部に対して背景色が異なるなど、セクション間の視覚的な違いに基づいて導入されます。

開発の観点からは、通常、CSS スタイル設定以外のセクションとのインタラクションはほとんどありません。
セクションには、セクションにデータ属性を持つ Section Metadata という特殊なブロックを含めることができます。 データ属性の名前は作成者が選択でき、唯一のよく知られているセクションのメタデータプロパティは Style であり、これは、含まれているセクション要素に追加される追加の CSS クラスに変換されます。

作成者がセクション区切りを特別に導入しない場合でも、ブロックとデフォルトコンテンツは常にセクションにラップされます。

デフォルトコンテンツ

Word ドキュメント、Google Docs、Markdown およびHTML間で共有されるセマンティクスは様々です。 例えば、異なるレベルの見出し（例： <h1> ～ <h6>）、画像、リンク、リスト（<ul>、<ol>）、強調（<em>、<strong>）など。

作成者が、使い慣れたツール（例： Word/Google ドキュメント）を Markdown にマッピングし、HTML マークアップでレンダリングします。

すべてのマッピングは、開発者にとって比較的単純で直感的なものにする必要があります。 最も単純な翻訳よりも少し先に進む領域の 1 つは、画像の処理です。 単純な <img> タグの代わりに、完全な <picture> タグが、デスクトップやモバイルデバイスでの表示に必要な様々な解像度や、webp をサポートする最新のブラウザーとそうでない古いブラウザーの様々な形式でレンダリングされます。

ブロック

プロジェクト固有の CSS とJavaScriptのほとんどは、ブロック単位で格納されます。 作成者は、ドキュメント内にブロックを作成し、開発者は、CSS を使用してブロックのスタイルを設定したり、DOM を修飾してブロックのマークアップを取得し、目的のスタイル設定や機能に必要または便利な構造に変換したりする、対応するコードを記述します。

ブロック名は、ブロックのフォルダー名と、ブロックがページで使用されるときにブロックローダーによって読み込まれる CSS およびJavaScript ファイルのファイル名の両方として使用されます。 また、ブロック名はブロックの CSS クラス名としても使用され、スタイルを直感的に設定できます。

JavaScriptはモジュール（ESM）として読み込まれ、ブロック読み込みの一部として実行されるデフォルトの関数を書き出します。

すべてのブロックレベル CSS は、プロジェクトの他の部分に対する副作用がないことを確認するために、ブロックに対してスコープ設定する必要があります。つまり、ブロック内のすべてのセレクターには、対応するブロッククラスのプレフィックスを付ける必要があります。 場合によっては、セレクターにブロックのラッパーまたは格納セクションを使用しても意味があります。

JavaScriptでの DOM 操作と CSS セレクターの複雑さのバランスが取れています。 複雑で脆い CSS セレクターは推奨されませんが、同時にすべての要素にクラスを追加すると、コードがより複雑になり、要素のセマンティクスが無視されます。

プロジェクトの最も重要な考え方の 1 つは、作成者にとって物事をシンプルで直感的に保つことです。 複雑なブロックがあるとコンテンツを作成するのが難しくなるので、開発者は、直感的なオーサリングエクスペリエンスをレイアウトやアプリケーションロジックに必要な DOM に変換する複雑さを吸収することが重要です。 作成者に複雑さをデリゲートしたくなることがよくあります。 代わりに、開発者は、作成者がブロックを作成するのが面倒にならないようにする必要があります。 作成者は、常にブロックを単純にコピー/貼り付けでき、ブロックが何であるかを直感的に理解できる必要があります。

簡単な例として、 列ブロックが挙げられます。 作成者が作成した各インスタンス内の列数に基づいて、JavaScriptにクラスを追加します。 これにより、3 列ではなく 2 列のコンテンツの柔軟なスタイル設定を使用できます。

ブロックは非常に単純にすることも、完全なアプリケーションコンポーネントやウィジェットを含めることもできます。また、開発者がコードベースを小さなコードチャンクにコンポーネント化する方法を提供し、簡単に管理でき、必要に応じて web ページに読み込むことができます。

ブロックのコンテンツは、作成者が入力した行と列のネストされた <div> タグとしてマークアップにレンダリングされます。 最も単純なケースでは、ブロックには 1 つのセルのみが含まれます。

<div class=”blockname”>
  <div>
     <div>
      <p>Hello, World.</p>
     </div>
  </div>
</div>

作成者は、最初の行またはテーブルの見出しにブロック名のあるテーブルを追加するだけで、アドホックな方法でページにブロックを追加できます。 一部のブロックも自動的に読み込まれます。 サイトのすべてのページに存在する必要がある header および footer ブロックは、その良い例です。

ブロックオプション

特定の状況に応じてブロックの外観や動作を少し変える必要があるものの、それ自体が新しいブロックになるほど異なっていない場合、作成者は括弧内のブロックに ブロックオプション を追加できます。 これらのオプションは、変更されたクラスをブロックに追加します。 例えば、テーブルヘッダーの Columns (wide) では、次のマークアップが生成されます。

<div class=”columns wide”>

ブロックオプションには複数の単語を含めることもできます。 例えば、Columns (super wide) はハイフンを使用して連結されます。

<div class=”columns super-wide”>

ブロックオプションがコンマ区切り（Columns (dark, wide) など）の場合は、別のクラスとして追加されます。

<div class=”columns dark wide”>

自動ブロック

理想的なシナリオでは、ドキュメントにテーブルを導入すると読みや編集が困難になるので、コンテンツの大部分がブロックの外部で作成されます。 逆に、ブロックは、開発者がコードを整理しておくための優れたメカニズムを提供します。

両方の長所を生かすために頻繁に使用されるメカニズムは、自動ブロッキング と呼ばれます。 自動ブロックでは、作成者がコンテンツを物理的に作成しなくても、デフォルトのコンテンツとメタデータがブロックに変換されます。 自動ブロックは、ブロックが読み込まれる前のページ装飾プロセスの非常に早い段階で発生します。これは、サーバーからマークアップが取り込まれるように、ブロックの DOM 構造をプログラムによって作成する方法です。

多くの場合、自動ブロックは、メタデータ、特に template プロパティと組み合わせて使用されます。 ページに共通のテンプレートがある（つまり、特定のページデザインや機能を共有している）場合、通常は自動ブロックに適した機会となります。

良い例は、ブログ投稿の記事ヘッダーです。 作成者に関する情報、ブログ投稿のタイトル、ヒーロー画像、公開日が含まれる場合があります。 作成者が、すべての情報を含むブロックを作成する代わりに、自動ブロック（article-header ブロックなど）が、<h1>、最初の画像、ブログ作成者および公開日のメタデータに基づいて、プログラムによってページに追加されます。

これにより、コンテンツ作成者は、自然な場所、つまりブロックの外側のドキュメント構造に情報を保持できます。 同時に、開発者は、すべてのレイアウトとスタイル設定の情報を 1 つのブロックに保持できます。

もう 1 つの非常に一般的なユースケースは、ドキュメント内のリンクをブロックで囲むことです。 例えば、作成者がリンクを含めるだけでYouTube ビデオにリンクする一方、デベロッパーはビデオのすべてのコードを embed ブロックにインライン埋め込みしたままにしたい場合です。

このメカニズムは、外部アプリケーションと、ビデオ、コンテンツフラグメント、モーダル、フォーム、その他のアプリケーション要素への内部参照の両方を含める柔軟な方法としても使用できます。

プロジェクトの自動ブロックのコードは、scripts.js 内の buildAutoBlocks() に存在します。

以下の自動ブロックの例を参照してください。