Modx formit error message

Что такое FormIt?¶

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

История¶

FormIt был написан Shaun McCormick как Компонент для обработки форм и впервые выпущен 19 октября 2009 г. В настоящее время поддерживается командой Sterc.

Скачать¶

Formit можно загрузить из Менеджера MODX Revolution через Управление пакетами или из репозитория MODX здесь: https://modx.com/extras/package/formit.

Разработка и ошибки¶

FormIt хранится и разрабатывается в GitHub, и его можно найти здесь: https://github.com/Sterc/FormIt

Здесь можно писать об ошибках: https://github.com/Sterc/FormIt/issues

Документацию по API также можно найти здесь: https://api.modx.com/formit/

Важные изменения¶

FormIt 3.0 представляет обновление методов шифрования, используемых для шифрования отправленных форм. До версии 3.0 использовался mcrypt, который в версии 3.0 заменен на openssl из-за того, что mcrypt устарел с версии PHP 7.2. FormIt 3.0 поставляется со страницей миграции, доступной из Менеджера.

Начиная с FormIt 2.2.9, ко всем полям автоматически применяется html_entities. Чтобы разрешить сохранение HTML-тегов, вам нужно будет использовать валидатор allowSpecialChars для каждого поля, который должен сохранять необработанные html-теги.

Начиная с FormIt 1.1.4, ко всем полям будут автоматически применяться stripTags. Чтобы разрешить сохранение HTML-тегов, вам нужно будет использовать валидатор allowTags для каждого поля, определяя, какие теги разрешены.

Как использовать¶

Просто поместите вызов Сниппета FormIt в Ресурс, содержащий форму, которую вы хотите использовать. В отличие от аналогичных предшественников (особенно eForm в MODX Evolution), вы не помещаете форму в Чанк и не ссылаетесь на него в вызове сниппета FormIt: вы буквально помещаете вызов Сниппета рядом с формой, которую хотите обработать. Укажите «hooks» (или сценарии обработки после проверки) в вызове Сниппета. Затем добавьте проверку с помощью параметров &validate и &customValidators.

Если у вас есть несколько форм на странице, установите для свойства &submitVar в вызове Cниппета имя элемента формы (например, &submitVar = form1-submit). Это указывает FormIt обрабатывать запросы формы только, если в переданных полях формы (POST) есть эта переменная. Если у вас на одной странице несколько форм, обрабатываемых Formit, следует использовать теги с INPUT type = «submit» name = «form1-submit», элементы button работать не будут.

Доступные свойства¶

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

Валидация¶

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

Для получения дополнительной информации о проверке в FormIt смотрите Валидаторы.

Хуки¶

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

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

Для получения дополнительной информации о хуках смотрите Хуки.

Посмотрите также¶

1. Хуки
   1. FormIt.Hooks.email
   2. FormIt.Hooks.FormItAutoResponder
   3. FormIt.Hooks.math
   4. FormIt.Hooks.recaptcha
   5. FormIt.Hooks.redirect
   6. FormIt.Hooks.spam
   7. FormIt.Hooks.FormItSaveForm
2. Валидаторы
3. FormItRetriever
4. Руководства и примеры
   1. Пользовательский произвольный хук
   2. Пример простой формы
   3. Обработка выпадающих списков, чекбоксов и радио кнопок
   4. Использование пустого поля для защиты от спама
5. FormItCountryOptions
6. FormItStateOptions

Open COllective

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$307 per month—let’s make that $500!

Learn more

What is FormIt?¶

FormIt is a dynamic form processing Snippet for MODX Revolution. It handles a form after submission, performing validation and followup actions like sending an email. It does not generate the form, but it can repopulate it if it fails validation.

History¶

FormIt was written by Shaun McCormick as a form processing Extra, and first released on October 19th, 2009. It is currently maintained by the team at Sterc.

Download¶

It can be downloaded from within the MODX Revolution manager via Package Management, or from the MODX Extras Repository, here: https://modx.com/extras/package/formit

Development and Bug Reporting¶

FormIt is stored and developed in GitHub, and can be found here: https://github.com/Sterc/FormIt

Bugs can be filed here: https://github.com/Sterc/FormIt/issues

API Documentation can also be found here: http://api.modx.com/formit/

Important changes¶

FormIt 3.0 introduces an update to the encryption methods used for encrypting form submissions. Prior to 3.0 mcrypt was used, which in 3.0 is replaced with openssl, due to mcrypt being deprecated as of PHP 7.2. FormIt 3.0 comes with a migration page which is accessible from the manager.

As of FormIt 2.2.9, all fields will automatically have html_entities applied. To allow HTML tags to be saved/stored, you will need to use the allowSpecialChars validator on each field, that should save raw html tags.

As of FormIt 1.1.4, all fields will automatically have stripTags applied. To allow HTML tags to be saved/stored, you will need to use the allowTags validator on each field, stipulating which tags are permitted.

How to Use¶

Simply place the FormIt snippet call into the Resource that contains the form you want to use. Unlike similar predecessors (most notably eForm in MODX Evolution), you do not put the form into a Chunk and reference the Chunk in the FormIt snippet call: you literally put the snippet call along side the form you want it to process. Specify the «hooks» (or post-validation processing scripts) in the snippet call. Then add validation via the &validate and &customValidators parameters in the snippet tag.

If you have multiple forms on a page, set the &submitVar property on your Snippet call to a name of a form element within the form (ie, &submitVar=`form1-submit` ). This tells FormIt to only process form requests with that POST variable. Multiple forms should be used with INPUT type=»submit» name=»form1-submit», button elements have been reported not working.

Available Properties¶

These are the available general properties for the FormIt call (not including hook-specific properties):

Validation¶

Validation in FormIt is done via the &validate property, and can be used to automatically handle validation on any of the fields in your form.

For more information on validation in FormIt, see the Validators page.

Hooks¶

Hooks are basically scripts that run during FormIt processing. The hooks always execute in the order they appear in the property. If, for example, you have an email hook followed by a validation hook, the email will be sent before the validation occurs.

If any hook fails, the ones following it will not execute.

For more information on hooks, see the Hooks page.

See Also¶

1. FormIt.Hooks
   1. FormIt.Hooks.email
   2. FormIt.Hooks.FormItAutoResponder
   3. FormIt.Hooks.math
   4. FormIt.Hooks.recaptcha
   5. FormIt.Hooks.redirect
   6. FormIt.Hooks.spam
   7. FormIt.Hooks.FormItSaveForm
2. FormIt.Validators
3. FormIt.FormItRetriever
4. FormIt.Tutorials and Examples
   1. FormIt.Examples.Custom Hook
   2. FormIt.Examples.Simple Contact Page
   3. FormIt.Handling Selects, Checkboxes and Radios
   4. FormIt.Using a Blank NoSpam Field
5. FormIt.FormItCountryOptions
6. FormIt.FormItStateOptions

Open COllective

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$307 per month—let’s make that $500!

Learn more

В этой статье рассмотрим процесс создания формы обратной связи на MODX с использованием FormIt. А также работу с ней через Ajax посредством AjaxForm.

В репозитории MODX имеется очень популярное дополнение для динамической обработки форм. Называется оно FormIt.

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

Установить пакет FormIt можно из главного репозитория modx.com/extras/package/formit.

