【WordPress】Advanced Custom Fields（ACF）を出力する方法

Advanced Custom Fields（ACF）は、ブログ記事や商品ページなど、特定の情報を入力する必要があるときに便利なプラグインです。
基本的な使い方はこちらでご紹介したので、今回はACFの出力方法をご紹介します。

ACFの専用関数とは

Advanced Custom Fields（ACF）の公式ドキュメント（ACF Documentation（英語））に書かれているBasic Functionは、カスタムフィールドで入力されたデータを取得し、WordPressのテーマやプラグイン内で使用するための基本的な関数群です。ACFの関数には、次のようなものがあります。

1. get_field(): 特定のカスタムフィールドの値を取得します。この関数は、カスタムフィールドの名前を引数として受け取り、そのフィールドの値を返します。各フィールド・タイプは異なる形式のデータ（文字列、配列など）を返すことに注意してください。

   <?php $value = get_field('field_name'); ?>

2. the_field(): この関数は、get_field()と同様に特定のカスタムフィールドの値を取得しますが、その値を直接出力します。

   <?php the_field('field_name'); ?>

3. have_rows() / the_row() / rewind_rows()（プロ版のみ）: リピーターフィールド内の行をループ処理するための関数群です。have_rows()はループの繰り返し条件、the_row()はループ内で行を処理するための関数、rewind_rows()はループのリセットを行います。

   <?php
       if (have_rows('repeater_field_name')) {
           while (have_rows('repeater_field_name')) {
               the_row();
               the_sub_field('sub_field_name');
           }
       }
   ?>

4. get_sub_field()（プロ版のみ）: the_sub_field()と同様に動作しますが、値を返す代わりに返り値を返します。ループ内で使用します。

   <?php $value = get_sub_field('sub_field_name'); ?>

これらの関数をテーマファイルなどに使用することでACFで作成したカスタムフィールドの値を取得し、WordPressのテーマやプラグインで柔軟に使用することができます。

基本的な出力方法

上記コードから、無料版のACFで頻繁に使うget_field()/the_field()を詳しくご説明します。

get_field()関数

get_field() 関数を使用すると、指定したフィールドの値を取得できます。この関数はテキストやチェックボックスなど、全てのフィールドタイプで利用可能ですが、前述のとおり、各フィールド・タイプは異なる形式のデータ（文字列、配列など）を返すことに注意してください。

<?php get_field($field_name, [$post_id], [$format_value]); ?>

パラメーター

1. $field_name (必須): カスタムフィールドの名前、またはキーを指定します。このパラメーターには、カスタムフィールドの名前（ラベル）またはキー（フィールド識別子）を指定します。
2. $post_id (オプション): カスタムフィールドの値を取得する投稿/ページのIDを指定します。デフォルトは現在の投稿/ページのIDです。
   例えば、トップページのメインビジュアルをクライアントが編集できるようにする際に使います。
3. $format_value (オプション): フィールドの値のフォーマットを指定します。デフォルトは true です。
   フォーマットが有効な場合、返される値は ACF フィールドタイプに基づいて自動的にフォーマットされます。例えば、日付フィールドの値は、日付の形式で返されます。
   一方で、このパラメーターを false に設定すると、フォーマットされていない生の値が返されます。つまり、フィールドの値がそのまま出力され、返される値は文字列や配列の形式になります。この場合、取得した値を任意の方法でフォーマットする必要があります。
   例えば、日付フィールドの値が “2024-02-06” の場合、フォーマットを有効にすると “February 6, 2024” のようにフォーマットされ、フォーマットを無効にすると “2024-02-06” のままの値が返されます。
   このパラメーターを使うことで、カスタムフィールドの値を必要な形式で取得できるようになります。

戻り値

カスタムフィールドの値が返されます。指定されたフィールド名に対応する値が存在しない場合は、false が返されます。

使用例

<?php 
    // 現在の投稿のフィールド名 'field_name' の値を取得する
    $field_value = get_field('field_name');

    // 特定の投稿（ID: 123）のフィールド名 'field_name' の値を取得する
    $specific_field_value = get_field('field_name', 123);

    // フォーマットを無効にしてカスタムフィールド 'date' の生の値を取得する
    $format_disabled_date = get_field('date', null, false);
?>

これらは「変数に取得した値を代入する」ところまでを行っているため、「値を出力する」には別途下記のコードが必要です。

<?php 
    echo esc_html($field_value);
    echo esc_html($specific_field_value);
    echo esc_html($format_disabled_date);
