Елемент форми

Елемент Esl’ “Форма” є готовим елементом для створення та розміщення форм на будь-якій сторінці, побудованій з Esl. Елемент форми дозволяє вам створювати користувацькі форми з наступними типами полів:

  • Електронна пошта
  • Текст
  • Текстове поле
  • Телефон
  • Число
  • URL
  • Перемикач
  • Вибір (випадний список)
  • Радіо
  • Пароль
  • Запам’ятати мене (з Esl 1.9.2)
  • Вибір дати
  • Завантаження файлів
  • Сховане (з Esl 1.3.5)

Ви можете визначити дії, котрі виконуються під час відправки форми, такі як надсилання електронного сповіщення, перенаправлення на певну сторінку, зв’язок з серверами SendGrid або Mailchimp, або вхід/реєстрація користувача. Якщо цього недостатньо, ви також можете розробити свої власні дії.

Елемент форми також інтегрується з Google reCaptcha V3, hCaptcha та Cloudflare Turnstile, щоб захистити ваші сайти від шахрайських дій, спаму та зловживань. Підтримує динамічні дані, а з версії 1.7.1 валідність форми через новий хук дії.

Як використовувати елемент Форми

Дії

Дії форми виконуються, коли форма відправлена. Ви можете налаштувати одну або кілька дій для вашої форми. Вони будуть виконуватися послідовно відповідно до визначеного порядку, за винятком дії “Перенаправлення”, яка буде виконана після всіх інших дій.

Для кожної дії у вас буде окрема група налаштувань.

Налаштування дії електронної пошти елемента форми

Електронна пошта

Дія електронної пошти форми надсилає один електронний лист при відправці форми. За замовчуванням він налаштований на надсилання електронного листа на електронну пошту адміністратора сайту, що містить усі вміст полів форми.

Ви можете налаштувати дію електронної пошти форми з наступними налаштуваннями:

  • Тема: Тема електронного листа
  • Надіслати на електронну адресу: Заповніть адреси електронної пошти отримувачів. Ви можете надіслати електронний лист адміністраторам сайту або на спеціальну електронну адресу (вона приймає кілька електронних адрес, розділених комою)
  • Електронна адреса відправника: Електронна адреса, яка відображається як відправник
  • Ім’я відправника: Ім’я, яке відображається як відправник
  • Відповісти на електронну адресу: Якщо отримувач відповість на електронний лист, ця електронна адреса буде використана замість «Електронної адреси відправника»
  • Зміст електронної пошти: У разі, якщо ви хочете персоналізувати зміст електронного листа. Для стандартного повідомлення, що містить усі поля, залиште це поле пустим.
  • Повідомлення про помилку: Повідомлення, яке буде представлене користувачеві сайту, якщо електронна пошта не надійде з будь-якої причини.
  • HTML електронна пошта: Увімкніть, щоб відправити електронні листи в форматі HTML. Залиште вимкненим, щоб надіслати електронний лист у форматі простого тексту.

Електронний лист підтвердження (з 1.7.2)

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

Ми настійно рекомендуємо правильно налаштувати SMTP, щоб забезпечити найкращу доставку електронних листів з вашого сайту. Є багато безкоштовних плагінів для WordPress, які дозволяють налаштувати це всього за кілька хвилин. Пошук «WordPress SMTP» повинен вивести безліч статей та плагінів для цього.

Якщо ім’я відправника та електронна адреса, які ви налаштували в налаштуваннях «Електронного листа підтвердження» у елементі Форми, не використовуються, вам потрібно перевірити, чи не переписує будь-який плагін та/або власний код інше ім’я та електронну адресу.

Динамічні поля форми

ID поля

У певних сценаріях може бути корисно отримати зміст деяких надісланих полів форми для заповнення налаштувань дій електронної пошти.

Щоб використовувати надіслані дані у налаштуваннях вашої форми, необхідно скопіювати та вставити унікальний ID поля (який ви знайдете в кінці кожного поля форми) і обгорнути його в дві фігурні дужки, як ось: {{form_field_id}}

Використовуйте ці динамічні поля в налаштуваннях «Тема», «Електронна адреса», «Зміст електронної пошти», «Ім’я відправника» та «Електронна адреса відправника».

Використовуйте {{referrer_url}} у вищезгаданих полях, щоб вставити URL-адресу сторінки, на якій була надіслана форма.

Щоб відобразити всі надіслані поля у «Змісті електронної пошти», використовуйте плейсхолдер {{all_fields}} (@з 1.9.2).