Пример простой формы обратной связи на FormIt

В этом примере создадим простую HTML форму с использованием Bootstrap 5. Она будет состоять из 3 полей: имя, email и сообщение. FormIt будет выполнять валидацию формы и отправлять сообщение с данными, которые ввел пользователь, на email.

Вызов сниппета FormIt:

[[!FormIt?
  &emailFrom=`[[++emailsender]]`
  &emailTo=`alexander@mail.com`
  &emailTpl=`myEmailTpl`
  &hooks=`email`
  &submitVar=`feedback-form`
  &successMessage=`Форма успешно отправлена!`
  &validate=`nospam:blank,
    name:required,
    email:email:required,
    message:required:minLength=^20^`
]]

Список используемых параметров:

• hooks – список скриптов, которые нужно выполнить после успешной валидации формы; скрипты будут запускаться последовательно друг за другом; если какой-то скрипт завершится не удачно, то следующие за ним выполняться не будут;
• validate – список полей, которые нужно проверить на соответствии указанным требованиям; можно указать несколько валидаторов, например, как это сделано для email;
• submitVar – необходим, чтобы этот вызов сниппета FormIt обрабатывал не все формы, а только те, которые содержат указанный ключ в составе передаваемых на сервер данных (в суперглобальном массиве $_POST);
• successMessage – сообщение, которое необходимо вывести после успешного завершения обработки формы; работает, только если не используется свойство для редиректа;
• emailTpl – чанк, содержащий шаблон email письма;
• emailTo – адрес, на который нужно отправить email;
• emailFrom – адрес, от которого будет отправлен email; в этом примере email будем брать из системного параметра emailsender;
• emailSubject – тема письма.
• validationErrorMessage – сообщение, которое нужно вывести, если в форме содержатся ошибки.

Работает FormIt следующим образом:

1. Получает данные формы. Так как в вызове сниппета FormIt, мы указали свойство submitVar, то этот сниппет будет обрабатывать только ту форму, которая будет передавать в теле запроса этот ключ. Его мы добавили к кнопке type="submit".

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

Валидатор blank проверяет, является ли поле пустым. В данном примере мы проверяем с помощью него поле nospam:

nospam:blank

Кроме blank в этом примере ещё используются следующие валидаторы:

• required – проверяет, является ли поле не пустым;
• email – содержит ли поле корректный адрес электронной почты;
• minLength – требование, к минимальному количеству символов.

Например, для проверки поля email мы используем 2 валидатора:

email:email:required

Таким образом это поле должно быть не пустым и содержать корректный email.

Если какие-то поля не прошли валидацию, то ошибки будут выведены в соответствующие плейсхолдеры. Например, для поля email это будет:

[[+fi.error.email]]

3. Выполнение хуков. После успешной валидации будут последовательно друг за другом выполнены скрипты, указанные в hooks.

В приведённом примере мы используем в hooks только один скрипт: email. Он отправит форму на email. Шаблон для этого письма он возьмёт из чанка, заданного в emailTpl. А отправит он письмо на email, указанный в свойстве emailTo.

4. Вывод сообщения об успехе. После успешного завершения хука email будет выведено в плейсхолдер fi.successMessage сообщение, указанное в свойстве successMessage.

HTML код формы:

[[!+fi.successMessage:notempty=`<div class="alert alert-success" role="alert">[[!+fi.successMessage]]</div>`]]
<form action="[[~[[*id]]]]" method="post" class="form">
  <input type="hidden" name="nospam" id="nospam" value="">
  <div class="mb-3">
    <label for="name" class="form-label">Name</label>
    <input type="text" class="form-control[[!+fi.error.name:notempty=` is-invalid`]]" name="name" id="name" value="[[!+fi.name]]">
    <div class="invalid-feedback">[[!+fi.error.name]]</div>
  </div>
  <div class="mb-3">
    <label for="email" class="form-label">Email</label>
    <input type="email" class="form-control[[!+fi.error.email:notempty=` is-invalid`]]" name="email" id="email" value="[[!+fi.email]]">
    <div class="invalid-feedback">[[!+fi.error.email]]</div>
  </div>
  <div class="mb-3">
    <label for="phone" class="form-label">Phone</label>
    <input type="tel" class="form-control[[!+fi.error.phone:notempty=` is-invalid`]]" name="phone" id="phone"
        value="[[!+fi.phone]]">
    <div class="invalid-feedback">[[!+fi.error.phone]]</div>
  </div>
  <div class="mb-3">
    <label for="message" class="form-label">Message</label>
    <textarea class="form-control[[!+fi.error.message:notempty=` is-invalid`]]" name="message" id="message"
        rows="5">[[!+fi.message]]</textarea>
    <div class="invalid-feedback">[[!+fi.error.message]]</div>
  </div>
  <div class="mb-3">
    <input type="submit" class="btn btn-primary" name="feedback-form" value="Отправить">
  </div>
</form>

Оформление формы выполнено на Bootstrap 5.

Скрытое поле nospam используется для защиты от спама. Обычно спам боты пытаются заполнить все поля, а это поле должно быть пустым. Если поле nospam не пустое, то форма не пройдёт проверку и её дальнейшая обработка выполняться не будет.

Сниппет FormIt будет заполнять в форме заданные плейсхолдеры. Например, для поля email:

• fi.email – значением поля email;
• fi.error.email – сообщением об ошибке при валидации.

Выделение полей, которые не прошли валидацию, выполняется посредством добавления к ним класса is-invalid. Например, для поля email это будет выглядеть так:

[[!+fi.error.email:notempty=` is-invalid`]]

Т.е. когда плейсхолдер fi.error.email не пустой, у элемента <input> появится класс is-invalid.

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

[[!+fi.successMessage:notempty=`<div class="alert alert-success" role="alert">[[!+fi.successMessage]]</div>`]]

Она работает очень просто: если плейсхолдер fi.successMessage что-то содержит, то выведи HTML блок с содержимым [[!+fi.successMessage]]:

<div class="alert alert-success" role="alert">[[!+fi.successMessage]]</div>

Этот HTML блок является компонентом Alert фреймворка Bootstrap.

В теге <form> для атрибута action укажем URL на эту же страницу:

<form action="[[~[[*id]]]]" method="post">

Содержимое чанка myEmailTpl:

<p style="font-weight: bold;">Сообщение с формы обратной связи.</p>
<p><mark>[[+name]]</mark> (email: <mark>[[+email]]</mark>, phone: <mark>[[+phone:default=`-`]]</mark>) оставил следующее сообщение:</p>
<p style="background-color: #eee; padding: 15px;">[[+message]]</p>

Отправка формы через AJAX

По умолчанию FormIt не умеет работать с формой через AJAX. Но в репозитории modstore.pro имеется дополнение AjaxForm, которое позволяет отправлять формы через AJAX. По умолчанию оно работает с FormIt. Но при необходимости вместо FormIt можно использовать собственный сниппет.

При использовании AjaxForm работа с формой будет осуществляться следующим образом:

1. вывод HTML формы будет осуществляться из чанка, который передан AjaxForm в свойстве form;
2. отправка форма выполняется через AJAX, для этого сниппет AjaxForm регистрирует на фронтенде нужные скрипты;
3. на сервере запускает сниппет FormIt и передаёт ему данные формы;
4. после получения ответа от FormIt передаёт его браузеру, который выводится пользователю на страницу с использованием JavaScript.

