Плагин Advanced Custom Fields (ACF) поддерживает полную настройку полей и групп с помощью кода PHP в вашей теме или плагине. Преимущество этого заключается в том, что все ваши поля будут доступны независимо от экземпляра WordPress, над которым вы работаете (например, если вам нужно переключаться между локальным, тестовым сервером и рабочим сервером). Вы можете настроить все поля в панели администратора ACF и использовать инструмент экспорта для экспорта в PHP.

Однако, если вы делаете это часто, вы можете заметить, что экспорт PHP ACF содержит много кода, что делает ваши файлы PHP ненужными. В некоторых случаях лучше написать код самостоятельно, с минимальным необходимым минимумом, чтобы код был чище в вашей теме или плагине. Это руководство призвано предоставить вам полную информацию о том, как вручную записывать добавление полей и групп ACF в PHP. Обратите внимание, что здесь не будет подробно описываться каждый тип поля, поскольку предполагается, что вы уже знакомы с различными полями, возможными в ACF.

Но сначала; некоторые меры предосторожности

Чтобы поддерживать хорошие стандарты кода и гарантировать, что ваш сайт WordPress не выйдет из строя, вы всегда должны проверять, действительно ли существуют функции или классы, которые использует ваш код. Особенно, когда речь идет о плагинах, которые можно легко деактивировать или даже не устанавливать на сайт, вы всегда должны оборачивать свой код плагина в if-test, который проверяет, существуют ли используемые вами функции, прежде чем вы их используете.

Что касается ACF, вы можете сделать это, проверив, существует ли класс 'acf'или существует ли функция добавления полей и групп, 'acf_add_local_field_group'. Оберните любой из них вокруг приведенного ниже кода.


if (function_exists('acf_add_local_field_group')) {
    // Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
    // Your ACF specific code here
}

Скелетный код

Для добавления метабоксов (групп) и полей мы используем хук с именем acf/init. Внутри функции мы вызываем функцию acf_add_local_field_group()с массивом в качестве параметра. Внутри этого массива находится полная настройка группы и всех ее полей. Наиболее важными из них являются ключи массива 'fields'и 'location'. Для ключа массива 'fields'вы предоставляете массив для всех полей, а для ключа 'location'вы предоставляете настройки того, где должен отображаться метабокс. В этом посте подробно рассказывается о том, какие возможные варианты у вас есть для каждого из приведенных ниже.

Это минимум добавления группы, кроме полей и местоположения:

Каждой группе нужен уникальный ключ, но само фактическое имя не имеет большого значения (для нас). Если вы добавляете больше групп, не забудьте изменить 'key'поле. Заголовок метабокса можно задать в ключевом элементе массива, как вы уже догадались, 'title'. Если вы добавляете несколько метабоксов в одно и то же место (например, при редактировании постов), вы можете указать, какие из них будут первыми, указав разные номера в файлах 'menu_order'.

Вы можете управлять дизайном метабокса, предоставив любой из них в defaultформате. Однако с новым редактором Gutenberg это имеет гораздо меньшее значение. То же самое касается ключа, где в старые времена вы могли разместить метабокс под содержимым поста (), сбоку () или сразу после заголовка поста ().seamless``'style'``'position'``'normal'``'side'``'acf_after_title'

Хорошо! Давайте углубимся в два более интересных элемента массива; начиная с местоположения — это определяет, где появляется метабокс.

Расположение

Это все о том, что вы вкладываете в ключ 'location'. Но прежде чем мы рассмотрим возможные варианты, нам нужно понять структуру его массива.

'location'принимает массив с массивом элементов в массиве! Задержать. Да, потому что можно обеспечить и комбинировать логику И и ИЛИ в местоположении (например, «показать в редактировании сообщения, но не если тип сообщения «книга»» или «показать на экране редактирования пользователя, а также создать новый экран пользователя, но для обоих случаев нет, если текущая роль — автор»). Способ, которым вы указываете, является ли это И или ИЛИ, заключается в структурировании массивов. Гораздо проще показать, чем объяснить словами:

Вот как вы объединяете два элемента местоположения с помощью логического И (оба они должны быть истинными):

И это для объединения местоположений с логикой ИЛИ (только одно должно быть правдой):

