Урок 9. Создание контакт-формы с помощью FormIt

Итак сегодня мы начинаем наш 9 урок MODX Revolution для новичков. Сегодня мы рассмотрим как создать простую контакт форму на нашем вебсайте используя сниппет FormIt. В предыдущем уроке мы ознакомились с работой Wayfinder. Научились делать вывод динамического меню с этим сниппетом. Сегодня опираясь на некоторые ваши знания о сниппетах попытаемся разобраться со сниппетом FormIt, урок будет довольно-таки длинным, поэтому сразу настраиваемся на интересную и плодотворную работу.

Что такое FormIt?

FormIt – это сниппет, который позволяет строить динамические формы всередине MODX Revolution. Если вы используете MODX Evolution, то вы возможно уже использовали eForm для генерирования и обработки своих форм. FormIt – это MODX Revolution эквивалент сниппета eForm, но это абсолютно иной сниппет.

Почему использовать именно FormIt?

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

Загрузка и установка FormIt

Знакомый нам по предыдущим урокам процесс, здесь я не буду останавливатся. Думаю у вас прекрасно пройдет установка и без объяснений.

Подготовка шаблона

Я надеюсь, что сейчас вы уже прошли предыдущие уроки и портировали шаблоны внутренних страниц в вашем MODX сайте. Если вы используете тот же шаблон что и я, то вы увидите, что страница контактов является php страницой с PHP скриптами. Если вы использовали этот шаблон для построения статического сайта, то это будет как раз кстати, так как вы будете использовать для построения вашей формы существующий PHP код. В то же время, так как мы портируем наш шаблон в MODX, то нам не нужен этот код PHP, так как сам MODX разберется с построением всех наших форм. Всё, что нам нужно, – это HTML код формы и затем мы используем FormIt, который сделает всю остальную работу.

Посмотрите на статическую страницу контактов, которая идет вместе с нашим шаблоном:

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

Первое, что необходимо сделать – это убрать HTML/CSS код и портировать его в MODX, если вы это уже не сделали. Так как моя контакт страница – это на самом деле PHP скрипт, то я просто открыл эту страницу в браузере и посмотрел исходный код. Это позволило мне увидеть простой выводимый HTML без кода PHP. Далее я скопировал данный код и вставил его в MODX для формирования шаблона моей страницы контактов. Дальше я по обычной схеме использовал несколько чанков для упрощения работы, то как мы уже делали на предыдущих уроках. И вот что у меня получилось:

Я сохранил этот шаблон под названием 7in1-contact и назначил его шаблоном страницы контактов.

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

Важной особенностью здесь является та, что я заменил текст Contact в h2 тегах чанком [[*pagetitle]], который всплывет в вашей памяти, если вы внимательно прошли мои уроки.

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

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

Приступим к нашей форме. Для начала я заменил HTML код для формы, который содержался между div тегами “contact-wrapper” и заменил его тегом [[*content]]. Это значит, что всё в основном поле контента появится в моей странице контактов на этом месте. Поэтому сейчас страница контактов будет иметь такой вид:

Видно, что там где должна быть форма, сейчас находится текст, который я вставил в область контента страницы контактов при её создании. Как видно на странице этот текст заключён в светлобежевый контейнер.

Как использовать сниппет FormIt

Итак, чтобы FormIt заработал, вам необходимо разместить вызов сниппета и HTML код формы в месте контакт формы. Если вы используете eForm сниппет MODX Evolution, то вам необходимо создать tpl шаблон для вашей формы, а затем вызвать его в сниппете, но при использовании FormIt вам не нужно вызывать форму в сниппете, вместо этого вы размещаете форму после вызова сниппета.

Давайте взглянем на вызов сниппета. Документация FormIt официального сайта MODX содержит отличный пример формы контакта и мы модифицируем его и используем в нашем случае. Будет полезно почитать документацию по этой ссылке http://rtfm.modx.com/display/ADDON/FormIt

Первое, что вы видите, когда смотрите на документацию – это то, что вам необходимо определить хуки вашего FormIt вызова. Хуки – это скрипты, которые срабатывают при вызове вашего сниппета. Вы можете связывать их вместе, но важно знать, что они исполняются последовательно и если один выдаст ошибку, то не сработают и остальные. Существуют предхуки и обычные хуки, но сейчас нас будут интересовать только нормальные хуки, которые запускаются после подтвержения и обработки формы. Вы можете создать собственные пользовательские хуки, но пока будем использовать обычные хуки.

