FetchIt — отправка форм без перезагрузки

FetchIt — это современный, легковесный компонент для MODX Revolution, предназначенный для отправки и обработки форм с использованием нативного Fetch API. Он пришел на смену устаревшим решениям (вроде AjaxForm), обеспечивая работу форм без перезагрузки страницы и без зависимости от тяжелых библиотек, таких как jQuery.

Почему стоит выбрать FetchIt?

• Отсутствие зависимостей. Компонент работает на чистом JavaScript. Вам не нужно подключать jQuery, что ускоряет загрузку сайта и улучшает показатели PageSpeed.
• Легкость. Скрипт весит всего ~5 КБ и подключается с атрибутом defer, не блокируя рендеринг страницы.
• Гибкость. Легко интегрируется с любыми CSS-фреймворками (Bootstrap, Tailwind) и JS-библиотеками уведомлений (Notyf, SweetAlert2).
• Простота миграции. Логика работы максимально близка к AjaxForm + FormIt, что делает переход интуитивно понятным.

Установка

FetchIt доступен для бесплатной установки через «Установщик пакетов» в админке MODX. Основные источники:

• Официальный репозиторий MODX.
• Магазин дополнений modstore.pro.
• GitHub репозиторий (для ручной сборки).

Быстрый старт

Для запуска формы потребуется выполнить всего два шага: подготовить HTML-разметку (чанк) и вызвать сниппет на странице.

1. Создание чанка формы

Создайте чанк (например, tpl.MyForm) со следующей разметкой. Обратите внимание на важные атрибуты:

• У полей (input, textarea) обязательно должен быть атрибут name.
• Кнопка отправки должна иметь type="submit".
• Для вывода ошибок валидации используйте спаны с атрибутом data-error="имя_поля".

<form action="[[~[[*id]]]]" method="post">
    <div class="form-group">
        <label for="name">Имя:</label>
        <input type="text" name="name" id="name" value="[[+fi.name]]" class="form-control" required>
        <!-- Сюда FetchIt вставит текст ошибки при валидации -->
        <span class="error" data-error="name">[[+fi.error.name]]</span>
    </div>

    <div class="form-group">
        <label for="email">Email:</label>
        <input type="email" name="email" id="email" value="[[+fi.email]]" class="form-control" required>
        <span class="error" data-error="email">[[+fi.error.email]]</span>
    </div>

    <div class="form-group">
        <label for="message">Сообщение:</label>
        <textarea name="message" id="message" class="form-control" required>[[+fi.message]]</textarea>
        <span class="error" data-error="message">[[+fi.error.message]]</span>
    </div>

    <button type="submit" class="btn btn-primary">Отправить</button>
    
    <!-- Сообщения об успехе/ошибке (опционально) -->
    [[+fi.success:is=`1`:then=`<div class="alert alert-success">[[+fi.successMessage]]</div>`]]
    [[+fi.validation_error:is=`1`:then=`<div class="alert alert-danger">[[+fi.validationErrorMessage]]</div>`]]
</form>

2. Вызов сниппета

Разместите вызов FetchIt на странице, где должна быть форма. Внутри FetchIt мы вызываем стандартный FormIt для обработки почты и валидации.

[[!FetchIt?
    &snippet=`FormIt`
    &form=`tpl.MyForm`
    &hooks=`email`
    &emailSubject=`Новое сообщение с сайта`
    &emailTo=`info@mysite.com`
    &validate=`name:required,email:required:email,message:required`
    &validationErrorMessage=`Пожалуйста, исправьте ошибки в форме!`
    &successMessage=`Спасибо! Ваше сообщение успешно отправлено.`
]]

Параметры сниппета

FetchIt принимает собственные параметры для настройки поведения фронтенда, а все неизвестные параметры передает в сниппет-обработчик (по умолчанию FormIt).

JavaScript API и События

FetchIt предоставляет мощный API для взаимодействия с формой на клиенте. Вы можете перехватывать процесс отправки, модифицировать данные или выводить кастомные уведомления.

Основные события

