エントリーのメイン画像

a-blog cms の メイン画像 は、エントリーに紐付く代表画像です。一覧ページのサムネイル、OGP 画像、関連エントリーのサムネイルなど、エントリーを「外」から見せるときの顔として利用されます。

メイン画像の用途

メイン画像を設定しておくと、以下のような場面で自動的に利用されます。

  • Entry_Summary / Entry_GeoList / Entry_TagRelational / Category_EntrySummary / Entry_Body / V2_Entry_Summary / V2_Entry_Body などエントリーモジュールのサムネイル

  • Ogp モジュールが出力する og:image

  • エントリー管理画面の一覧サムネイル

  • 関連エントリー設定 UI のサムネイル

メイン画像の設定方法

メイン画像は次の 3 通りの方法で設定できます。1 エントリーに対して、いずれか一つの方法で指定すれば OK です。

1. カスタムフィールドで指定する（推奨）

もっとも推奨される方法です。テーマのカスタムフィールドに、メディアフィールドを entry_main_image という名前で用意しておきます。

<!-- themes/{テーマ}/admin/entry/field.html など -->
        <div class="js-media-field">
          <div class="js-droparea" data-thumbnail="{entry_main_image@thumbnail}" data-type="image" style="width:200px"></div>
          <p class="js-text acms-admin-text-danger" style="display:none">許可されていないファイルのため挿入できません。</p>
          <div class="acms-admin-margin-top-mini">
            <button type="button" class="js-insert acms-admin-btn" data-type="image">メディアを選択</button>
          </div>
          <input type="hidden" name="entry_main_image" value="{entry_main_image}" class="js-value js-block-editor-set-main-image" />
          <input type="hidden" name="field[]" value="entry_main_image" />
          <input type="hidden" name="entry_main_image:extension" value="media" />
        </div>

エントリー編集画面から本文のユニットとは独立してアイキャッチを管理でき、運用と表示ロジックを一番きれいに分離できます。フィールド名 entry_main_image はエントリー管理画面や関連エントリー設定 UI のサムネイルにも自動で反映されるため、特別な理由がなければこの名前に揃えるのがおすすめです。

メイン画像で利用するフィールド名は private/config.system.yaml で変更可能です。

main_image_field_name: entry_main_image # エントリーのメイン画像のフィールド名を設定します。

ブロックエディターの画像ブロックから設定する

ブロックエディターで追加した画像をメイン画像として設定するには、以下の手順に従ってください。

  1. ブロックエディターで画像ブロックを追加する

  2. 画像ブロックとともに表示されるツールバーから「メイン画像に設定」をクリックします。

  3. 変更を適用するには、「保存」ボタンをクリックしてください。

画像ブロックのツールバーから「メイン画像に設定」をクリックできます。

詳しくはブロックエディターの基本を参照ください。

2. メディアユニットで指定する

エントリー本文のメディアユニットに画像を追加し、ユニット下部の 「メイン画像にする」 ラジオボタンを選択すると、そのユニットの画像がメイン画像になります。

本文中の画像をそのままサムネイルに流用したいときに便利です。Ver. 3.2 以降のメディア管理と統合されており、メディアライブラリからの再利用もしやすい構成です。

3. 画像ユニットで指定する

従来の画像ユニットにも「メイン画像にする」ラジオボタンがあります。既存コンテンツの互換性のために引き続き利用できますが、Ver. 3.2 以降の新規テーマではメディアユニット／カスタムフィールドを優先してください。

テンプレートからの出力

どの方法で設定したメイン画像でも、テンプレートからは同じ記法で出力できます。エントリーモジュールのループ内で path 変数を書くだけです。

<!-- BEGIN_MODULE Entry_Summary -->
<!-- BEGIN entry:loop -->
  <div>
      <!-- BEGIN_IF [{path}/nem] -->
        <img
          src="%{ROOT_DIR}{path}[resizeImg(360)]"
          alt="{alt}"
          class="acms-img-responsive"
          width="{x}"
          height="{y}"
          loading="lazy"
          decoding="async"
        >
      <!-- END_IF -->
  </div>
<!-- END entry:loop -->
<!-- END_MODULE Entry_Summary -->

{% set entrySummary = module('V2_Entry_Summary') %}