Перед тем как начать переделывать форму проверим установлено ли у нас расширение AjaxForm.

Ход работы:

1. Создадим чанк myFormTpl и вставим в него HTML код формы.

AjaxForm вывод сообщений об ошибках, например, для поля email, осуществляет в элемент с классом error_mail. Кроме этого, к полям, которые не прошли валидацию добавляет класс error.

Но нас это не устраивает, т.к. сообщения об ошибке нужно помещать в элемент с классом invalid-feedback, а к полям, которые не прошли проверку необходимо добавлять класс is-invalid.

Это мы будем выполнять с помощью JavaScript при получении ответа от сервера:

$(document).on('af_complete', function (event, response) {
  const elForm = $(response.form);
  elForm.find('.is-invalid').each(function (index, el) {
    $(el).removeClass('is-invalid');
  });
  for (let key in response.data) {
    const elInput = elForm.find(`[name=${key}]`);
    elInput.addClass('is-invalid');
    elInput.next('.invalid-feedback').text($(response.data[key]).text());
  }
});

После этого из формы необходимо удалить плейсхолдеры [[!+fi.name]], [[!+fi.error.name]] и др. Они используются в качестве заполнителей для сниппета FormIt и позволяют нам сохранять значения, введённые пользователем и отображать ошибки валидации. Но так как сейчас работа ведётся через AJAX, то они нам не нужны.

В итоге HTML форма будет иметь следующий код:

<form action="#" method="post" class="feedback-form">
  <input type="hidden" name="nospam" id="nospam">
  <div class="mb-3">
    <label for="name" class="form-label">Имя</label>
    <input type="text" class="form-control" name="name" id="name">
    <div class="invalid-feedback"></div>
  </div>
  <div class="mb-3">
    <label for="email" class="form-label">Email</label>
    <input type="email" class="form-control" name="email" id="email">
    <div class="invalid-feedback"></div>
  </div>
  <div class="mb-3">
    <label for="message" class="form-label">Сообщение</label>
    <textarea class="form-control" name="message" id="message" rows="3"></textarea>
    <div class="invalid-feedback"></div>
  </div>
  <div class="mb-3">
    <input type="submit" class="btn btn-primary" name="feedback-form" value="Отправить">
  </div>
</form>

2. Добавим в нужный ресурс или шаблон вызов сниппета AjaxForm и скрипт:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
[[AjaxForm?
  &form=`myFormTpl`
  &formSelector=`feedback-form`
  &emailTpl=`myEmailTpl`
  &emailTo=`alexander@gmail.com`
  &hooks=`email`
  &successMessage=`Форма успешно отправлена!`
  &validationErrorMessage=`В форме содержатся ошибки!`
  &submitVar=`feedback-form`
  &validate=`nospam:blank,
    name:required,
    email:email:required,
    message:required:minLength=^20^`
]]
<script>
  $(document).on('af_complete', function(event, response) {
    const elForm = $(response.form);
    elForm.find('.is-invalid').each(function(index, el) {
      $(el).removeClass('is-invalid');
    });
    for (let key in response.data) {
      const elInput = elForm.find(`[name=${key}]`);
      elInput.addClass('is-invalid');
      elInput.next('.invalid-feedback').text($(response.data[key]).text());
    }
  });
</script>

Свойство form в вызове сниппета AjaxForm указывает чанк, в котором содержится HTML форма. Остальные свойства данный сниппет просто передаёт FormIt.

Скрипт необходим для установки не валидным полям класса is-invalid и вставки сведений об ошибках в элементы .invalid-feedback. Кроме этого JavaScript файлы, которые регистрирует AjaxForm во фронтенде, написаны с использованием библиотеки jQuery. Поэтому её нужно подключить.

Дополнительно

1. Редирект на другую страницу после успешной обработки формы.

Перенаправить пользователя на другую страницу после успешной отправки формы можно с помощью хука redirect:

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

Указание ресурса, на который необходимо перенаправить пользователя осуществляется с помощью свойства redirectTo. В данном примере пользователь будет перенаправлен на ресурс, который имеет в качестве id значение 7.

2. Сохранение данных формы в базу данных.

Сохранить отправленные формы в базу данных можно с помощью хука FormItSaveForm:

&hooks=`email,FormItSaveForm`
&formName=`Форма обратной связи`
&formFields=`name,email,message`
&fieldNames=`name==Имя,email==Email,message==Сообщение`

Свойства:

• formName – название формы. По умолчанию: "form-{resourceid}";
• formFields – список полей, которые следует сохранить. По умолчанию: все поля, включая кнопку submit;
• fieldNames – позволяет задать отображение полей на форме в менеджере.

3. Добавление в форму заголовка и URL страницы

Добавить в форму дополнительные данные, например заголовок страницы и её URL, можно с помощью скрытых полей:

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

Для отправки этой информации на email добавьте в шаблон письма:

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

4. Обработка полей select

Для обработки <select> FormIt предоставляет фильтр вывода FormItIsSelected. Он устанавливает атрибут selected, если значение <option> соответствует выбранной:

<div class="mb-3">
  <label for="color" class="form-label">Цвет</label>
  <select class="form-select[[!+fi.error.color:notempty=` is-invalid`]]" name="color" id="color" value="[[!+fi.color]]">
    <option value="" selected disabled>Выберите цвет</option>
    <option value="Красный" [[!+fi.color:FormItIsSelected=`Красный`]]>Красный</option>
    <option value="Оранжевый" [[!+fi.color:FormItIsSelected=`Оранжевый`]]>Оранжевый</option>
    <option value="Желтый" [[!+fi.color:FormItIsSelected=`Желтый`]]>Желтый</option>
  </select>
  <div class="invalid-feedback">[[!+fi.error.color]]</div>
</div>

5. Обработка чекбоксов и радиокнопок

FormIt для обработки type="checkbox" и type="radio" предоставляет фильтр FormItIsChecked аналогичный FormItIsSelected.

Это пример с чекбоксами:

<div class="mb-3">
  <div class="form-check">
    <input type="checkbox" class="form-check-input [[!+fi.error.colors:notempty=` is-invalid`]]" name="colors[]" id="colors-red" value="Красный" [[!+fi.colors:FormItIsChecked=`Красный`]]>
    <label class="form-check-label" for="colors-red">Красный</label>
  </div>
  <div class="form-check">
    <input type="checkbox" class="form-check-input [[!+fi.error.colors:notempty=` is-invalid`]]" name="colors[]" id="colors-orange" value="Оранжевый" [[!+fi.colors:FormItIsChecked=`Оранжевый`]]>
    <label class="form-check-label" for="colors-orange">Оранжевый</label>
  </div>
  <div class="form-check">
    <input type="checkbox" class="form-check-input [[!+fi.error.colors:notempty=` is-invalid`]]" name="colors[]" id="colors-yellow" value="Желтый" [[!+fi.colors:FormItIsChecked=`Желтый`]]>
    <label class="form-check-label" for="colors-yellow">Желтый</label>
  </div>
  <input type="hidden" class="[[!+fi.error.colors:notempty=` is-invalid`]]" name="colors[]" value="">
  <div class="invalid-feedback">[[!+fi.error.colors]]</div>