Увидеть разницу?

Хорошо, давайте двигаться дальше. Каждый вариант местоположения состоит из массива из трех элементов; 'param'где мы добавляем все разные местоположения 'operator', и 'value'. Оператор — это то, как сравнивать значение, и оно может быть '=='равно или '!='не равно.

Давайте рассмотрим возможные варианты один за другим.

Расположение по типу поста

Установите желаемый тип сообщения в 'value'. Имейте в виду, что вы не можете предоставить массив из нескольких типов записей, вы должны объединить несколько таких массивов в конфигурации AND.

Расположение по статусу сообщения

Установите желаемый статус публикации как 'value'. Опять же, имейте в виду, что вы не можете предоставить массив из нескольких статусов сообщений, вам нужно будет предоставить каждое желаемое значение в конфигурации AND или OR.

Расположение по шаблону страницы

Это отображается только в том случае, если для выбранной страницы (или пользовательского типа сообщений с поддержкой шаблонов страниц) выбрано указанное имя шаблона страницы.

Расположение по присвоенному термину таксономии

Это место используется, когда сообщению назначен определенный термин. Вам нужно будет указать имя таксономии, двоеточие и слаг термина в качестве значения.

Местоположение по типу страницы

ACF группирует специальные свойства страниц как «тип страницы». В основном это касается того, является ли текущая страница родительской или дочерней, а также таргетинга на страницы, установленные в качестве главной страницы WordPress или страницы блога.

Местонахождение: таксономия

Место для редактирования или добавления термина в таксономию.

Укажите имя таксономии как 'value'. Имейте в виду, что вы не можете предоставить массив из нескольких таксономий, но вы можете 'all'настроить таргетинг на все таксономии.

Местонахождение: пользователь

Это место предназначено для добавления или редактирования профиля пользователя.

Укажите 'edit‘ только для экрана редактирования существующих пользователей, 'register'для таргетинга только на форму при регистрации нового пользователя или ‘ all'для обоих вышеперечисленных.

Местонахождение: пункт меню

Начиная с ACF 5.6, вы также можете добавлять группы полей в пункты меню.

Вы можете установить value, чтобы allприменить группу ко всем элементам меню, или вы можете указать меню либо по местоположению (зарегистрированные местоположения в вашей теме), либо по идентификатору меню. Для использования местоположения 'location/<name>'— поэтому для местоположения с именем ‘ primary‘ вы можете установить значение, 'location/primary'чтобы применить вашу группу к меню, назначенному только этому местоположению. Если вы хотите настроить таргетинг на определенный идентификатор меню, задайте для значения строку этого идентификатора.

Местонахождение: виджет

ACF даже предоставляет вам местоположение в настройках виджета без изменения основного кода виджета.

Вы можете настроить таргетинг на все виджеты с помощью 'all'as 'value'или на конкретный виджет. Вам нужно знать «внутренний идентификатор» виджета, с которым они зарегистрированы.

Расположение: страница параметров ACF (только Pro)

С ACF Pro вы можете использовать ACF для настройки пользовательских страниц администратора.

Укажите имя, которое вы установили acf_add_options_pageв menu_slugкачестве 'value'.

Расположение: блок (только Pro 5.8+)

ACF Pro (5.8+) имеет функцию добавления блоков Gutenberg с полями из ACF и управления его выводом с помощью PHP. Довольно изящно для тех, кто еще не погрузился в добавление пользовательских блоков Gutenberg и необходимого Javascript.

Поля

Теперь мы переходим к более интересной части; сами поля. ACF предлагает (действительно) широкий спектр типов полей, и я повторюсь; это руководство не показывает вам, что такое каждое поле и как оно работает или выглядит.

В основном массиве, который вы предоставляете 'fields', acf_add_local_field_group()вы предоставляете массив, в котором каждое поле является собственным массивом.

Абсолютный минимум, требуемый для каждого поля, следующий: уникальный, 'key'который может быть чем угодно, и вам, вероятно, никогда не понадобится ссылаться на него. Вам также нужен 'name'мета-ключ (сообщение, пользователь, термин), в котором значение поля сохраняется как — и это тот, на который вы будете ссылаться при получении значения полей. Вы должны предоставить 'label'и, наконец, ключевое значение 'type', которое определяет, какой тип поля мы обрабатываем. Остальные поля зависят от 'type'того, как мы увидим, когда мы рассмотрим каждый тип поля ниже.

