⚙️

【a-blog cms】Twigでコンポーネントをつくってみた

に公開

はじめに

このエントリーは「a-blog cms Advent Calendar 2025」の15日目の記事です!
今回は自身の勉強も兼ねて、Twigでコンポーネントを作って使い回す方法をまとめてみました。

やりたいこと

  • 既存テンプレートから共通パーツを抜き出し、コンポーネント化する
  • 表示したい内容に差があっても、1コンポーネントで対応できるようにする

なぜやろうと思ったか

私はもともとコンポーネント指向の考え方が好きで、a-blog cmsのテーマ開発にも取り入れたいなと考えていました。
a-blog cms v3.2からTwigが導入されたことで、「コンポーネント指向を取り入れるチャンス!」と思い、試してみることにしました。
今回は、はじめからTwig記法で実装されているdevelopテーマをベースにカスタマイズを進めていきます。

a-blog cmsでのTwigの基本的な使い方については、公式ハンズオン記事が大変参考になります!
https://developer.a-blogcms.jp/hands-on/camp2024autumn/twig.html

まずは簡単なコンポーネントをつくってみる

本格的にテンプレートを切り出す前に、まずはTwigでのコンポーネントのつくり方を試してみます。
今回は簡単なリンクボタンコンポーネントをつくってみました。

コンポーネント用テンプレート

include/components/link-button.twig
<a
  href="{{ link.href }}"
  class="inline-block px-6 py-2 text-sm font-semibold text-center text-white transition duration-100 bg-indigo-600 rounded-md outline-none hover:bg-indigo-500 active:bg-indigo-700 ring-blue-300 md:text-base ">
  {{ link.text }}
</a>

スタイル指定には、developテーマにはじめからインストールされているTailwindCSSを使用します。ここでは、お問い合わせページのボタンと同じものを指定しました。
コンポーネントの仕様としては、linkという変数名のオブジェクトを受け取り、hrefをリンク先、textをリンクテキストとして出力できるようにしています。

呼び出し側テンプレート

トップページの記事一覧の下に「お知らせ一覧へ」というリンクボタンを表示するため、以下のように呼び出します。

index.twig(一部抜粋)
<div id="swap-htmx">
  {{ include('/include/htmx/swap-index.html.twig') }}

  {% if VIEW == 'top' %}
  <div class="text-center">
    {{ include('/include/components/link-button.twig', {
      link: {
        href: HOME_URL ~ 'news/',
        text: 'お知らせ一覧へ'
      }
    }) }}
  </div>
  {% endif %}
</div>

テンプレートの呼び出しにはinclude関数を利用し、コンポーネントで出力したいデータを第2引数で渡します。
トップページでのみリンクボタンを表示するために、ifブロックで条件分岐を行いました。

表示は以下のような形になります。

ここまでコンポーネントの基本的なつくり方がわかったので、今度はテンプレートの切り出しを行ってみます。

既存テンプレートの一部をコンポーネント化する

今回は以下のテンプレートのリンク部分を切り出し、共通コンポーネントにします。

  • include/entry/summary-card.twig
    記事一覧で使用されているV2_Entry_Summaryのテンプレート
  • include/entry/tag-relational-card.twig
    記事詳細下部、「関連記事」セクションで使用されているV2_Entry_TagRelationalのテンプレート


エントリー一覧のカード型リンクをコンポーネント化する

コンポーネントの作成

まずは include/entry/summary-card.twig からリンク部分を切り出してコンポーネント化します。