Вхід користувача, реєстрація, втрачене пароль та скидання паролю

Ми представили дві нові дії форм у Esl 1.9.2: Втрачене пароль та Скидання паролю.

Ці дії, разом із наявними діями Вхід користувача та Реєстрація користувача, дозволяють вам створювати користувацькі форми аутентифікації без кодування.

При виборі однієї з цих дій вам потрібно відповідно призначити поля форми:

  • Вхід користувача: Призначте поля форми на “Вхід”, “Пароль” та, за бажанням, новий чекбокс “Запам’ятати мене” (з 1.9.2).
  • Реєстрація користувача: Призначте поля форми на “Електронна пошта”, “Пароль”, “Ім’я користувача” та, за бажанням, “Ім’я/Прізвище”.
  • Втрачене пароль (з 1.9.2): Призначте поле форми на “Електронна пошта” або “Ім’я користувача” для відправки інструкцій для скидання.
  • Скидання паролю (з 1.9.2): Призначте поле форми “пароль”.

Для детальних інструкцій з налаштування користувацьких сторінок аутентифікації за допомогою елемента Форми, будь ласка, відвідайте статтю Сторінки аутентифікації.

Перенаправлення

Ця дія форми перенаправляє користувача з сторінки форми на іншу сторінку на вашому сайті. Ви можете встановити перенаправлення на адміністративну зону або на користувацьку URL-адресу та встановити перенаправлення так, щоб воно відбулося тільки після певного періоду часу.

Дія перенаправлення форми спрацьовує лише після того, як всі інші дії успішно виконані.

З 1.10 поле користувацької URL-адреси перенаправлення підтримує тег Динамічне поле Форми.

Користувацьке

Користувацька дія дозволить вам підключитися до дії esl/form/custom_action та виконати ваш код.

Будь ласка, переконайтеся, що ви включили Користувацьке у полі “Дії після успішної відправки форми” на вашому елементі форми, використовуючи цей хук.

Зворотний виклик дії отримає об’єкт $form, який відкриває наступні методи для отримання налаштувань форми, полів форми та завантажених файлів форми (якщо потрібно):

Налаштування: $form->get_settings()

Цей метод відкриває асоціативний масив з налаштуваннями форми (налаштування полів та дій), схожими на ці:

