Advanced Custom Fields(ACF)を使いこなそう Vol.2 【コード有】

前回vol.1ではACFのメリットや注意点について書きました。

今回は、ACF v4/5系のインストール〜使い方を抑えていきます。

本体をインストールする

まずはAdvanced Custom Fields (ACF)の本体をダウンロードします。フリー版とPro版があり、フリー版は以下WordPressプラグインから取得することができます。

https://wordpress.org/plugins/advanced-custom-fields/

フリー版では以下機能が利用できません。

・繰り返しフィールド (The Repeater Field)
・ギャラリー (The Gallery Field)
・柔軟コンテンツ (The Flexible Content Field)
・Clone (Clone field)
・オプションページ (Options Pages)

「繰り返し」「柔軟コンテンツ」「オプションページ」の役割については、前回のAdvanced Custom Fields(ACF)を使いこなす Vol.1でも触れました。

またフリー版とPro版では最新のリリースバージョンも異なります。2018年1月時点ではフリー版の最新は4.4.12となり、Pro版は4.6.7となります。

ACF Pro版の場合

Pro版では、以下の2つのライセンスから選ぶことができます。

Personal版では$25（≒2,815円)、Developer版では$100(≒11,261円)となり、いずれも今後半永久的に最新版へのアップデート権限があります。

違いはPersonal版は1サイトのみ、Developer版はサイト制限数なしのみの違いです。支払いについては、Paypal、またはVISAカード、Masterカードなどが利用できます。

決済が完了すると、メールが届くので、ログインID/PWを元にACFの管理画面にログインをします。

すると「Key」がありますのでそれをコピーしておきます。また「Download」から最新のACF Proのzipデータを取得しておきます。

FTP接続を行い、先ほど取得した「advanced-custom-fields-pro.zip」を解凍し、/wp-content/plugins/配下にファイルを設置します。

WordPressの管理画面を開き、ACF Proを有効化します。

カスタムフィールド > アップデートを開き、先ほどの「Key」を適用します。

一度有効化して、ライセンスキーを登録すると、以後は管理画面からACF Proのアップデートを行えるようになります。

以上でインストールは完了となります。

ACFフィールドグループの定義

ACFを利用する上で、まずは管理画面にカスタムフィールドの入力エリアを作る必要があります。その際「どこにどんな要素を定義したいか」を予めワイヤーフレームやデザインを見て決めた上で設計を行います。

ACFで定義するカスタムフィールドは、実に多くの場所で利用することができます。従来であれば「固定ページ」「投稿」「カスタム投稿タイプ」が浮かぶかと思いますが、それ以外にも表示できます。

例えば、で例にすると

・ページテンプレート
・ページタイプが親ページ、または子ページ
・特定のカテゴリー（タクソノミー）
・個別のターム
・特定のユーザー権限先

など実に多くの場所にカスタムフィールドを定義できます。殆どの場合、ACFがあることで困らなくなることと思います。

フィールドグループ

まずはカスタムフィールドの定義から始まります。カスタムフィールドを作成するには、「カスタムフィールド > 新規追加」から行います。

ここで定義する1つのグループのことを、フィールドグループと呼びます。

このブログを例にすると、以下のひとまとまりがフィールドグループとなります。

このように1つのグループ化されたカスタムフィールドがフィールドグループですね。

では「どこまでの単位を1つのフィールドグループとして定義するか？」ですが、再利用しやすい単位にしておくと、後々使いやすいと思います。

この場合、「meta」という要素を規定しており、他の投稿タイプでも参照するいわば1つのまとまったファンクションである、ということでこの単位としています。

そして、このフィールドグループの中では大きく3つのことを定義します。

・どんなフィールド / 名を定義するか
・位置 – そのフィールドグループをどこの投稿/固定に表示するか
・Setting – そのフィールドグループの見た目や設定

それではそれぞれ確認をしていきます。

01. 位置

これはこの定義したフィールドグループを「投稿」または「固定」に表示するとして定義したものです。

とすると、オプションページのcommonという先にそのフィールドグループを表示することができます。

またこれは基本的な使い方ですが、先ほど触れたようにもっと様々な条件でand / or指定をすることができます。

特定の「投稿タイプ」はもちろん、特定の「タクソノミー」やその中の「ターム」の直接指定であったり、「特定のページのみ」や「子を持つ親のページの場合」、「ユーザーの権限で投稿者」といった様々な条件指定をここで行います。

複数箇所に表示できるので、「投稿」でも表示をし「固定ページ」でも表示する、といったこともできます。

ぜひ試してみてください。

02. Setting

