[FetchIt] - Полноценная замена AjaxForm без зависимостей

Представляю вашему вниманию новый бесплатный компонент MODX Revolution для обработки и отправки форм, который пришёл на замену AjaxForm. И давайте начнём сразу с преимуществ и различий:




FetchIt не имеет никаких зависимостей, тогда как у AjaxForm их три:

1. Большая библиотека jquery.
2. Плагин для работы с формами jquery-form.
3. И jGrowl для показа уведомлений.

Минифицированный скрипт весит 5 килобайт и сниппет регистрирует его с атрибутом defer тем самым не мешая загрузке страницы.

Встраивание вашей вёрстки, добавление всплывающих сообщений и модальных окон, это задачи которые Вы сможете решить очень просто.

Почему не AjaxForm 2.0.0?

Сразу отвечу на этот предсказуемый вопрос, ведь я в организации modx-pro и мог бы выпустить новую мажорную версию и разработчики могли бы обновиться. Причин два: во-первых это название – AjaxForm, дело в том, что аббревиатура AJAX которая расшифровывается как Asynchronous Javascript and XML для данного компонента не подходит, он для отправки форм использует Fetch API. Во-вторых, изменения большие и обратную совместимость всё равно сохранить было невозможно.

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

Для быстрого старта Вам необходимо вызвать сниппет FetchIt который идёт в компоненте, передав ему основные параметры которые совпадают по названию с параметрами AjaxForm.

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

или на fenom

{'!FetchIt' | snippet : [
  'snippet' => 'FormIt',
  'form' => 'myForm.tpl',
  'hooks' => 'email',
  'emailSubject' => 'Тема письма',
  'emailTo' => 'info@domain.com',
  'validate' => 'name:required,email:required',
  'validationErrorMessage' => 'В форме содержатся ошибки!',
  'successMessage' => 'Сообщение успешно отправлено',
]}

Миграция с AjaxForm

На сайте с документацией есть подробное описание миграции, но тут опишу вкратце. Параметры frontend_css и formSelector убраны за ненадобностью, а frontend_js и objectName были перемещены в системные настройки и называются fetchit.frontend.js и fetchit.frontend.js.classname соответственно.

Компонент не регистрирует стили. Так что вам самим нужно позаботиться о них (речь о стилях отвечающих за невалидным состоянием полей). Есть две настройки fetchit.frontend.input.invalid.class и fetchit.frontend.custom.invalid.class отвечающие за добавление классов полям ввода и кастомным элементам (например элементам-обёрткам).

Вывод всплывающих сообщений также перекладывается на плечи самих разработчиков, но реализация максимально простая и в документации уже есть подробные примеры популярных и не очень библиотек: SweetAlert2, Notyf, iziToast, Notiflix.Notify, Notie, Awesome Notifications, Toastify JS, AlertifyJS, PNotify, toastr и даже наш любимый jGrowl.

Изменились селекторы, теперь не используются CSS классы, которые предназначены для определения стилей. Вместо них дата-атрибуты. Опять же, призываю вас на сайт документации, где подробно описаны примеры типовых решений разметок Bootstrap, Bulma, UIkit, Fomantic-UI, Pico.css, Cirrus CSS, turretcss и Vanilla.

Если у вас была какая-то логика связанная с отправкой формы (Например, дополнительная отправка данных в CRM или аналитические сервисы и метрики), то нужно будет немного переписать. jQuery больше нет и у AjaxForm было одно событие на фронте, а в FetchIt их пять:

• fetchit:before
• fetchit:after
• fetchit:success
• fetchit:error
• fetchit:reset

Ниже пример в котором добавляется новое поле перед отправкой формы:

document.addEventListener('fetchit:before', (e) => {
  const { formData } = e.detail;

  formData.set('newField', 'Значение нового поля'); // Добавляем новое поле
})

или отправляем данные в CoMagic после успешной отправки формы:

document.addEventListener('fetchit:success', (e) => {
    const { formData } = e.detail;

    Comagic.addOfflineRequest({
        name: formData.get('name'),
        email: formData.get('email'),
        phone: formData.get('phone'),
        message: formData.get('message'),
        group_id: 1234
    });
})

На этом думаю пока что достаточно, как уже несколько раз было упомянуто выше, больше примеров и описание API на сайте с документацией. Компонент уже доступен для установки на маркетплейсе modstore.pro и modx.com.

Сайт с документацией
Репозиторий на GitHub
☕ Угостить чашкой кофе

(ERROR @ ...\core\cache\includes\elements\modsnippet\41.include.cache.php : 53) PHP warning: Undefined variable $hash
ERROR @ ...\core\components\fetchit\model\fetchit.class.php : 94) PHP warning: Undefined array key ""

{'!FetchIt' | snippet : [
            'snippet' => 'FormIt',
            'form' => 'tpl_form_popup',
            'emailTpl' => 'tpl_email',
            'hooks' => 'FormItSaveForm,email',
            'emailTo' => $_modx->config.email_address,
            'emailFrom' => $_modx->config.email,
            'aliases' => 'phone==Телефон,name==Имя',
            'emailSubject' => 'Заявка на консультацию с сайта',
            'validate' => 'name:required:minLength=^5^,phone:required:minLength=^17^',
            'validationErrorMessage' => 'В форме содержатся ошибки!',
            'name.vTextRequired' => 'Укажите ФИО.',
            'name.vTextMinLength' => 'Слишком короткое ФИО.',
            'phone.vTextRequired' => 'Укажите телефон.',
            'phone.vTextMinLength' => 'Слишком короткий телефон.',
            'successMessage' => 'Сообщение успешно отправлено',
            'clearFieldsOnSuccess' => 1,
        ]}