typo3-content-blocks

TYPO3 Content Blocks の開発

ソース：https://github.com/dirnbauer/webconsulting-skills

互換性： このスキルは TYPO3 v14.3+ と Content Blocks 2.x を対象としています。Packagist の friendsoftypo3/content-blocks の制約が、常に Core のバージョンと一致するようにしてください。 TYPO3 v13 で Content Blocks 1.x を使用する場合、上流では TYPO3 ≥ 13.4（typo3/cms-core: ^13.4）が必要です。Packagist で確認してください。 例では TYPO3 v14 の API と CB 2.x を使用しています。上流の制約が異なる場合は、composer.json を調整してください。

TYPO3 API を優先： カスタム実装を作成する前に、必ず TYPO3 の組み込み API、Core の機能、確立された規約を使用してください。TYPO3 がすでに提供している機能を再実装しないでください。使用する API とメソッドが存在し、TYPO3 v14 で非推奨になっていないことを、必ず TYPO3 の公式ドキュメントで確認してください。

マイグレーションの対象範囲： Content Blocks のマイグレーションと、スキル間の引き継ぎに関するガイダンスは、このスキルとローカルアドオンに直接記載されています。

1. 単一の信頼できる情報源の原則

Content Blocks は、TYPO3 でカスタムコンテンツタイプを作成するための最新の方法です。以下を生成する単一の YAML 設定を提供し、冗長性を解消します。

• TCA（テーブル設定配列）
• データベーススキーマ（SQL）
• TypoScript によるレンダリング
• バックエンドのフォームとプレビュー
• ラベルと翻訳

Content Blocks を選ぶ理由

従来の方法	Content Blocks の方法
複数の TCA ファイル	1 つの config.yaml
SQL 定義を手動で作成	スキーマを自動生成
TypoScript を個別に作成	レンダリングを自動登録
翻訳が分散	1 つの labels.xlf
複雑なセットアップ	シンプルなフォルダー構造

2. インストール

# Install via Composer (DDEV recommended)
ddev composer require friendsoftypo3/content-blocks

# After installation, clear caches
ddev typo3 cache:flush

バージョン制約： Content Blocks 1.x には TYPO3 ≥ 13.4 が必要です（パッケージ内の typo3/cms-core: ^13.4）。TYPO3 13.1–13.3 は、この Composer の制約を満たしません。

セキュリティ設定（クラシックモード）

Composer を使用しないインストールでは、ContentBlocks フォルダーへの Web アクセスを拒否します。

# .htaccess addition
RewriteRule (?:typo3conf/ext|typo3/sysext|typo3/ext)/[^/]+/(?:Configuration|ContentBlocks|Resources/Private|Tests?|Documentation|docs?)/ - [F]

3. コンテンツタイプの概要

Content Blocks は、次の 4 つのコンテンツタイプをサポートしています。

タイプ	フォルダー	テーブル	用途
ContentElements	ContentBlocks/ContentElements/	tt_content	フロントエンドコンテンツ（ヒーロー、アコーディオン、CTA）
RecordTypes	ContentBlocks/RecordTypes/	カスタム／既存	構造化レコード（ニュース、製品、チーム）
PageTypes	ContentBlocks/PageTypes/	pages	カスタムページタイプ（ブログ、ランディングページ）
FileTypes	ContentBlocks/FileTypes/	sys_file_reference	拡張ファイル参照（撮影者、著作権）

4. フォルダー構造

EXT:my_sitepackage/
└── ContentBlocks/
    ├── ContentElements/
    │   └── my-hero/
    │       ├── assets/
    │       │   └── icon.svg
    │       ├── language/
    │       │   └── labels.xlf
    │       ├── templates/
    │       │   ├── backend-preview.fluid.html
    │       │   ├── frontend.fluid.html
    │       │   └── partials/
    │       └── config.yaml
    ├── RecordTypes/
    │   └── my-record/
    │       ├── assets/
    │       │   └── icon.svg
    │       ├── language/
    │       │   └── labels.xlf
    │       └── config.yaml
    ├── PageTypes/
    │   └── blog-article/
    │       ├── assets/
    │       │   ├── icon.svg
    │       │   ├── icon-hide-in-menu.svg
    │       │   └── icon-root.svg
    │       ├── language/
    │       │   └── labels.xlf
    │       ├── templates/
    │       │   └── backend-preview.fluid.html
    │       └── config.yaml
    └── FileTypes/
        └── image-extended/
            ├── language/
            │   └── labels.xlf
            └── config.yaml

5. コンテンツ要素の作成

キックスタートコマンド（推奨）

# Interactive mode
ddev typo3 make:content-block

# One-liner
ddev typo3 make:content-block \
  --content-type="content-element" \
  --vendor="myvendor" \
  --name="hero-banner" \
  --title="Hero Banner" \
  --extension="my_sitepackage"

# After creation, update database
ddev typo3 cache:flush -g system
ddev typo3 extension:setup --extension=my_sitepackage

定義済みの基本項目（コンテンツ要素）

basics: の下に一覧を記述すると、Core のフィールドグループを取り込めます。TYPO3/Header、TYPO3/Appearance、TYPO3/Links、TYPO3/Categories を指定できます。Content Blocks の基本項目リファレンスを参照してください。