<div>
  <div>
    {% for entry in entrySummary.items %}
    <div>
      {% if entry.mainImage.path %}
      <img
        src="{{ entry.mainImage.path|resizeImg(360) }}"
        alt="{{ entry.mainImage.alt }}"
        class="acms-img-responsive"
        width="{{ entry.mainImage.width }}"
        height="{{ entry.mainImage.height}}"
        loading="lazy"
        decoding="async"
      >
      {% endif %}
    </div>
    {% endfor %}
  </div>
</div>

標準テンプレート

Twig テンプレート

説明

{path}

path

通常サイズの画像パス

{imgX} / {imgY}

width / height

通常サイズの幅・高さ

{alt} 

alt

代替テキスト

カスタムフィールド・メディアユニット・画像ユニットのどの方式で設定されていても、同じインターフェースで変数を提供するため、テンプレート側の書き方を使い分ける必要はありません。

モジュールごとに参照元を切り替える

サイト全体としては カスタムフィールド entry_main_image でメイン画像を運用していても、「特定の一覧だけは別のフィールドの画像を使いたい」「エントリー本文ではメイン画像を出したくない」のように、モジュール単位で挙動を変えたい場面があります。

エントリー系モジュール（Entry_Summary、Entry_Body、etc… ）には、表示設定で次の設定が用意されています。

モジュールのメインイメージ設定から、メイン画像データの取得元を「ユニット」か「カスタムフィールド」で切り替えられます
モジュールのメインイメージ設定

  • メインイメージ対象(*_main_image_target) — メイン画像データの取得元を「ユニット」か「カスタムフィールド」で切り替えられます。

  • カスタムフィールド名(*_main_image_field_name) — 「カスタムフィールド」を選んだときに参照するフィールド名

* の部分はモジュールごとに変わります。「カスタムフィールド名」は空のままで構いません。空欄ならサイト全体の既定（main_image_field_name、初期値 entry_main_image）がそのまま使われ、特定モジュールだけ別のフィールドにしたいときだけ値を入れます。V1 / V2 系のモジュールはどちらも同じ設定を共有しているため、V2 に置き換えても設定を作り直す必要はありません。

取得元ごとの優先順位

「ユニット」を選んだ場合は、エントリーで「メイン画像にする」を選んだユニットだけが参照されます。カスタムフィールド側はチェックされません。

「カスタムフィールド」を選んだ場合は、次の順で画像が探されます。

  1. 指定したカスタムフィールドに画像があれば、それを使う

  2. なければ、エントリーで「メイン画像にする」を選んだユニットにフォールバックする

  3. それも無ければメイン画像は未登録として処理

つまり「カスタムフィールド」を選んでおくと、フィールド優先・ユニット予備 という挙動が自動で得られます。新規エントリーはカスタムフィールド方式、過去のエントリーはユニット方式、という移行期の混在運用でもどちらも対応できるようになっています。

関連エントリー編集 UI のサムネイル

エントリー編集画面の「関連エントリー」欄で出る候補画像も、別途カスタムフィールド名を指定できます。「編集画面設定 > 関連記事グループ」 にある 「サムネイル」 設定です。

スタムフィールド名を登録することで任意のメディアフィールドを関連エントリーのサムネイルとして利用することができます。

関連記事グループのサムネイル設定です。カスタムフィールド名を登録することで任意のメディアフィールドを関連エントリーのサムネイルとして利用することができます。
関連記事グループのサムネイル設定

  • サムネイル(既定タイプ: related_entry_first_thumbnail_field )

ここで指定するのは 編集画面の関連エントリー選択 UI に出るサムネイル であって、サイト表示時のメイン画像とは別物です。サイト表示側は前述のモジュール設定によって決められます。

「サムネイル」列を空のままにしておくと、サイト全体の既定（main_image_field_name、初期値 entry_main_image）が使われます。

表示までの優先順位

  1. そのグループの「サムネイル」欄に入れたカスタムフィールドに画像があれば、それを使う

  2. なければ、サイト全体の既定（main_image_field_name）に画像があれば、それを使う

  3. それも無ければ、エントリーで「メイン画像にする」を選んだユニットにフォールバックする

  4. それも無ければ プレースホルダ画像を表示

関連エントリー UI ではカスタムフィールド経由の解決が強制されますが、ユニットへのフォールバックはモジュール設定と同様に効くので、運用方式が混在していても基本的には何かしらサムネイルが表示されます。

イントロダクション

入門

コア概念

フロントエンド開発

機能ガイド

リファレンス

アップデート

拡張・カスタマイズ

ツール