</div>

Если colors должно быть обязательным, то нужно добавить «скрытое» поле, как это показано в примере выше. После этого в свойство validate добавить colors:required:

[[!FormIt?
  ...
  &validate=`...
    colors:required`
]]

In this tutorial we will discuss how to create a form in MODX with FormIt, how to display individual error messages for input fields, an error message alert box with a list of errors and a success message. Let’s get started we got a lot to cover.

Prerequisites

• FormIt Extra
• Bootstrap Framework (if you want to style your form like our example)

What is FormIt?

FormIt is a dynamic form processing Snippet for MODX Revolution. It handles a form after submission, performing validation and follow-up actions like sending an email. It does not generate the form, but it can repopulate it if it fails validation.

Basically FormIt is a simple MODX Extra that handles what occurs before and after it interacts with a form on your MODX site. For more information about how FormIt works and what other features and options it has please refer to the official FormIt documentation.

Tip: Using FormIt is not necessary, you can also create your own form and PHP code to validate and process your form without the use of FormIt.

FormIt works just like any other MODX extra you call the snippet and pass some parameters, FormIt also comes with built in Hooks. Hooks are basically scripts that run during FormIt processing. Hooks can be chained; the first hook will execute, and if it succeeds, it will proceed onto the next hook.

FormIt also has Pre-Hooks which execute before you load your form; a good example of a Pre-Hook is one which sets a default value to your forms input fields for older browsers that don’t support the input placeholder parameter.

You can create your own custom Hook and Pre-Hooks and call these in the preHook and hook parameters of FormIt, remember these will be executed based on the order in which they are in your hook or pre-hook call so if one hook fails it will stop and not execute the next one.

For more information on hooks and pre-hooks, see the Hooks on the MODX RTFM page.

Creating your forms HTML

The first step is to create the HTML for your form, for this example we will create a simple comment form that will have 3 fields that our user will fill out which are: Name, Email and Comment. Here is what our forms HTML looks like.

Adding Placeholder Tags

In order to retrieve the values of our form with FormIt we need to add placeholders to our input fields so FormIt knows how to process them. All FormIt placeholders must be prefixed with fi so FormIt knows it’s a placeholder which pertains to it, so after doing this our forms HTML code should look like this:

Tip: The default FormIt placeholder prefix is fi but this is not mandatory, you can specify your own custom placeholder prefix by adding the placeholderPrefix property to your FormIt call.

As you can see we are calling our placeholders uncached by using the (!) to make sure we don’t receive cached values from previous form entries followed by a (+) which is the placeholder syntax for MODX internal tag system. It is good practice to use the name or ID of your input field as your placeholder in order to keep things relevant but this is not a requirement.

Adding the FormIt Call

So far we have modified our HTML form by adding placeholders to the input fields so FormIt knows where to get the values from, now we have to add our FormIt call which looks something like this:

[[!FormIt?
  &hooks=`email`
  &emailFrom=`donotreply[@]yourdomain.com`
  &emailTpl=`myEmailChunk`
  &emailTo=`[[+email]]`
  &emailSubject=`My First FormIt Form`
]]

First we are instantiating the FormIt snippet by calling it uncached

  [[!FormIt]]

The (?) lets the snippet know that we are about to send it some parameters or set some properties. The first parameter we are passing is the email hook.

  &hooks=`email`

Tip: To view all of the email hook properties that can be accessed please refer to the email properties page.

Now that we’ve instantiated the email hook we can access its properties. The first one is the emailFrom property.

  &emailFrom=`donotreply[@]yourdomain.com`

This property allows us to specify the email sender that will appear on our forms email response. The next property is emailTpl.

  &emailTpl=`myEmailChunk`

This property allows us to specify the name of the chunk we will use to format the outgoing email we will submit to our recipient; this is the sample code we are using inside the myEmailChunk:

  
Name: [[+name]]
  
Email: [[+email]]
  
Comment: [[+comment]]

As you can see all our chunk contains is some HTML code and the placeholder for our FormIt input fields.

Tip: Remember the emailTpl can contain images and HTML code; just make sure your image paths are absolute so they can be viewed on the recipients email client.

The emailTo property:

  &emailTo=`[[+email]]`

Lets us specify a who will receive the form when its submitted, in this case we are using the email placeholder since we want the user filling out the form to receive the email.

Tip: You can specify more than one email recipient in the emailTo property just make sure you insert a (,) after each email address.

The last property:

  &emailSubject=`My First FormIt Form`

Let’s us insert a predefined email subject for our form.

    &emailSubject=`[[+subject]]`
  

Validation

The next step is to add validation to our form so we can make sure each input field is filled out before submitting the form. In order to achieve this we just need to add the validate parameter to our FormIt call and specify which fields are required in order to submit the form successfully. Lets add our validate parameter and make our name, email and comment fields required.

  &validate=`name:required,
    email:email:required,
    comment:required:stripTags`

You may be asking yourself how do I tell FormIt which field it needs to check, easy you use the input fields name attribute and put a (:required) after it and FormIt automatically knows that this is a required field.

The validate parameter can be chained in order to validate more than one field, each field value needs to be separated by a (,) and FormIt will take care of the rest.

Tip: If you notice the email field has email: twice this is not a typo this is how FormIt validates required email fields, so keep this in mind.

Adding Validation Errors and Styling our Form

So we just made our fields required no we need to make user friendly error messages so our users know that there are errors they need to correct before they can successfully submit the form. Before we do that we will need to modify our HTML structure in order to take advantage of twitter Bootstraps styles.

Tip: Make sure your HTML template has references to Bootstraps classes and js files.

In order to use Bootstraps validation states we need to wrap our inputs with a div that has the controls class.

Now let’s wrap our labels and divs with the control class with a div with an ID attribute for each of these.

Our form should look like this now.

Now lets start adding the FormIt error messages to our form, we will be displaying our error messages next to our field labels. Validation errors are prefixed with fi.error.placeholder_name then you can use and Output Modifier in order to check if the message should display. Lets add this line of code next to all of our label tags; this is where our error messages will appear.

    [[!+fi.error.placeholder_name:notempty=`This is a required field.`]]

What this does is call the FormIt error processor uncached we need to replace placeholder_name with the name of the placeholder we used for the input field the error message is referring to, then we use the Output Modifier notempty this tells MODX to display the value of this error placeholder when there is an error for the specific input. Now our forms HTML should look something like this:

If you submit the form with all fields empty you should now see error messages next to the field labels.

Adding Error Alert Messages

So we already added field validation errors now let’s go the extra mile for a great user experience and let’s add an error alert box that will list all the errors in our form. FormIt has a validation_error_message placeholder that will allow us to do this, lets add the following code to our page.

  [[!+fi.validation_error_message:!empty=`
    `]]

Lets go through our code to see what is happening, first we are calling the validation_error_message uncached and we’re telling it to display our HTML if there are validation errors

  [[!+fi.validation_error_message:!empty=``]]

Then we insert the Bootstrap code for the error alert message box

Next we insert an h3 title with a message and an unordered list that will display the errors in our form.

  
Please review the following errors:
    

        [[!+fi.error.name:!empty=`
Name is a required field
`]]
        [[!+fi.error.email:!empty=`
Email is a required field
`]]
        [[!+fi.error.comment:!empty=`
Comment is a required field
`]]
    