Это скелетный код для добавления поля.

Имейте в виду, что вам потребуется указанное выше для каждого поля, но чтобы не повторять один и тот же код, каждый тип поля ниже будет включать только 'type'любые другие элементы, необходимые для этого типа поля.

Поле: ввод текста

Самое простое поле. Все, что нам действительно нужно, это:

Но для дальнейшей настройки ввода текста вы также можете указать любое из следующего:

Поле: ввод числа

Поле: Текстовое поле

Поле: Ползунок диапазона

Поле: Пароль

То же, что и текстовый ввод, за исключением того, что все, что вы вводите, будет покрыто *, как и следовало ожидать в поле пароля.

Поле: Изображение

Выбор одного изображения.

Поле: Файл

Аналогичен изображению выше, за исключением того, что он не выполняет предварительный просмотр файла.

Вы также можете 'mime_types' => '',указать и установить его, например, 'pdf,docx'для разрешения только файлов PDF и DOCX.

Поле: Редактор WYSIWYG

WYSIWYG — это редактор «что видишь, то и получишь» — тот, с которым мы были знакомы до появления Гутенберга (TinyMCE).

Параметр 'media_upload'и 'delay'может принимать значения 1 (истина) или 0 (ложь).

Поле: Выбрать

Поле: Флажок

Обратите внимание, что это 'default_value'может быть массив из нескольких вариантов.

Поле: Радиокнопка

При значении 'other_choice'true добавляется дополнительный переключатель с надписью «Другое» с полем для ввода текста, где пользователь может что-то ввести.

Поле: True/False (переключить)

И допустимо только в том случае, если 'ui_on_text'равно 1, поскольку они определяют, что должно отображаться в специальном переключателе пользовательского интерфейса.'ui_off_text'``'ui'

Поле: Ссылка

Дает вам кнопку для ввода ссылки, либо путем ввода, либо выбора из контента на вашем сайте WordPress (должно быть знакомо по добавлению ссылки в обычном редакторе WordPress).

Поле: Объект публикации

Дает поле выбора, в котором вы можете выбрать содержимое WordPress. Выбор позволяет вам искать, набрав, и весь контент разделен по типу сообщения. Вы можете разрешить выбор нескольких сообщений или только одного.

Сфера: Отношения

Поле: Выберите термины в таксономии

Селектор терминов таксономии имеет четыре различных «режима» или типа, два из которых позволяют сделать множественный выбор.

Поле: Выберите пользователя

Поле: Карты Google

Имейте в виду, что вам необходимо предоставить действительный ключ API GoogleMaps для ACF, чтобы это поле работало, например:


add_filter('acf/fields/google_map/api', function($api) {
    $api['key'] = 'YOURAPIKEY';
    return $api;
});

Поле: Datepicker

Поле: Выбор даты и времени

Поле: Выбор времени

Поле: Colorpicker

Поле: Галерея (только ACF Pro)

Специальные типы полей

ACF также предлагает некоторые типы полей, которые не сохраняют значение как таковое, но они больше предназначены для организационных целей. Для всех этих значений устанавливается 'name'пустая строка.

HTML-сообщение

Если вам нужно просто распечатать какой-нибудь HTML без фактического сохранения значения, вы можете использовать type 'message'.

Повторитель (только ACF Pro)

Повторитель содержит массив полей, которые могут повторяться.

Элемент sub_fieldsожидает массив полей, точно так же, как вы настроили поля выше.

Вывод

Это ни в коем случае не исчерпывающее руководство, поскольку ACF предлагает такой широкий спектр опций и настроек. Но он должен охватывать наиболее часто используемые параметры и пользовательские варианты использования. Лично я довольно часто обращаюсь к этому всякий раз, когда добавляю поля ACF для клиентов. И даже для самых странных вариантов этого руководства достаточно, чтобы мне не нужно было раздувать мои PHP-файлы кодом экспорта ACF. Я надеюсь, что это было полезно и для вас!

Источник записи: awhitepixel.com