Первый необходимый хук, который посылает электронную почту – это email и он имеет несколько параметров задокументированных здесь (http://rtfm.modx.com/display/ADDON/FormIt.Hooks.email). Выберите нужные для создания формы контактов параметры. Давайте сформируем наш вызов сниппета:

Как видно мы использовали вызов сниппета с одним хуком – email, и определили для него три параметра &emailTpl, &emailSubjectи &emailTo. Убедитесь что параметру &emailTo вы присвоили ваш email адрес вместо показаного в примере me@myemailaddress.com.

Параметр emailTpl определяет чанк, который содержит шаблон для сообщения высылаемого формой. Перед созданием этого чанка нам нужно добавить форму, которую будет заполнять пользователь. Как я уже сказал до этого, мы будем использовать код HTML для формы, который содержался в нашем шаблоне и модифицируем его для работы с вызовом нашего сниппета FormIt call. Сырой код выглядит вот так:

Нам нужно немного изменить эту форму, чтобы FormIt мог ее обработать. Первое, что мы сделаем – это поменяем поменяем действие, чтобы оно указывало на текущую страницу, так как именно здесь находиться вызов сниппета FormIt. Мы делаем ссылку на текущую страницу используя синтаксис MODX Revo: [[~[[*id]]]]. Если вы посмотрите внимательно на этот вызов, то увидите то, что внутренний блок – это просто тег для ID поля: [[*id]] и внешняя часть – это тег для привязки url, например: [[~123]]

Во-вторых, поменяем форму вложив в соответвтвующие FormIt заполнители в значения атрибутов каждого элемента поля для замены статических битов.

Результат выглядит приблизительно так:

Быстрый способ это сделать можно сравнив вашу контактную форму с формой представленной в документации FormIt. Также вы можете начать с формы в документации и в ней просто поменять классы для соответсвия вашей форме.

Далее разместите вызов сделанного нами сниппета в области контента вашей страницы Contact, а далее вставьте ваш код формы после вызова сниппета. Область контента должна содержать:

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

Отлично, форма выглядит в точности как оригинал. Но нам нужно протестировать её и посмотреть как MODX делает всю работу. Перед тестированием давайте создадим сообщениее, которое будет отправлено получателю с вебсайта. Этот чанк emailTpl мы обозначили в нашем FormIt вызове.

Мы используем заполнители для отправки необходимой информации из формы и мы ссылаемся на них, используя имена соответствующих полей. В моем случае я хочу знать все детали и контактную инфомацию введённую в форму. Поэтому я создал чанк sentEmailTpl и добавил к нему следующее:

Из того, что мы уже изучили вы можете догадаться что произойдет. Сниппет FormIt и парсер MODX возмёт значения из контакной формы и вставит их в заполнители в почте, которую я получу.

Теперь давайте протестируем нашу контактную форму. .

Проверим почту и увидим, что получено сообщение:

Вы видите, что введенный текст в поле параметра тема сниппета FormIt оказалась строчкой нашей строчкой темы.

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

Единственной вещью, которую я заметил – это то, что я забыл добавить закрывающую скобку после (ext в моем шаблоне. Остальное выгдядит отлично и форма работает.

Добавление проверки

Следующей вещью, которую вы заметите – это то, что форма имеет поля, которые нужно обозначить как «обязательные для заполения», такие как: имя, имейл и комментарий. Дополнительно имена должны быть длинной более чем две буквы. Мы добавляем проверку к нашей форме, используя свойство &validate (смотрите ссылку в конце записи). Существует несколько встроенных валидаторов и мы будем использовать их в нашем вызове. Отмечу, что валидаторы могут быть связанными, поэтому если вам нужно проверить несколько вещей в одном поле, например, имя обязательно к заполнению И оно должно быть больше двух букв, то вы связываете эти два валидатора вместе. Поэтому для поля имя, первым шагом будет проверка наличия имени:

Теперь добавим второй валидатор:

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

…то бишь с соединёнными валидаторами, которые передают параметры, вы можете сделать так:

Отлично, давайте продолжим и добавим проверку в наш вызов FormIt.

Теперь же, если какой-нибудь Вася Петров пытается послать сообщение и вместо своих имени и фамилии ставит инициалы, то форма выдаст ошибку:

Для вывода ошибок вам необходимо воспользоваться чанком вывода ошибки работы спиппета FormIt:

[[!+fi.error.attibute_name]], где attribute_name – имя атрибута вашей контакт формы.

В контакт-форму для вывода ошибки в таком случае необходимо вставить запись вида:

Возле каждого атрибута, который мы проверяем – подвергаем валидации.

Если вас интересует откуда появились данные сообщения, то они закрепленны в Lexicon за formit. Зайдите в System->LexiconManagement, и далее поменяйте в выпадающем списке “core” на “formit” и далее вы увидите эти сообщения. Там вы можете поменять их либо же добавить свои собственные.

Мы можем продолжить и создать пользовательский валидатор для поля номера, но это тема другого урока.

Борьба со спамом

Теперь мы знаем как работает наша форма и мы получаем сообщения и проверка поля работает. Осталось выяснить как же бороться с попытками ботов высылать спам через нашу форму. Сниппет FormIt имеет два встроенных способа решения данной проблемы. Одна – это spam хук и вторая – это reCaptcha хук.

Спам хук просто проверяет поля, которые вы настроили согластно спам фильтра через http://www.stopforumspam.com/. Если они совпадают, то тогда высвечиваетсчя ошибка напротив поля(ей) и сообщение просто не посылается. Больше вы сможете почитать об этом здесь: http://rtfm.modx.com/display/ADDON/FormIt.Hooks.spam. Мы будем использовать значения по умолчанию для спам хука, который будет проверять поле имейл адреса.

Таким образом в нашем параметре хуков в FormIt добавим спам хук:

Хук reCaptcha работает на базе the reCaptcha service для обеспечения поддержки вашей формы. Для использования reCaptcha вам вначале необходимо иметь бесплатный аккаунт на http://www.google.com/recaptcha. После создания аккаунта добавте домен вашего сайта и вам выдадут два ключа: частный ключ и публичный ключ. Вы можете использовать эти ключи на ваших доменнах либо субдоменнах. Если вы создаете глобальный ключ, то вы можете использовать его на множестве доменов.

Теперь необходимо ввести эти два ключа в системных настройках для сниппета formit. Зайдите в System->System Settings, и в выпадающем списке вместо core выберите formit.

Перед вами появятся три поля, одно для частного ключа, одно для публичного и одно задаст запрос о том, хотите ли вы использовать SSL. Введите ключи от reCaptcha в эти два поля:

Отлично, теперь можно добавить рекапча хук к нашему вызову FormIt:

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

Теперь моя форма выглядит вот так:

Перенаправление на страницу успешного выполнения

Сейчас форма сделана так, что как только сообщение успешно послано, то пользователь переходит на пустую форму контакта. Мы можем это поменять так, что пользователь отсылается на страницу, которая показывает, что сообщение успешно отослано. Чтобы это сделать мы используем хук редиректа. Нам нужно определить на какую страницу должен быть перенаправлен пользователь и делаем это используя параметр redirectTo и добавляем что-то типа &redirectTo=`123`, где 123 это идентификатор ID страницы куда будет перенаправлятся пользователь. Я просто добавлю хук в конце списка хуков и добавлю параметр redirectTo:

После успешного выполнения формы, посетитель сайта будет отослан на страницу с ID of 10, которая является thank you странице (я создал ее и скрыл от меню).

Создание автоответчика

Последний хук о котором мы поговорим в даной записи – это хук автоответчика FormItAutoResponder hook, аон просто отсылает автоответ отсылателю комментария. Этот хук имеет несколько свойств (http://rtfm.modx.com/display/ADDON/FormIt.Hooks.FormItAutoResponder) но мы используем лишь некоторые из них в нашей форме. Вначале мы созданим шаблон содержащий имейл для обратной отсылки на имейл. Это единственное необходимое для заполнения поле. Я создал чанк с названием autoResponseTpl и добавил следующие строки:

Как вы видите я снова использовал заполнители так же, как и до этого в случае с sentEmailTpl. Теперь нужно добавть хук FormItAutoResponder и его свойства к вызову сниппета FormIt как показано ниже:

Как вы видите выше я добавил не только необходимые свойства, но и несколько доступных для заполнения. Важно отметить реквизит &fiarToField который я определил как contact_email. Это важно, потому что если вы не установите его по умолчанию в “email” но ваше поле почты может иметь другое имя, как в моём случае.

Я протестирую эту форму отсылая сообщение, используя один из моих имейл адресов. Когда я проверю этот адрес, я увижу, что получил автоответ от формы с темой, как я определил в реквизите &fiarSubject и отослал от имени указаном в реквизите&fiarFromName:

Как вы видите по полученному письму – оно соответстует тому, что мы задали в нашем чанке автоответчика

Заключение

В этом уроке мы научились как использовать сниппет FormIt для обработки контакт формы в сайте MODX Revolution. Мы исследовали различные хуки и основы их использования. Теперь мы имеем функционирующую форму полностью под управлением MODX, но по внешнему виду совпадающей с нашим шаблоном. Еще много чего можно сделать с FormIt и мы будем более детально исследовать данный сниппет в следующих уроках.

Как домашнее задание – можете исследовать сниппет FormIt Retriever и узнайте, сможете ли вы интегрировать его в вашу контакт форму.

Дополнительные источники :

• Урок 24. Создание простого компонента Qaptcha
• FormIt official Documentation
• FormIt Hooks
• FormIt Validators
• FormIt Tutorials and Examples
Oct 28 2011 уроки MODx Revolution FormIt дополнения сниппеты Виктор Матушевский
Урок 8. Вывод меню с помощью Wayfinder Урок 9-2. Добавление поля вложения в…