Повний довідник для додавання розширених груп спеціальних полів і полів за кодом
Плагін Advanced Custom Fields (ACF) підтримує повне налаштування полів і груп за кодом PHP у вашій темі чи плагіні. Переваги цього полягають у тому, що всі ваші поля будуть доступні незалежно від екземпляра WordPress, над яким ви працюєте (наприклад, якщо вам потрібно перемикатися між локальним, тестовим сервером і живим сервером). Ви можете налаштувати всі поля в адміністраторі ACF і скористатися інструментом експорту для експорту в PHP.
Однак якщо ви робите це часто, ви можете помітити, що PHP-експорт ACF містить багато коду, що робить ваші PHP-файли непотрібними. У деяких випадках краще написати код самостійно, використовуючи необхідний мінімум, щоб отримати чистіший код у вашій темі чи плагіні. Цей посібник має на меті надати вам повну довідку про те, як вручну написати додавання полів і груп ACF у PHP. Зауважте, що тут не буде вдаватися в подробиці кожного типу поля, оскільки передбачається, що ви вже знайомі з різними полями, можливими в ACF.
Але спочатку; деякі запобіжні заходи
Щоб підтримувати хороші стандарти коду та гарантувати, що ваш сайт WordPress не аварійно завершує роботу, ви завжди повинні перевіряти, чи дійсно існують функції або класи, які використовує ваш код. Особливо, коли мова йде про плагіни, які можна легко деактивувати або навіть не встановлювати на сайті, ви завжди повинні загортати свій код плагіна в if-тест, який перевіряє, чи існують функції, які ви використовуєте, перш ніж використовувати їх.
Що стосується 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'.
Ви можете керувати дизайном метабокса, надаючи або defaulteller seamlessу 'style'. Однак у новому редакторі Gutenberg це має набагато менше значення. Те саме стосується ключа, 'position'де в старі часи ви могли розташувати метабокс під вмістом публікації ('normal'), збоку ('side') або відразу після заголовка публікації ('acf_after_title').
добре! Давайте зануримося в два більш цікаві елементи масиву; починаючи з розташування – це визначає, де з’являється метабокс.
Місцезнаходження
Це все про те, що ви вкладаєте в ключ 'location'. Але перш ніж ми розглянемо можливі варіанти, нам потрібно зрозуміти його структуру масиву.
'location'приймає масив із масивом елементів у масиві! Тримайся. Так, тому що можна надати та поєднати логіку І та АБО в розташуванні (наприклад, «показати під час редагування публікації, але не якщо тип публікації є «книга»», або «показати на екрані редагування користувача, а також створити новий екран користувача, але для обох випадків не якщо поточною роллю є автор"). Спосіб позначення І чи АБО – це структурування масивів. Це набагато легше показати, ніж пояснити словами:
Ось як ви об’єднуєте два елементи розташування за допомогою логіки І (обидва вони мають бути істинними):
І це для об’єднання місць за допомогою логіки АБО (тільки одне має бути істинним):
Бачите різницю?
Добре, йдемо далі. Кожен варіант розташування складається з масиву з трьох елементів; 'param'куди ми додаємо всі різні місця, 'operator', і 'value'. Оператор дає змогу порівнювати значення, і він може бути '=='дорівнює або '!='не дорівнює.
Давайте по черзі розберемо можливі варіанти.
Розташування за типом поста
Встановіть бажаний тип публікації в 'value'. Майте на увазі, що ви не можете надати масив із кількох типів публікацій, вам потрібно об’єднати кілька цих масивів у конфігурації І.
Розташування за статусом поста
Установіть бажаний статус публікації як 'value'. Знову ж таки, майте на увазі, що ви не можете надати масив кількох статусів публікації, вам потрібно буде надати кожне бажане значення в конфігурації І або АБО.
Розташування за шаблоном сторінки
Це відображається, лише якщо для вибраної сторінки (або спеціального типу публікації з підтримкою шаблону сторінки) вибрано надане ім’я шаблону сторінки.
Розташування за приписаним таксономічним терміном
Це місце призначено для публікації, яка має певний термін. Вам потрібно буде вказати назву таксономії, двокрапку та символ терміна як значення.
Розташування за типом сторінки
ACF групує спеціальні властивості для сторінок як «тип сторінки». Здебільшого це стосується того, чи є поточна сторінка батьківською чи дочірньою сторінкою, а також для націлювання на сторінки, встановлені як головна сторінка WordPress або сторінка блогу.
Розташування: таксономія
Розташування для редагування або додавання терміна в таксономії.
Введіть назву таксономії як 'value'. Майте на увазі, що ви не можете надати масив із кількох таксономій, але ви можете надати 'all'націлювання на всі таксономії.
Розташування: користувач
Це місце для додавання або редагування профілю користувача.
Укажіть 'edit‘ лише для націлювання на екран редагування існуючих користувачів, 'register'для націлювання лише на форму під час реєстрації нового користувача або ‘ all'для обох вищевказаних дій.
Починаючи з ACF 5.6, ви також можете додавати групи полів до пунктів меню.
Ви можете встановити value, щоб allзастосувати групу до всіх пунктів меню, або ви можете вказати меню або за розташуванням (зареєстровані місця у вашій темі), або за ідентифікатором меню. Для використання розташування 'location/<name>'– отже, для розташування під назвою «primary» ви можете встановити значення, 'location/primary'щоб застосувати вашу групу до меню, призначеного лише для цього розташування. Якщо ви хочете націлити певний ідентифікатор меню, установіть значення рядка цього ідентифікатора.
Розташування: віджет
ACF навіть надає вам розташування в налаштуваннях віджета без зміни коду основного віджета.
Ви можете націлити всі віджети за допомогою 'all'як 'value'або на певний віджет. Вам потрібно буде знати «внутрішній ідентифікатор» віджета, у якому вони зареєстровані.
Розташування: сторінка параметрів ACF (лише Pro)
За допомогою ACF Pro ви можете використовувати ACF для налаштування власних сторінок адміністратора.
Введіть ім’я, яке ви встановили в acf_add_options_page.menu_slug``'value'
Розташування: блок (лише Pro 5.8+)
ACF Pro (5.8+) має функцію для додавання блоків Гутенберга з полями з ACF і керування їх виведенням за допомогою PHP. Досить чудово для тих, хто ще не занурився в додавання власних блоків Гутенберга та необхідного Javascript.
поля
Тепер ми переходимо до більш цікавої частини; самі поля. ACF пропонує (справді) широкий спектр типів полів, і я повторю; цей посібник не показує вам, що таке кожне поле і як воно працює або виглядає.
У основному масиві, який ви надаєте 'fields', acf_add_local_field_group()ви надаєте масив, де кожне поле є окремим масивом.
Абсолютний мінімум, необхідний для кожного поля, такий: унікальний, 'key'який може бути будь-яким, і вам, ймовірно, ніколи не потрібно буде посилатися на нього. Вам також потрібен 'name'мета-ключ (публікація, користувач, термін), у якому зберігається значення поля – і це той, на який ви посилатиметеся під час отримання значення полів. Ви повинні надати 'label'і, нарешті, ключове значення, 'type'яке визначає тип поля, який ми обробляємо. Решта полів залежить від 'type'того, що ми побачимо під час перегляду кожного типу поля нижче.
Це каркасний код для додавання поля.
Майте на увазі, що вам знадобиться наведене вище для кожного поля, але щоб не повторювати той самий код, кожен тип поля нижче включатиме лише 'type'та будь-які інші елементи, необхідні для цього типу поля.
Поле: Введення тексту
Найпростіше поле з усіх. Все, що нам дійсно потрібно, це:
Але для подальшого налаштування введення тексту ви також можете надати будь-який із наведеного нижче:
Поле: введення числа
Поле: Textarea
Поле: повзунок діапазону
Поле: Пароль
Те саме, що й введення тексту, за винятком того, що все, що ви вводите, буде покрито *, як і очікувалося, у полі пароля.
Поле: Зображення
Вибір одного зображення.
Поле: файл
Подібно до зображення вище, за винятком того, що воно не переглядає файл.
Ви також можете надати 'mime_types' => '',та налаштувати його, наприклад, 'pdf,docx'для дозволу лише файлів PDF та DOCX.
Поле: редактор WYSIWYG
WYSIWYG — це редактор «Що бачиш, те й отримуєш» — той, з яким ми були знайомі до появи Гутенберга (TinyMCE).
Параметр 'media_upload'and 'delay'може мати значення 1 (true) або 0 (false).
Поле: Виберіть
Поле: прапорець
Зауважте, що 'default_value'може бути масив із кількох варіантів.
Поле: радіокнопка
Якщо встановити 'other_choice'значення true, додається додаткова перемикач із позначкою «Інше» з текстовим введенням, де користувач може щось вводити.
Поле: True/false (перемикач)
І дійсні, лише якщо 'ui_on_text'дорівнює 1, оскільки вони визначають, що має відображатися на спеціальному перемикачі інтерфейсу користувача.'ui_off_text'``'ui'
Поле: Посилання
Надає вам кнопку для введення посилання, ввівши або вибравши вміст на вашому сайті WordPress (це має бути знайоме з додавання посилання у звичайному редакторі WordPress).
Поле: Post Object
Дає поле вибору, де ви можете вибрати вміст WordPress. Вибір дозволяє здійснювати пошук шляхом введення, а весь вміст розділено за типом публікації. Ви можете дозволити вибрати кілька публікацій або лише одну.
Поле: Стосунки
Поле: Виберіть терміни в таксономії
Селектор таксономічних термінів має чотири різні «режими» або типи, де два з них дають змогу вибирати кілька варіантів.
Поле: Виберіть користувача
Область: Google Maps
Майте на увазі, що вам потрібно надати дійсний ключ GoogleMaps API для ACF, щоб це поле працювало, наприклад:
add_filter('acf/fields/google_map/api', function($api) {
$api['key'] = 'YOURAPIKEY';
return $api;
});Поле: Вибір дати
Поле: Дата і час
Поле: вибір часу
Поле: Colorpicker
Поле: Галерея (лише ACF Pro)
Спеціальні види полів
ACF також пропонує деякі типи полів, які не зберігають значення як такі, але вони більше призначені для організаційних цілей. Для всіх цих параметрів встановіть 'name'порожній рядок.
Повідомлення HTML
Якщо вам потрібно просто роздрукувати деякий HTML без фактичного збереження значення, ви можете використати type 'message'.
Повторювач (лише ACF Pro)
Повторювач містить масив полів, які можна повторювати.
Елемент sub_fieldsочікує масив полів, як ви налаштували поля вище.
Висновок
Це аж ніяк не вичерпний посібник, оскільки ACF пропонує такий широкий спектр опцій і налаштувань. Але він повинен охоплювати найбільш використовувані параметри та спеціальні випадки використання. Особисто я досить часто згадую це, коли додаю поля ACF для клієнтів. І навіть для найдивніших варіантів цього посібника достатньо, щоб мені не потрібно було роздувати свої PHP-файли кодом експорту ACF. Сподіваюся, це також було корисно для вас!