canvas-content-templates

プロジェクトの種類

このスキルを適用する前に、package.json に @drupal-canvas/headless という名前、または @drupal-canvas/headless- で始まる依存関係があるか確認してください。該当する依存関係がある場合は、Canvas Headless のコードベースです。まず canvas-headless を読んでください。コンテンツテンプレートはヘッドレスのコードベースでも動作しますが、canvas.config.json で sync.contentTemplates が有効になっている場合にのみ作成してください。Canvas Create（@drupal-canvas/create）で生成されたプロジェクトでは、デフォルトで無効になっており、content-templates/ ディレクトリも含まれていません。該当する依存関係がない場合は、Canvas でレンダリングする React のコードベースです。コンポーネントは React（index.jsx／.tsx）であり、このスキルの内容がすべてそのまま適用されます。プロジェクトの種類はこの 2 つのみです。

標準定義

コンテンツテンプレートは、Drupal コンテンツエンティティ（エンティティタイプ、バンドル、表示モードで識別されます）を Canvas コンポーネント要素のツリーにマッピングする JSON ファイルです。コンテンツテンプレートでは、どのエンティティフィールドをどのコンポーネントの props に割り当てるかなど、Canvas コンポーネントを使った Drupal コンテンツのレンダリング方法を定義します。

保存場所と命名規則

設定されたコンテンツテンプレートディレクトリ（canvas.config.json の contentTemplatesDir）にコンテンツテンプレートを作成してください。contentTemplatesDir が設定されていない場合、デフォルトは最上位の content-templates/ ディレクトリです。

命名規則： {entityType}.{bundle}.{viewMode}.json

例：

• <content-templates-dir>/node.article.full.json
• <content-templates-dir>/node.article.teaser.json

コンテンツテンプレートの形式

各コンテンツテンプレートは、次のトップレベルキーを持つ JSON オブジェクトです。

• label（必須）：テンプレートの説明（例： "Article — Full content"）
• entityType（必須）：Drupal のエンティティタイプ（例："node"）
• bundle（必須）：コンテンツタイプ／バンドル（例："article"）
• viewMode（必須）：表示モード（例："full"、"teaser"）
• elements（必須）：要素 ID をキーとするコンポーネント要素のオブジェクト

ファイル名は {entityType}.{bundle}.{viewMode}.json と一致し、ファイル内の値にも対応している必要があります。

要素

elements の構造は Canvas ページ仕様と同じです。例については canvas-page-definition スキルを参照してください。唯一の違いは props の値の型です。コンテンツテンプレートでは、ホスト Drupal エンティティから値を取得する prop ソースもサポートしています（以下で説明します）。

elements の各エントリは要素 ID をキーとし、次の内容を含みます。

• type（必須）：Canvas コンポーネントの型。js. を前置します（例： "js.hero"、"js.card"、"js.section"）
• props（任意）：コンポーネントの props。静的な値またはエンティティフィールド参照を指定できます
• slots（任意）：スロット名をキーとし、同じテンプレート内の要素 ID の配列を値とするマップ

要素 ID

別のソース（エクスポートされた Canvas コンテンツテンプレートなど）の ID を意図的に維持する場合を除き、安定した、説明的な要素 ID を使用してください。

Prop の値の型

props には、次の 3 種類の値を指定できます。

1. 静的な値

文字列、数値、ブール値、またはリッチテキスト用の value と format を持つオブジェクトなど、通常の JSON 値です。

{
  "buttonLabel": "Build your hybrid team",
  "darkVariant": true,
  "description": {
    "value": "Some <em>HTML</em> content here.",
    "format": "canvas_html_block"
  }
}

2. エンティティフィールド参照

Drupal エンティティから取得する動的な値です。sourceType: "entity-field" と expression 文字列を使用します。

{
  "title": {
    "sourceType": "entity-field",
    "expression": "ℹ︎␜entity:node:article␝title␞␟value"
  }
}

3. ホストエンティティの URL

エンティティの正規 URL へのリンクです。sourceType: "host-entity-url" を使用します。

{
  "link": {
    "sourceType": "host-entity-url",
    "absolute": false
  }
}

