Перейти к содержанию

MODx/Встроенные сниппеты/eForm

Добавить ссылки
Материал из Викиучебника — открытых книг для открытого мира

Кратко о eForm

[править]

eForm - сниппет входящий в стандартную поставку Modx. Отвечает за обработку данных, которые пользователи вводят в формы на сайте. Полученные данные можно отослать по электронной почте используя формат html, вложения, автоответчик, а также расширенную обработку данных и генерацию настраиваемых отчетов.

Функции, параметры, возможности

[править]

Обязательные параметры

[править]


&formid

Идентификатор формы, который используется при отправке данных. Этот параметр необходим если на странице используется более одной формы. Шаблон вашей формы должен иметь скрытое поле с тем же идентификатором: <input type="hidden" name="formid" value="formName" /> или (начиная с eForm 1.4.x) вы можете установить идентификатор прямо в теге формы: <form id="formName"...>;

&tpl

Название чанка (не число) или идентификатор документа (число) для используемого шаблона (новое в 1.4.4) Вы можете также использовать сниппет как источник шаблона. При этом никакие параметры не передаются. Для регулярных полей формы вам не нужно включать переменные, так как они автоматически включаются eForm, исключая случаи когда вы сами задаете значения. Доступны специальные переменные: [+validationmessage+], [+postdate+],[+verimageurl+] и [+debugText+]. Каждая форма должна содержать переменную [+validationmessage+].

&report

Название чанка (не число) или идентификатор документа (число) для шаблона отчета. Должна содержать каждая форма. Дополнительные параметры

Дополнительные параметры

[править]

&to (необязательно)

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

&from (необязательно)

Устанавливает адрес отправителя письма.

&fromname (необязательно)

Устанавливает имя отправителя письма.

&replyto (необязательно)

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

&sendirect (необязательно)

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

  • 1 - включение
  • 0 - выключение (по умолчанию)

&cc (необязательно)

Также как &email но для Cc:

&bcc (необязательно)

Также как &email но для Bcc:

&ccsender (необязательно)

Послать копию данных формы пользователю. По умолчанию установлено в 0. eForm ищет адрес пользователя в поле с названием email.

  • 1 - включить
  • 0 - отключено (по умолчанию)

&subject (необязательно)

Тема сообщения, которая может включать [.поля формы.]. Например: Спасибо за ваш заказ [.firstname.] [.lastname.]

&noemail (необязательно)

Защищает eForm от посылки писем.

  • 1 - отключить отправку писем
  • 0 - включить отправку писем (по умолчанию)

&mailselector (необязательно)

Устанавливает поле формы, которое будет использоваться при выборе единственного адреса из списка адресов разделенных запятой (,) для использования в параметре &to. Значения поля будет определять номер используемого почтового адреса. Номер 1 соответствует первому адресу и N - последнему.

Пример: &to =`sales@me.com,support@me.com,billing@me.com` &mailselector=`topic`

В форме используется поле topic в виде выпадающего списка. Когда пользователь выбирает значение, то тем самым он определяет один адрес, по которому будут посланы данные формы.

&mobile (необязательно)

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

&mobiletext (необязательно)

Сообщение для отправки на мобильное устройство. Может содержать [.поля формы.]. Например: Заказ для [.firstname.].

&thankyou (необязательно)

Название чанка (не число) или идентификатор документа (число) для используемого шаблона сообщения выводимого пользователю после отправки данных формы. Теги как у &tpl

&gotoid (необязательно)

Идентификатор документа на который будет совершен переход после отправки данных формы. Смотрите также &thankyou.

&category (необязательно)

Название или идентификатор категории используемый для категоризации eForm. Если категория не найдена, то она автоматически будет создана. Это используется в теме сообщение.

&keywords (необязательно)

Разделяемые запятой (,) ключевые слова или [+поле формы+] используемое при поиске банка данных. Например: [+firstname+], [+lastname+], [+email+]

&autosender (необязательно)

Адрес электронной почты, который показывается при отправке сообщения автоответчика. Например: no-reply@mydomain.com

&autoSenderName (необязательно)

Имя, используемое в сообщении автоответчика.

&automessage (необязательно)

Название чанка (не число) или идентификатор документа (число) для используемого шаблона в сообщении автоответчика. Может содержать [.поля формы.].

&allowhtml (необязательно)