Lets explain whats going on here, we are using the same principle we used for our input validation errors. You can see we are using the validation error place holder with the name of each of our input fields and telling it to display a list item with a link and an error message for each of our errors.

  [[!+fi.error.name:!empty=`
Name is a required field
`]]

If you look at the href of our link you will notice a MODX tag before the Anchor ID of each error.

  href="[[~[[*id]]]]#name"

This will ensure that when you click on the link of the error message the page will scroll down to the Anchor ID we used in each of our forms sections.

So if you submit the form with an empty field you will see something like this:

Adding a Success Message

We will use FormIts successMessage property in order to display a user friendly message to our user which will let them know we have received their form submission successfully. The successMessage parameter accepts HTML or a simple message as its value in this example we will be using HTML since we will be using Bootstrap to style our success message. Let’s add the successMessage parameter with our HTML code to our FormIt call.

  &successMessage=`

    
Your comment has been submitted successfully, please check your email.
  
`

Now when the form is submitted successfully without any errors our users will see this message.

So our final completed code should look like this:

  

[[!FormIt?
   &hooks=`email`
   &emailFrom=`donotreply[@]youremail.com`
   &emailTpl=`MyEmailChunk`
   &emailTo=`[[+email]]`
   &emailSubject=`Your Subject Goes Here`
   &validate=`name:required,
      email:email:required,
      comment:required:stripTags`
      &successMessage=`

      
Your comment has been submitted successfully, please check your email.
    
`
    &validationErrorMessage=`
`
]]
[[!+fi.validation_error_message:!empty=`
    
`]]
    [[!+fi.successMessage]]

This concludes our FormIt tutorial I hope you learned something new or got a better understanding on how FormIt works, let me know your feedback and don’t forget you can use the contact form to suggest a tutorial you would like us to cover or why not make your own tutorial as a guest blogger on our site. Thanks and see you next time.

Отредактировано: 20 Февраля 2019

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

У FormIt есть Хуки (Hooks) — скрипты, которые выполняются во время обработки. Хуки могут быть линейными, т.е. выполняются по очереди, а могут быть последовательными, т.е. если выполнено условие первого хука, то начнется выполнение следующего хука.

Существуют также Прехуки (Pre-Hooks), скрипты, которые выполняются до загрузки формы. К примеру скрипт который устанавливает значение по умолчанию для полей форм в старых браузерах, которые не поддерживают соответствующие html плейсхолдеры.

Можно создавать собственные хуки и прехуки указывая их в параметрах preHook и hook FormIt. Стоит учитывать, что они будут выполняться в порядке указанном при вызове, поэтому, если один из скриптов выдал ошибку, сломаются и последующие.

Код полностью

[<!--code-->[!FormIt?
   &hooks=`email`
   &emailFrom=`donotreply[@]yourdomain.com`
   &emailTpl=`mailtpl.feedback`
   &emailTo=`donotreply@yourdomain.com, admin@yourdomain.com`
   &emailSubject=`Письмо с сайта yourdomain.com`
   &successMessage=`Сообщение отправлено`
   &validate=`name:required,
      email:email:required,
      comment:required,
      antispam:blank`
]]

<form action="" method="post">
    <label for="name">Name:</label>
    <input type="text" name="name" id="name" value="[<!--code-->[!+fi.name]]">
    <label for="email">Email</label>
    <input type="text" name="email" id="email" value="[<!--code-->[!+fi.email]]">
    <label for="comment">Comment</label>
    <textarea name="comment" id="comment" cols="30" rows="10" value="[<!--code-->[!+fi.comment]]"></textarea>
    <input type="text" name="antispam" id="antispam" value="">
    <input type="submit" value="Submit">
</form>

[[!+fi.validation_error_message:!empty=`
<div class="alert">
  <h3>Пожалуйста, исправьте следующие ошибки:</h3>
    <ul>
        [[!+fi.error.name:!empty=`<li><a href="blog/web/back-end/modx/formit/#name">Поле «Имя» не заполнено</a></li>`]]
        [[!+fi.error.email:!empty=`<li><a href="blog/web/back-end/modx/formit/#email">Поле «Email» не заполнено</a></li>`]]
        [[!+fi.error.comment:!empty=`<li><a href="blog/web/back-end/modx/formit/#comment">Поле «Комментарий» не заполнено</a></li>`]]
    </ul>
</div>`]]

1. В нужном месте шаблона, или на отдельной странице создадим html код формы

2. <form action="" method="post">
       <label for="name">Имя:</label>
       <input type="text" name="name" id="name" >
       <label for="email">Email</label>
       <input type="text" name="email" id="email" >
       <label for="comment">Комментарий</label>
       <textarea name="comment" id="comment" cols="30" rows="10"></textarea>
       <input type="submit" value="Submit">
   </form>

   Добавим некешируемые плейсхолдеры FormIt ([[!+fi.код_поля]])

   <form action="" method="post">
       <label for="name">Name:</label>
       <input type="text" name="name" id="name" value="[[!+fi.name]]">
       <label for="email">Email</label>
       <input type="text" name="email" id="email" value="[[!+fi.email]]">
       <label for="comment">Comment</label>
       <textarea name="comment" id="comment" cols="30" rows="10" value="[[!+fi.comment]]"></textarea>
       <input type="submit" value="Submit">
   </form>

   (префикс fi при желании можно изменить свойством placeholderPrefix при вызове сниппета)

3. Создаем чанк письма, которое будет приходить на почту после отправки результатов формы. К примеру mailtpl.feedback:

   /* В качестве плейсхолдеров указывается код поля,
    который был записан в форме после префикса fi*/
   <p>Имя: [[+name]]</p>
   <p>Email: [[+email]]</p>
   <p>Комментарий: [[+comment]]</p>     

4. Вызываем сниппет FormIt 

   [[!FormIt?
      &hooks=`email`
      &emailFrom=`donotreply@yourdomain.com`
      &emailTpl=`mailtpl.feedback`
      &emailTo=`donotreply@yourdomain.com, admin@yourdomain.com`
      &emailSubject=`Письмо с сайта yourdomain.com`
      &successMessage=`Сообщение отправлено`
   ]]

5. К коду выше добавляем параметры для проверки заполненности обязательных полей и другие параметры проверки:

   &validate=`name:required,
         email:email:required,
         comment:required`
   
   /* К полю email добавлен параметр :email,
   он проверяет правильность написания адреса электронной почты */
   
   

6. Добавим оповещение пользователя, о неправильно заполненном поле. В специально отведенное для сообщения об ошибке место (к примеру в тег <label>) вставляем код: 

   [[!+fi.error.placeholder_code:notempty=`<span>Обязательное поле не заполнено</span>`]]

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

   [[!+fi.validation_error_message:!empty=`
   <div class="alert">
     <h3>Пожалуйста, исправьте следующие ошибки:</h3>
       <ul>
           [[!+fi.error.name:!empty=`<li><a href="[[*uri]]#name">Поле «Имя» не заполнено</a></li>`]]
           [[!+fi.error.email:!empty=`<li><a href="[[*uri]]#email">Поле «Email» не заполнено</a></li>`]]
           [[!+fi.error.comment:!empty=`<li><a href="[[*uri]]#comment">Поле «Комментарий» не заполнено</a></li>`]]
       </ul>
   </div>`]]

