ACF（Advanced Custom Fields）向けにデータをインポートした時のメモ

説明

ACFを採用するサイトにデータをインポートする際、ほとんどのことはwww.advancedcustomfields.comに記載されていたのだが、いくつかわからないことがあった。ここでは、その時に調べたことをメモしておく。

基本はupdate_field関数で

ACFの各フィールドは、WordPress標準の投稿メタ情報（カスタムフィールド）と同じようにpostmetaテーブルに保存され、その「フィールド名」とフィールド名の前に_（アンダースコア）を付けたペアのデータで構成されている。このペアのデータを同時に更新してくれるのが、update_field関数である。

bool update_field( string $selector, mixed $value [ , int $post_id ] )

投稿メタ情報を更新するWordPress標準の関数としては update_post_meta関数がある。

bool update_post_meta( int $post_id, string $meta_key, mixed $meta_value [ , mixed $prev_value = '' ] )

update_field関数とupdate_post_meta関数とでは$post_idパラメータの順番が異なり、update_post_meta関数には第4の$prev_valueパラメータが指定可能な点が異なる。まあupdate_post_meta関数を2度使うより、1度で済むupdate_field関数を使うほうが簡単である。

update_field関数は多くのフィールドタイプに対応している。「セレクト」や「ラジオボタン」の場合は、値を$valueに指定することになる。例えば、対象のフィールドの「選択肢」が、次のようになり、「戻り値の形式」が「値」となっているとしよう。

値1 : ラベル1
値2 : ラベル2

この選択肢の内容は、acf_get_field関数で取得できる連想配列に格納されている。

array(26) {
  ：
  ["choices"]=>array(2) {
    ["値1"]=>"ラベル1"
    ["値2"]=>"ラベル2"
  }
  ["default_value"]=>"値1"
  ：
}

インポートするデータが「ラベル」があり「値」がわからない場合は、array_search( $label, $field['choices'] )でキーを取得すれば登録する「値」がわかる。また、インポートするデータが「値」がわかる場合は、isset( $field['choices'][$value] )で「値」が有効なものか判断できる。

繰り返し（Repeater）はadd_row関数で

ACFには多様なフィールドタイプがあり、その中にはupdate_field関数でデータを更新できないフィールドタイプの1つとして「繰り返し」がある。「繰り返し」はその中にサブフィールドとして任意のフィールドタイプを複数設定することができるようになっており、登録（追加）する場合はadd_row関数を、更新する場合はupdate_row関数を使用する。

使い方として、「繰り返し」のフィールド名が「ギャラリー」、そのサブフィールドにフィールド名が「画像」と「キャプション」だとすると、データを登録するadd_row関数は次のような記述となる。

$row = [
	'画像'         => $attachment_id,
	'キャプション' => $caption
];
add_row( 'ギャラリー', $row, $post_id );

実際にはadd_row関数をループ処理内で呼び出すことになり、その都度サブフィールドのデータが追加される。

柔軟コンテンツ（Flexible Content）もadd_row関数

さてadd_row関数は「繰り返し」のほかに「柔軟コンテンツ」の追加にも対応しているとリファレンスページには記述されているのだが、ページ内の記述ではその方法がわからなかった。具体的には「柔軟コンテンツ」にはレイアウトの名前が存在しており、その指定方法が記載されていない。

指定方法を調べてみると、第2パラメータの連想配列に赤字の1行追加するだけでよかった。

$row = [
	'acf_fc_layout' => 'パターン1',
	'サブタイトル'  => $subtitle,
	'テキスト'      => $text
];
add_row( 'ギャラリー', $row, $post_id );

これくらいならadd_row関数のリファレンスページに使用例として記載してほしいものだ。

繰り返しと柔軟コンテンツの行数

テンプレートで繰り返しや柔軟コンテンツを使用する場合、登録されているかを調べる場合はhave_rows関数で判断できるが、実際にいくつ登録されているか知りたい時がある。リファレンスサイトを探しても数を取得する関数は見つからなかったが、get_field関数を使うと、繰り返しや柔軟コンテンツをまるごと配列で取得でき、その数を調べればいいことがわかった。

$items = get_field( 'ギャラリー', $post_id );
if ( 1 < count( $items ) ) {
	// 複数行の場合の処理
}

行数を取得する関数があってもいいんではなかろうか。