acf_add_local_field_group() │ ACF 5.7.10

Регистрирует группу полей ACF и добавляет её поля в локальное хранилище.

Группа существует только во время выполнения PHP. Она не сохраняется в базе данных и не отображается для редактирования на странице «Группы полей» ACF.

Регистрация через PHP упрощает перенос настроек между окружениями и уменьшает количество запросов к базе данных. Если требуется только синхронизация групп, можно использовать Local JSON.

Рекомендуется вызывать функцию внутри события acf/include_fields. В этот момент ACF уже загружен, и функция гарантированно доступна.

Каждая группа и каждое поле должны иметь уникальный key. Если группа с таким ключом уже зарегистрирована, функция не заменит её и вернёт false.

Если key не указан, ACF создаст его из title с префиксом group_.

Хуков нет.

Возвращает

boolean.

• true - группа и её поля зарегистрированы.
• false - группа с таким ключом уже существует.

Использование

acf_add_local_field_group( $field_group );

$field_group(array) (обязательный)

Настройки группы полей.

• key(string)
  Уникальный ключ группы. Обычно начинается с group_.

  Если значение не указано, ACF создаст ключ из title.

• title(string)
  Название группы. Отображается в заголовке метабокса.
  По умолчанию: ''

• fields(array)
  Массив полей группы. Настройки каждого поля зависят от его типа.

  Ключ каждого поля должен быть уникальным и обычно начинаться с field_.
  По умолчанию: []

• location(array)
  Правила, определяющие экраны, на которых отображается группа.

  Внешние группы правил объединяются через «ИЛИ». Правила внутри одной группы объединяются через «И».

  Каждое правило содержит:

  • param(string) (обязательный)
    Тип проверяемого условия. Например, post_type, page_template, taxonomy или block.

  • operator(string) (обязательный)
    Оператор сравнения. Обычно == или !=.

  • value(string) (обязательный)
    Значение для сравнения.

• menu_order(int)
  Порядок группы относительно других групп. Меньшие значения отображаются раньше.
  По умолчанию: 0

• position(string)
  Положение группы на экране редактирования.

  Возможные значения: acf_after_title, normal, side.
  По умолчанию: normal

• style(string)
  Стиль метабокса.

  Возможные значения: default, seamless.
  По умолчанию: default

• label_placement(string)
  Положение подписей относительно полей.

  Возможные значения: top, left.
  По умолчанию: top

• instruction_placement(string)
  Положение инструкций поля.

  label выводит инструкцию под подписью. field выводит её под элементом поля.
  По умолчанию: label

• hide_on_screen(array|string)
  Элементы стандартного экрана редактирования, которые нужно скрыть.

  Например: the_content, excerpt, custom_fields, discussion, comments, slug, author, format, page_attributes, featured_image, revisions, categories, tags, send-trackbacks.

• active(bool)
  Включает/отключает группу.
  По умолчанию: true

• description(string)
  Описание группы.
  По умолчанию: ''

• show_in_rest(bool|int)
  Разрешает использовать поля группы через REST API.
  По умолчанию: 0

• local(string)
  Источник локальной группы. Функция автоматически устанавливает php.
  По умолчанию: php

Примеры

#1 Регистрация группы полей для записей

Добавим к обычным записям текстовое поле «Подзаголовок».

add_action( 'acf/include_fields', 'wpkama_register_post_fields' );

function wpkama_register_post_fields() {
	if ( ! function_exists( 'acf_add_local_field_group' ) ) {
		return;
	}

	acf_add_local_field_group(
		[
			'key'    => 'group_post_details',
			'title'  => 'Данные записи',
			'fields' => [
				[
					'key'   => 'field_post_subtitle',
					'label' => 'Подзаголовок',
					'name'  => 'post_subtitle',
					'type'  => 'text',
				],
			],
			'location' => [
				[
					[
						'param'    => 'post_type',
						'operator' => '==',
						'value'    => 'post',
					],
				],
			],
		]
	);
}

#2 Несколько условий отображения

Группа появится только у страниц с шаблоном templates/landing.php.

add_action( 'acf/include_fields', 'wpkama_register_landing_fields' );

function wpkama_register_landing_fields() {
	if ( ! function_exists( 'acf_add_local_field_group' ) ) {
		return;
	}

	acf_add_local_field_group(
		[
			'key'    => 'group_landing',
			'title'  => 'Настройки лендинга',
			'fields' => [
				[
					'key'   => 'field_landing_heading',
					'label' => 'Заголовок',
					'name'  => 'landing_heading',
					'type'  => 'text',
				],
			],
			'location' => [
				[
					[
						'param'    => 'post_type',
						'operator' => '==',
						'value'    => 'page',
					],
					[
						'param'    => 'page_template',
						'operator' => '==',
						'value'    => 'templates/landing.php',
					],
				],
			],
		]
	);
}