Включает использовании пользователями HTML в сообщении.

  • 1 - включено
  • 0 - выключено (по умолчанию)

&language (необязательно)

Устанавливает используемый язык сообщений и проверки. Название языков совпадает с MODx.

&vericode (необязательно)

Включает код проверки. Шаблон должен содержать поле для проверки и переменную [+vericode+].

&debug (необязательно)

Включает расширенные сообщения об ошибках в проверке формы. В основном для отладки #LIST и #SELECT.

&sendAsHtml (необязательно)

Определяет, какие сообщения будут использовать формат html.

  • 1 - все сообщения

report, autotext, mobile - конкретные типы сообщений

&sendAsText (необязательно)

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

  • 1 - все сообщения

report, autotext, mobile - конкретные типы сообщений

&sessionVars (необязательно)

Названия переменных сессии $_SESSION, разделенные запятой (,). Они будут добавлены в список значений полей перед отображением формы и может быть использована качестве скрытых полей. Если вы используете этот параметр, то убедитесь, что вы не раскрываете важную информацию сессии (скрытые поля не защищают информацию!).

Так как eForm не выполняет самостоятельную обработку таких значений, то вам необходимо включить их в шаблон. Например: [!eForm &sessionVars=`jobID` ... ]] и <input type="hidden" value="[+jobID+]" />

&postOverides (необязательно)

Используется в комбинации с &sessionVars. Переменные сессии будут переписаны введенными в форму значениями. При установке значения 1 полученные в форме данные получают приоритет.

&reportAbuse (необязательно)

При установке значения `1` будут посылаться сообщения на специальный электронный адрес если будет замечена попытка инъекции eForm (используйте умеренно).

&cssStyle (необязательно)

Добавляет определение стиля в область <head> страницы, на которой располагается форма или сообщение для пользователя показываемое после отправки (только если параметр &thankyou установлен). Значения могут быть в виде идентификатора документа (число), имени чанка или ссылки на таблицу стилей (относительная или абсолютная). Можно использовать несколько значений разделяя их запятыми (,) (фактически можно комбинировать все три вида значений).

Примеры:

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

  • как встроенный блок <style>: <style type="text/css">/*какие-то стили*/</style>
  • как ссылка на таблицу стилей: <link href="assets/site/forms.css" rel="stylesheet" type="text/css">
  • как разделенный запятой (,) список ссылок на таблицы стилей: assets/site/forms.css,assets/site/more.css,assets/site/gone_overboard.css

&jScript (необязательно)

Аналогично с &cssStyle, но для добавления javasript в область <head> страницы. На текущий момент может быть использовано только при отображении формы.

&protectSubmit (необязательно) по умолчанию - 1 (включено)

Защита формы от повторной отправки с теми же данными. Отправка данных формы автоматически отключается после первой успешной попытки пока ключ формы является одним и тем же. Для этого используется переменной сеанса с md5 хэшем в качестве ключа. Какие поля используются для сравнения задается в параметре &protectSubmit. Возможные значения:

  • 0 - выключено
  • 1 - используются все поля `required`

Список полей - список используемых полей через запятую.

Чтобы гарантировать, что используются соответствующие поля для разных форм переменная сессии основана на &formid ({formid}_hash).

&submitLimit (необязательно) по умолчанию - 0 (выключено)

Устанавливает лимит времени (в минутах) между отправками данных формы. После первой успешной отправки данных запрещает отправку других данных на определенное время. При использовании совместно с &protectSubmit этот параметр имеет приоритет, позволяя повторную отправку данных независимо от установки &protectSubmit (будет сброшена сессионная переменная). Как и &protectSubmit этот параметр использует сессионную переменную основанную на &formid.

&requiredClass (необязательно)

Название класса. Добавляет класс в определенные поля формы при проверке. Существующие классы будут сохранены.

Если вы уже определили класс для полей или меток (label) и получили неожиданные результаты, то проверьте порядок определения классов. &requiredClass устанавливается в начало любых классов, которые уже установлены.

&invalidClass (необязательно)

Название класса. Добавляет класс к неправильно заполненным полям формы, которые выявились при проверке. Существующие классы будут сохранены.

&runSnippet (новое в 1.4.4) (необязательно)

