MODX Formit — документация и примеры создания форм

В данном уроке подробно разберем документацию по компоненту для отправки форм: FormIt и различные фишки к нему. И разберем пример как создать сложную форму.

Что такое FormIt?

FormIt — это MODX сниппет для обработки формы. Обрабатывает форму после нажатия на кнопку отправки: выполняет проверку и последующие действия, такие как отправка электронного письма. Он не генерирует форму, но может повторно заполнить ее, если она не прошла проверку.

Установка

Установка у него стандартная из основного репозитория MODX.

Документация

Доступные свойства (параметры)

Это доступные общие свойства для вызова FormIt (не включая специфичные для ловушки свойства):

Проверка

Проверка в FormIt выполняется через свойство &validate и может использоваться для автоматической обработки проверки в любом из полей вашей формы.

Хуки

Хуки — это в основном скрипты, которые запускаются во время обработки FormIt. Хуки всегда выполняются в порядке их появления в свойстве. Если, например, у вас есть хук электронной почты, за которым следует хук проверки, электронное письмо будет отправлено до того, как произойдет проверка.

Если какой-либо хук потерпит неудачу, последующие не будут выполнены.

Теории думаю достаточно, перейдем к практике.

Модернизация страницы контакты — оживляем форму

Открываем ресурс (документ) Контакты, который вы должны были создать в предыдущем уроке.

Там у нас есть секция с контактной формой, которая имеет следующий код:

<form action="forms/contact.php" method="post" class="php-email-form">
             <div class="row gy-4">
                <div class="col-md-6">
                  <input type="text" name="name" class="form-control" placeholder="Your Name" required>
                </div>
                <div class="col-md-6 ">
                  <input type="email" class="form-control" name="email" placeholder="Your Email" required>
                </div>
                <div class="col-md-12">
                  <input type="text" class="form-control" name="subject" placeholder="Subject" required>
                </div>
                <div class="col-md-12">
                  <textarea class="form-control" name="message" rows="6" placeholder="Message" required></textarea>
                </div>
                <div class="col-md-12 text-center">
                  <div class="loading">Loading</div>
                  <div class="error-message"></div>
                  <div class="sent-message">Your message has been sent. Thank you!</div>
                  <button type="submit">Send Message</button>
                </div>
            </div>
        </form>

Создание контактной формы на FormIt

Начнем с разметки, первым делом разметим элемент form, сейчас он выглядит так:

<form action="forms/contact.php" method="post" class="php-email-form">

Здесь в атрибуте action указан файл — php обработчик (который мы не загружали) — по идее его можно загрузить на сайт, отредактировать и использовать, но мы все будем обрабатывать при помощи FormIt. По этому в атрибуте action указываем [[~[[*id]]? &scheme=`full`]] — данная конструкция подставляет туда полную ссылку на страницу. В конечном итоге получаем:

<form action="[[~[[*id]]? &scheme=`full`]]" method="post" class="php-email-form">

Теперь апгрейдим наши поля ввода textarea и input. Разберу на примере input, он сейчас выглядит так:

<input type="text" name="name" class="form-control" placeholder="Your Name" required>

Здесь уже есть обязательный атрибут name (если в вашей форме в полях ввода его нет, то нужно добавить, например: name="phone").

По поводу кнопки отправить, она всегда должна иметь атрибут type="submit" (у нас он есть).

В принципе наш код должен работать с Formit, единственное нужно русифицировать значения в placeholder и все остальное. В конечном итоге получаем примерно следующее:

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

Теперь нам нужно создать чанк который будет отвечать за оформление данных отправляемых на email.

Создание чанка с оформлением письма

Создайте чанк с именем «tplForm» со следующим содержимым:

<p><strong>Имя</strong>: [[+name]]</p> 
<p><strong>Почта</strong>: <a href="mailto:[[+email]]">[[+email]]</a></p>
<p><strong>Тема</strong>: [[+subject]]</p> 
<p><strong>Сообщение</strong>: [[+message]]</p>

<p><strong>Имя</strong>: {$name}</p> 
<p><strong>Почта</strong>: <a href="mailto:{$email}">{$email}</a></p>
<p><strong>Тема</strong>: {$subject}</p> 
<p><strong>Сообщение</strong>: {$message}</p>