Анти-спам

• Капча (captcha) — распространенный метод. Некоторые виды этой защиты боты научились распознавать и обходить. Самой эффективной на данный момент является reCAPTCHA от Google. Минусы — дополнительное поле, которое надо заполнить пользователю.
  Для FormIt есть специальные хуки с капчами math и reCaptcha (смотрите в резделе Хуки);
• Скрытые поля ввода

  /* Скрытое поле. Не эффективный метод, т.к. боты научились не заполнять скрытые поля */
  <input type="hidden" name="antispam" value=""> 
  
  /* Обычное поле, скрытое за счет css */
  <input type="text" id="antispam" value="">
  
  /* Такие поля можно добавлять с использованием JS, 
  это усилит защиту, т.к. большинство ботов не использует js */
  
  /* При использовании скрытых полей в FormIT надо добавить проверку*/
  [[!FormIt? &validate=`antispam:blank`]]

• Для FormIt есть специальный хук; проверяющий указанный email в спам-листе. Данный метод помогает далеко не всегда.

  [[!FormIt? &hooks=`spam` &spamCheckIp=`true`]]

• Метод от Ильи Уткина, добавить замаскированное поле, которое будет отвечать на спам успешной отправкой, благодаря чему спам-бот и его хозяин сочтут что сообщение отправлено:

/* Создаём сниппет checkSpam */
<?php
if ($_POST['surname']) { // проверяем наше поле на пустоту
    echo $AjaxForm->success('Ваше сообщение отправлено');
    die();
} else {
    return true;
}

/* Добавляем в форму поле, по которому будем фильтровать */
<input type="text" name="surname" class="form-input" placeholder="Фамилия">

/* Маскируем поле */
input[name="surname"] {
    display: block;
    width: 2px;
    height: 3px;
    margin-bottom: -3px;
    opacity: 0.01;
}

/* Добавляем сниппет checkSpam в качестве хука перед email */
`hooks` => `checkSpam,email...`

AjaxForm

Сниппет ajaxForm представляет из себя надстройку над FormIt реализующую Ajax вызов. Вызов сниппета

[[!AjaxForm?
    &snippet=`FormIt`
    &form=`tpl.AjaxForm.example`
    &emailTpl=`mailtpl.feedback`
    &hooks=`email`
    &emailSubject=`Письмо с сайта yourdomain.com`
    &emailFrom=`donotreply[@]yourdomain.com`
    &emailTo=`donotreply@yourdomain.com, admin@yourdomain.com`
    &validate=`name:required,
      email:email:required,
      comment:required,
      antispam:blank`
    &successMessage=`Сообщение отправлено`
]]
   

Подробнее на странице об AjaxForm

Параметры FormIt

// запись при вызове
&submitVar=`contactform`

// в форме добавляется скрытое поле с аналогичным именем
<input type="hidden" name="contactform" value="1" />

Хуки (hooks)

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

Список предустановленных хуков

Email — отправляет результат формы на почту (активирует функцию mail()).

FormItAutoResponder — отправляет автоответ автору сообщения.

math — добавляет математическую капчу к форме.

&hooks=`math,email`
&validate=`math:required`

<label>[[!+fi.op1]] [[!+fi.operator]] [[!+fi.op2]]?</label>
[[!+fi.error.math]]
<input type="text" name="math" value="[[!+fi.math]]" />
<input type="hidden" name="operator" value="[[!+fi.operator]]" />

<label>[[!+fi.op1]] [[!+fi.operator:is=`-`:then=`minus`:else=`plus`]] [[!+fi.op2]]?</label>

recaptcha — добавляет рекапчу к форме.

&hooks=`recaptcha,email`

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

redirect — перенаправляет пользователя на специальный ресурс, при завершении отправки.

[[!FormIt?
   &hooks=`redirect`
   &redirectTo=`212`
   &redirectParams=`{"user":"123","success":"1"}`
]]

<!-- 
С redirectParam формат полученного адреса будет таким
test.html?user=123&success=1 
-->

spam — проверяет все поля формы, указанные в свойстве spamEmailFields, на фильтр спама через StopForumSpam. Если пользователь помечен как спамер, форма покажет сообщение об ошибке.

[[!FormIt? &hooks=`spam`]]

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

Дополнительные хуки 

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

Список полезных хуков которые можно скачать:

recaptchav2 — хук для интеграции с рекапчей от гугл второй и третьей версии.

&hooks=`recaptchav2,email`

// для 3 версии
   &hooks=`recaptchav3,email`

    [[!recaptchav2_render]]
    [[!+fi.error.recaptchav2_error]]

// для 3 версии
    [[!recaptchav3_render]]
    [[!+fi.error.recaptchav3_error]]

Селекты, чекбоксы, переключатели

(selects, checkboxes, radio buttons)

Для множественных полей формы, таких как селекты, чекбоксы и переключатели, стандартный способ подключения не сработает. Для таких случаев в FormIt предусмотрены сниппеты FormItIsSelected и FormItIsChecked.

Оформление select поля

<select name="color">
   <option value="blue" [[!+fi.color:FormItIsSelected=`blue`]] >Синий</option>
   <option value="red" [[!+fi.color:FormItIsSelected=`red`]] >Красный</option>
   <option value="green" [[!+fi.color:FormItIsSelected=`green`]] >Зеленый</option>
   <!-- Способ заполнения с использованием phx фильтров -->
   <option value="yellow" [[!+fi.color:is=`yellow`:then=`selected`]]>Желтый</option>
</select>

Оформление checkbox и radio поля

<label>Color: [[!+fi.error.color]]</label>
<input type="checkbox" name="color[]" value="blue" [[!+fi.color:FormItIsChecked=`blue`]] > Синий
<input type="checkbox" name="color[]" value="red" [[!+fi.color:FormItIsChecked=`red`]] > Красный
<input type="checkbox" name="color[]" value="green" [[!+fi.color:FormItIsChecked=`green`]] > Зеленый

У html чекбоксов есть особенность — если значение отсутствует, параметр не передаётся, это так же влияет на проверку заполненности поля. Для того, чтобы отправить пустое значение, необходимо добавить скрытое input поле

[[!FormIt? &validate=`color:required`]]
...
<label>Color: [[!+fi.error.color]]</label>
<input type="hidden" name="color[]" value="" />
<input type="checkbox" name="color[]" value="blue" [[!+fi.color:FormItIsChecked=`blue`]] > Синий
<input type="checkbox" name="color[]" value="red" [[!+fi.color:FormItIsChecked=`red`]] > Красный
<input type="checkbox" name="color[]" value="green" [[!+fi.color:FormItIsChecked=`green`]] > Зеленый

 Таким образом можно проверить, выбран ли хотябы 1 флажок. 

Если надо установить поле с массивом значений (группу флажков, с одинаковым именем, или множественный селект) в преХук, надо сперва раскодировать данные из json формата

$hook->setValue('цвет',json_encode(array('синий','красный','зеленый')));

Настройка целей для счетчиков

Самый простой способ отслеживать успешную отправку формы, без изменения кода компонента — добавить перехватчик в сообщение об успешной отправке:

&successMessage=`Ваше письмо успешно отправлено <script>yaCounterXXXXXXXX.reachGoal('form');</script>`