absolute（任意。デフォルトは true）で URL 形式を指定します。false の場合は相対パス（/node/123）を出力し、true の場合は完全修飾 URL（https://example.com/node/123）を出力します。ページ内リンクには absolute: false を設定してください。正規リンク、フィード、またはサイト外で利用するものには、省略するか true を設定してください。

エンティティフィールド式の構文

式の区切り文字には、特殊な Unicode 制御文字を使用します。

ℹ︎␜entity:{entityType}:{bundle}␝{fieldName}␞␟{property}

文字	名前	目的
ℹ︎	情報	式の開始
␜	ファイル区切り	セグメントの区切り
␝	グループ区切り	エンティティとフィールドの境界
␞	レコード区切り	フィールドとプロパティの境界
␟	単位区切り	プロパティの開始

単純なフィールド式

フィールドから単一のプロパティを取得する場合：

ℹ︎␜entity:node:article␝title␞␟value
ℹ︎␜entity:node:article␝body␞␟processed

画像フィールド式

複数のプロパティが必要な画像フィールドでは、↠（右向き矢印）でソースプロパティを対応付ける、複数プロパティ構文を使用します。

ℹ︎␜entity:node:article␝field_image␞␟{src↠src_with_alternate_widths,alt↠alt,width↠width,height↠height}

{prop↠source,...} 構文では、コンポーネントのプロップキーをエンティティフィールドのプロパティに対応付けます。

エンティティ参照のたどり方

エンティティ参照をたどる場合（例：著者のプロフィール画像）、エンティティセグメントを ␜␜ で連結します。

ℹ︎␜entity:node:article␝uid␞␟entity␜␜entity:user␝user_picture␞␟{src↠src_with_alternate_widths,alt↠alt,width↠width,height↠height}

これは次の順にたどります：node → uid フィールド → 参照先の user エンティティ → user_picture フィールド。

利用可能なプロップソース

プロップソースは、Drupal エンティティフィールドをどのコンポーネントのプロップに対応付けられるかを示します。利用できる場合、エンティティフィールドのマッピングを作成する際の信頼できる情報源となるため、手動で式を組み立てるよりも必ず優先してください。

プロップソースは .agents/drupal-canvas/prop-sources.json に保存され、{entityType} → {bundle} → {js.component} → {propName} → ソースオプションの配列として整理されています。各ソースオプションには、次の項目があります。

• label：フィールドの人が読める説明（例："Title"、"Image"、"Body"）
• source：コンテンツテンプレートでそのまま使用するプロップ値オブジェクト。{ "sourceType": "entity-field", "expression": "..." } または { "sourceType": "host-entity-url", "absolute": false } のいずれかです。

プロップソースの使用方法：

1. 利用可能なバンドルを確認する： 最上位のキーがエンティティタイプを示し、その下にバンドルがネストされています（例：node.article、node.page）
2. コンポーネントを選択する： 各バンドル内の第2階層のキー（例：js.card、js.hero）から、そのバンドルでプロップをマッピングできるコンポーネントがわかります
3. プロップソースを選択する： 各コンポーネントのプロップについて、利用可能なソースの配列を確認し、最も適切なものを選びます。source オブジェクトをコンテンツテンプレートのプロップ値にそのままコピーしてください。一致するソースがある場合は、エンティティフィールド式を手動で組み立てないでください
4. ラベルから最適なソースを選ぶ： プロップに複数のソースがある場合は、label を参考に意味的に正しいものを選びます（例：カードの heading プロップには、"Alternative text" よりも "Title" を選びます）

プロップソースが利用できない場合は、ワークフローのセクションに記載されている鮮度チェックに従い、エージェントのコンテキストを更新してください。一致するソースがない場合に限り、エンティティフィールド式を手動で組み立ててください。

利用可能なビューモード

ビューモードは、接続先の Drupal サイトで有効なエンティティタイプ、バンドル、ビューモードの組み合わせを定義します。これらを使って、作成可能なコンテンツテンプレートと、すでに存在するテンプレートを判断してください。

ビューモードは .agents/drupal-canvas/view-modes.json に保存され、{entityType} → {bundle} → {viewMode} → ラベル文字列として整理されています（例："Full content"、"Teaser"）。

ビューモードの使用方法：