Определяет имя сниппета. Сниппет будет выполнен перед всеми обработками eForm. Один параметр &&formid, будет опущен для сниппета. Любые возвращенные значения из сниппета не будут учитываться. Это может быть использовано как альтернатива использования функций в документе. К сожалению eForm молча проигнорирует результат работы сниппета, так как $modx->runSnippet не возвращает никаких значений.

&snipFolder (новое в 1.4.4) (необязательно)

Для тех кто хочет использовать оставить другие версии eForm активными. Теперь вы можете сохранить все файлы eForm и соответственно установить &snipFolder. Например вы можете сохранить версию 1.4.4 в папку assets/snippets/eform/1.4.4 и установить &snipFolder=`eform/1.4.4`. К значению автоматически добавится путь 'assets/snippets/'. Не нужно использовать закрывающий слэш (/)!



Функции событий

[править]


Функции событий eForm теперь включены в параметры.

&eFormOnBeforeMailSent (необязательно)

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

&eFormOnMailSent (необязательно)

Определяет название функции. Эта функция будет запущена после обработки всех шаблонов и любое сообщение будет послано.

&eformOnBeforeFormParse (необязательно)

Определяет название функции. Эта функция будет запущена после загрузки шаблонов и определения идентификатора формы. Функции передаются следующие параметры: &$templates - массив всех шаблонов с индексами 'tpl', 'report','thankyou' и 'autotext'. Последние три будут иметь значение только после отправки формы.

&eFormOnBeforeFormMerge (необязательно)

Определяет название функции. Эта функция будет запущена только при показе форм и до определения всех переменных шаблона. Функции передаются следующие параметры: &$fields - массив полей и значений переменных.

&eFormOnValidate (необязательно)

Определяет название функции. Эта функция будет запущена после проверки данных формы. Это можно использовать для определения собственного алгоритма обработки. Функции передаются следующие параметры:

  • &$fields - массив полей и значений переменных
  • &$vMsg - числовой массив ошибок проверки данных формы
  • &$rMsg - числовой массив пропущенных обязательных полей

Примеры: 

*[[!eForm? &to=`me@mydomain.com` &gotoid=`1` &tpl=`orders` &report=`orderreport` ]]
*[[!eForm? &to=`sales@mysuppliers.com` &category=`Purchase Order` &tpl=`chunkPurchaseOrder` &report=`chunkPurchaseReport` ]]

Переменные шаблона

[править]

Для многих стандартных полей формы eFrom автоматически вставляет соответствующие переменные шаблона. Также вы можете определить их самостоятельно:

  • [+validationmessage+] - Необходимо использовать в каком-то месте вашего шаблона или документа. С версии 1.4.2 эта переменная шаблона подверглась изменениям. Во-первых теперь ее не обязательно использовать в шаблоне. Теперь вы можете разместить ее в любом месте вашего документа. Во-вторых вам необязательно устанавливать какие-то тэги вокруг этой переменной. Теперь все html окружение включается в значение $_lang['ef_validation_message'] в языковом файле eForm.
  • [+vericode+] и [+verimageurl+] - необходимы если вы собираетесь использовать в форме графическую проверку (captcha). Смотрите в примерах как это использовать.
  • [+postdate+] - эта переменная будет использована в отчете и сообщении для пользователя после отправки данных формы и установит текущую дату и время.
  • [+debug+] - начиная с версии 1.4.1, автоматически устанавливается, если включен режим отладки, в форме и сообщении для пользователя после отправки. Не помещается автоматически в шаблон отчета. Необходимо избегать отправку технической информации через сервер. Если вы хотите протестировать отправку писем, то можете включить эту переменную самостоятельно.

Типы и форматы данных

[править]


eForm имеет встроенный анализатор определяющий формат и тип данных с соответствующей проверкой каждого поля. Для настройки используется добавление дополнительного параметра eform в необходимые поля.

<input type="text" name="color" eform="A Color:string:1" />

Базовый вид параметра eform следующий:

[description/title]:[datatype]:[required]:[validation message]:[validation rule] Data types


Data types (Типы данных)

[править]

Вы можете устанавливать только эти типы данных. Другие определяются автоматически.

Все поля автоматически проверяют на пустоту значений.

  • string - не имеет специальной проверки кроме пустоты и обязательности заполнения.
  • date - проверяется на правильность формата даты (основано на функции strtotime())
  • integer - проверяется на числовое значение (не проверяется, если оно целое)
  • float - проверка на числовое значение
  • email - проверяет правильность адреса email с использованием регулярных выражений
  • file - (для поля загрузки файла) - проверяет соответствие разрешенному размеру, на текущий момент не имеет проверки типов файлов.
  • html - также как тип string только перенос строки преобразуется в тэг