include/components/entry-card.twig
<a href="{{ entry.url }}" class="block w-full text-sm hover:opacity-70">
  {% if entry.mainImage.path %}
    <img
      src="{{ entry.mainImage.path|resizeImg(686, 386) }}"
      width="343"
      height="193"
      alt="{{ entry.mainImage.alt }}"
      loading="lazy"
      decoding="async"
      class="object-cover w-full mb-4 overflow-hidden rounded-md shadow-sm aspect-video"
    />
  {% else %}
    <img
      src="/images/default/noimage.gif"
      width="343"
      height="193"
      alt="画像なし"
      loading="lazy"
      decoding="async"
      class="object-cover w-full mb-4 overflow-hidden rounded-md shadow-sm aspect-video"
    />
  {% endif %}
  <h2 class="mt-3 text-gray-900 text-lg font-bold line-clamp-2">{{ entry.title }}</h2>
  <p class="mt-2 line-clamp-2">
    {{ entry.summary }}
  </p>
  <div class="flex items-center mt-2">
    <p class="text-gray-500">
      <time datetime="{{ entry.datetime|date('Y-m-d') }}">{{ entry.datetime|date('Y年m月d日') }}</time>
    </p>
    {% if entry.isNew %}
      <p class="ml-2 px-2 py-1 rounded-full bg-gray-50 text-gray-900 text-xs">
        NEW
      </p>
    {% endif %}
  </div>
  {% if entry.category.items %}
    <p class="mt-2 text-gray-500 font-bold">
      {{ entry.category.items[0].name }}
    </p>
  {% endif %}
  {% if entry.tags %}
    <ul class="flex flex-wrap gap-x-3 gap-y-1 mt-2 text-gray-500">
      {% for tag in entry.tags %}
        <li>#{{ tag.name }}</li>
      {% endfor %}
    </ul>
  {% endif %}
</a>

コンポーネントの呼び出し

include/entry/summary-card.twig のリンク部分があった場所に、先ほどつくったテンプレートを呼び出します。
V2_Entry_Summaryでは、メイン画像やタイトルなどのデータはentryという変数(プロパティ)に含まれています。これをinclude関数の第2引数でコンポーネントに渡して出力します。

include/entry/summary-card.twig(一部抜粋)
<div class="grid grid-cols-12 pb-10 gap-y-8 gap-x-4 sm:gap-8">
  {% for entry in entrySummary.items %}
    <div class="flex flex-col items-start space-y-3 col-span-12 {{ column_class|default('sm:col-span-6') }}">
      {{ include('/include/components/entry-card.twig', { entry: entry }) }}
    </div>
  {% endfor %}
</div>

出力結果は以下のようになります。抜き出したパーツをそのまま呼び出しているため、見た目に変化はありません。

続いて、include/entry/tag-relational-card.twig のリンク部分も同じように置き換えます。
先ほどと違ってこちらはV2_Entry_TagRelationalモジュールのデータを取り扱いますが、データの構成としてはV2_Entry_Summaryとほぼ同じです。そのため、includeも同じように行います。

include/entry/tag-relational-card.twig(一部抜粋)
<div class="grid grid-cols-1 sm:grid-cols-2 gap-8">
  {% for entry in items %}
    <article>
      {{ include('/include/components/entry-card.twig', { entry: entry }) }}
    </article>
  {% endfor %}
</div>

出力結果は以下のようになります。記事一覧とはフォントサイズなどに少し差異があったのですが、共通化を行ったことで見た目が揃いました。

呼び出し場所によって変数を出し分けたくなったら?

記事一覧では日付を表示したいけれど、関連記事一覧では表示したくない、といったケースはテーマ開発をしているとよく出てきます。

こうした場合、テンプレート側で表示の出し分けを頑張るのではなく、モジュールIDの設定で「どのデータを出すか」を制御し、テンプレート(コンポーネント)側はどんなデータが渡ってきても耐えられる作りにしておくのがよいと考えています。

今回抜き出したリンクカードは、そもそも変数の出力箇所がifブロックでくくられており、この方針に合った実装になっていました。そのため、手を加えずにそのままコンポーネント化することができました。

まとめ:コンポーネント指向の導入は難しくない!

今回developテーマベースでパーツのコンポーネント化を試してみて、想像よりずっと簡単に作業できることがわかりました。
コンポーネント化はメンテナンス性の向上が図れること、デザインシステムとの相性がよくなることなど、メリットが盛り沢山です。
今後、案件などでテーマ開発を進めていく中でも積極的にコンポーネント化を進めていきたいと思います!

Discussion