?>

the_field()関数

the_field() 関数は、Advanced Custom Fields（ACF）プラグインで設定されたカスタムフィールドの値を出力するために使用されます。
値を出力する以外はget_field()と同じです。

<?php the_field( $field_name, $post_id, $format_value ); ?>

上記コードはechoを使用していませんが、これだけで値が出力されます。
パラメーターの説明はget_field()関数のものと同じです。

使用例

<?php 
    // カスタムフィールドの値をそのまま出力する
    the_field('field_name');

    // 特定の投稿（ID: 123）のフィールド名 'field_name' の値を出力する
    the_field('field_name', 123); // 123 は投稿のID

    // フォーマットを無効にしてカスタムフィールド 'date' の生の値を出力する
    the_field('date', null, false);
?>

フィールドグループの出力方法

フィールドタイプとしてグループを選択すると、上記の基本の書き方だけでは表示することができません。
例として、

• フィールドタイプ：グループ
• フィールドラベル：商品
• フィールド名：product_item
  • サブフィールド：ブランド名（brand）
  • サブフィールド：商品名（product）
  • サブフィールド：価格（price）

という項目を作成します。
これを表示する際は、下記のようなコードが必要です。

<?php
// $product_infoに「商品」グループフィールドの値を格納
$product_info = get_field('product_item');

if ($product_info) : ?>
    <p>ブランド名: <?php echo esc_html($product_info['brand']); ?></p>
    <p>商品名: <?php echo esc_html($product_info['product']); ?></p>
    <p>価格: <?php echo esc_html($product_info['price']); ?>円</p>
<?php endif; ?>

変数（今回は$product_info）にグループフィールド（今回はproduct_item）のデータをまとめて格納してしまった方が毎回get_field()するよりもパフォーマンスへの影響が少ないため、グループフィールドを出力する際はこのやり方がおすすめです。

さて、フィールドグループのメリットは、複数の関連するフィールドを一つのグループにまとめて管理できることです。
例えば、その商品のブランド名、商品名、価格、必要ならば写真など、複数のデータポイントを含む情報をグループ化することで、管理が簡単になります。これにより、データの一貫性が保たれ、エンドユーザーに対して整理された形で情報を提供できます。

画像の出力方法

ACFの画像フィールドを設定する際には、「戻り値の形式」を選択する必要があります。この設定は、テンプレートファイル内で画像を表示する方法に直接影響します。以下では、「画像オブジェクト」、「画像URL」、「画像ID」の3つの戻り値の形式について、それぞれの特徴と具体的な使用例を紹介します。

「画像オブジェクト」の場合

この形式を選択すると、画像に関する様々な情報（URL、タイトル、キャプション、サイズなど）を含む配列（オブジェクト）が返されます。これにより、画像自体だけでなく、画像に関連する詳細情報にも簡単にアクセスできるようになります。

<?php $image = get_field('画像フィールドの名前');
if( !empty($image) ): ?>
    <img src="<?php echo esc_url($image['url']); ?>" alt="<?php echo esc_attr($image['alt']); ?>" />
    <p><?php echo esc_html($image['caption']); ?></p>
<?php endif; ?>

「画像URL」の場合

このオプションを選択すると、選択された画像のURLのみが返されます。画像を表示するだけの場合は、この形式が最もシンプルで直接的な方法です。

<?php $image_url = get_field('画像フィールドの名前');
if( !empty($image_url) ): ?>
    <img src="<?php echo esc_url($image_url); ?>" alt="画像の説明" />
<?php endif; ?>

「画像ID」の場合

この形式を選ぶと、画像の投稿IDが返されます。このIDを使用して、WordPressの wp_get_attachment_image() や他の関数を用いて、さらに柔軟に画像を取り扱うことが可能です。例えば、異なるサイズの画像を動的に表示したい場合に便利です。

<?php $image_id = get_field('画像フィールドの名前');
if( !empty($image_id) ): ?>
    <?php echo wp_get_attachment_image( $image_id, 'full' ); ?>
    <!-- 'full'は画像のサイズを示し、他に'thumbnail', 'medium', 'large'などを指定できます -->
<?php endif; ?>

まとめ

Advanced Custom Fieldsを使用すると、WordPressサイトにカスタムフィールドを簡単に追加し、よりダイナミックなコンテンツ管理が可能になります。
上記の方法を活用して、自分のサイトにカスタムフィールドに入力したデータを追加してみてください。