Выпадающие списки, чекбоксы, и радиобатоны не требуют определения типа. eForm определяет их автоматически.



Extended Server Validation (Дополнительная проверка сервером)

[править]


Эта версия поддерживает расширенную проверку на стороне сервера и фильтрацию, использующую очень гибкие правила проверки, которые включаются в параметр eform. Вы можете определить 2 дополнительных параметра проверки, сообщение об ошибке и проверке или правило фильтра.

Например:

eform="Year of Birth:integer:1:Must be between 1950 and 2002:#RANGE 1950-2002"



Правила проверки:

[править]

\#LIST - перечисленные через запятую возможные значения. Например: #LIST красный,зеленый,оранжевый,синий

\#RANGE - разделенные запятой возможный числовые значения или числовые диапазоны. При установке диапазона порядок не имеет значения. 1~10 и 10~1 будут одинаково определять числа между 1 и 10 (включительно). Можно использовать как положительные так и отрицательные числа.

Например: 

#RANGE 1,3,-5~-15,60~82

\#SELECT - определяет правильность значений, которые будут возвращены из базы при запросе. Запрос должен возвращать значения только одной колонки (функция проверяет только первую колонку). Вы можете использовать {DBASE} {PREFIX} тэги. Они будут автоматически заменены на название базы MODx и используемый префикс таблицы.

Например: 

#SELECT keyword FROM {PREFIX}site_keywords

\#EVAL - строка кода PHP. Может возвращать true или false. Внимание! Хотя #EVAL все еще используется в eForm 1.4, но в будущих версиях они скорее всего больше не будут поддерживаться. Взамен используйте #FUNCTION.

\#FUNCTION - название функции. Функция должна использовать только одно значение (значение поля) и возвращать TRUE или FALSE. Смотрите примеры, чтобы разобраться как это действует.

Например: 

#FUNCTION myValidationFunction

\#REGEX - регулярное выражение. Синтаксис preg_match() в PHP.

Пример: 

#REGEX /^[a-z]+ [a-z0-9_]+/i

\#FILTER - фильтры не проверяют введенных значений, но заменяют слова и значения, которые соответствуют критериям. Вы можете использовать следующие фильтры:

\#FILTER #LIST

Используйте две вертикальные черты для разделения заменяемых и заменяющих слов.

Например: 

#FILTER #LIST badword,verybadword||goodword,verygoodword

\#FILTER #EVAL

Например: 

#FILTER #EVAL return myFilterFunction($value);

(естественно вы должны быть уверены в существовании указанной функции) Примеры применения фильтра: 

function myFilterFunction($value){
   $badWords = array('scribble','coding');
   $goodWords = array('design','sleep');
   return str_replace($badWords,$goodWords,$value);
}
#FILTER #REGEX

Регулярное выражение замены. Синтаксис preg_replace() в PHP. Поиск и выражение замены разделяется двумя вертикальными чертами (||)

SMTP(Отправка писем через SMTP)

[править]

Стандартный сниппет eform не поддерживает возможность отправки писем по протоколу SMTP c аутентификацией, и использует PHP функцию mail(), но на некоторых серверах с целью борьбы с рассылкой спама закрыта возможность неаутентифицированной отправки писем. Модифицированный скрипт eform modx (v 1.4.4.5) позволяет отправлять письма по протоколу SMTP, а также поддерживает вызов сниппета с указанием параметров вызова через конфигуратор smartConfig.

Eform modx c расшренным функционалом.

Поля select, radio и checkbox

[править]

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

Скрытые поля

[править]

По умолчанию скрытые поля присутствуют как защита от подделки формы при сравнении используемых значений (как в полях select, radio и checkbox). Но в некоторых местах это может быть ненужно. Например если вы используете обработку javascript, которая хранит свои значения в скрытых полях. В этом случае вы можете изменить это поведение используя параметр eform (включая или выключая проверку).

Скрытое поле пример 1:

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

<input type="hidden" name="docId" value="31" />

Скрытое поле пример 2:

Если вы используете javascript, который хранит значения в скрытых полях, то вам необходимо убрать проверку поля так: <input type="hidden" name="calculatedField" value="" eform="::0::" />