Возможные ошибки

— Если FormIt говорит об успешной отправке формы, но письмо на почту не приходит, стоит проверить

1. правильную настройку mx записи на сервере;
2. в вызове formIt указан ли адрес исходящей почты: &emailFrom=`mail@site.ru`

— Если FormIt или AjaxForm выдают 500 ошибку при отправке, причин может быть несколько, и все они связаны с проблемами на сервере. К примеру, если на сервере используется php ниже 5.4 (не рекомендуется для новых версий modx), то проблему можно решить установкой в файле .htaccess следующего параметра:

php_flag register_globals off

Если же на сервере стоит версия php 5.4 и выше, то искать проблему стоит в логах Modx (core/cache/logs/error.log) и сервера. Если записей в логах нет,  попробуйте переустановить компоненты FormIt и AjaxForm, и посмотрите, не вылезают ли ошибки во время установки. Если компонент ругается на ошибки, проставьте соответствующим папкам на сервере права доступа 700. И попробуйте переустановить снова (кнопка reinstall может не помочь, иногда эффективнее воспользоваться uninstall). Подробнее об ошибке 500.

— Если в списке отправленных форм, на странице FormIt в админ панели, вместо нормального списка отображается массив символов — вероятно вы раньше времени перешли на php 7.1, спуститесь на 7.0, либо ждите фикса компонента.

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

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

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

Что такое FormIt?

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

Установка

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

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

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

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

Проверка

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

Хуки

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

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

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

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

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

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

<div class="col-lg-6 col-xl-5 offset-lg-1 appear-animation" data-appear-animation="fadeInUpShorter" data-appear-animation-delay="1250">
	<form class="contact-form custom-form-style-1" action="php/contact-form.php" method="POST">
                <div class="contact-form-success alert alert-success d-none mt-4">
                    <strong>Success!</strong> Your message has been sent to us.
                </div>

                <div class="contact-form-error alert alert-danger d-none mt-4">
                    <strong>Error!</strong> There was an error sending your message.
                    <span class="mail-error-message text-1 d-block"></span>
                </div>

                <div class="row row-gutter-sm">
                    <div class="form-group col mb-3">
                        <input type="text" value="" data-msg-required="Please enter your name." maxlength="100" class="form-control" name="name" id="name" required placeholder="First Name">
                    </div>
                </div>
                <div class="row row-gutter-sm">
                    <div class="form-group col mb-3">
                        <input type="email" value="" data-msg-required="Please enter your email address." data-msg-email="Please enter a valid email address." maxlength="100" class="form-control" name="email" id="email" required placeholder="E-mail Address">
                    </div>
                </div>
                <div class="row">
                    <div class="form-group col mb-3">
                        <textarea maxlength="5000" data-msg-required="Please enter your message." rows="4" class="form-control" name="message" id="message" required placeholder="Message"></textarea>
                    </div>
                </div>
                <div class="row appear-animation" data-appear-animation="fadeInUpShorterPlus" data-appear-animation-delay="1500">
                    <div class="form-group col mb-0">
                        <button type="submit" class="btn btn-primary btn-modern font-weight-bold custom-btn-border-radius custom-btn-arrow-effect-1 text-3 px-5 py-3" data-loading-text="Loading...">
                        	SUBMIT
                        	<svg class="ms-2" version="1.1" viewBox="0 0 15.698 8.706" width="17" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
								<polygon stroke="#FFF" stroke-width="0.1" fill="#FFF" points="11.354,0 10.646,0.706 13.786,3.853 0,3.853 0,4.853 13.786,4.853 10.646,8 11.354,8.706 15.698,4.353 "/>
							</svg>
                        </button>
                    </div>
                </div>
            </form>
	</div>

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

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

<form class="contact-form custom-form-style-1" action="php/contact-form.php" method="POST">

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

<form class="contact-form custom-form-style-1" action="[[~[[*id]]? &scheme=`full`]]" method="post">

тоже самое на fenom:

<form class="contact-form custom-form-style-1" action="{$_modx->makeUrl($_modx->resource.id, '', '', 'full')}" method="post">

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

<input type="email" value="" data-msg-required="Please enter your email address." data-msg-email="Please enter a valid email address." maxlength="100" class="form-control" name="email" id="email" required placeholder="E-mail Address">

Так как вся валидация у нас будет на плечах дополнения, то data-msg-.. можно удалить, maxlength и id можно удалить — т.к. он не влияет на внешний вид и сразу русифицируем.

<input type="email" value="" class="form-control" name="email" required placeholder="Введите ваш E-mail">

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

Атрибут value="" можно оставить, можно удалить, либо в него можно поместить вот такую конструкцию: [[!+fi.email]], где email это имя атрибута name=. Лично я обычно удаляю, работает и без него, либо оставляю пустым, а в забугорных статьях везде показано с такими конструкциями.

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

В конечном итоге у вас должен получиться следующий код формы:

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

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

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

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

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

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

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

Вызываем FormIt

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

[[!FormIt? 
    &hooks=`email` 
    &emailTpl=`tplForm` 
    &emailTo=`[[++emailsender]]` 
]]
тоже самое на fenom:
{'!FormIt' | snippet : [
   'hooks' => 'email',
   'emailTpl' => 'tplForm',
   'emailTo' => $_modx->config.emailsender,
]}

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

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

Этого достаточно чтобы форма начала отправляться.

В данном случае форма не отправлялась пока не убрал из шаблона (чанка tpl) подключение скрипта view.contact.js.

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

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

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

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

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

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

<div class="contact-form-success alert alert-success d-none mt-4">
                    <strong>Success!</strong> Your message has been sent to us.
                </div>

                <div class="contact-form-error alert alert-danger d-none mt-4">
                    <strong>Error!</strong> There was an error sending your message.
                    <span class="mail-error-message text-1 d-block"></span>
                </div>

Удаляем (ну вернее мы ее перенесем в вызов в параметры successMessage и  validationErrorMessage) и вместо нее пишем:

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

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