最小限のコンテンツ要素

# EXT:my_sitepackage/ContentBlocks/ContentElements/hero-banner/config.yaml
name: myvendor/hero-banner
fields:
  - identifier: header
    useExistingField: true
  - identifier: bodytext
    useExistingField: true

コンテンツ要素の完全な例

# EXT:my_sitepackage/ContentBlocks/ContentElements/hero-banner/config.yaml
name: myvendor/hero-banner
group: default
description: "A full-width hero banner with image and CTA"
prefixFields: true
prefixType: full
basics:
  - TYPO3/Appearance
  - TYPO3/Links
fields:
  - identifier: header
    useExistingField: true
  - identifier: subheadline
    type: Text
    label: Subheadline
  - identifier: hero_image
    type: File
    minitems: 1
    maxitems: 1
    allowed: common-image-types
  - identifier: cta_link
    type: Link
    label: Call to Action Link
  - identifier: cta_text
    type: Text
    label: Button Text

フロントエンドテンプレート

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:cb="http://typo3.org/ns/TYPO3/CMS/ContentBlocks/ViewHelpers"
      data-namespace-typo3-fluid="true">

<f:asset.css identifier="hero-banner-css" href="{cb:assetPath()}/frontend.css"/>

<section class="hero-banner">
    <f:if condition="{data.hero_image}">
        <f:for each="{data.hero_image}" as="image">
            <f:image image="{image}" alt="{data.header}" class="hero-image"/>
        </f:for>
    </f:if>
    
    <div class="hero-content">
        <h1>{data.header}</h1>
        <f:if condition="{data.subheadline}">
            <p class="subheadline">{data.subheadline}</p>
        </f:if>
        
        <f:if condition="{data.cta_link}">
            <f:link.typolink parameter="{data.cta_link}" class="btn btn-primary">
                {data.cta_text -> f:or(default: 'Learn more')}
            </f:link.typolink>
        </f:if>
    </div>
</section>
</html>

shadcn/ui フロントエンドテンプレートのパターン

コンテンツブロックを shadcn/ui のスタイルに合わせる場合は、コンテンツモデルとしてコンテンツブロックの YAML を維持し、繰り返し使う視覚的な構造を共有 Fluid コンポーネントに移します。frontend.fluid.html エントリーポイントでは、各ブロックで個別の CSS を重複して定義するのではなく、{data} のフィールドを型付きのアトミックコンポーネントに割り当てます。

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:d="http://typo3.org/ns/Vendor/Sitepackage/Components/ComponentCollection"
      data-namespace-typo3-fluid="true">

<section class="py-12 md:py-16">
    <d:molecule.card class="mx-auto max-w-2xl">
        <d:molecule.cardHeader>
            <d:molecule.cardTitle>{data.header}</d:molecule.cardTitle>
            <f:if condition="{data.subheadline}">
                <d:molecule.cardDescription>{data.subheadline}</d:molecule.cardDescription>
            </f:if>
        </d:molecule.cardHeader>
        <d:molecule.cardContent>
            <f:format.html>{data.bodytext}</f:format.html>
        </d:molecule.cardContent>
    </d:molecule.card>
</section>
</html>

ガイドライン：

• コンテンツモデル自体を変更する場合を除き、既存のフィールド識別子、fixture.json、ラベル、エディターワークフローを維持します。
• Button、Badge、Card、Form コントロール、Tabs、Accordion、Alert、Table、Sheet/Dialog シェルなどの shadcn プリミティブには、共有 Fluid コンポーネントを使用します。
• 再利用可能な Fluid コンポーネントやパーシャルには、<f:argument> の型コントラクトを指定します。レンダーコンテキストが完全に制御されていない限り、コンテンツブロックのエントリーテンプレートに必須引数を追加しないでください。
• ブロック固有のアセットに限り、f:asset.css / f:asset.script を使用します。共有の shadcn/Tailwind トークンとユーティリティクラスは、サイトの CSS エントリーポイントに配置します。
• インタラクティブな shadcn パターンには、React/Radix のランタイム依存関係ではなく、ARIA 属性と data-state 属性を使った Alpine または小規模な Vanilla JS コントローラーを使用します。
• ライトモードとダークモードの両方で、現実的なコンテンツを使って各コンテンツブロックをレンダリングできるよう、スタイルガイドのフィクスチャを作成または更新します。

バックエンドプレビューテンプレート

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:be="http://typo3.org/ns/TYPO3/CMS/Backend/ViewHelpers"
      data-namespace-typo3-fluid="true">

<div class="content-block-preview">
    <strong>{data.header}</strong>
    <f:if condition="{data.subheadline}">
        <br/><em>{data.subheadline}</em>
    </f:if>
    <f:if condition="{data.hero_image}">
        <f:for each="{data.hero_image}" as="image">
            <be:thumbnail image="{image}" width="100" height="100"/>
        </f:for>
    </f:if>
</div>
</html>

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティングのマトリックス、付録、または上記に含まれていないセクションが必要な場合は、完全版ガイドを参照してください。作業範囲が限定されている場合は、このファイルを読み込まず、スキルが段階的開示に従うようにしてください。