Settingでは、フィールドグループの以下項目を設定できます。

03. フィールドの定義

ここがメインですね。フィールドの定義を行う箇所となります。

全て説明をすると膨大になるので省略としますが、フィールドタイプには以下があります。

・テキスト
・テキストエリア
・数値
・Range
・メール
・URL
・パスワード
・画像
・ファイル
・WYSIWYGエディタ
・oEmbed
・ギャラリー (Pro機能)
・Select
・チェックボックス
・ラジオボタン
・Button Group
・真/偽
・Link
・投稿オブジェクト
・ページリンク
・関連
・タクソノミー
・ユーザー
・Googleマップ
・デイトピッカー
・Date Time Picker
・Time Picker
・カラーピッカー
・メッセージ
・Accordion
・タブ
・Group
・繰り返しフィールド (Pro機能)
・柔軟コンテンツ (Pro機能)
・Clone (Pro機能)

2017年12月現在で、35個ものフィールドが用意されています。

まず最初にフィールドグループを選択します。すると下記のようなローディングが表示され、各フィールドグループに応じて呼び出されるフィールドが変わります。

チェックボックスでは以下のようなフィールドが表示され、

「画像」では以下のようなフィールドが表示されます。

共通の項目としては以下のようなものになります。

・フィールドラベル – 管理画面に表示するラベルのことです。
・フィールド名 – ここはテンプレートで利用する名称なので半角英字で定義します。
・説明 – ラベルと一緒に表示される補助テキストのことです。
・必須か – 保存時に必須項目として設定する場合に利用します。
・条件判定 – ラジオボタンやプルダウンメニューなどで分岐表示したい場合に利用します。

フィールドの定義を行うと下記のようになります。

番号が振られていますが、ドラッグをすると並び替えをしたりできます。

ご参考までに、35個もフィールドがあり迷いそうですが、個人的によく使う入力フィールドは下記となります。

基本のフィールド

・テキスト (一行テキストのこと)
・テキストエリア (複数行のテキストのこと)
・画像
・Wysiwygエディタ
・Select (セレクトボックスのこと)
・チェックボックス
・ラジオボタン
・真/偽 (これはTrue/Falseのこと)
・デイトピッカー (カレンダーから日付選択)
・Googleマップ

投稿間の紐づけ

・投稿オブジェクト
・関連

柔軟なレイアウト用途 (要素の内包に利用)

・繰り返しフィールド
・柔軟コンテンツ

管理画面の補助レイアウト用途

・メッセージ (HTMLも利用可)
・タブ (管理画面にタブを生成)

ACFの定義フィールド再利用

・clone

となります。

基本的なACFのテンプレートへの書き方

それではフィールドグループで定義するカスタムフィールドと、テンプレート側に記述する表示をする為のphpコードを見ていきます。

1. テキスト

<?php if(get_field('single_text')): // もし一行テキストがあれば表示 ?>
　<?php the_field('single_text'); ?>
<?php endif;?>

2. テキストエリア

<?php if(get_field('multi_text')): ?>
　<?php the_field('multi_text'); ?>
<?php endif;?>

3. 画像

<?php
	$image = get_field('image'); //フィールド名imageを変数$imageに代入
	$size = 'img240x140'; //WordPressのメディアサイズを指定
?>
<?php if( $image ): //$imageが登録されている場合 ?>
	<?php echo wp_get_attachment_image( $image, $size );?>
	<?php else: //$imageが登録されていない場合 ?>
	<img src="/images/noimage.jpg" alt="">
<?php endif;?>

4. Wysiwygエディタ

<?php if(get_field('wysiwyg')): ?>
　<?php the_field('wysiwyg'); ?>
<?php endif;?>

5. Select

<!--  選択されたセレクトボックスをそのまま表示 -->
<?php the_field('select'); ?>

<!-- 選択によって表示する項目を変更したい場合は以下 -->
<?php if( get_field('select') == 'セレクトA' ): ?>
	<p>セレクトAが選択されています</p>
<?php elseif ( get_field('select') == 'セレクトB'): ?>
	<p>セレクトBが選択されています</p>
<?php elseif ( get_field('select') == 'セレクトC'): ?>
	<p>セレクトCが選択されています</p>
<?php endif; ?>

6. チェックボックス

<?php
// $checksに値を代入
$checks = get_field('checkbox');

// チェックボックスにチェックがある場合、以下を処理
if( $checks ): ?>
<ul>
	<?php foreach( $checks as $check ): ?>
		<li><?php echo $check; ?></li>
	<?php endforeach; ?>
</ul>
<?php endif; ?>