Здесь у нас обычный html с перечислением полей формы в формате [[+name_polya]]. Имена полей берем из атрибутов name (в input и textarea).

Осталось сделать вывод самого FormIt.

Вызываем FormIt

FormIt вызывается перед самой формой, вот пример минимального вызова:

[[!FormIt? 
    &hooks=`email` 
    &emailTpl=`tplForm` 
    &emailTo=`[[++emailsender]]` 
]]

{'!FormIt' | snippet : [ 
   'hooks' => 'email', 
   'emailTpl' => 'tplForm', 
   'emailTo' => $_modx->config.emailsender, 
]}

Здесь указываем:

• хук email — который отвечает за отправку формы на email;
• в emailTpl — указываем ранее созданный чанк, который отвечает за оформление письма;
• в emailTo — указываем почту, куда отправлять письма (я указал системную настройку emailsender — в которой прописан email, а так его можно и в ручную указать).

Этого достаточно чтобы форма начала отправляться. Пробуем заполнить и отправить. У меня не отправилось пока не удалил из шаблона подключение js валидатора:

<script src="/assets/vendor/php-email-form/validate.js"></script>

После этого форма начала отправляться:

Минусы минимального вызова следующие:

• После отправки формы не понятно что-то отправилось или нет (пользователь не поймет отправилась форма или нет).
• Форму можно отправить и пустой (если убрать атрибуты required).

Поэтому давайте сделаем обязательные поля, добавим вывод ошибок, сделаем валидацию и уведомим пользователя что форма отправлена.

Добавим ко всем нашим полям формы input и textarea (над ними или под ними) вот такие конструкции:

<span class="error">[[!+fi.error.name_polya]]</span>

А вот эту разметку вывода ошибок и сообщений:

<div class="loading">Загрузка</div>
<div class="error-message"></div>
<div class="sent-message">Ваше сообщение было отправлено. Спасибо!</div>

Можно удалить, и вместо нее поместить параметры successMessage и  validationErrorMessage:

[[+fi.validation_error_message]]
[[+fi.successMessage]]

{$fi.successMessage} 
{$fi.validation_error_message}

И перепишем вызов формит так:

[[!FormIt?
&hooks=`email`
&validate=`name:required:maxLength=^21^,email:email:required,subject:required,message:required:minLength=^30^`
&emailTpl=`tplForm`
&emailTo=`[[++emailsender]]`
&emailSubject=`Сообщение со страницы контакты на сайте [[++site_url]]`
&successMessage=`<div class="sent-message">Ваше сообщение было отправлено. Спасибо!</div>`
&validationErrorMessage=`<div class="error-message">Произошла ошибка при отправке вашего сообщения.</div>`
]]

{'!FormIt' | snippet : [ 
    'hooks' => 'email', 
    'validate' => 'name:required:maxLength=^21^,email:email:required,subject:required,message:required:minLength=^30^',
    'emailTpl' => 'tplForm', 
    'emailTo' => $_modx->config.emailsender, 
    'emailSubject' => 'Сообщение со страницы контакты на сайте' ~ $_modx->config.site_name,
    'successMessage' => '<div class="sent-message">Ваше сообщение было отправлено. Спасибо!</div>',
    'validationErrorMessage' => '<div class="error-message">Произошла ошибка при отправке вашего сообщения.</div>'
]}

Краткий разбор всего вышеописанного:

В вызове formIt появился параметр validate — в нем я перечислил поля в формате «Имя_поля:параметр:параметр». Давайте пробежимся по указанным параметрам:

