FormIt - создание формы обратной связи в Revo

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

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

Параметр (значение по умолчанию)	Применение
&hooks=``	Скрипты, которые запускаются в том случае, если форма прошла валидацию. Хуков может быть несколько и они могут перечисляться через запятую (соответственно и выполняться в этом порядке). В качестве значений может принимать как путь к файлу, так и имя сниппета. Если один из хуков вернёт отрицательный результат, то остальные выполнены не будут. Примечание. Чтобы отправлялось письмо на почту, должен присутствовать хук email, совместно с которым используются следующие параметры.
&preHooks=``	Скрипты, которые будут выполнены при загрузке формы. Хуков может быть несколько и они могут перечисляться через запятую (соответственно и выполняться в этом порядке). В качестве значений может принимать как путь к файлу, так и имя сниппета. Если один из хуков вернёт отрицательный результат, то остальные выполнены не будут.
&submitVar=``	В качестве параметра указывается имя POST переменной, в случае отсутствия которой форма не будет отправлена. Используется в том случае, если на сайте несколько форм. В самой разметке, переменная задаётся в тэге input типа submit.
&validate=``	В качестве параметра задаются правила валидации полей перед отправкой. Соответственно, пользователь не сможет отправить форму без прохождения этих проверок. Подробнее.
&validationErrorMessage=`A form validation error occurred. Please check the values you have entered.`	Сообщение, которое будет выводиться пользователю в случае если данные, заполненные в форме, не прошли валидацию.
&validationErrorBulkTpl=`<li>[[+error]]</li>`	HTML шаблон для каждого сообщения об ошибке.
&errTpl=`[[+error]]`	HTML шаблон-обёртка для всех сообщений об ошибке.
&customValidators=``	Перечень сниппетов через запятую, которые будут использованы при кастомной валидации отдельных полей. Подробнее.
&clearFieldsOnSuccess=`1`	Очищать ли поля, после успешной отправки формы? 1 - очищать
&store=`0`	Если стоит 1, то данные будут храниться в кэше для последующего использования сниппетом FormItRetriever
&storeTime=`300`	Время (в секундах), в течении которого будут храниться данные после отправки формы. Используется, если параметр &store равен 1.
&storeLocation=`cache`	Определяет хранилище, которое будет использовано при хранении данных после отправки формы. В качестве доступных значений могут быть использованы: cache, session.
&placeholderPrefix=`fi.`	Префикс для плэйсхолдеров, устанавливаемых для полей. Необходимо удостовериться, что в префиксе используется разделитель в виде точки.
&successMessage=``	Сообщение, которое будет выведено в случае успешной отправки формы.
&successMessagePlaceholder=`fi.successMessage`	Имя плэйсхолдера, в котором находится сообщение об успешной отправке.
&redirectTo	В качестве параметра указывается ID страницы, на которую будет перенаправлять в случае успешной отправки сообщения. Обычно используется редирект на страницу с благодарственным сообщением.

Хук email

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

Параметр (значение по умолчанию)	Применение
&emailTo	Список email адресов через запятую, на которые будут отправлены заполненные пользователем данные.
&emailTpl	Чанк письма, которое будет приходить на почту. Подробнее.
&emailSubject	Тема письма
&emailUseFieldForSubject	Если стоит 1, и значение параметра &emailSubject пропущено, то значение поля можно будет использовать в качестве подстановки для темы письма.
&emailToName	Заголовок письма "Кому" (опционально). В качестве значения выступает имя получателя.
&emailFrom	Заголовок письма "От" (опционально). В качестве значения выступает email отправителя.
&emailFromName	Заголовок письма "От" (опционально). В качестве значения выступает имя отправителя.
&emailHtml=`1`	Если стоит 1, то формат письма, которое приходит на почту - HTML (опционально)
&emailConvertNewlines	Если стоит 1, то все переносы строки будут сконвертированы в тэг <br />
&emailReplyTo	Email, который будет указан в качестве ответного сообщения. По умолчанию данные берутся из поля с именем email. Если такого поля нет, то из значения параметра emailFrom
&emailReplyToName	Имя, которое будет указано в ответном сообщении пользователя (опционально).
&emailCC	Email адреса через запятую, которым так же будет отправлена копия. Все остальные адресаты будут в курсе того, кому ещё были отправлены копии.
&emailCCName	Имена тех, кому так же будет отправлена копия. Все остальные адресаты будут в курсе того, кому ещё были отправлены копии (опционально).
&emailBCC	Email адреса через запятую, которым так же будет отправлена копия. Все остальные адресаты не будут в курсе того, кому ещё были отправлены копии (скрытая копия).
&emailBCCName	Имена через запятую, которым так же будет отправлена скрытая копия (опционально).
&emailMultiWrapper	Обёртка для значений множественного типа.
&emailMultiSeparator	Разделитель для значений множественного типа.

Валидаторы

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

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

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

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

Имя	Назначение
blank	Поле должно быть пустым. Данный трюк используется, если нужно например обмануть спам-роботов, которые заполняют все поля. Пример: nospam:blank
required	Поле является обязательным для заполнения. Пример: username:required
password_confirm	Значение данного поля должно совпадать со значением другого поля. Пример: password2:password_confirm=^password^ То есть, значение поля с именем password2 должно совпадать со значением поля с именем password.
email	Поле должно быть типа email. Пример: email:email
minLength	Значение поля должно быть не меньше указанной длины. Пример: password:minLength=^6^ То есть, не меньше 6 символов.
maxLength	Значение поля должно быть не больше указанной длины. Пример: password:maxLength=^12^ То есть, не больше 12 символов.
minValue	Минимальное значение. Пример: number:minValue=^1^ То есть, числа 0 и меньше - недопустимы.
maxValue	Максимальное значение. Пример: number:maxValue=^100^ То есть, числа больше 100 - недопустимы.
contains	Значение, которое должно содержать поле. Пример: title:contains=^Welcome^
strip	Подстрока, которая будет вырезана из поля. Пример: reviews:strip=^badword^
stripTags	Из поля будут вырезаны все HTML тэги. По умолчанию включено. Пример: message:stripTags
allowTags	Разрешать в поле HTML тэги. По умолчанию выключено. Пример: message:allowTags
isNumber	Значение поля должно быть числом. Пример: cost:isNumber
allowSpecialChars	Не заменять HTML символы их сущностями. По умолчанию выключено. Пример: message:allowSpecialChars
isDate	Поле должно являться датой. Пример: startDate:isDate=^%Y-%m-%d^
regexp	Значение поля должно подпадать под регулярное выражение. Пример: secretPin:regexp=^/[0-9]{4}/^

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

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

[[!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;
?>

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

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

Валидатор	Свойство
blank	vTextBlank
required	vTextRequired
password_confirm	vTextPasswordConfirm
email	vTextEmailInvalid, vTextEmailInvalidDomain
minLength	vTextMinLength
maxLength	vTextMaxLength
minValue	vTextMinValue
maxValue	vTextMaxValue
contains	vTextContains
isNumber	vTextIsNumber
isDate	vTextIsDate
regexp	vTextRegexp

В первой колонке указан валидатор, который отвечает за проверку поля (их описание можно найти чуть выше), а вторая колонка - это параметр снипета 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,
]]

Комментарии ()

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