Як створити зовнішню форму за допомогою ACF

У цьому підручнику я покажу вам, як створити зовнішню форму з розширеними настроюваними полями (ACF). Я детально розповім, як це працює та як ви можете налаштувати його відповідно до своїх потреб.

Advanced Custom Fields (ACF) — це безкоштовний плагін, який допомагає додавати налаштування полів цілого ряду типів практично до будь-якого типу вмісту в WordPress. Ви можете додавати поля до публікацій, таксономій, меню, віджетів, користувачів і навіть власних сторінок адміністратора. Його в основному використовують для адміністратора, але ви також можете використовувати його для створення полів у інтерфейсі.

Програм для додавання полів ACF до інтерфейсу багато; ви можете додати форму для створення та оновлення публікацій, категорій або користувачів. За допомогою певного коду можна навіть створити загальну контактну форму, де відповіді зберігаються як дописи спеціального типу, а код запускає сповіщення електронною поштою про відповіді у формі. Як звичайна контактна форма. Використання функціональних можливостей зовнішніх форм ACF для створення форм і дозволу відвідувачам створювати або редагувати вміст сайту без входу в систему є поширеним використанням. Але використовуйте це з обережністю. Це легко відкриває для спаму та зловживань, а в гіршому випадку відвідувачі можуть знищити вміст або налаштування вашого сайту. Ви повинні принаймні вимагати від відвідувачів входити в обліковий запис із дійсними користувачами, щоб отримати доступ до форм, які можуть змінювати критичний вміст WordPress (профіль користувача, публікації тощо).

Що ми зробимо

Я припускаю, що сайт WordPress визначив набір додаткових полів для користувачів спеціальної ролі (‘ member‘) за допомогою ACF. Ці користувачі взагалі не мають прав адміністратора, але ми хочемо запропонувати їм можливість редагувати власні поля у своєму профілі. Рішення, яке я обрав, полягає у створенні власного шаблону сторінки для оновлення їхнього профілю, який показує форму, лише якщо вони ввійшли в систему та мають правильну роль.

У цьому підручнику я роблю це досить просто, тому не буду включати приклад додавання стандартних полів профілю користувача в WordPress (електронна адреса, пароль тощо). Це трохи виходить за рамки цього підручника. Я дозволю лише редагувати поля ACF на цій сторінці профілю редагування.

За допомогою ACF я створив групу полів із набором налаштувань для користувачів-учасників:

І в моїй темі є спеціальний шаблон сторінки, який наразі виглядає так – на даний момент просто стандартний односторінковий шаблон;

У рядку #11ми перевіряємо, чи поточний користувач увійшов у систему та має настроювану роль member. Змініть роль або мінімальне правило на будь-яке, для чого ви хочете дозволити цю зовнішню форму. Просто пам’ятайте, що навіть найнижча роль у WordPress, subscriber, має доступ до редагування свого профілю в панелі адміністратора.

Коротше кажучи, ми хочемо додати ці поля для кожного учасника на цю спеціальну зовнішню сторінку:

Як працюють зовнішні форми ACF