7. ラジオボタン

<!-- 選択されたラジオボタンをそのまま表示 -->
<?php the_field('radio'); ?>

<!-- 選択によって表示する項目を変更したい場合は以下 -->
<?php 
if( get_field('radio') == 'ラジオA' ): ?>
	<p>ラジオAが選択されています</p>
<?php elseif ( get_field('radio') == 'ラジオB'): ?>
	<p>ラジオBが選択されています</p>
<?php elseif ( get_field('radio') == 'ラジオC'): ?>
	<p>ラジオCが選択されています</p>
<?php endif; ?>

8. 真/偽

<?php if( get_field('trueFalse') ): ?>	
	<p>トップへ表示するにチェックが入っています。</p>
<?php else: ?>
	<p>チェックが入っていない場合の処理をします。</p>
<?php endif; ?>

9. デイトピッカー

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

ここまでは基本的なフィールドなので処理もシンプルでした。

繰り返しフィールドの表示

ACF Pro版の機能となりますが、上図のような繰り返しフィールド（Repeater Fields）では要素のネスト構造があるので以下のようになります。

<?php if(have_rows('repeater')):?>
	<ul>
		<?php while(have_rows('repeater')) : the_row();?>
			<li><?php the_sub_field('single_text');?></li>
		<?php endwhile; ?>
	</ul>
<?php endif; ?>

WordPressループと同じですね。もし「repeater」が値を持っていたら、<li>〜</li>の間にある「single_text」を繰り返しする。といったような条件指定となりますね。

先ほどまでは1階層での表示だったので「the_field(‘フィールド名’)」で呼び出しをしましたが、繰り返しフィールドなど多階層として内包する場合は「get_sub_field(‘フィールド名’)」として呼び出しをする必要があります。

柔軟コンテンツの表示

これもACF Pro版の機能とはなりますが、柔軟コンテンツ（Flexible Content Fields）を利用するには、以下のように要素の定義を行います。

<?php if( have_rows('article_set')):
	while ( have_rows('article_set') ) : the_row();?>

	<?php if( get_row_layout() == 'set1' ): //セット1の場合に表示するもの ?>
		<!-- ここに必要なカスタムフィールドを定義 -->
	<?php endif; ?>

	<?php if( get_row_layout() == 'set2' ): //セット2の場合に表示するもの ?>
		<!-- ここに必要なカスタムフィールドを定義 -->
	<?php endif; ?>

	<?php if( get_row_layout() == 'set3' ): //セット3の場合に表示するもの ?>
		<!-- ここに必要なカスタムフィールドを定義 -->
	<?php endif; ?>

	<?php endwhile; ?>
<?php endif; //記事セット終了 ?>

実際に「set1」に「テキスト」、「set2」に「WYSIWYG」、「set3」に「繰り返しフィールド」を入れて見てみましょう。

以下のようになります。

<?php if( have_rows('article_set')):
	while ( have_rows('article_set') ) : the_row();?>

		<?php if( get_row_layout() == 'set1' ): //セット1の場合に表示するもの ?>
			<?php if(get_sub_field('text')): //もしtextがあれば以下を表示?>
				<?php the_sub_field('text'); ?>
			<?php endif; ?>	
		<?php endif; ?>

		<?php if( get_row_layout() == 'set2' ): //セット2の場合に表示するもの ?>
			<?php if (get_sub_field('wysiwyg')): //もしWYSIWYGに登録があれば以下を表示?>
				<?php the_sub_field('wysiwyg');?>
			<?php endif; ?>
		<?php endif; ?>

		<?php if( get_row_layout() == 'set3' ): //セット3の場合に表示するもの ?>
			<?php if(have_rows('repeater')): //繰り返しフィールド?>
		    	<ul>
					<?php while(have_rows('repeater')) : the_row();?>
						<li><?php the_sub_field('text');?></li>
					<?php endwhile; ?>
				</ul>
			<?php endif; ?>
		<?php endif; ?>

	<?php endwhile; ?>
<?php endif; //柔軟コンテンツの終了 ?>

となります。

また今回、その場に要素の定義を行う形で記述しましたが、下記のように記述することで要素の再利用も便利になりますね。

<?php
	$description = '';
	if (get_field('description')){
		$description = get_field('description');
	}
?>
<meta name="description" content="<?php echo $description; ?>">

状況に合わせて使い分けると便利でしょう。

その他、より詳細なドキュメンテーションについては、公式サイトのDocumentaionサンプルコードもあるのでそちらを見るとより詳細なことが分かるかと思います。

最後までお読み頂きありがとうございます！