FormIt 5.2: нативный AJAX и reCAPTCHA v3

Вышли версии FormIt 5.2.0 и 5.2.1 с двумя значимыми обновлениями: встроенной поддержкой отправки форм через AJAX и переходом хука recaptcha с устаревшей v1 на v3.

Контекст: что было раньше

Для AJAX-отправки форм на MODX существуют отдельные компоненты — AjaxForm, SendIt и FetchIt. У каждого свои особенности: AjaxForm требует jQuery и не обрабатывает хук redirect; FetchIt работает без jQuery, но это всё равно отдельный инструмент поверх FormIt. У SendIt вообще другой подход, насколько я помню, он не использует FormIt, работает вообще самостоятельно.

Хук recaptcha в FormIt существовал давно, но работал с reCAPTCHA v1 — API, которое Google давно признал устаревшим и отключил.

Теперь обе вещи решены в самом FormIt.

AJAX из коробки

Начиная с 5.2.0, FormIt умеет отправлять формы через AJAX без каких-либо дополнительных компонентов. Он подключает свой JavaScript-файл — никаких дополнительных действий не требуется.

Для желающих есть системная настройка formit.frontend_js, если вы хотите отключить автоматическое подключение скрипта или заменить его своим файлом.

Как это работает:

• Сниппет сохраняет конфигурацию в сессии/кэше и выводит токен в плейсхолдер [[!+fi.ajaxToken]].
• Токен размещается в атрибуте data-formit-ajax-token на теге <form>.
• JS перехватывает сабмит, отправляет данные через fetch() на action.php.
• Сервер возвращает JSON с результатом, JS обновляет DOM — ошибки полей, сообщения, редирект.

Вызов сниппета не меняется — никаких дополнительных параметров для AJAX:

[[!FormIt?
    &hooks=`email,redirect`
    &emailTpl=`MyEmailChunk`
    &emailTo=`info@example.com`
    &redirectTo=`123`
    &validate=`name:required,email:email:required`
]]

Разметка формы — добавляем data-formit-ajax-token и data-formit-* на элементы ошибок:

<form action="[[~[[*id]]]]" method="post" data-formit-ajax-token="[[!+fi.ajaxToken]]">

    <div data-formit-validation-error-message>[[!+fi.validation_error_message]]</div>
    <div data-formit-success-message>[[!+fi.successMessage]]</div>

    <input type="text" name="name" value="[[!+fi.name]]" />
    <span data-formit-error="name">[[!+fi.error.name]]</span>

    <input type="text" name="email" value="[[!+fi.email]]" />
    <span data-formit-error="email">[[!+fi.error.email]]</span>

    <input type="submit" value="Отправить" />
</form>

Атрибут action остаётся как запасной вариант при отключённом JS. Без атрибута data-formit-ajax-token форма работает в обычном режиме — обратная совместимость полная.

Хук redirect теперь работает через AJAX. Сервер возвращает redirect_url в JSON-ответе, JS выполняет переход на стороне клиента. Переход можно перехватить:

document.getElementById('my-form').addEventListener('formit:redirect', function(e) {
    e.preventDefault();
    console.log('Редирект на:', e.detail.url);
});

Полный список JavaScript-событий:

Событие	Описание
formit:beforesubmit	До отправки, отменяемое
formit:success	Успешная отправка
formit:error	Ошибка валидации
formit:complete	После любого ответа
formit:redirect	До редиректа, отменяемое

Во время запроса форма получает класс formit-loading, кнопка сабмита блокируется. Можно оформить loading state в CSS:

.formit-loading {
    opacity: 0.6;
    pointer-events: none;
}

Обновление хука recaptcha: v1 → v3

В 5.2.1 хук recaptcha перешёл с reCAPTCHA v1 на v3. Главное отличие v3 — она работает полностью в фоне, без каких-либо действий от пользователя: нет чекбокса «я не робот», нет загадок с картинками. Google анализирует поведение посетителя и возвращает оценку от 0.0 до 1.0; заявки ниже установленного порога отклоняются автоматически.

Что изменилось в настройках:

Старые системные настройки recaptcha_public_key и recaptcha_private_key упразднены. Вместо них:

Настройка	Описание	По умолчанию
formit.recaptcha_site_key	Публичный ключ (site key) v3	—
formit.recaptcha_secret_key	Приватный ключ (secret key) v3	—
formit.recaptcha_min_score	Минимальная оценка для принятия (0.0–1.0)	0.5

Параметры сниппета recaptchaTheme, recaptchaJs, recaptcha_use_ssl удалены.

Добавлен параметр recaptchaAction — action для панели администратора Google (по умолчанию submit).

Подключение не изменилось:

[[!FormIt?
    &hooks=`recaptcha,email`
]]

В шаблоне формы:

[[+formit.recaptcha_html]]
[[!+fi.error.recaptcha]]

[[+formit.recaptcha_html]] выводит два скрытых поля (g-recaptcha-response и g-recaptcha-action). FormIt автоматически подключает скрипт Google и запрашивает токен при отправке.

Отдельные компоненты ReCaptchaV2 / reCaptchaV3 никуда не делись и продолжают работать — это независимые решения.

Миграция для пользователей хука recaptcha

• Получите ключи reCAPTCHA v3 на google.com/recaptcha.
• В системных настройках: вместо formit.recaptcha_public_key → formit.recaptcha_site_key, вместо formit.recaptcha_private_key → formit.recaptcha_secret_key.
• Добавьте хук recaptcha в вызов сниппета.
• Добавьте в форму плейсхолдеры [[+formit.recaptcha_html]] и [[!+fi.error.recaptcha]].

Ссылки

• CHANGELOG на GitHub
• Документация: AJAX
• Документация: хук recaptcha