Вам потрібно додати два виклики функцій у шаблоні, у якому ви бажаєте використовувати зовнішню форму; [acf_form_head](https://www.advancedcustomfields.com/resources/acf_form_head/)()і [acf_form](https://www.advancedcustomfields.com/resources/acf_form/)().

Функція acf_form_head()повинна бути розміщена в самому верху вашого шаблону, перед будь-яким виведенням. Зазвичай у шаблоні це означає перед [get_header](https://developer.wordpress.org/reference/functions/get_header/)(). Виклик функції забезпечує додавання всіх сценаріїв і стилів, щоб поля ACF відображалися правильно, а також усі функції для обробки, перевірки та подання роботи. Нам не потрібно додавати параметри до цієї функції.

Ця acf_form()функція відображає зовнішню форму, і її слід розмістити там, де ви хочете, щоб форма з’явилася. Він приймає набір налаштувань. Нам потрібно як мінімум повідомити про те, які поля чи групи показувати та де їх зберігати.

Коли потрібно вирішити, які поля відображати, ви зазвичай надаєте групу полів (властивість field_groups). Але acf_form()функція також підтримує надання окремих полів (властивість fields). Ви також можете надати кілька полів або груп полів, щоб об’єднати їх в одну форму. Через це field_groupsочікує масив. Отже, навіть якщо ви хочете показати лише одну групу полів, вам потрібно надати цей ідентифікатор або слаг всередині масиву.

Друга обов’язкова властивість, яку вам потрібно надати у формі acf_form(), — це те, звідки мають бути завантажені дані та де вони мають бути збережені, у властивості post_id. Нехай вас не вводить в оману назва «пост». Правила для post_idє такими ж, коли ви використовуєте get_field(), якщо ви знайомі з роботою з ACF раніше. Якщо поля призначені для публікації (публікації, сторінки, публікації спеціального типу публікації), вам потрібно лише вказати тут ідентифікатор. Але якщо ви хочете завантажити та оновити дані про користувачів, ви повинні дотримуватися такого формату: user_{user ID}. Так само з полями для категорії: category_{category ID}. Перегляньте всі правила під заголовком «Отримати значення з різних об’єктів» у документації ACF наget_field().

Додавання зовнішньої форми ACF до нашого шаблону

Спочатку ми додаємо acf_form_head()в самому верху, безпосередньо перед get_header()– але після оголошення шаблону сторінки (рядок #3). Потім у місці, де ми хочемо відобразити форму, ми додаємо acf_form()дві властивості.

Нам потрібно дізнатися ID нашої групи полів. Якщо ви додали групу полів за кодом (у мене є публікація про те, як додати поля ACF за кодом ), ви вже надали слаг групи полів. Потім ви повинні надати слаг до field_groupsвластивості в масиві. Якщо ви додали групу полів на панелі адміністратора, вам потрібно відкрити групу в браузері та перевірити URL-адресу. Нас цікавить ідентифікатор, який відображається після «?post=»:

У моєму прикладі ідентифікатор 1145. Тоді це те, що я надаю в масиві field_groups.

PS: я не рекомендую жорстко кодувати ідентифікатор, оскільки цей ідентифікатор буде різним у кожному екземплярі WordPress! Якщо ви працюєте над локальною інсталяцією, а також над проміжним і робочим сервером, я б точно рекомендував замість цього додати поля за кодом. Таким чином ви можете визначити назву групи полів, і вона працюватиме всюди.

Що стосується post_idвластивості, я можу отримати поточний ідентифікатор користувача за допомогою функції WordPress [get_current_user_id](https://developer.wordpress.org/reference/functions/get_current_user_id/)(). Я об’єдную рядок ‘ user_‘ і повернення цієї функції як post_id.

І це в принципі все!

Якщо я відвідаю цю сторінку, увійшовши як користувач-учасник, я отримаю поточні значення для цього користувача. Усі типи полів ACF працюють і виглядають добре. І я можу оновити значення за допомогою зовнішньої форми, а також побачити, що вони оновлюються в адміністраторі.

Подальше налаштування форми

Ми можемо додатково налаштувати параметри, передані в acf_form(). Зверніться до документації ACF щодо acf_form(), щоб побачити всі можливі налаштування.

На даний момент наша форма профілю користувача відображає «Публікацію оновлено», коли налаштування надсилаються. Це не має сенсу для налаштувань профілю. Ми можемо налаштувати повідомлення за допомогою властивості updated_message.

Якщо ви хочете, ви можете визначити іншу URL-адресу для переспрямування після надсилання форми. За умовчанням та сама сторінка перезавантажується з параметром GET " ?updated=true". Ви можете вказати конкретну URL-адресу сторінки подяки або, якщо форма призначена для публікації, ви можете переспрямувати її на перегляд цієї публікації. Ми можемо надати URL-адресу у власності return.

Якщо ми хочемо інший текст на кнопці надсилання форми, ми можемо вказати це у властивості submit_value.

Ви також можете наказати acf_form()не відтворювати <form>тег. Якщо ви бажаєте об’єднати форму ACF з вашою власною формою, ви можете встановити formта falseввести <form>та <input type="submit"/>вручну. Якщо ви зробите це, ACF все одно зможе оновити значення, але вам потрібно подбати про оновлення будь-яких інших полів у вашій настроюваній формі.

Запуск дій після надсилання форми

Іноді вам може знадобитися запустити певну спеціальну функцію або подію під час оновлення зовнішньої форми. Типовим прикладом є написання функції, яка надсилає сповіщення електронною поштою після кожного надсилання форми.

Розширені користувацькі поля пропонують два корисні підказки для оновлення полів; дія [acf/save_post](https://www.advancedcustomfields.com/resources/acf-save_post/)та фільтр [acf/pre_save_post](https://www.advancedcustomfields.com/resources/acf-pre_save_post/). Знову ж таки, нехай вас не вводить в оману назва «пост». Вони запускаються для будь-якого оновлення полів ACF, включаючи поля для користувача, категорії, меню тощо.

Фільтр acf/pre_save_postзапускається лише на зовнішніх формах за допомогою acf_form(). Як параметр для цього фільтра ми отримуємо post_idте саме значення, яке ми передали вище post_id. acf_form()Фільтр очікує, що ви повернетеся post_id. Пам’ятайте, що нам потрібно проаналізувати це, якщо ми не посилаємося на ідентифікатор публікації. Наприклад, для користувача потрібно зробити щось на зразок:

add_filter('acf/pre_save_post', function($post_id) {
    if (strpos($post_id, 'user_') === false) {
        return $post_id;
    }
 
    $user_id = intval(substr($post_id, 5));  // Extracts the user ID
 
    // Do your thing. You'll find the submitted values in $_POST
 
    return $post_id;
});

Крім того, ви можете використовувати хук acf/save_post, але пам’ятайте, що він також запускається в адмінці. Як параметр цього хука ви отримаєте post_idте саме, що й acf/pre_save_post. Важливо пам’ятати acf/save_post, що під час використання ви можете використовувати пріоритет підключення, щоб контролювати, чи виконується ваша функція до збереження полів чи після. Функція, підключена до пріоритету 10 або вище, буде запущена після збереження полів. І пріоритет менше 10 буде активовано до того, як ACF збереже значення.

add_action('acf/save_post', function($post_id) {
    // You can fetch the values with standard get_field()
});
 
add_action('acf/save_post', function($post_id) {
    // You can access the submitted values in $_POST
}, 8);

Коли ви підключили функцію перед збереженням (пріоритет менше 10), ви можете порівняти надіслані значення з тими, які ACF збереже. Ви можете зробити, get_field()щоб отримати поточне значення та порівняти його з відповідним значенням у $_POST.

Якщо ви хочете зробити щось лише тоді, коли поля були оновлені у інтерфейсі, ви можете просто перевірити, чи є ми в адміністраторі за допомогою [is_admin](https://developer.wordpress.org/reference/functions/is_admin/)(). Нижче наведено приклад того, як можна налаштувати сповіщення електронною поштою, коли користувач оновлює свої налаштування у інтерфейсі;

add_action('acf/save_post', function($post_id) {
    if (strpos($post_id, 'user_') === false) {
        return $post_id;
    }
 
    if (is_admin()) {
        return;  // Bail if we are updating in admin
    }
 
    $user_id = intval(substr($post_id, 5));
 
    // Use get_field() to get the saved/submitted values if needed
    // Then use wp_mail() to send an email
});