Скрипты, которые запускаются в том случае, если форма прошла валидацию. Хуков может быть несколько и они могут перечисляться через запятую (соответственно и выполняться в этом порядке). В качестве значений может принимать как путь к файлу, так и имя сниппета. Если один из хуков вернёт отрицательный результат, то остальные выполнены не будут.
Примечание. Чтобы отправлялось письмо на почту, должен присутствовать хук email, совместно с которым используются следующие параметры.
Скрипты, которые будут выполнены при загрузке формы. Хуков может быть несколько и они могут перечисляться через запятую (соответственно и выполняться в этом порядке). В качестве значений может принимать как путь к файлу, так и имя сниппета. Если один из хуков вернёт отрицательный результат, то остальные выполнены не будут.
В качестве параметра указывается имя POST переменной, в случае отсутствия которой форма не будет отправлена. Используется в том случае, если на сайте несколько форм. В самой разметке, переменная задаётся в тэге input типа submit.
В качестве параметра задаются правила валидации полей перед отправкой. Соответственно, пользователь не сможет отправить форму без прохождения этих проверок. Подробнее.
&validationErrorMessage=`A form validation error occurred. Please check the values you have entered.`
Сообщение, которое будет выводиться пользователю в случае если данные, заполненные в форме, не прошли валидацию.
HTML шаблон для каждого сообщения об ошибке.
HTML шаблон-обёртка для всех сообщений об ошибке.
Перечень сниппетов через запятую, которые будут использованы при кастомной валидации отдельных полей. Подробнее.
Если стоит 1, то данные будут храниться в кэше для последующего использования сниппетом FormItRetriever
Время (в секундах), в течении которого будут храниться данные после отправки формы. Используется, если параметр &store равен 1.
Определяет хранилище, которое будет использовано при хранении данных после отправки формы. В качестве доступных значений могут быть использованы: cache, session.
Префикс для плэйсхолдеров, устанавливаемых для полей. Необходимо удостовериться, что в префиксе используется разделитель в виде точки.
Сообщение, которое будет выведено в случае успешной отправки формы.
Имя плэйсхолдера, в котором находится сообщение об успешной отправке.
В качестве параметра указывается ID страницы, на которую будет перенаправлять в случае успешной отправки сообщения. Обычно используется редирект на страницу с благодарственным сообщением.
Хук email
Параметры, которые используются совместно с данным хуком:
Параметр (значение по умолчанию)
Применение
Список email адресов через запятую, на которые будут отправлены заполненные пользователем данные.
Чанк письма, которое будет приходить на почту. Подробнее.
Если стоит 1, и значение параметра &emailSubject пропущено, то значение поля можно будет использовать в качестве подстановки для темы письма.
Заголовок письма «Кому» (опционально). В качестве значения выступает имя получателя.
Заголовок письма «От» (опционально). В качестве значения выступает email отправителя.
Заголовок письма «От» (опционально). В качестве значения выступает имя отправителя.
Если стоит 1, то все переносы строки будут сконвертированы в тэг
Email, который будет указан в качестве ответного сообщения. По умолчанию данные берутся из поля с именем email. Если такого поля нет, то из значения параметра emailFrom
Имя, которое будет указано в ответном сообщении пользователя (опционально).
Email адреса через запятую, которым так же будет отправлена копия. Все остальные адресаты будут в курсе того, кому ещё были отправлены копии.
Имена тех, кому так же будет отправлена копия. Все остальные адресаты будут в курсе того, кому ещё были отправлены копии (опционально).
Email адреса через запятую, которым так же будет отправлена копия. Все остальные адресаты не будут в курсе того, кому ещё были отправлены копии (скрытая копия).
Имена через запятую, которым так же будет отправлена скрытая копия (опционально).
Обёртка для значений множественного типа.
Разделитель для значений множественного типа.
Валидаторы
Частенько бывает необходимо перед отправкой самой формы, произвести необходимые проверки: было ли заполнено поле, является вводимый пользователем e-mail на самом деле электронным адресом и так далее. В FormIt для этих целей используются валидаторы, которые записываются следующим образом:
То есть в параметре validate мы перечисляем имена полей, которые будем проверять, а через двоеточие метод проверки. В данном случае используется валидатор «required», который проверяет заполнено ли определённое поле или нет. Полей можно указывать несколько, через запятую.
Встроенные валидаторы FormIt:
Поле должно быть пустым. Данный трюк используется, если нужно например обмануть спам-роботов, которые заполняют все поля. Пример: nospam:blank
Поле является обязательным для заполнения. Пример: username:required
Значение данного поля должно совпадать со значением другого поля. Пример: password2:password_confirm=^password^ То есть, значение поля с именем password2 должно совпадать со значением поля с именем password.
Поле должно быть типа email. Пример: email:email
Значение поля должно быть не меньше указанной длины. Пример: password:minLength=^6^ То есть, не меньше 6 символов.
Значение поля должно быть не больше указанной длины. Пример: password:maxLength=^12^ То есть, не больше 12 символов.
Значение, которое должно содержать поле. Пример: title:contains=^Welcome^
Подстрока, которая будет вырезана из поля. Пример: reviews:strip=^badword^
Из поля будут вырезаны все HTML тэги. По умолчанию включено. Пример: message:stripTags
Разрешать в поле HTML тэги. По умолчанию выключено. Пример: message:allowTags
Значение поля должно быть числом. Пример: cost:isNumber
Не заменять HTML символы их сущностями. По умолчанию выключено. Пример: message:allowSpecialChars
Поле должно являться датой. Пример: startDate:isDate=^%Y-%m-%d^
Значение поля должно подпадать под регулярное выражение. Пример: secretPin:regexp=^/4<4>/^
Кастомные валидаторы
На тот случай, если по какой-то причине стандартных валидаторов будет не хватать, можно написать свои, которые будут являться ничем иным как сниппетами:
Чтобы данный пример заработал, необходимо будет создать одноимённый сниппет isBigEnough, который будет проверять, превышает ли введённое число значение 1000. И если да, то выводить ошибку.
То есть содержимое сниппета будет примерно таким:
Кастомные сообщения об ошибках
Если пользователь при заполнении формы введёт какую-либо неверную информацию или не введёт её вовсе, то ему будет показано стандартное сообщение об ошибке. Но мы и этот момент можем кастомизировать, для этого воспользуемся следующей таблицей:
Валидатор
Свойство
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
Шаблон формы обратной связи
Форма должна размещаться на той же странице, где и сам сниппет. Вот простейший пример с двумя полями:
Тут собственно всё просто:
Так же, в самой форме указан аттрибут action=»[[
[[*id]]]]». Но прописывать его вовсе необязательно, поскольку форма и так по умолчанию будет указывать на текущий ресурс.
Однако, всего этого пока ещё недостаточно. Нам нужно создать чанк, в котором будет находиться шаблон письма, которое будет к нам приходить на почту. И вот собственно, следующая тема:
Шаблон письма, приходящий на почту
Шаблон, напомню, находится в чанке, имя которого прописано в параметре emailTpl снипета FormIt. Выглядеть он будет следующим образом:
Как вы могли уже догадаться, здесь всё просто: в плэйсхолдерах [[+name]] и [[+email]] находятся значения, которые пользователь ввёл в поля с атрибутами name=»name» и соответственно name=»email».
Пример вызова сниппета
Итак, подводя итоги, чтобы сделать форму обратной связи будет достаточно:
1. Разместить HTML код самой формы. Пример есть выше.
2. Создать чанк отправки на почту. Опять же, как это сделать, рассказывал ранее.
FormIt был написан Shaun McCormick как Компонент для обработки форм и впервые выпущен 19 октября 2009 г. В настоящее время поддерживается командой Sterc.
Скачать¶
Formit можно загрузить из Менеджера MODX Revolution через Управление пакетами или из репозитория MODX здесь: https://modx.com/extras/package/formit.
Разработка и ошибки¶
FormIt хранится и разрабатывается в GitHub, и его можно найти здесь: https://github.com/Sterc/FormIt
Документацию по API также можно найти здесь: https://api.modx.com/formit/
Важные изменения¶
Как использовать¶
Если у вас есть несколько форм на странице, установите для свойства &submitVar в вызове Cниппета имя элемента формы (например, &submitVar = form1-submit ). Это указывает FormIt обрабатывать запросы формы только, если в переданных полях формы (POST) есть эта переменная. Если у вас на одной странице несколько форм, обрабатываемых Formit, следует использовать теги с INPUT type = «submit» name = «form1-submit», элементы button работать не будут.
Доступные свойства¶
Это доступные общие свойства для вызова FormIt (не включая свойства, специфичные для хуков):
Валидация¶
Проверка в Formit выполняется с помощью свойства &validate и может использоваться для автоматической обработки любого из полей вашей формы.
Для получения дополнительной информации о проверке в FormIt смотрите Валидаторы.
Если какой-либо хук завершится с ошибкой, последующие за ним не будут выполняться.
Для получения дополнительной информации о хуках смотрите Хуки.
FormIt был написан Shaun McCormick как Компонент для обработки форм и впервые выпущен 19 октября 2009 г. В настоящее время поддерживается командой Sterc.
Скачать¶
Formit можно загрузить из Менеджера MODX Revolution через Управление пакетами или из репозитория MODX здесь: https://modx.com/extras/package/formit.
Разработка и ошибки¶
FormIt хранится и разрабатывается в GitHub, и его можно найти здесь: https://github.com/Sterc/FormIt
Документацию по API также можно найти здесь: https://api.modx.com/formit/
Важные изменения¶
Как использовать¶
Если у вас есть несколько форм на странице, установите для свойства &submitVar в вызове Cниппета имя элемента формы (например, &submitVar = form1-submit ). Это указывает FormIt обрабатывать запросы формы только, если в переданных полях формы (POST) есть эта переменная. Если у вас на одной странице несколько форм, обрабатываемых Formit, следует использовать теги с INPUT type = «submit» name = «form1-submit», элементы button работать не будут.
Доступные свойства¶
Это доступные общие свойства для вызова FormIt (не включая свойства, специфичные для хуков):
Валидация¶
Проверка в Formit выполняется с помощью свойства &validate и может использоваться для автоматической обработки любого из полей вашей формы.
Для получения дополнительной информации о проверке в FormIt смотрите Валидаторы.
Если какой-либо хук завершится с ошибкой, последующие за ним не будут выполняться.
Для получения дополнительной информации о хуках смотрите Хуки.
Возьмём главные способы создания форм обратной связи на сайтах под управлением Modx Revolution. Выбор способа зависит от навыков разработчика или сложности формы.
Преимущества самописного кода для обратной связи очевидны — полная вариативность результата и функционала. Закрывает любые цели, использует любые технологии.
Но есть недостатки:
Итог: тратить время на написание с абсолютного нуля имеет смысл лишь в особо «запущенных» случаях, когда нужен уникальный результат с уникальным функционалом.
Formit для Revo
Самое «народное» решение — форма обратной связи MODx Revo через компонент FormIT. Это стандартный компонент «модикса», позволяющий быстро создавать простые формы для отправки пользовательских данных на электронную почту из любого места сайта.
Разберем пример простой пример работы с Formit. В том месте, где будет отстраиваться форма, необходимо разместить чанк. В него добавить вызов сниппета с минимально необходимым набором параметров:
Выше — готовый код сниппета, который можно добавить в новый чанк с формой. Не забудьте удалить строки с комментариями, начинающиеся с //!
После написания сниппета нужно прописать в том же чанке HTML-код. Он должен отвечать следующим правилам:
Чтобы форма обрабатывалась без перезагрузки страниц используют сниппет AjaxForm. Он по умолчанию рассчитан на работу с FormIt, но вы можете использовать и собственный сниппет.
Как работает AjaxForm?
Сниппет AjaxForm — является оберткой для Formit и отвечает только за асинхронную отправку.
Для его настройки необходимо заменить код вызова FormIt (снипет в начале текста) на вызов AjaxForm, задать в качестве параметра snippet — FormIt и передать все параметры, которые были в вызове Formit.
В данном случае часто возникают конфликты скриптов и библиотек. Для отладки всего этого Вам понадобятся минимальные знания JavaScript.
Недостатками использования связки Formit (и AjaxForm) являются:
Итог: использовать FormIt как основу — вероятно лучший вариант для команды разработчиков. При наличии нужных навыков можно разработать практически любую обратную связь. Простую и рабочую форму можно скопировать из примеров выше.
Онлайн-конструкторы
Есть более простые варианты, не требующих от пользователей никаких знаний вообще. Сервисы-конструкторы обратной связи исчисляются 10-ками и почти все отлично работают с MODx. Другое дело — функционал внутри сервисов: многие из них стоят неоправданно высоко, где-то не хватает важных фишек и почти везде бесплатная версия сервиса урезана до полной бесполезности.
Мы разберём работу подобных сервисов на примере QForm24 — он достаточно прост для пользователей любого уровня и имеет полноценный функционал даже в бесплатной версии.
После регистрации и добавления сайта в сервис нужно вручную в визуальном конструкторе создасть свою форму.
Основные настройки сайта, добавленного в конструктор
Первый шаг — это настройка «скелета». Определите, какие поля и кнопки будет содержать форма, какие плейсхолдеры, имена иметь, поставьте обязательные поля.
Выбраны и настроены все поля форм и кнопка
Настройте адрес для отправки заявки. При помощи меню выберите, с каким CMS и по какому протоколу будет работать элемент. Это необходимо для корректной обработки ошибок и интеграции.
Опционально можно установить галку с принятием «Соглашения об обработке» и настроить капчу. Подобный функционал не везде доступен на бесплатном тарифе, но в QForm нет ограничений по настройкам.
Здесь можно задать текст соглашения об обработке ПД
В финале настройте дизайн — оформление, выбор цветовой темы и фона, вида кнопок. На сервисах почти всегда доступны шаблоны оформления, где-то можно разработать дизайн с нуля (как правило и то и другое ограничено тарифом). На QForm доступные шаблоны и адаптация дизайна под существующие стили сайта.
Настройка дизайна формы
В первом случае останется выбрать шаблон и вставить строчку кода в чанк, который будет выводить форму обратной связи. После вставки чанка в любое место сайта, он автоматически выводит там обратную связь. Для настройки дизайна потребуется чуть больше времени, подробнее здесь.
В конце настраивается отправка сообщений или интеграция с CRM.
Итог: вне зависимости от сложности работы и опыта предыдущего пользования, отправить первую успешную заявку вы сможете через 10-30 минут, бесплатно без каких либо ограничений.
Почитать полезную информацию по сервису или бесплатно попробовать создать первую форму обратной связи можно ниже.
MODX. Создание и обработка форм с использованием FormIt
Отредактировано: 20 Февраля 2019
FormIt — компонент который обрабатывает поля формы после нажатия кнопки «Отправить». Не стоит расценивать его как компонент которым можно создавать форму, это лишь помощник в настройке уже подготовленной формы, избавляющий от написания своих PHP скриптов.
У FormIt есть Хуки (Hooks) — скрипты, которые выполняются во время обработки. Хуки могут быть линейными, т.е. выполняются по очереди, а могут быть последовательными, т.е. если выполнено условие первого хука, то начнется выполнение следующего хука.
Существуют также Прехуки (Pre-Hooks), скрипты, которые выполняются до загрузки формы. К примеру скрипт который устанавливает значение по умолчанию для полей форм в старых браузерах, которые не поддерживают соответствующие html плейсхолдеры.
Можно создавать собственные хуки и прехуки указывая их в параметрах preHook и hook FormIt. Стоит учитывать, что они будут выполняться в порядке указанном при вызове, поэтому, если один из скриптов выдал ошибку, сломаются и последующие.
(префикс fi при желании можно изменить свойством placeholderPrefix при вызове сниппета)
Создаем чанк письма, которое будет приходить на почту после отправки результатов формы. К примеру mailtpl.feedback:
Вызываем сниппет FormIt
К коду выше добавляем параметры для проверки заполненности обязательных полей и другие параметры проверки:
Добавим оповещение пользователя, о неправильно заполненном поле. В специально отведенное для сообщения об ошибке место (к примеру в тег ) вставляем код:
Вместо оповещения об ошибках рядом с полями, можно создать специальный блок, в котором будут указаны все ошибки разом. Для этого надо обернуть код выше в специальный плейсхолдер, примерно так:
Анти-спам
Метод от Ильи Уткина, добавить замаскированное поле, которое будет отвечать на спам успешной отправкой, благодаря чему спам-бот и его хозяин сочтут что сообщение отправлено:
AjaxForm
Сниппет ajaxForm представляет из себя надстройку над FormIt реализующую Ajax вызов. Вызов сниппета
Подробнее на странице об AjaxForm
Параметры FormIt
По умолчанию
Описание
hooks
Скрипты, которые запускаются после того как нажимается кнопка отправки. Сюда также можно записать имя сниппета, который должен воспроизводиться после отправки формы.
preHooks
Скрипты, которые запускаются после загрузки формы. Сюда также можно записать имя сниппета, который должен воспроизводиться после отправки формы.
submitVar
Если параметр установлен, не будет начинаться обработка формы, если эта переменная POST не передается. Может применяться при конфликте нескольких форм на странице.
Префикс для плейсхолдеров полей формы, которые должен обрабатывать FormIt. Разделитель в виде точки ‘.’ обязателен.
successMessage
Если не используется переадресация, отобразите это сообщение об успешном завершении после успешной отправки.
successMessagePlaceholder
fi.successMessage
Имя плейсхолдера, для размещения сообщения об успешной отправке.
redirectTo
ID страницы, с сообщением отображающимся после отправки формы. Является частью хука redirect, работает только с его подключением.
allowFiles
true
Разрешены ли файлы для публикации. Отправленные файлы хранятся во временном каталоге, для предотвращения потери файлов в многоэтапных формах.
Хуки (hooks)
Хуки — специальные скрипты, которые запускаются во время обработки FormIt. Хуки могут быть связаны, к примеру, второй хук начнет выполняться только если первый отработан успешно.
Список предустановленных хуков
Email — отправляет результат формы на почту (активирует функцию mail()).
FormItAutoResponder — отправляет автоответ автору сообщения.
math — добавляет математическую капчу к форме.
Подобная капча выглядит как вопрос формата: 12 + 23?
Для ее интеграции надо добавить math к параметру &hooks и валидацию к соответствующему полю
В нужное место формы вставить вызов
Дополнительные параметры хука math
По умолчанию
mathMinRange
Минимальное допустимое число
10
mathMaxRange
Максимальное допустимое число
100
mathField
Имя поля с ответом
math
mathOp1Field
Устаревший параметр. Имя поля для первого числа в уравнении.
op1
mathOp2Field
Устаревший параметр. Имя поля для второго числа в уравнении.
op2
mathOperatorField
Имя поля определяющего оператор уравнения
operator
Кастомизация хука math
recaptcha — добавляет рекапчу к форме.
Хук recaptcha предназначен для вставки в форму устаревшей версии рекапчи от гугл. На момент написания статьи лучше установить и использовать хук recaptchav2.
Для использования recaptcha надо добавить подключение в параметр hooks
и вставить следующие теги в нужное место формы
затем прописать ключи google в системные настройки:
Дополнительные настройки хука recapture
Ключи можно получить на странице google recapture
redirect — перенаправляет пользователя на специальный ресурс, при завершении отправки.
При переадресации, значения полей формы не будут доступны на конечном ресурсе. Если необходимо передать значения полей формы, можно использовать свойство &store компонента FormItRetriever.
spam — проверяет все поля формы, указанные в свойстве spamEmailFields, на фильтр спама через StopForumSpam. Если пользователь помечен как спамер, форма покажет сообщение об ошибке.
Не рекомендуется использовать IP для проверки спама, поскольку спамеры могут легко изменять IP-адреса, а проверка IP-адресов может выдать ложное срабатывание.
FormItSaveForm — хук для сохранения результатов формы внутри панели менеджера.
Список расположен в Приложения (Extras) => FormIt. Доступные настройки:
Дополнительные хуки
Помимо предустановленных хуков можно писать свои или скачивать их с репозиториев. Для написания своего хука можно использовать сниппет, указав в параметре hooks его название.
Список полезных хуков которые можно скачать:
recaptchav2 — хук для интеграции с рекапчей от гугл второй и третьей версии.
Для интеграции надо добавить подключение в параметр hooks:
и вставить следующие теги в нужное место формы:
затем прописать ключи google в системные настройки:
для рекапси 3 версии используйте соответствующие настройки:
Ключи можно получить на странице google recapture
Селекты, чекбоксы, переключатели
(selects, checkboxes, radio buttons)
Для множественных полей формы, таких как селекты, чекбоксы и переключатели, стандартный способ подключения не сработает. Для таких случаев в FormIt предусмотрены сниппеты FormItIsSelected и FormItIsChecked.
Оформление select поля
Оформление checkbox и radio поля
У html чекбоксов есть особенность — если значение отсутствует, параметр не передаётся, это так же влияет на проверку заполненности поля. Для того, чтобы отправить пустое значение, необходимо добавить скрытое input поле
Таким образом можно проверить, выбран ли хотябы 1 флажок.
Если надо установить поле с массивом значений (группу флажков, с одинаковым именем, или множественный селект) в преХук, надо сперва раскодировать данные из json формата
Настройка целей для счетчиков
Возможные ошибки
— Если FormIt говорит об успешной отправке формы, но письмо на почту не приходит, стоит проверить
Если же на сервере стоит версия php 5.4 и выше, то искать проблему стоит в логах Modx (core/cache/logs/error.log) и сервера. Если записей в логах нет, попробуйте переустановить компоненты FormIt и AjaxForm, и посмотрите, не вылезают ли ошибки во время установки. Если компонент ругается на ошибки, проставьте соответствующим папкам на сервере права доступа 700. И попробуйте переустановить снова (кнопка reinstall может не помочь, иногда эффективнее воспользоваться uninstall). Подробнее об ошибке 500.
— Если в списке отправленных форм, на странице FormIt в админ панели, вместо нормального списка отображается массив символов — вероятно вы раньше времени перешли на php 7.1, спуститесь на 7.0, либо ждите фикса компонента.
Основные настройки сайта, добавленного в конструктор
Выбраны и настроены все поля форм и кнопка
Здесь можно задать текст соглашения об обработке ПД
Настройка дизайна формы