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

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

ドキュメントの構造

ドキュメントを構築する際の最も重要な側面は、コンテンツを投稿する作成者が簡単で直感的に作成できるようにすることです。

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

ドキュメントは、要約の次の構造に従います。

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

デフォルトコンテンツに加えて、ページの概念があります セクション( 横置きのルールまたは --- を使用して、ページの特定の要素をグループ化します。 コンテンツをグループ化するには、セマンティックな理由とデザイン上の理由の両方が考えられます。 単純な例としては、ページの 1 つのセクションの背景色が異なる場合があります。

それに加えて、 ブロック ブロックの種類を識別する最初の行として見出しを持つテーブルとして作成される この概念は、コードをコンポーネント化する最も簡単な方法です。

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

DOM とマークアップの比較

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

で使用される JavaScript ライブラリ scripts.js はマークアップを取り込み、DOM に拡張します。この 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> タグは、デスクトップおよびモバイルデバイスでの表示に必要な様々な解像度と、Web をサポートする最新のブラウザーとサポートしない古いブラウザーでは様々な形式でレンダリングされます。

ブロック

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

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

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

すべてのブロックレベルの CSS は、プロジェクトの他の部分に対する副作用がないように、ブロックにスコープする必要があります。つまり、ブロック内のすべてのセレクターには、対応するブロッククラスのプレフィックスを付けます。 場合によっては、ブロックのラッパーまたは含むセクションをセレクターに使用すると効果的です。

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

プロジェクトの最も重要なガイドラインの 1 つは、作成者が物事をシンプルで直感的に保つことです。 複雑なブロックはコンテンツの作成を困難にするので、開発者は、直感的なオーサリングエクスペリエンスをレイアウトやアプリケーションロジックに必要な DOM に変換する複雑さを吸収することが重要です。 多くの場合、作成者に複雑さを委任したいと思われます。 代わりに、開発者は、作成者用にブロックが作成しにくくなるのを防ぐ必要があります。 作成者は、常に、ブロックをコピー/貼り付けるだけで、その内容を直感的に理解できるはずです。

簡単な例は、 列ブロック. 作成者が作成した各インスタンスの列数に基づいて、JavaScript に追加のクラスを追加します。 これにより、2 列と 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 ブロック。

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

プロジェクトの自動ブロックコードがに存在する buildAutoBlocks() の scripts.js.

次に示す自動ブロックの例を参照してください。