Array([fields] => Array([0] => Array([type] => text[label] => Ім'я[placeholder] => Ваше ім'я[id] => 15bc57)[1] => Array([type] => email[label] => Електронна пошта[placeholder] => Ваша електронна пошта[required] => 1[id] => 3db633)[2] => Array([type] => textarea[label] => Повідомлення[placeholder] => Ваше повідомлення[required] => 1[id] => f65f2c)...)[submitButtonStyle] => primary[actions] => Array([0] => email...)[successMessage] => Повідомлення успішно надіслано. Ми зв'яжемося з вами якомога швидше.[emailSubject] => Запит контактної форми[emailTo] => admin_email[fromName] => esl[emailErrorMessage] => Відправку не вдалося завершити. Будь ласка, перезавантажте сторінку та спробуйте надіслати форму знову.[htmlEmail] => 1[mailchimpPendingMessage] => Будь ласка, перевірте свою електронну пошту, щоб підтвердити підписку.[mailchimpErrorMessage] => Вибачте, але ми не змогли вас підписати.[sendgridErrorMessage] => Вибачте, але ми не змогли вас підписати....)

Значення полів: $form->get_fields()

Цей метод надає асоціативний масив з поданими значеннями для кожного поля форми, разом з ідентифікатором посту та ідентифікатором форми:

Array([form-field-15bc57] => Джон Доу[form-field-3db633] => john.doe@example.com[form-field-f65f2c] => Дякуємо, що користуєтеся Esl!...[postId] => 167[formId] => yrnkmt...[referrer] => https://example.com/contact)

Подані файли: $form->get_uploaded_files()

Цей метод надає асоціативний масив з властивостями поданих файлів, згрупованих за ідентифікатором поля форми:

[‘file’] => Фізичне збережене місце
[‘url’] => Може бути недоступним, якщо не зберегти в медіа або в інший каталог. 

Array([form-field-sajbjc] => Array([0] => Array([file] => /.../public/wp-content/uploads/2022/03/my-uploaded-file.png[url] => https://example.com/wp-content/uploads/2022/03/my-uploaded-file.png[type] => image/png)[1] => Array([file] => /.../public/wp-content/uploads/2022/03/my-other-file.png[url] => https://example.com/wp-content/uploads/2022/03/my-other-file.png[type] => image/png)...))

Приклад #1 Базова настройка

<?phpfunction my_form_custom_action( $form ) {// $fields = $form->get_fields();// $formId = $fields['formId'];// $postId = $fields['postId'];// $settings = $form->get_settings();// $files = $form->get_uploaded_files();// Виконайте деяку логіку тут...// Встановіть результат у випадку, якщо це не вдасться$form->set_result(['action' => 'my_custom_action','type'    => 'success', // або 'error' або 'info''message' => esc_html__('Ой, моя спеціальна дія не вдалася', 'esl'),]);}add_action( 'esl/form/custom_action', 'my_form_custom_action', 10, 1 );

Приклад #2 Відправка другого електронного листа після відправлення форми.

З нинішньою версією Esl ви можете встановити лише одне повідомлення про електронну пошту. За допомогою цього фрагмента коду ви можете відправити другий.

<?phpfunction my_form_custom_action_sending_email( $form ) {$fields = $form->get_fields();// $formId = $fields['formId'];// $postId = $fields['postId'];$settings = $form->get_settings();// $files = $form->get_uploaded_files();$to = 'recipient@example.com'; // Замініть це$from = 'sender@example.com'; // Замініть це$subject = 'Ваш Тема'; // Замініть цеif ( ! empty( $settings['emailContent'] ) ) {$message = $form->render_data( $settings['emailContent'] );$message = isset( $settings['htmlEmail'] ) ? nl2br( $message ) : $message;} else {$email = new EslIntegrationsFormActionsEmail('email');$message = $email->get_default_message( $settings, $fields );}$headers[] = 'From: Ваше Ім'я <'.$from.'>';$headers[] = 'Reply-to: '. $from;if ( isset( $settings['htmlEmail'] ) ) {$headers[] = 'Content-Type: text/html; charset=UTF-8' . "rn";}$result = wp_mail( $to, $subject, $message, $headers );// $form->set_result([//  'action' => 'my_custom_action',//  'type'    => 'success', // або 'error' або 'info'//  'message' => esc_html__('Ой, моя спеціальна дія не вдалася', 'esl'),// ]);}add_action( 'esl/form/custom_action', 'my_form_custom_action_sending_email', 10, 1 );

Приклад #3 Особлива перенаправлення на URL прихованого поля

В деяких випадках ви хочете перенаправити користувача на сторінку на основі певних значень параметрів URL. У такому сценарії ви не можете використовувати на полі URL для спеціального перенаправлення. Це пов’язано з тим, що форма була відправлена через AJAX, і параметри URL поточної сторінки не будуть надіслані разом із викликом AJAX.

Метод 1
З версії 1.10, дія перенаправлення підтримує динамічне поле форми. Ви можете вибрати дію перенаправлення і налаштувати це так.

Метод 2
Ви можете використовувати спеціальну дію з деяким PHP-кодом для складнішої логіки. Спочатку ви можете помістити параметр url у приховане поле.

Збережіть URL параметр у прихованому ключі та виберіть Користувальницьку дію

Тоді виберіть Користувальницьку дію та дотримуйтесь наведеного нижче коду як прикладу

<?phpadd_action( 'esl/form/custom_action', 'redirect_to_my_key', 10, 1 );function redirect_to_my_key( $form ) {$form_fields   = $form->get_fields();$form_id       = $form_fields['formId'];// Перевірте, чи є ідентифікатор форми тим, що вам потрібноif( $form_id !== 'cyrozb' ) return;// oeckxw - це ID прихованого поля, в якому я помістив$my_key = isset( $form_fields['form-field-oecdxz'] ) ? $form_fields['form-field-oecdxz'] : '';if( $my_key ) {// Тепер ви отримуєте значення прихованого поля та перенаправляєте на сторінку, яку хочете, наприклад:$redirect_to = get_site_url() . '/?key=' . $my_key;// Якщо значення прихованого поля є URL, просто перенаправте на нього замість слідування моєму коду// $redirect_to = $my_key;$form->set_result(['action'          => 'my_custom_redirect', // Це назва дії, ви можете встановити будь-яке ім'я, яке хочете'type'            => 'redirect', // Повинно бути встановлено на 'redirect''redirectTo'      => $redirect_to,'redirectTimeout' => 0 // Потрібно затримання? Встановіть тайм-аут у мілісекундах]);}}

Валідація форми

Esl 1.7.1 надає новий фільтр під назвою esl/form/validate, який дозволяє вам валідовувати кожне надсилання форми та повертати повідомлення про помилки, якщо ваша користувацька валідація не проходить. Перший параметр $errors є масивом, кожен елемент якого є повідомленням про помилку. Другий параметр $form є екземпляром надісланої форми.

Наступний приклад коду перевіряє надіслану електронну адресу для поля форми з ID 7e30aa.

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

add_filter( 'esl/form/validate', function( $errors, $form ) {$form_settings = $form->get_settings();$form_fields   = $form->get_fields();$form_id       = $form_fields['formId'];// Пропустіть валідацію: ID форми не є 'kfbqso'if ( $form_id !== 'kfbqso' ) {// Ранній вихід масиву $errors, якщо це не цільова формаreturn $errors;}// Отримати надіслане значення поля форми з ID форми '7e30aa'$email_address = $form->get_field_value( '7e30aa' );// Помилка: електронна пошта від зареєстрованого користувача (показати повідомлення про помилку, і не надсилати електронну пошту)if ( ! email_exists( $email_address ) ) {// Додати повідомлення про помилку до масиву $errors$errors[] = esc_html__( 'Ця електронна адреса не в нашій системі, вибачте.', 'esl' );}// Переконайтеся, що завжди повертаєте масив $errorsreturn $errors;}, 10, 2 );.

Непосредня валідація введення

Поле форми: Повідомлення про помилку

Починаючи з версії 1.9.2, Esl покращило досвід роботи з формою, додавши можливість відображати повідомлення про помилки негайно, щойно поле втратить фокус.

Щоб скористатися цією функцією:

  1. Додайте «Повідомлення про помилку» до певного поля форми.
  2. Після втрати фокусу форма оцінить введені користувачем дані, щоб визначити, чи слід відображати «Повідомлення про помилку» на основі наступних критеріїв:
    • Обов’язкове: Перевіряє, чи є дані в обов’язкових полях.
    • Мін/max номер: Гарантує, що введені числа знаходяться в визначеному діапазоні.
    • Електронна пошта: Підтверджує правильність формату електронної пошти.
    • URL: Перевіряє структуру введених URL-адрес.

Захист від спаму (Google reCaptcha V3)

Елемент форми Esl підтримує останній механізм Google reCaptcha V3. Щоб активувати його, спочатку створіть сайт-ключ і сайт-секретний ключ, а потім додайте обидва в вашій адміністративній області під «Esl > Налаштування > API ключі».

Після додавання ключів активуйте налаштування reCaptcha під час редагування елемента форми в системі під контрольним групою «Захист від спаму».

Якщо ви все ще отримуєте багато спаму, можливо, вам потрібно налаштувати рівень порогу SPro. За замовчуванням поріг налаштований на 0.5. API Google reCaptcha V3 повертає значення в діапазоні від 0.0 до 1.0, де 0.0, ймовірно, є ботом, а 1.0, ймовірно, є людською взаємодією. Щоб підвищити поріг Esl, будь ласка, використовуйте наступний фрагмент PHP:

add_filter( 'esl/form/recaptcha_spro_threshold', function( $spro ) {// Esl за замовчуванням 0.5$spro = 0.8;return $spro;}, 10, 1 );

Налаштування порогу на 0.8 означає, що Esl прийме лише відправлення форм з вищими SPro (ймовірніше, людськими взаємодіями).

Захист від спаму (hCaptcha)

Починаючи з версії 1.9.2, Esl інтегрується з hCaptcha. Щоб скористатися ним, додайте свій ключ сайту hCaptcha та секретний ключ hCaptcha під «Esl > Налаштування > API ключі».

Після додавання ключів активуйте налаштування reCaptcha під час редагування елемента Форми в системі під контрольним групою «Захист від спаму». Ви знайдете опції вибору «Невидимого» або «Видимого» hCaptcha. Для «Видимого» hCaptcha:

  • Тема: Виберіть між темним і світлим темами.
  • Розмір: Виберіть з компактного або нормального.

Для детальних інструкцій з налаштування зверніться до документації hCaptcha.

Захист від спаму (Cloudflare Turnstile)

Починаючи з версії 1.9.2, Esl представив підтримку Cloudflare Turnstile. Щоб скористатися його можливостями, спочатку додайте свій ключ сайту та секретний ключ Cloudflare Turnstile у розділі “Esl > Налаштування > API ключі”.

Після реєстрації необхідних даних перейдіть до елемента Форми в рушії та знайдіть групу керування “Захист від спаму”. Тут ви можете вмикати або вимикати налаштування Cloudflare Turnstile.

Після активації у вас буде можливість налаштувати наступне:

  • Тема: Виберіть між “темною”, “світлою” або за замовчуванням “авто” темою.
  • Розмір: Виберіть “компактний” або “нормальний”.

Для отримання додаткової інформації про те, як отримати свій ключ сайту та секретний ключ, зверніться до документації Cloudflare Turnstile.

Налаштуйте поле вибору дати

Esl (1.5+) використовує бібліотеку Javascript для вибору дати Flatpickr, яку можна розширити, локалізувати або налаштувати відповідно до доступних опцій.

Щоб змінити опції ініціалізації бібліотеки, використовуйте фільтр esl/element/form/datepicker_options, як показано нижче:

add_filter( 'esl/element/form/datepicker_options', function( $options, $element ) {$options['locale'] = ['firstDayOfWeek' => 1 // Встановіть понеділок як перший день тижня];return $options;}, 10, 2 );

Функція зворотного виклику фільтра приймає два аргументи:

Локалізуйте рядки вибору дати

Flatpickr підтримує л10н для різних мов. Вам потрібно завантажити мовний пакет, вставивши наступні інструкції в Налаштування Esl > Кастомний код > Сценарії тіла (футер):

<script src="https://npmcdn.com/flatpickr/dist/l10n/XX.js"></script><script>window.flatpickr.localize(window.flatpickr.l10ns.XX)</script>

Замініть XX на код мови, який вам потрібен (наприклад, de для німецької, pt для португальської, …).

Якщо вам потрібно налаштувати мову для конкретної форми, вам потрібно завантажити мовний пакет, як описано в першому рядку коду вище, але потім ви можете використовувати фільтр Esl для завантаження мови для конкретного елемента форми.

add_filter( 'esl/element/form/datepicker_options', function( $options, $element ) {if ( $element->id === 'abcdef' ) {// локалізувати елемент форми "abcdef"$options['locale'] = 'XX';}return $options;}, 10, 2 );

Інтеграції

Елемент форми інтегрується з Mailchimp та Sendgrid. Дозволяє вам додавати нові контакти до ваших електронних списків. Переконайтеся, що ви додали свої API ключі Mailchimp/Sendgrid, як описано нижче.

При редагуванні елемента форми вам потрібно вибрати Mailchimp або Sendgrid в розділі “Дії”, щоб форма знала, що потрібно додати надіслану електронну адресу до вашого списку.

Коли ви виберете правильну дію, повинна з’явитися нова група контролю “Mailchimp” або “Sendgrid”. Там ви повинні вибрати список, до якого хочете додати цей новий контакт, та “Поле електронної пошти” вашої форми, яке містить електронну адресу.

Mailchimp

Дія форми Mailchimp дозволяє вам генерувати дані вашої форми (електронна пошта, ім’я та прізвище) в список і групу Mailchimp.

Щоб використовувати дію Mailchimp, вам потрібно створити обліковий запис Mailchimp, а потім отримати API ключ.

Щоб використовувати цю дію форми, додайте API ключ під “Esl > Налаштування > API ключі > Mailchimp API ключ”.

SendGrid

Дія форми SendGrid дозволяє вам генерувати дані вашої форми (електронна пошта, ім’я та прізвище) в список SendGrid.

Щоб використовувати дію SendGrid, вам потрібно створити обліковий запис SendGrid, а потім отримати API ключ.

Щоб використовувати цю дію форми, додайте API ключ під “Esl > Налаштування > API ключі > SendGrid API ключ”.

Як створити форму з декількома колонками

Для створення форми з декількома колонками спочатку потрібно встановити “Ширину” полів форми у відсотках.

Приклад: Дво-колонна верстка

Створити дво-колонну форму так само просто, як встановити ширину окремих полів форми на 50%.

Щоб додати трохи відстані між нашими полями форми, давайте встановимо «Ширину» перших двох полів у нашому прикладі на 49%. Ці поля тепер займають 98% горизонтальної ширини. Це створює 2% промежок між нашими стовпцями. Встановіть значення «Відстань» внизу на «2%», щоб застосувати таку ж відстань у всіх напрямках.

Нарешті, встановіть «Вирівнювання» на «space-between», щоб забезпечити горизонтальне вирівнювання наших полів з зовнішніми краями нашої форми.

Дво-column форма макета