MODX. Создание и обработка форм с использованием FormIt

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

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

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

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

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

Подключение простой формы с использованием 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