Скрытое поле пример 3:

Пример похожий на 2, но вы хотите убедиться, что возвращенные значения лежат в допустимом диапазоне чисел. Установим для параметра eform заголовок, числовой тип данных, обязательность заполнения, сообщение об ошибке и проверку на диапазон. Это будет выглядеть так: <input type="hidden" name="calculatedField" value="" eform="Calculated Value:integer:1:Calculation out of range:#RANGE 1-10" />

Пример полей с проверкой

[править]

Выпадающий список - обязательное поле (не требуется проверка)

<select name="mySelect" eform_options="Select Country::1" /> (тип данных не определен) <option value="en-au">Australia</option> <option value="en-us">USA</option> </select>

Текстовое поле - обязательное поле и формат данных для дат. <input type="text" name="dobDate" eform_options="Date of Birth:date:1:@EVAL return (strtotime($value)!==-1)?true:false;" />

Много чекбоксов - обязательное поле, можно выбрать только одно значение. <input type="checkbox" name="myColors[]" value="Red" eform_options="Colors::1" /> (тип данных не определен) <input type="checkbox" name="myColors[]" value="Green" /> (тип данных не определен)

Простейший пример использования

[править]

Шаг 1. Создаём форму и помещаем её в чанк. Назовем её 'eFeedbackForm' 


<p><span style="color:#900;">[+validationmessage+]</span></p>
<form method="post" action="[~[*id*]~]">
	<input type="hidden" name="formid" value="feedbackForm" />
	
	<p><label accesskey="n">Ваше Имя</label>
	<input type="text" name="Name" maxlength="60" eform="Your Name::1" /></p>

	<p><label accesskey="e">Ваш е-мэйл адрес</label>
	<input type="text" name="email" size="40" maxlength="40" eform="Your Email Address:email:1" /></p>
	
	<label accesskey="s">Тема</label>
	<select name="subject">
		<option value="Feedback">Проблемы с сайтом, пожелания.</option>
		<option value="Support request">Запрос технической поддержки</option>
		<option value="Feature Request">Запрос подробностей.</option>
	</select>
	
	<p><label accesskey="c">Текст письма</label><br />
	<textarea cols="40" rows="10" name="comments" eform="Comments:html:1"></textarea></p>

	<p><label>Хотели бы вы подписаться на нашу рассылку?</label>
	<input type="radio" name="list" value="Yes" eform="Mailling List::0:" /> Да&nbsp;
	<input type="radio" name="list" value="No" /> Нет&nbsp;</p>

	<p>
	Пожалуйста введите код: (Чтобы предупредить спам)<br />
	<img src="[+verimageurl+]" alt="verification code" /><br />
	<input type="text" name="vericode" size="20" />
	</p>
	
	<p><input type="submit" name="submit" value="Send Feedback"></p>
</form>

Шаг 2. создадим емэйл шаблон (шаблон отчёта) И поместим в чанк. Назовем его 'eFeedbackReport' 

<p>Прислано человеком, с именем: [+Name+] . Подробности ниже:</p>
<table>
<tr valign="top"><td>Имя:</td><td>[+Name+]</td></tr>
<tr valign="top"><td>mail:</td><td>[+email+]</td></tr>
<tr valign="top"><td>тема:</td><td>[+subject+]</td></tr>
<tr valign="top"><td>Содержание:</td><td>[+comments+]</td></tr>
</table>
<p> Хочет ли  [+name+] Быть в рассылке? <strong>[+list+]</strong></p>
 
<p>Можно использовать ссылку для ответа: <a href="mailto:[+email+]?subject=RE:[+subject+]">[+email+]</a></p>

Шаг 3. (по желанию) создаём страницу благодарности. И поместим её на страницу с id 34. 

<h3>Спасибо Вам!</h3>
<p>Мы рады, что Вы воспользовались этим сервисом.</p>
<p>Если Вам на письмо никто не ответит - напишите через несколько дней.</p>

Step 4. добавляем вызов сниппета на (новую) страницу. 

[!eForm? &formid=`feedbackForm` &to=`me@some.domain.com` &tpl=`eFeedbackForm` &report=`eFeedbackReport` &gotoid=`34` &vericode=`1`!]

Источник

Источник — https://ru.wikibooks.org/w/index.php?title=MODx/Встроенные_сниппеты/eForm&oldid=163623