[[!FormIt?
&hooks=`email`
&validate=`name:required:maxLength=^21^,email:email:required,message:required:minLength=^30^`
&emailTpl=`tplForm`
&emailTo=`[[++emailsender]]`
&emailFrom=`noretly@[[++base_url]]`
&emailSubject=`Сообщение со страницы контакты на сайте [[++site_url]]`
&successMessage=`<div class="contact-form-success alert alert-success mt-4"><strong>Успешно!</strong> Ваше сообщение отправлено нам.</div>`
&validationErrorMessage=`<div class="contact-form-success alert alert-danger mt-4"><strong>Ошибка!</strong> Произошла ошибка при отправке вашего сообщения.</div>`
]]
тоже самое на fenom:
{'!FormIt' | snippet : [
   'hooks' => 'email',
   'validate' => 'name:required:maxLength=^21^,email:email:required,message:required:minLength=^30^',
   'emailTpl' => 'tplForm',
   'emailTo' => $_modx->config.emailsender,
   'emailFrom' => 'noretly@modx-revolution.ru',
   'emailSubject' => 'Сообщение со страницы контакты на сайте' ~ $_modx->config.site_name,
   'successMessage' => '<div class="contact-form-success alert alert-success mt-4"><strong>Успешно!</strong> Ваше сообщение отправлено нам.</div>',
   'validationErrorMessage' => '<div class="contact-form-success alert alert-danger mt-4"><strong>Ошибка!</strong> Произошла ошибка при отправке вашего сообщения.</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 class="contact-form custom-form-style-1" action="[[~[[*id]]? &scheme=`full`]]" method="post">
        [[+fi.validation_error_message]]
        [[+fi.successMessage]]
        <div class="row row-gutter-sm">
            <div class="form-group col mb-3">
                <input type="text" value="" class="form-control" name="name" id="name" placeholder="Ваше имя">
                <span class="error">[[+fi.error.name]]</span>
            </div>
        </div>
        <div class="row row-gutter-sm">
            <div class="form-group col mb-3">
                <input type="email" value="" class="form-control" name="email" placeholder="Введите ваш E-mail">
                <span class="error">[[+fi.error.email]]</span>
            </div>
        </div>
        <div class="row">
            <div class="form-group col mb-3">
                <textarea rows="4" class="form-control" name="message" placeholder="Сообщение"></textarea>
                <span class="error">[[+fi.error.message]]</span>
            </div>
        </div>
        <div class="row appear-animation" data-appear-animation="fadeInUpShorterPlus" data-appear-animation-delay="1500">
            <div class="form-group col mb-0">
                <button type="submit" class="btn btn-primary btn-modern font-weight-bold custom-btn-border-radius custom-btn-arrow-effect-1 text-3 px-5 py-3">
                	ОТПРАВИТЬ
                	<svg class="ms-2" version="1.1" viewBox="0 0 15.698 8.706" width="17" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    					<polygon stroke="#FFF" stroke-width="0.1" fill="#FFF" points="11.354,0 10.646,0.706 13.786,3.853 0,3.853 0,4.853 13.786,4.853 10.646,8 11.354,8.706 15.698,4.353 "/>
    				</svg>
                </button>
            </div>
        </div>
    </form>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для того чтобы была возможность прикреплять и отправлять вложения, необходимо в тег формы прописать 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`]]">

fenom:

<input type="hidden" name="pagetitle" value="{$_modx->resource.pagetitle}">

<input type="hidden" name="urladress" value="{$_modx->makeUrl($_modx->resource.id, '', '', '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>

Обработка 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

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

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

Пример empty:

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

Пример if на fenom:

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

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

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 (о нем и поговорим в следующем уроке), потом о борьбе со спамом. А затем сделаем хлебные крошки — чтобы наш шаблон выглядел как оригинал.

Этот сниппет предназначен для реализации формы обратной связи, ближайший его аналог в Modx Evo — это eForm.

Основные параметры

 Хук email

Параметры, которые используются совместно с данным хуком:

Валидаторы

Частенько бывает необходимо перед отправкой самой формы, произвести необходимые проверки: было ли заполнено поле, является вводимый пользователем e-mail на самом деле электронным адресом и так далее. В FormIt для этих целей используются валидаторы, которые записываются следующим образом: 

[[!FormIt? &validate=`username:required,message:required`]]

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

Встроенные валидаторы FormIt:

Кастомные валидаторы

На тот случай, если по какой-то причине стандартных валидаторов будет не хватать, можно написать свои, которые будут являться ничем иным как сниппетами: 

[[!FormIt? &customValidators=`isBigEnough` &validate=`cost:isBigEnough`]]

Чтобы данный пример заработал, необходимо будет создать одноимённый сниппет isBigEnough, который будет проверять, превышает ли введённое число значение 1000. И если да, то выводить ошибку.

При этом доступны будут следующие переменные: 
$key — название самого поля; 
$value — значение самого поля; 
$param — параметр валидатора, если таковой присутствует;
$type — имя валидатора или сниппета;
$validator — связь с экземпляром класса fiValidator.

То есть содержимое сниппета будет примерно таким:

<?php 
$value = (float)$value;
$success = $value > 1000;
if (!$success) {
  // Note how we can add an error to the field here.
  $validator->addError($key,'Not big enough!');
}
return $success;
?>

Кастомные сообщения об ошибках

Если пользователь при заполнении формы введёт какую-либо неверную информацию или не введёт её вовсе, то ему будет показано стандартное сообщение об ошибке. Но мы и этот момент можем кастомизировать, для этого воспользуемся следующей таблицей: 

В первой колонке указан валидатор, который отвечает за проверку поля (их описание можно найти чуть выше), а вторая колонка — это параметр снипета FormIt, указав который, можно кастомизировать сообщение об ошибке для валидатора из первой колонки. Чтобы было понятно, о чём речь, вот пример:

[[!FormIt?
  &vTextRequired=`Пожалуйста, заполните поле, чтобы продолжить дальше`
  &name.vTextRequired=`Заполните ваше имя. Мы должны знать его, чтобы знать как к вам обращаться`
]]

На месте параметра name.vTextRequired может быть любое другое поле — subject.vTextRequired, message.vTextRequired и так далее. 

Шаблон формы обратной связи

Форма должна размещаться на той же странице, где и сам сниппет. Вот простейший пример с двумя полями:

[[!+fi.validation_error_message:notempty=`<p>[[!+fi.validation_error_message]]</p>`]]
<form id="our-form" method="post" action="[[~[[*id]]]]">
<div>
<label for="name">Имя пользователя: </label><br />
<input id="name" name="name" value="[[!+fi.name]]" />
<span class="error">[[!+fi.error.name]]</span>
</div>
<div>
<label for="email">E-Mail </label><br />
<input id="email" name="email" value="[[!+fi.email]]" />
<span class="error">[[!+fi.error.email]]</span>
</div>
<div>
<input name="submit" type="submit" value="Отправить"/>
</div>
</form>

Тут собственно всё просто:

[[!+fi.validation_error_message]] — выводится в том случае, если у нас в форме есть какие-либо ошибки. 
[[!+fi.error.name]] — в этом месте будут выводиться ошибки, связанные с каким-то одним полем. В данном случае это поле name. 

Так же, в самой форме указан аттрибут action=»[[~[[*id]]]]». Но прописывать его вовсе необязательно, поскольку форма и так по умолчанию будет указывать на текущий ресурс. 

Однако, всего этого пока ещё недостаточно. Нам нужно создать чанк, в котором будет находиться шаблон письма, которое будет к нам приходить на почту. И вот собственно, следующая тема: 

Шаблон письма, приходящий на почту

Шаблон, напомню, находится в чанке, имя которого прописано в параметре emailTpl снипета FormIt. Выглядеть он будет следующим образом:

Вам пришло письмо от пользователя с именем [[+name]] А вот и его email:
[[+email]]

Как вы могли уже догадаться, здесь всё просто: 
в плэйсхолдерах [[+name]] и [[+email]] находятся значения, которые пользователь ввёл в поля с атрибутами name=»name» и соответственно name=»email».

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

Итак, подводя итоги, чтобы сделать форму обратной связи будет достаточно: 

1. Разместить HTML код самой формы. Пример есть выше.

2. Создать чанк отправки на почту. Опять же, как это сделать, рассказывал ранее.

3. Ну и собственно сам вызов сниппета. 

[[!FormIt?
   &hooks=`email`
   &emailTpl=`form_feed`
   &emailTo=`user@example.com`
   &validate=`
      name:required,
      email:email:required,
      message:required:stripTags,
]]