• Документация
• Конструктор
• Регистрация

API формы обратной связи

В большинстве режимов конструктор скрывает от пользователя технические детали вёрстки HTML-кода и CSS-стилей формы, логику JavaScript-обработчика, механизм взаимодейтсвия формы с нашим сервером. В результате функциональность формы ограничивается только теми возможностями, настройка которых доступна в интерфейсе конструктора. При этом формируемый код оказывается избыточным и не интегрируется в единый стиль сайта — это плата за одинаковое отображение формы на всех сайтах, в том числе плохо исполненных технически.

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

Общий механизм работы

HTML-код, устанавливаемый на сайте пользователя, содержит статически свёрстанную форму со стилями, включённый блок JavaScript с дескриптором формы в формате JSON, и загружаемый с нашего сервера клиентский JavaScript-обработчик формы. Форме назначен развёрнутый у нас серверный обработчик — он получает введённые пользователем данные и обеспечивает формирование и отправку писем. После обработки данных — в случае удачной отправки письма или при возникновении ошибок — обработчик возвращает пользователя назад на страницу, где установлена форма, и передаёт дополнительные параметры. По этим параметрам клиентский JavaScript-обработчик понимает, какой ответ нужно показать: об успешной отправке, либо об ошибке. В случае ошибки заполнения формы дополнительно делается запрос на сервер, введённые данные восстанавливаются, а пользователю предлагается внести исправления.

Размещение клиентского и серверного обработчика на нашем сервере позволяет согласованно изменять их при обновлениях системы, сохраняя работоспособность старых корректно установленных форм.

Дескриптор формы

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

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

Ручная вёрстка кода формы

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

В таком режиме создаётся минимальная, но полнофункциональная разметка. По умолчанию клиентские события обрабатываются загружаемым с нашего сервера обработчиком, при этом он использует служебные элементы разметки, их адресация выполняется по CSS-классам. Элемент с классами ff_form style_lib задаёт реестр стилей, применяемых для «раскрашивания» элементов формы при возникновении различных событий. Каждый вложенный элемент реестра является носителем стиля и имеет класс-метку для определения его назначения. Стиль элемента-носителя может задаваться как добавлением CSS-классов, так и явным заданием CSS-свойств в атрибуте style. При применении стиля к целевому элементу ему назначаются все CSS-классы элемента-носителя, кроме метки, а также переносятся все явно заданные CSS-свойства. Все элементы-носители стилей являются опциональными — при их отсутствии стиль целевого элемента не изменяется.

Реализованы следующие сценарии обработки событий (говоря о применении стиля X к элементу, подразумеваем перенос стиля из реестра с элемента-носителя с меткой __zff_X):

• Успешная отправка. Форма скрывается (display:none), элементу с классами ff_form message назначается стиль ok_msg, а внутри него выводится сообщение об успешной отправке письма.
• Техническая ошибка. Форма скрывается, элементу с классами ff_form message назначается стиль err_msg, а внутри него выводится сообщение об ошибке.
• Ошибка проверки данных. Элементу с классами ff_form message назначается стиль err_msg, а внутри него выводится сообщение об ошибке. При ошибках сразу в нескольких полях их имена перечисляются в виде списка <ul><li>Поле1</li>...</ul>. Введённые пользователем данные восстанавливаются — загружаются с сервера и заносятся в поля формы, адресуемые по атрибуту name). Для всех ошибочных полей заполняются и отображаются стилем err_el_msg ассоциированные с ними элементы вывода ошибок, если таковые имеются — их поиск выполняется по классу, например __zffel_1_err. Ко все меткам ошибочных полей, также адресуемым по CSS-классу, применяется стиль err_label, а ко всем полям — err_field.

<!-- Минимальная вёрстка, рассчитанная на клиентскую обработку событий по умолчанию --> <div> <form method="post" action="http://www.zahodi-ka.ru/i/ff_v001.fcgi"> <!-- Реестр стилей, применяемых клиентским обработчиком --> <span style="display:none;" class="ff_form style_lib"> <!-- Элементы-носители стилей, применяемых к: полю, заполненному с ошибкой --> <span class="__zff_err_field"></span> <!-- метке ошибочно заполненного поля --> <span class="__zff_err_label"></span> <!-- подписью под ошибочно заполненным полем --> <span class="__zff_err_el_msg"></span> <!-- сообщению об ошибке --> <span class="__zff_err_msg"></span> <!-- сообщению об удачной отпраке --> <span class="__zff_ok_msg"></span> </span> <!-- Элемент для вывода сообщений --> <div class="ff_form message"></div> <div class="ff_form elements_wrap"> <!-- Идентификатор с версией формы — по нему сервер определяет необходимость регистрации изменений; менять вручную нельзя --> <input type="hidden" name="rev_id" value="xDGQWE2pCcFc0002"/> <!-- Метка поля, ID можно удалить, если не нужно изменять стиль метки при ошибке заполнения поля --> <label for="__zffel_1" class="__zffel_1_lbl">Сообщение</label><br/> <!-- Тип поля можно менять, важно сохранить имя и ID --> <textarea name="__zffel_1" id="__zffel_1" rows="10"></textarea> <!-- Элемент вывода ошибок заполнения поля, можно удалить, если вывод ошибок для поля не нужен --> <br/><span class="__zffel_1_err"></span><br/> <input type="submit" value="Поехали!"/> </div> </form> </div> <!-- Дескриптор формы нельзя изменять вручную и обращаться к нему программно --> <script language="JavaScript" type="text/javascript"> var zform_metadata = {"rev_id":"xDGQWE2pCcFc0002","descr":{"elements":[{"n":"Сообщение","t":7,"height":"200"},{"n":"Поехали!","t":8}],"t":0},"cp_test":"АаБбВвЪъЫыЬьЭэЮюЯя"}; </script> <!-- Клиентский обработчик --> <script type="text/javascript" charset="utf-8" src="http://www.zahodi-ka.ru/form/ff.js"></script>