MODx-cms.ru » Документация » Программистам » MODx — Ditto, eForm, Wayfinder и т.д.">Основные сниппеты »

Описание

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

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

&formid

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

&tpl

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

&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=`Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.,Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.,Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.` &mailselector=`topic`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Адрес электронной почты, который показывается при отправке сообщенияавтоответчика. Например: Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.

&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установлен). Значения могут быть в виде идентификатора документа (число), именичанка или ссылки на таблицу стилей (относительная или абсолютная). Можноиспользовать несколько значений разделяя их запятыми (,) (фактически можнокомбинировать все три вида значений).

Примеры:

[ !eForm&cssStyle=`assets/site/forms.css,chunkName` ... ]]
[ !eForm &cssStyle=`chunkName` ... ]]
[ !eForm &cssStyle=`http://mysite.com/assets/styles/forms.css` ... ]]

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

  1. как встроенный блок <style>: <style type="text/css">/*какие-то стили*/</style>
  2. как ссылка на таблицу стилей: <link href="/assets/site/forms.css" rel="stylesheet" type="text/css">
  3. как разделенный запятой (,) список ссылок на таблицы стилей: 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=`Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.` &gotoid=`1` &tpl=`orders` &report=`orderreport`]]
[ !eForm? &to=`Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.` &category=`Purchase Order`&tpl=`chunkPurchaseOrder` &report=`chunkPurchaseReport` ]]

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

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

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

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

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

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

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

[ description/title]:[ datatype]:[ required]:[ validationmessage]:[ validation rule]

Data types

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

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

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

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

Extended Server Validation

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

Например:eform="Year of Birth:integer:1:Must be between 1950 and 2002:#RANGE1950-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 всееще используется в eForm1.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. Поиски выражение замены разделяется двумя вертикальными чертами (||)

Поля 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="CalculatedValue:integer:1:Calculation out of range:#RANGE 1-10" />

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

  1. Выпадающий список — обязательное поле (не требуется проверка)
    <select name="mySelect" eform_options="Select Country::1" /> (тип данных не определен)
    <option value="en-au">Australia</option>
    <option value="en-us">USA</option>
    </select>
  2. Текстовое поле — обязательное поле и формат данных для дат.
    <input type="text" name="dobDate" eform_options="Date of Birth:date:1:@EVAL return (strtotime($value)!==-1)?true:false;" />
  3. Много чекбоксов — обязательное поле, можно выбрать только одно значение.
    <input type="checkbox" name="myColors[]" value="Red" eform_options="Colors::1" /> (тип данных не определен)
    <input type="checkbox" name="myColors[]" value="Green" /> (тип данных не определен)