• required — поле обязательно для заполнения (html атрибут required, боты научились обходить);
• minLength=^30^ — минимальное количество вводимых символов должно быть не меньше 30 (данный html атрибут б;
• maxLength=^21^ — максимальное количество вводимых символов должно быть не более 21;
• email — вводимый тип email.

К стати бывают глюки с отправками форм, когда в html разметке, у инпута указан тип email. Поэтому рекомендую поменять type="email", на type="text".

Параметры:

• emailFrom — это email с которого отправляется форма;
• emailSubject — тепа письма (которое к вам отправляется);
• successMessage — сообщение которое выводиться после успешной отправки формы.
• validationErrorMessage- сообщение которое выводиться если форма не отправлена.

Конечный код формы будет следующим:

<form action="[[~[[*id]]? &scheme=`full`]]" method="post" class="php-email-form">
    <div class="row gy-4">
        <div class="col-md-6">
            <input type="text" name="name" class="form-control" placeholder="Ваше Имя">
            <span class="error">[[!+fi.error.name]]</span>
        </div>
        <div class="col-md-6 ">
            <input type="email" class="form-control" name="email" placeholder="Ваш Email">
            <span class="error">[[!+fi.error.email]]</span>
        </div>
        <div class="col-md-12">
            <input type="text" class="form-control" name="subject" placeholder="Тема">
            <span class="error">[[!+fi.error.subject]]</span>
        </div>
        <div class="col-md-12">
            <textarea class="form-control" name="message" rows="6" placeholder="Сообщение"></textarea>
            <span class="error">[[!+fi.error.message]]</span>
        </div>
        <div class="col-md-12 text-center">
            [[+fi.validation_error_message]]
            [[+fi.successMessage]]
            <button type="submit">Отправить сообщение</button>
        </div>
    </div>
</form>

<form action="{$_modx->makeUrl($_modx->resource.id, '', '', 'full')}" method="post" class="php-email-form">
    <div class="row gy-4">
        <div class="col-md-6">
            <input type="text" name="name" class="form-control" placeholder="Ваше Имя">
            <span class="error">{$fi.error.name}</span>
        </div>
        <div class="col-md-6 ">
            <input type="email" class="form-control" name="email" placeholder="Ваш Email">
            <span class="error">{$fi.error.email}</span>
        </div>
        <div class="col-md-12">
            <input type="text" class="form-control" name="subject" placeholder="Тема">
            <span class="error">{$fi.error.subject}</span>
        </div>
        <div class="col-md-12">
            <textarea class="form-control" name="message" rows="6" placeholder="Сообщение"></textarea>
            <span class="error">{$fi.error.message}</span>
        </div>
        <div class="col-md-12 text-center">
            {$fi.validation_error_message}
            {$fi.successMessage}
            <button type="submit">Отправить сообщение</button>
        </div>
    </div>
</form>

Из самого основного все, теперь давайте протестируем работоспособность. Для этого откройте страницу контактов в режиме инкогнито и попробуйте сначала заполнить к примеру только имя (я убрал из разметки input атрибут required) и отправить форму. Должны выйти ошибки валидации.

И заполните форму полностью, при успешной отправке увидим наше сообщение, об успешной отправке:

Чтобы появлялись цветные плашки  перед кнопкой отправить (как на сриншотах выше), уберите в CSS их скрытие (display: none;):

До этого их менял JS валидатор, который мы удалили.

Дополнительно — для создания более сложных форм или просто смены логики

Сохранение форм в административной панели MODX

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

Чтобы хук заработал нам его нужно указать в вызове, а также заполнить дополнительные параметры formName — название формы, formFields — перечисление полей для сохранения и fieldNames — делаем поля русскими. Пример для нашей формы указанной выше:

&hooks=`email,FormItSaveForm`
&formName=`Контакты`
&formFields=`name,email,subject,message`
&fieldNames=`name==Имя,email==Электронная почта,subject==Тема,message==Сообщение`

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

<form action="" method="post">
    <input type="email" name="email">
    <input type="submit" value="Subscribe">
</form>

Модернизируем ее с учетом информации выше, получим:

[[!FormIt?
    &hooks=`email,FormItSaveForm`
    &validate=`email:email:required`
    &formName=`Форма подписки`
    &formFields=`email`
    &fieldNames=`email==Электронная почта`
    &emailTpl=`tplForm`
    &emailTo=`[[++emailsender]]`
    &emailSubject=`Новый подписчик с сайта [[++site_url]]`
    &successMessage=`<div class="sent-message">Спасибо за доверие!</div>`
]]
<form action="[[~[[*id]]? &scheme=`full`]]" method="post">
    <input type="email" name="email">
    <span class="error">[[!+fi.error.email]]</span>
    <input type="submit" value="Подписываться">
    [[+fi.successMessage]]
</form>

Проверяем. Формы сохраняются в Пакеты — Formit.

Как использовать 1 обработчик для всех форм на сайте

Чтобы не создавать для разных форм свои обработчики, я обычно все поля дописываю в данный обработчик, но у же с модификатором модификатором empty или if (на fenom).

Пример empty:

[[+phone:!empty=`<p><strong>Телефон</strong>: [[+phone]]</p>`]]

Пример if на fenom:

{if $phone?}<p><strong>Телефон</strong>: {$phone}</p>{/if}

В принципе можно прям все поля в обработчике завернуть в  одно из этих условий.

Как скрыть форму после успешной отправки.

Хотите скрыть форму после успешной отправки сообщения, оберите ее в конструкцию [[!+fi.successMessage:default=`код формы <form .... </form>`]]. Соответственно [[+fi.successMessage]] нужно удалить.

Перестало работать в formit 4.2.7 может и в чуть более старых версиях, возможно поправят в новых версиях компонента.

Перенаправление после успешной отправки на другую страницу

Используйте для этого хук redirect.

&hooks=`email,redirect`
&redirectTo=`12`

Где 12 — это id ресурса на который нужно перенаправить пользователя.

Примечание! Тогда из вызова формы выше можно (нужно) удалить параметр successMessage .

Прикрепление файлов к форме

Для того чтобы была возможность прикреплять и отправлять вложения, необходимо в тег формы прописать enctype=»multipart/form-data».

<form class="form-contact contact_form" action="[[~[[*id]]? &scheme=`full`]]" method="post" enctype="multipart/form-data">

Соответственно добавить поля для прикрепления файла.

<div class="control-group form-group"> 
   <label for="upload">Прикрепить файл</label>
   <input type="file" name="upload"> 
</div>

И прописать в чанке оформления письма (tplForm) данное поле.

[[+upload:!empty=`<p><strong>Вложение</strong>: [[+upload]]</p>`]]

Как в FORMit передать название и url адрес страницы

Для того чтобы в форме получить Название страницы и ее адрес — удобно когда есть сквозные формы (например заказ звонка в шапке сайта). В форме выведете 2 скрытых поля:

<input type="hidden" name="pagetitle" value="[[*pagetitle]]">

<input type="hidden" name="urladress" value="[[~[[*id]]? &scheme=`full`]]">

После чего в чанке оформления письма (tplForm), добавьте следующую строку.

<p><strong>Страница, с которой отправлена форма</strong>: <a href="[[+urladress]]" target="_blank">[[+pagetitle]]</a></p>

Маска ввода для полей телефон, дата, время

Для этого подключаем к сайту jquery (если не подключен) и maskedinput (подключается внизу сайта)

<script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.maskedinput/1.4.1/jquery.maskedinput.js"></script>

Далее прописываем для полей телефон, дата и время id=»name», пример.

<input type="text" name="phone" id="phone" class="form-control">
<input type="text" value="[[+fi.date]]" name="date" id="date" class="form-control">
<input type="text" value="[[+fi.cloc]]" name="cloc" id="cloc" class="form-control">

Далее инициализируем maskedinput

<script>
    $(function() {
        $("#date").mask("99.99.9999");
        $("#phone").mask("+7(999) 999-9999");
        $("#cloc").mask("99:99");
    });
</script>

А если нужна простенькая маска ввода только для телефона и без каких либо зависимостей, лучше использовать маску из урока: Маска ввода телефона в input на чистом JS.

Обработка checkbox

Для того чтобы FormIt начал обрабатывать чекбоксы, необходимо к атрибуту name в конце добавить [], пример:

<p class="h4">Виды работ*</p>
<div class="form-group form-check">
    <input type="checkbox" class="form-check-input" name="kopka_kolodca[]">
    <label class="form-check-label">Копка колодца</label>
</div>
<div class="form-group form-check">
    <input type="checkbox" class="form-check-input" name="chistka_kolodca[]">
    <label class="form-check-label">Чистка колодца</label>
</div>

а в чанке tplForm выводим его так:

[[+kopka_kolodca:!empty=`<p><strong>Вид работы</strong>: Копка колодца</p>`]]

[[+chistka-kolodca:!empty=`<p><strong>Вид работы</strong>: Чистка колодца</p>`]]

Базовая защита от спама — использование пустого поля NoSpam

Часто спам-боты заполняют каждое поле формы, чтобы пройти проверку. Таким образом, хорошим способом предотвращения спама является добавление поля в форму и требование, чтобы оно было пустым для успешной отправки.

Добавьте в форму поле

<input type="hidden" name="workemail" value="" />

Затем в вызове, в validate укажите через запятую после email значение workemail:blank

&validate=`email,workemail:blank`

Внимание! Если на страницах сайта по несколько форм, лучше использовать связку Formit + AjaxForm

FormIt не работает — не отправляет письма, как исправить?

Давайте разберем самые типовые проблемы, почему формы не отправляться.

Проверка возможности отправки почты

Первым делом установите из общего репозитория дополнение Console и проверьте в саму возможность отправки почты, выполнив два отдельных кода:

1. Просто через функцию mail(): print (int)mail('test@some.host', 'subject', 'message');

2. Через MODX: print (int)$modx->user->sendEmail('message');

Желательно, чтобы оба варианта вернули 1. Если оба кода возвращают не единицу, пишите хостеру и ругайтесь с ним, либо попробуйте настроить отправку почты через SMTP.

Возможности отправки почты работает, но FormIt все равно не отправляет письма

В данном случае уже может быть множество проблем: встроенные в шаблон скрипты валидаций, ошибки в коде, в настройках и т.д.

Для начала обновите FormIt (Пакеты — Установщик — проверить обновления — обновить (если пакет не актуальный)).

Создайте любую страницу (ресурс) с пустым шаблоном, отключите у него html редактор и в поле содержимое поместите самую примитивную html разметку с простеньким вызовом formit:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <title>Тест формы</title>
</head>
<body>
[[!FormIt?
&hooks=`email`
&emailTpl=`testForm`
&emailTo=`ваш_email`
&emailFrom=`mail@ваш_домен`
&successMessage=`<h2>Отправлено</h2>`
]]
[[!+fi.successMessage:default=``]]
<form action="[[~[[*id]]]]" method="post">
    <input type="text" name="text" placeholder="Введите любой текст" value="[[!+fi.text]]" />
    <input type="submit" value="Отправить" />
</form>
[[!+fi.validation_error_message:notempty=`<p>[[!+fi.validation_error_message]]</p>`]]
</body>
</html>

Соответственно замените значения ваш_email и ваш_домен на свои. Создайте чанк testForm со следующим содержимым: <p><strong>Текст</strong>: [[+text]]</p> и попробуйте отправить форму.

Если после отправки увидите сообщение, что оправлено

а в почте письмо не видите, проверьте в первую очередь папку со спамом. Если и там письма нет, то попробуйте указать другой ящик (особенно если вы пользуйтесь почтой от mail.ru (bk, list)), например от google или яндекс. Так же бывает такое, что хостеры не хотят отсылать почту на сторонние сервисы, поэтому также можно попробовать создать на хостинге почту типа admin@ваш_домен и указать ее. И заново отправить форму и снова проверить отправку.

Если помогло, попробуйте перенести свой вызов формы на эту страницу (доработав данный вызов и форму) и снова отправить ее — не отправилась ищите ошибки в вызове. Если все отправляется с этой страницы, а со страницы с полноценным шаблоном нет — копайте в сторону js скриптов.

Если вообще не чего не отравляется (даже с базовой формы с рекомендациями описанными выше). Первым делом идем в логи (Управление — Отчеты — Журнал ошибок) и смотрим их. Если там пусто, можете попробовать альтернативный вариант: проверять отправку почты с помощью дополнения QuickEmail:

[[!QuickEmail?
    &to=`my-mail@mydomain.ru`
    &debug=`1`
]]

Не смогли решить проблему: опишите ее в комментариях: что в логах, пришлите сам вызов с формной и т.д. Попробую вам помочь.

Смотрите также

• Официальные уроки и примеры работы с formit;
• все стандартные хуки formit.
• Борьба со спамом: без капч и при помощи recaptcha от google.

Как я уже говорил выше, когда у вас много форм на странице и шаблон использует — лучше использовать FormIt в связке с Ajaxform (о нем и поговорим в следующем уроке). А затем сделаем хлебные крошки — чтобы наш шаблон выглядел как оригинал.