• fetchit:before — срабатывает перед отправкой. Отличное место для дополнительной JS-валидации или добавления данных в FormData.
• fetchit:success — срабатывает при успешном ответе от сервера (success: true).
• fetchit:error — срабатывает при ошибке (валидация не прошла или ошибка сервера).

Пример 1: Добавление данных перед отправкой

document.addEventListener('fetchit:before', (e) => {
    const { form, formData } = e.detail;
    // Добавляем произвольное поле, которого нет в верстке
    formData.append('page_title', document.title);
    console.log('Форма отправляется...');
});

Пример 2: Всплывающие уведомления (Notyf)

FetchIt «из коробки» не навязывает стили уведомлений. Вы можете подключить любую библиотеку, например, Notyf.

// Подключите JS и CSS библиотеки Notyf в шаблоне заранее
const notyf = new Notyf();

document.addEventListener('fetchit:success', (e) => {
    const { response } = e.detail;
    // response.message приходит из параметра &successMessage
    notyf.success(response.message || 'Форма успешно отправлена!');
});

document.addEventListener('fetchit:error', (e) => {
    const { response } = e.detail;
    // response.message содержит &validationErrorMessage или ошибку хука
    notyf.error(response.message || 'Произошла ошибка.');
});

Обработка кастомным сниппетом

Если вам нужно обработать данные сложнее, чем это позволяет FormIt, вы можете указать свой сниппет в параметре &snippet. Внутри него доступен объект $FetchIt для возврата стандартизированных ответов.

Вызов:

[[!FetchIt?
    &form=`myForm`
    &snippet=`myCustomHandler`
]]

Сниппет myCustomHandler:

<?php
// Получаем данные
$name = $_POST['name'] ?? '';

// Простейшая проверка
if (empty($name)) {
    // Возвращаем ошибку. Второй аргумент - массив ошибок полей для подсветки
    return $FetchIt->error('Ошибка валидации', [
        'name' => 'Поле имя обязательно для заполнения'
    ]);
}

// Какая-то логика (запись в БД, API запрос...)

// Возвращаем успех
return $FetchIt->success('Все прошло отлично!', [
    'custom_data' => 'Какие-то данные для JS'
]);

Работа с файлами

FetchIt автоматически обрабатывает загрузку файлов. Вам не нужно вручную собирать объект FormData или указывать специфические заголовки — компонент сделает это сам.

Для отправки вложений:

1. Добавьте в тег формы атрибут enctype="multipart/form-data".
2. Добавьте поле <input type="file" name="attachment">.
3. В вызове сниппета не забудьте указать хук для вложений, например, стандартный email (FormIt сам обработает файлы и прикрепит их к письму, если имя поля совпадает с настройками).

<form action="[[~[[*id]]]]" method="post" enctype="multipart/form-data">
    <!-- Остальные поля -->
    <div class="form-group">
        <label>Прикрепить файл:</label>
        <input type="file" name="file" class="form-control-file">
    </div>
    <button type="submit">Отправить</button>
</form>

Миграция с AjaxForm

Если вы привыкли использовать AjaxForm, переход на FetchIt будет безболезненным. Основные отличия касаются JavaScript-событий.

Пример: Интеграция с SweetAlert2

Вы можете использовать красивые модальные окна вместо стандартных alert() или Notyf. Пример подключения SweetAlert2:

// Обработка успешной отправки
document.addEventListener('fetchit:success', (e) => {
    const { response } = e.detail;

    Swal.fire({
        title: 'Отлично!',
        text: response.message,
        icon: 'success',
        confirmButtonText: 'Закрыть'
    });
});

// Обработка ошибок
document.addEventListener('fetchit:error', (e) => {
    const { response } = e.detail;

    Swal.fire({
        title: 'Ошибка!',
        text: response.message || 'Проверьте правильность заполнения полей',
        icon: 'error',
        confirmButtonText: 'Ок'
    });
});

Заключение

FetchIt — это «золотой стандарт» для форм в современном MODX. Он избавляет ваш сайт от наследия jQuery, ускоряет загрузку страниц и предоставляет разработчику полный контроль над процессом отправки данных через удобный JS API.

Используйте его для форм обратной связи, заказа звонков, калькуляторов и любых других интерактивных элементов, где важна скорость и гибкость.