У цьому підручнику я покажу вам, як створити розширений настроюваний тип поля Gravity Forms. Поле матиме кілька вхідних даних і потребуватиме спеціальної обробки, щоб зберігати та відображати надіслані значення.
Що ми зробимо
У цьому прикладі я припускаю приклад власника веб-сайту WordPress, який займається доставкою обідів на робоче місце. У власника є форма, у якій люди можуть заповнити, який обід вони хочуть і скільки на кожен день тижня. Це можна вирішити за допомогою табличного методу введення числа для будь-якого курсу в будь-який день, коли вони бажають отримати його.
Курси можна редагувати в налаштуваннях поля в редакторі форм і в будь-який час змінити. І для кожного надсилання форми власник веб-сайту отримує повний огляд поданих значень:
Очевидно, що це лише приклад, і вам, ймовірно, потрібно скоригувати це до вашого випадку. Але в цьому прикладі ми отримуємо шанс навчитися обробляти кілька введених даних в одному полі. Це має дати вам деякі ідеї щодо того, як працювати з вашим власним типом поля.
Перш ніж почати кодувати
Перш ніж ми почнемо, нам потрібно місце для додавання нашого коду. Ви можете додати це у свою тему functions.phpабо файл плагіна.
Метод, який я вибрав, є об’єктно-орієнтованим, що означає створення класу, який розширює клас Gravity Forms GF_Field. Я рекомендую помістити клас в окремий файл у вашому проекті. Ви також повинні перевірити наявність плагіна Gravity Forms, перш ніж додавати свій клас, щоб запобігти збою сайту.
Якщо вам цікаво, ви можете переглянути документацію Gravity Forms на GF_Field. Ви знайдете більше функцій і змінних, які можуть знадобитися для вашого типу поля.
Розширюючи GF_Fieldклас, ми можемо просто вибрати перевизначення функцій, які нам потрібно змінити. Що стосується функцій, які ми не перевизначаємо, Gravity Forms запускатиме стандартні параметри, визначені всередині GF_Field. У наведеному нижче підручнику ми одну за одною розглянемо кожну функцію, яку потрібно замінити для нашого спеціального поля. Без зайвих слів, почнемо!
Створення власного типу поля
Першим кроком є визначення спеціального класу PHP, який розширює GF_Field. Дайте класу унікальну назву та переконайтеся, що вона включена у ваш проект. Після визначення класу ми запускаємо register()статичну функцію, GF_Fieldпередаючи примірник нашого класу як параметр. Це ініціалізує наш клас і реєструє тип поля.
Єдина обов’язкова змінна, яка вам потрібна у вашому класі, це $type. Змінна класу $typeмає бути унікальною та бути ім’ям слага вашого типу поля. У своєму прикладі я назвав його " food_delivery".
if (class_exists('GF_Field')) {
class FoodDelivery extends GF_Field {
public $type = 'food_delivery';
// The rest of the code is added here...
}
GF_Fields::register(new FoodDelivery());
}За допомогою цього крихітного фрагмента коду наш спеціальний тип поля має бути доданий як доступний вибір у редакторі Gravity Forms. За замовчуванням вона відображається в кінці вікна «Стандартні поля». Оскільки ми ще не дали правильної назви нашому полю (це наступний крок), кнопка позначена як значення $type.
Визначення назви поля
Наступний крок є простим; просто дати нашій галузі кращу назву. Для цього ми перевизначаємо функцію get_form_editor_field_title(). Усе, що нам потрібно зробити, це повернути рядок із назвою поля.
public function get_form_editor_field_title() {
return esc_attr__('Food Delivery', 'txtdomain');
}За допомогою цієї функції в нашому класі кнопка для додавання поля оновлена набагато кращою міткою.
Зміна категорії поля
Цей крок необов’язковий. За замовчуванням у вікні «Стандартні поля» відображається наш спеціальний тип поля, але ми можемо це змінити. Припустімо, що ми хочемо, щоб воно з’явилося в полі «Додаткові поля».
Щоб змінити категорію, у якій має відображатися поле, ми замінюємо функцію get_form_editor_button(). Нам потрібно повернути асоціативний масив з двох елементів. Як значення для ключа «group» ви вказуєте внутрішню назву категорії, у якій має відображатися кнопка. Тут доступні параметри «standard_fields», «advanced_fields», «post_fields» або «pricing_fields». (Ви також можете створити власну категорію, але про це тут не йдеться). Другий елемент у масиві потребує ключа ‘ text‘, і для цього ми просто повертаємо назву поля, викликаючи get_form_editor_field_title(). Це функція, яку ми щойно створили вище.
Тепер кнопку для додавання нашого спеціального типу поля переміщено у вікно «Додаткові поля».
Активація польових налаштувань
Якщо ви намагалися додати тип поля у форму, ви могли помітити, що налаштувань немає взагалі. Ви навіть не можете редагувати мітку. Це працює так, що всі типи налаштувань насправді є, вони просто всі приховані за допомогою CSS від Gravity Forms. Нам потрібно окремо визначити, які параметри ми хочемо ввімкнути, і Gravity Forms відобразить для нас вибрані параметри.
Нам потрібно визначити функцію get_form_editor_field_settings()та повернути масив усіх параметрів, які ми не хочемо приховувати для нашого типу поля. Які налаштування ви хочете додати, залежить виключно від вас і вашого проекту. Майте на увазі, що ваше поле має підтримувати будь-які налаштування, які ви активуєте, інакше немає сенсу показувати налаштування для нього.
Я створив короткий огляд назв налаштувань нижче. Це далеко не повний список, тому що існує багато налаштувань, які корисні лише для дуже конкретних типів полів. Наприклад, формат телефону, формат дати/часу та ціла низка налаштувань, пов’язаних із полями публікації та цінами.
Вкладка Загальні
- Мітка поля:
label_setting - Опис поля:
description_setting - Вибір:
choices_setting - Вимагається:
rules_setting - Немає дублікатів:
duplicate_setting - Увімкнути стовпці:
columns_setting - Увімкнути вибір «вибрати все»:
select_all_choices_setting - Увімкнути «інший» вибір:
other_choice_setting
Вкладка зовнішнього вигляду
- Заповнювач:
placeholder_setting - Видимість мітки поля та розміщення опису:
label_placement_setting - Спеціальне повідомлення перевірки:
error_message_setting - Спеціальний клас CSS:
css_class_setting - Розмір поля:
size_setting
Розширена вкладка
- Мітка поля адміністратора:
admin_label_setting - Значення за замовчуванням:
default_value_setting - Увімкнути введення пароля:
password_field_setting - Примусовий SSL:
force_ssl_field_setting - Видимість:
visibility_setting - Дозволити динамічне заповнення поля:
prepopulate_field_setting - Увімкнути умовну логіку:
conditional_logic_field_setting - Увімкнути умовну логіку сторінки:
conditional_logic_page_setting
Що стосується нашого прикладу, найважливішими з них є мітка поля, опис, вибір і те, чи поле є обов’язковим чи ні. Ми також дозволяємо налаштування для класу CSS, спеціального повідомлення перевірки та умовної логіки.
public function get_form_editor_field_settings() {
return [
'label_setting',
'choices_setting',
'description_setting',
'rules_setting',
'error_message_setting',
'css_class_setting',
'conditional_logic_field_setting'
];
}Оновіть редактор форм, і ви побачите, що всі вибрані параметри та вкладки з’являться в нашому полі. Усі налаштування обробляються та зберігаються автоматично Gravity Forms.
Додайте кілька елементів у список варіантів, щоб нам було з чим працювати. Ось що я налаштував як приклад:
Визначення настроюваних параметрів за умовчанням
Якщо ви звикли використовувати, наприклад, перемикачі або прапорці у формах Gravity, ви, мабуть, помітили, що вони поширюються з такими варіантами, як «Перший вибір», «Другий вибір», «Третій вибір». Це типова поведінка від Gravity Forms, якщо жоден вибір не було збережено (раніше), і це активується лише для цих конкретних типів полів. Але для нашого спеціального типу поля вибір не буде заповнено. Це робить його трохи громіздким, оскільки ви не отримаєте кнопку «+», щоб додати інший вибір. Вам потрібно буде скористатися кнопкою «Масове додавання/попередньо визначені варіанти», додати туди кілька варіантів, а після цього ви отримаєте доступ до кнопок «+», щоб додати варіанти. Але легко визначити деякі користувацькі параметри – все, що вам потрібно, це визначити змінну масиву класуpublic $choicesі Gravity Forms автоматично згенерує попередньо визначені варіанти у вашому полі, коли ви додасте його до своїх форм.
Примітка: це змінна класу, яку ви можете додати у верхній частині класу, прямо під public $type. Кожен вибір має бути масивом із вибором як значенням ключа " text".
Майте на увазі, що якщо ви вже додали поле до форми, воно не заповнить вибір заднім числом. Це діє лише тоді, коли ви додаєте нове поле до форми.
Примітка: у Gravity Forms здається можливим також додати ключі «value» до кожного вибору. Але я не змусив це спрацювати – значення автоматично стануть такими ж, як текст вибору.
Визначення значення поля як масиву
Наступний крок досить простий, але необхідний. Стандартними значеннями полів у Gravity Forms є рядки. Нам потрібно, щоб значення було масивом, оскільки ми працюємо з кількома входами. Для цього ми визначаємо функцію is_value_submission_array()та повертаємо true.
public function is_value_submission_array() {
return true;
}Це гарантує, що ми можемо правильно працювати з введеним значенням наших кількох входів.
Візуалізація виведення поля
Коли мова заходить про візуалізацію результатів поля, слід пам’ятати про кілька речей.
По-перше, вам потрібно вибрати між двома функціями; get_field_input()або get_field_content(). У першому методі Gravity Forms автоматично візуалізує елемент списку упаковки, мітку, опис і контейнер для повідомлення про помилку перевірки у ваше поле, і ви керуєте лише виведенням внутрішнього поля. За допомогою другого методу нічого з цього не відбувається, і ви більше контролюєте вихід поля. Однак вам потрібно вручну відобразити мітку, опис і повідомлення про помилки. Перший спосіб, get_field_input(), цілком підходить для більшості випадків.
По-друге, про що слід пам’ятати, це те, що функція візуалізації для поля впливає на три різні місця. Три – це візуалізація виводу поля у інтерфейсі, попередній перегляд поля в редакторі форм і, нарешті, також поле під час редагування запису. На щастя, Gravity Forms пропонує функції, за допомогою яких можна легко визначити, у якому ракурсі ми знаходимося. Зазвичай ви відтворюєте поле однаково в усіх трьох випадках. Але оскільки візуалізація великої таблиці з великою кількістю вхідних даних стає непотрібною незграбною в редакторі форм, я вирішив по-іншому відобразити поле в редакторі форм.
І, нарешті, нам потрібно переконатися, що будь-які вхідні дані отримують належний nameатрибут, щоб Gravity Forms могла збирати його значення після надсилання форми. Усі вхідні дані у Gravity Forms потребують nameатрибутів, які відповідають цьому правилу: name="input_{FIELD_ID}"(для полів із множинним вибором використовується додатковий ідентифікатор, але нам не потрібно турбуватися про це в нашому випадку). Ми маємо доступ до ідентифікатора поля, оскільки це змінна класу (від GF_Field). Але в нашому випадку ми сказали Gravity Forms, що значення є масивом, а не одиничним значенням (попередній крок), тому ми додаємо дужки після атрибута name; name="input_{FIELD_ID}[]". Отже, якщо поле має ідентифікатор 4 у формі, атрибут name має бути «input_4[]».
Я обираю використання get_field_input(), яке має три параметри. Перший параметр — це об’єкт форми, який нам насправді не потрібен для нашого прикладу. Другий параметр – поточне значення. Це може бути значення поля з $_POSTмоменту спроби надсилання форми, але невдалої. Ми можемо зберегти попередні подані значення. Або якщо функція виконується під час редагування запису, значення буде збереженим значенням із подання. Пізніше ми розглянемо це значення більш детально. І третій параметр — об’єкт входу, який нам також не знадобиться для нашого прикладу.
Давайте почнемо реалізацію, get_field_input()яка очікує остаточний рендер у вигляді рядка. З самого початку я вирішив повернути порожній рядок, якщо ми перебуваємо всередині редактора форм, тому що я не хочу відтворювати повну таблицю в цьому поданні. Ми можемо використовувати цей метод $this->is_form_editor(), щоб перевірити, чи ми знаходимося в редагуванні форми. Ви можете пропустити це або відобразити щось інше, якщо хочете отримати попередній перегляд поля в редакторі форм.
Наступним кроком є створення HTML-коду для таблиці, яка повторює масив днів для створення стовпців і рядків для кожного пункту курсу. Але оскільки нам потрібен доступ до масиву днів (стовпців таблиці) у кількох місцях, ми повинні визначити його як змінну класу, зробивши його доступним з будь-якої функції в ньому. Я визначаю змінну класу $delivery_daysз масивом днів, на які я хочу запропонувати доставку.
class FoodDelivery extends GF_Field {
public $type = 'food_delivery';
private $delivery_days = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'];
public function get_form_editor_field_title() {
...
}Це лише приклад! Ви можете отримати масив для стовпців з іншого місця, яке не є жорстко закодованим.
Давайте повернемося get_field_input()до нашої таблиці з вхідними даними. Спочатку я перебираю змінну класу та генерую заголовки таблиці. Потім я переглядаю варіанти, введені в налаштування поля для вибору. Це доступно зі змінної класу (from GF_Field) $this->choices. Для кожного вибору я виводжу вхідні дані з атрибутами власного імені. Ми маємо доступ до ідентифікатора поля зі GF_Fieldзмінної класу $this->id.
З цим кодом ми маємо отримати гарну таблицю, відтворену для нашого типу поля у інтерфейсі! Очевидно, що HTML повністю залежить від вас, це лише базовий приклад.
Наразі ми залишаємо цю функцію, але повернемося до неї пізніше, щоб обробити надіслане значення!
Правильне зберігання вартості
Наразі Gravity Forms збереже наше поле як одновимірний масив, заповнений введеними значеннями та порожніми рядками, де введення було порожнім. Немає жодної інформації про те, до якого дня чи вибору належить значення, крім індексу. Нам потрібно перетворити цей одновимірний масив у багатовимірний асоціативний масив, де ми зберігаємо день і мітку вибору. Тоді ми можемо легко отримати доступ до збереженого значення числа, наприклад, $value['Ham sandwich']['Monday']. Після цього перетворення масиву нам також потрібно серіалізувати масив, щоб Gravity Forms могла правильно зберігати значення в базі даних.
Нам потрібно буде трансформувати цей масив значень у кількох місцях, тому я визначу для цього окрему функцію. Функція приймає одновимірний масив і перетворює його в багатовимірний масив із збереженими значеннями для днів і варіантами:
Це збереже назви днів і вибір безпосередньо в значенні поля. Зробивши це таким чином, ви зможете змінити вибір пізніше, не порушуючи старі записи.
Тепер давайте повернемося до перевизначення функції, яка обробляє збереження надісланого значення; get_value_save_entry(). Він містить п’ять параметрів, але нам потрібен лише перший, який є поданим значенням. Усередині функції ми передаємо значення в нашу спеціальну функцію вище, серіалізуємо її повернення і, нарешті, повертаємо нове значення.
На цьому етапі Gravity Forms успішно зберігатиме наші цінності саме так, як ми хочемо! Однак збережене значення тепер є серіалізованим масивом, який Gravity Forms із задоволенням повторить прямо. Нам потрібно реалізувати функції, щоб перетворити його з потворного серіалізованого масиву в якийсь гарний вихід, де б це нам було потрібно.
Відображення поданого значення
Є три місця, де нам потрібно змінити вивід значення нашого поля; список записів, дивлячись на один запис і в межах тегів злиття Gravity Forms. Теги злиття найчастіше використовуються в сповіщеннях електронною поштою. Наприклад {all_fields}, тег злиття відображає повні надіслані значення форми в електронних листах.
Оскільки ми відтворюємо один і той самий вихід у трьох різних випадках, має сенс створити для нього окрему функцію. Я визначив спеціальну функцію, яка приймає значення; несеріалізований багатовимірний масив як параметр. Потім функція створює деякий HTML, який красиво відображає масив і повертає рядок. Я вибрав вкладений <ul>список, але ви можете змінити результат, як забажаєте.
Чудово, почнемо з першого: список записів: get_value_entry_list(). Ви можете вибрати виведення повного виводу тут, але це може бути досить незграбним і довгим для перегляду списку, тому я вирішив просто повернути фіксований рядок, який пояснює, що користувачеві потрібно ввійти в деталі запису, щоб побачити повний огляд.
public function get_value_entry_list($value, $entry, $field_id, $columns, $form) {
return __('Enter details to see delivery details', 'txtdomain');
}Звичайно, це повністю залежить від вас, наприклад, ви можете вибрати відображення лише перших х символів.
Друга функція впливає на перегляд окремого запису: get_value_entry_detail():
Ми просто десеріалізуємо масив за допомогою функції WordPress [maybe_unserialize](https://developer.wordpress.org/reference/functions/maybe_unserialize/)()і повертаємо вихідний рядок із нашої спеціальної функції.
Остання функція впливає на теги злиття та переконається, що значення нашого поля також добре виглядає в електронних листах: get_value_merge_tag().
Зауважте, що нам не потрібно буде десеріалізувати значення всередині цієї функції.
З цими трьома функціями всі надіслані значення мають виглядати досить добре всюди! Наприклад, під час перегляду поданого запису:
Однак не вистачає однієї важливої речі! На цьому етапі наші вхідні дані не зберігають попередньо надіслані значення, і це дуже погано.
Зробити так, щоб наші введені дані зберігали попередньо подане значення
Є два випадки, коли нам потрібно переконатися, що вхідні дані зберігають попередньо надіслані значення. Перший випадок — це помилка надсилання форми (наприклад, користувач забув обов’язкове поле). Наразі всі наші введення втрачають усі попередньо введені значення, і користувач має повторно ввести всі значення знову. По-друге, коли власник сайту редагує запис, вхідні дані не заповнюються поданими значеннями з подання, що робить неможливим належне редагування значень.
Щоб виправити це, повернемося до функції get_field_input(). Другим параметром цієї функції є значення. Але пам’ятайте, що ця функція впливає як на візуалізацію інтерфейсу, так і на редагування запису. Це важливо, оскільки в цих двох випадках збережене значення різне. Якщо ми працюємо на інтерфейсі та обробляємо надсилання форми, значення має формат одновимірного масиву, згаданого раніше. І якщо ми редагуємо запис, значення має формат серіалізованого багатовимірного масиву. Тому нам потрібно правильно перекласти надане значення, get_field_input()щоб легко отримати доступ до фактичних значень.
У наведеному вище коді, перш ніж ми починаємо створювати HTML для виведення поля, ми створюємо змінну $table_value, яка містить правильно перекладене значення. Ми використовуємо GF_Fieldфункцію ‘s, is_entry_detail()щоб перевірити, редагуємо ми запис чи ні. І тоді для наших вхідних даних легко отримати доступ до належних значень і встановити їх як valueатрибути вхідних даних:
З оновленням вищевказаного вище, get_field_input()усі наші користувальницькі введення завжди повинні заповнюватися попереднім значенням; незалежно від того, чи це редагування запису, чи повторна спроба надсилання форми.
На цьому етапі все, що стосується візуалізації та зберігання наших значень, виконано та працює повністю. Але є ще одна річ, яку ми точно повинні виправити.
Зробіть наше поле «обов’язковою» перевіркою
Гравітаційні форми мають перевірки, щоб побачити, чи значення поля порожнє чи ні. Це часто необхідно, коли поле встановлено як потрібно. Якщо поле є обов’язковим, ви не можете надіслати форму, якщо вона порожня, чи не так? Проблема для нас полягає в тому, що у нас є кілька входів, і ми хочемо, щоб деякі з них були порожніми. Це стає проблемою, якщо наше поле встановлено як обов’язкове. На жаль, Gravity Forms неправильно тлумачить «це пусте» та вимагає, щоб усі введені дані були заповнені. Тож нам потрібно додати правило, яке говорить, що якщо принаймні один із наших багатьох вхідних даних заповнено, загальне значення поля не є порожнім.
Останньою функцією, яку нам потрібно перевизначити в нашому класі, є is_value_submission_empty(). Ми отримуємо лише ідентифікатор форми як параметр цієї функції, тому нам потрібно отримати значення поля за допомогою функції Gravity Forms, щоб отримати його з $_POSTмасиву: rgpost('input_<FIELD ID>'). Повернення має бути одновимірним масивом, який ми бачили раніше. Все, що нам потрібно зробити, це прокрутити масив і повернутися false, якщо ми десь знайдемо значення. В іншому випадку ми повертаємося true, оскільки значення поля справді абсолютно порожнє.
З наведеною вище функцією наше поле не буде подано, якщо для нього встановлено значення обов’язкове та заповнено принаймні один вхід.
Висновок і підсумковий код
У цьому підручнику детально показано, як створити власний розширений тип поля для Gravity Forms. Навіть якщо ваш проект відрізняється від мого прикладу, я сподіваюся, що у вас є якісь вказівки та «а-ха» на цьому шляху. Я вважаю, що в деяких випадках документації Gravity Forms досить бракує, і це результат багатьох спроб і помилок! У будь-якому випадку, сподіваюся, це було для вас корисним!
Для довідки, ось повний код: