Формы

Модуль Формы позволяет создавать формы в административной панели WPBox, выводить их на страницах и сохранять отправленные заявки.

Как работает модуль

1. В разделе WPBox > Формы создайте форму.
2. Добавьте строки и поля, настройте их порядок, обязательность и отображение.
3. После сохранения формы скопируйте готовый шорткод и вставьте шорткод на страницу.
4. Отправленные данные появятся в разделе WPBox > Отправленные формы.

Создание формы

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

Доступные типы полей:

• Текст, Email, Телефон, Число, Дата;
• Многострочное поле;
• Чекбокс;
• Выпадающий список и Множественный выбор;
• Радиокнопки.
• Кнопка отправки.

У каждого поля можно задать Подпись, Плейсхолдер, Имя поля, обязательность и, для списков и радио-кнопок, варианты выбора. Значение Имя поля используется как HTML-атрибут name и как ключ отправленных данных. Если подпись пустая, она не выводится.

Вывод формы

Основной шорткод выглядит подобным образом:

[wpbox_form id="form-e2baf9c8-11cf-4812-a6d9-fe9b79680be9"]

где form-e2baf9c8-11cf-4812-a6d9-fe9b79680be9 сгенерированный id. Формы являются непубличными записями и выводятся только через шорткод.

Шорткод контактной формы

Шорткоды contact_form и contactform используют тот же обработчик и рендеринг, что и Forms. Они подходят для совместимости со старыми страницами.

[contact_form form_id="123"]

[contactform form_id="123"]

Без ID создаётся виртуальная форма со стандартными полями:

[contact_form]

Параметры

• form_id — ID формы WPBox;
• fields — список имён полей через запятую, пробел или точку с запятой;
• success_text — сообщение после успешной отправки;
• submit_text — текст кнопки отправки.

[contact_form form_id="123" fields="name,email,message" success_text="Спасибо!" submit_text="Отправить"]

Параметр fields только ограничивает набор полей, уже добавленных в форму. Он не добавляет новые поля и не меняет сохранённую конфигурацию.

Настройки формы

В редакторе формы доступны следующие настройки:

• Расстояние между строками — Расстояние между строками в форме;
• Сообщение об успешной отправке — сообщение после успешной отправки;
• Отобразить кнопку отправки в одном ряду с полями — если в форме одна строка, кнопка добавляется в эту же строку после полей;
• URL для перенаправления после успешной отправки — полный или относительный URL. Пустое поле отключает перенаправление;
• Задержка перенаправления (секунды) — задержка после успешной отправки. По умолчанию 3 секунды;
• Отправлять данные администратору — отправлять заявку на email администратора WordPress. Если опция не включена, заявка все равно сохраняется в раздел Отправленные формы.
• Дополнительные email-адреса — адреса для скрытой копии (BCC).

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

Страница отправки и UTM-метки

Для каждой заявки сохраняется URL страницы, с которой была отправлена форма. URL доступен в записи заявки и в отдельной колонке списка отправок.

Параметры URL с префиксом utm_ автоматически передаются вместе с AJAX-заявкой и сохраняются. В карточке заявки они отображаются в разделе Campaign parameters.

Отправленные данные

Данные сохраняются как записи типа wpbox_form_data. В административной панели они доступны только для просмотра и удаления. Добавление заявок вручную не предусмотрено.

У каждой заявки сохраняется статус отправки данных. По умолчанию создаётся статус канала email со значением not_sent. После обработки письма статус меняется на sent или error в зависимости от результата wp_mail().

Также у заявки сохраняется и может быть изменен статус заявки. Значения статусов

• Новая
• В работе
• Завершена
• Отменена

Хуки

Проверка отправки

Фильтр вызывается после проверки данных запроса, но до валидации полей и сохранения заявки. Его можно использовать для подключения captcha или собственной проверки.

add_filter( 'forms/submission/validate', function ( $errors, $form_id, $form ) {
    if ( ! my_captcha_is_valid() ) {
        $errors[] = __( 'Please complete the captcha.', 'wpbox' );
    }

    return $errors;
}, 10, 3 );

После сохранения заявки

Действие вызывается после сохранения заявки. Его можно использовать для отправки данных в CRM, webhook или другую внешнюю систему.

add_action( 'forms/submission/saved', function ( $submission_id, $data, $form_id ) {
    // Отправка $data во внешнюю систему.
}, 10, 3 );

Статусы интеграций

Фильтр forms/submission/statuses позволяет добавить собственные каналы обработки, например CRM. Статусы сохраняются в метаполе заявки. После изменения статуса вызывается действие forms/submission/status_updated.

add_filter( 'forms/submission/statuses', function ( $statuses, $form_id, $form, $data ) {
    $statuses['crm'] = 'pending';

    return $statuses;
}, 10, 4 );

add_action( 'forms/submission/status_updated', function ( $submission_id, $channel, $status, $statuses ) {
    // Обновить запись в CRM после успешной обработки.
}, 10, 4 );

CSS-классы и переменные

Для дочерней темы доступны следующие CSS-переменные:

--wpbox-forms-gap
--wpbox-form-row-gap
--wpbox-form-field-gap
--wpbox-form-label-gap
--wpbox-forms-success-bg
--wpbox-forms-success-color
--wpbox-forms-error-bg
--wpbox-forms-error-color