1. 有効な組み合わせを確認する： ここに記載されているエンティティタイプ／バンドル／ビューモードの組み合わせに対してのみ、コンテンツテンプレートを作成します
2. 既存の適用状況を確認する： コンテンツテンプレートのディレクトリを一覧表示し、どの組み合わせにすでにテンプレートがあるかを確認して、重複の作成を避けます
3. ビューモードを選ぶ： ユーザーがビューモードを指定していない場合は、利用可能な選択肢と、まだテンプレートが必要なもの（ローカルファイルを基準とします）を提示し、作業を進める前に確認を求めます

ビューモードが利用できない場合は、ワークフローのセクションに記載されている鮮度チェックに従い、エージェントのコンテキストを更新してください。それでも利用できない場合は、対象とするビューモードをユーザーに尋ねてください。

ワークフロー

新しいコンテンツテンプレートの作成

1. エージェントのコンテキストが最新であることを確認する：
   .agents/drupal-canvas/prop-sources.json と
   .agents/drupal-canvas/view-modes.json が存在するか確認します。どちらかのファイルがない場合、または最終更新から1時間以上経過している場合は、
   npx canvas agents-context content-templates を実行して更新します。ファイルが1時間以内に更新されている場合は、更新を省略します
2. エンティティのマッピングを特定する：
   テンプレートのエンティティタイプ、バンドル、ビューモードを特定します。利用可能なビューモードを確認し、その組み合わせが有効であることを確かめます。ユーザーがビューモードを指定していない場合は、利用可能な選択肢を提示し、作業を進める前にどのビューモードを使うか確認します
3. 既存のテンプレートを確認する：
   設定されているコンテンツテンプレートのディレクトリを一覧表示し、既存の内容を確認します。依頼がない限り、上書きしないでください
4. プロップソースを確認する：
   対象のバンドルで利用可能なプロップソースを読み込み、どのコンポーネントにマッピング可能なプロップがあるかを確認します
5. コンポーネントを選択する：
   レイアウトを構成する src/components/ 内の利用可能なコンポーネントを確認します。各コンポーネントのプロップとスロットを把握するには、component.yml ファイルを参照します。利用可能なプロップソースと照合し、どのプロップをエンティティフィールドにマッピングできるかを確認します
6. 要素 ID を選択する：
   各要素に、安定したわかりやすい ID を使用します
7. テンプレートを作成する：
   上記の形式に従って JSON ファイルを作成します
8. エンティティフィールドをマッピングする：
   可能な場合は、利用可能なプロップソースのソースオブジェクトを使用します。固定コンテンツには静的な値を使用します。一致するソースがない場合に限り、エンティティフィールドの式を手動で作成します

# Check freshness of agents context files and refresh if missing or older than 1 hour.
# Use `date -r <file>` to check file modification time (works on macOS and Linux).
# If stale or missing:
npx canvas agents-context content-templates

# Check available view modes
cat .agents/drupal-canvas/view-modes.json

# Check existing templates (using configured contentTemplatesDir, default: content-templates/)
ls content-templates/

# Read prop sources for the target bundle (prefer jq when available)
jq '.node.article' .agents/drupal-canvas/prop-sources.json

# Check available components
ls src/components/

# Read a component's props to know what to map
cat src/components/hero/component.yml

既存のコンテンツテンプレートの変更

1. エージェントのコンテキストが最新であることを確認する：
   作成ワークフローと同じ方法で最新かどうかを確認します。ファイルがない場合、または最終更新から1時間以上経過している場合は更新し、1時間以内に更新されている場合は省略します
2. **既存のテンプレートを読み込み、**現在の構造を把握します
3. **変更しない要素については、**既存の要素 ID を保持します
4. **新たに追加する要素には、**わかりやすい ID を選びます
5. **スロット参照を検証します：**スロット内のすべての ID が elements に存在することを確認します

検証

作成したすべてのコンテンツテンプレートを、作業を終える前に検証します。

npx canvas validate

ユーザー向けのコミュニケーション

.agents/drupal-canvas/*.json ファイルは、内部エージェントコンテキストです。要約、コミットメッセージ、その他のユーザー向けの出力では、これらのファイルやパス、内容について言及しないでください。マッピングの由来ではなく、何をマッピングしたかを説明します。