[Документация] TS Умная форма обратной связи / Компоненты / api:feedback

Введение

Настройка

Советы

Компоненты

api:feedback

Конструктор форм

Встроенный конструктор форм (полей) в неограниченным количестве и порядке;
Полям конструктора можно задать любые data-атрибуты и классы;
Поддерживаемые типы полей:

Текстовое поле
Поле E-mail
Дата и время
Дата одиночное поле или множественное
Выпадающий список
Множественный список
Сгруппированный список
Поле-разделитель, поддерживает html
Флажки (выводятся множ. значения)
Флажок один (значение не выводится)
Переключатели (радиокнопки)
Генератор уникального числа (купона на скидку)
Текстовая область
Скрытое поле (hidden)
Загрузка файлов вложениями или ссылками
Числовой счетчик (степпер)
Соглашение об использовании

У полей с типом text, date, datetime, checkbox, radio, coupon, hidden - три обязательных атрибута @input, @type, @name и название поля
Текстовое поле@input@type=text@name=name
У полей типа select, textarea - два обязательных атрибута @select / @textarea, @name и название поля
Выпадающий список@select@name=select
Текстовая область@textarea@name=textarea

Для всех остальных атрибутов поля обязательный порядок не предусмотрен.

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

Все доступные атрибуты полей конструктора

Инпуты <input> - индивидуальные атрибуты для каждого типа

@input	<input>
@type	<input type="date\|datetime\|coupon\|stepper\|checkbox\|file\|hidden\|radio\|text">
	Для полей типа date\|datetime\|hidden\|text
@value	<input value=""> - можно опустить, если нет значения по умолчанию
	Для полей типа checkbox
@value	Одно значение, вместо него выводится флажок типа: Да/Нет
@values	Значение 1#Значение 2#Значение 3
	Для полей типа radio
@values	Значение 1#Значение 2#Значение 3
	Для полей типа coupon
@button_value	Получить
	Для полей типа stepper
@type	stepper
@value	1
@class	stepper
@data-type	int
@data-limit	[1,null]
@data-arrow-step	1
	Для полей типа file
@multiple	Множественное поле, возможность загружать несколько файлов
@size	Количество полей для загрузки файлов по умолчанию
@max	Ограничение на количество загружаемых файлов Если не задано, то берется максимальное значение из настроек сервера `max_file_uploads`

Список <select> - индивидуальные атрибуты

@select	<select>
@multiple	<select multiple>...</select> - означает множественный список
@size	<select size="число">...</select> - задает высоту списка
@values	Значения списка разделены одним знаком решетки # Опция 1#Опция 2#Опция 3 Значения группируются в группы, группы разделены двумя знаками ## Группа 1##Опция 1#Опция 2##Группа 2##Опция 4#Опция 5##Группа 3##Опция 6

Текстовая область <textarea> - индивидуальные атрибуты

@textarea	<textarea>...</textarea>
@cols	количество столбцов
@rows	количество строк

Общие атрибуты для всех полей

@name	Название поля может начинаться только с буквы или символа подчеркивания и состоит из букв латинского алфавита, цифр и подчеркиваний Названия можно писать и в ВЕРХНЕМ и в нижнем регистре заменяя пробелы знаком подчеркивания. Пример правильной записи названия поля: @name=last_name, @name=EMAIL, @name=MIDDLE_NAME Так это будет выглядеть в html-коде: <input type="text" name="EMAIL">
@class	@class=select_box
@required	Атрибут обязательного поля (без значения)
@sort	Сортировка поля (если используется группировка, то сортируются поля в каждой группе отдельно) @sort=1
@group	Группировка полей в отдельные дивы `<div class="group{ID}">группа полей</div>` @group=1 - и так для всех полей начиная с 1-го и до последнего, иначе группировка не сработает.
@placeholder	Серая подсказка у пустого поля @placeholder=Ваше имя
@data-validation	Валидация поля: @data-validation=[NOTEMPTY] - обязательное поле @data-validation=[EMAIL] - проверка e-mail @data-validation=[PHONE] - проверка мобильного телефона @data-validation=[L>=6] - проверка строки на длину больше либо равно 6 и многое другое... Все возможные правила и регулярки смотрите на странице плагина jQuery form Validation
@data-validation-label	Любое название поля для подсказки валидатора, можно опустить, тогда берутся подсказки из настроек компонента @data-validation-label=Ваш пароль
@data-inputmask	Маска поля, где значение является регулярным выражением, шаблоном или алиасом: @data-inputmask='alias': 'email' @data-inputmask='mask': '+7(999) 999-9999' Все возможные правила и регулярки смотрите на странице плагина Jquery.inputmask
@tooltip-title	Строковая подсказка `@tooltip-title=Подсказка` Все возможные настройки смотрите на странице плагина Tooltipster - The jQuery Tooltip Plugin
@tooltip-content	HTML-подсказка `@tooltip-content=#tooltip_content` Сам контент подсказки в любом месте сайта скрытый или видимый блок <div class="tooltip_templates" style="display:none"> <span id="tooltip_content"> <img src="/upload/main-feedback.png"/> <strong>This is the content of my tooltip!</strong> </span> </div>

Пример всех возможных полей конструктора форм

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

"CUSTOM_FIELDS" => array(
  0 => "Ваше имя@input@type=text@name=NAME@value=Значение по умолчанию@required@data-validation=[NOTEMPTY]@data-validation-label=Ваше имя@tooltip-title=Подсказка@sort=1",
  1 => "Ваш пароль@input@type=password@name=PASSWORD@required@data-validation=[L>=6]@data-validation-label=Ваш пароль@tooltip-content=#tooltip_content@sort=2",
  2 => "Номер телефона@input@type=text@name=PHONE@required@data-validation=[PHONE]@data-validation-label=Номер телефона@placeholder=+7(___) ___-____@data-inputmask='mask': '+7(999) 999-9999'@tooltip-content=#tooltip_content@sort=3",
  3 => "Ваш E-mail@input@type=text@name=EMAIL@required@data-validation=[EMAIL]@data-validation-label=Ваш E-mail@data-inputmask='alias': 'email'@tooltip-content=#tooltip_content@sort=3",
  4 => "Дата и время@input@type=datetime@name=DATETIME@required@tooltip-content=#tooltip_content",
  5 => "Дата множ.@input@type=date@name=DATE@size=2@required@tooltip-content=#tooltip_content",
  6 => "Вып-й список@select@name=SELECT1@values=Опция 1#Опция 2#Опция 3@required@tooltip-content=#tooltip_content",
  7 => "Список множ.@select@name=SELECT2@multiple@values=Опция 1#Опция 2#Опция 3@checked=Опция 2#Опция 3@required@tooltip-content=#tooltip_content",
  8 => "Список групп@select@name=SELECT3@multiple@size=8@values=Группа 1##Опция 1#Опция 2#Опция 3##Группа 2##Опция 4#Опция 5#Опция 6@required@tooltip-content=#tooltip_content",
  9 => "Флажки@input@type=checkbox@name=CHECKBOXES@values=Значение 1#Значение 2#Значение 3@checked=Значение 1#Значение 3@optional@inline@required@tooltip-content=#tooltip_content",
  10 => "Флажок@input@type=checkbox@name=CHECKBOX1@value=Да@checked=Да@required@tooltip-content=#tooltip_content",
  11 => "Переключатели@input@type=radio@name=RADIO1@values=Значение 1#Значение 2#Значение 3@required@tooltip-content=#tooltip_content",
  12 => "Дополнительно@input@type=radio@name=RADIO2@values=100#120#140#160#180#200@optional@inline@required@tooltip-content=#tooltip_content",
  13 => "Инлайн значения@input@type=radio@name=RADIO3@values=100#120#130#140#150@inline@required@tooltip-content=#tooltip_content",
  14 => "Купон на скидку@input@type=coupon@name=COUPON@button_value=Получить@required@tooltip-content=#tooltip_content",
  15 => "Текстовая область@textarea@name=TEXTAREA1@cols=30@rows=5@required@tooltip-content=#tooltip_content",
  16 => "<em>Это поле-разделитель, поддерживает HTML</em>",
  17 => "Счетчик@input@type=stepper@name=STEPPER1@value=1@class=stepper@data-type=int@data-limit=[1,null]@data-arrow-step=1@required@tooltip-content=#tooltip_content",
  18 => "Скрытое поле@input@type=hidden@name=HIDDEN1@value=Значение поля по умолчанию",
  19 => "Файлы@input@type=file@name=files@multiple@size=3@max=6@required@tooltip-content=#tooltip_content",
),

JavaScript & jQuery плагины

jQuery 1.8.3 ядра Битрикс;
Autosize - изменяет высоту "textarea" при наборе текста;
jQuery Form Validation - валидатор форм;
CSS Modal - модальные окна;
jQuery iCheck - оформление флажков и переключателей;
HTML5 Placeholder - кроссбраузерные плейсхолдеры для полей;
jQuery Inputmask - маска e-mail, телефон, дата и т.д.
Uikit 2 - плагин модального окна и оформление форм
Bootstrap 3 - плагин модального окна
Возможность спрятать форму после успешной отправки;
Возможность прокручивать страницу к форме при сообщениях и задать скорость прокрутки;

Загрузка файлов

Загрузка файлов в разных режимах, в виде ссылок на файл или вложениями;
Возможность очищать папку с загруженными файлами после отправки сообщения;
Внимание! Все файлы в указанной в настройке компонента папке для загрузки файлов будут удаляться;
Кириллические (Русские) имена загружаемых файлов транслируются в латиницу;
Вывод в шаблоне списка доступных для загрузки расширений файлов;
Задается количество загружаемых файлов;
Задаются названия полей для каждого загружаемого файла;
Задается максимальный размер загружаемого файла;
Задается папка для загружаемых файлов;
Загрузку файлов можно сделать обязательной;
Загружаемые файлы также сохраняются в инфоблоке при включенной записи в инфоблок;
Множественная загрузка файлов по кнопке "+ Добавить еще" в конструкторе форм.

Запись в инфоблок

В инфоблок записываются свойства TICKET_ID (строка или число - номер тикета) и FILES(файлы), а также текстовые и числовые поля, включая множественные.
Для записи свойств код свойства в инфоблоке должен совпадать с кодом в атрибуте @name=КОД ПОЛЯ поля конструктора форм.
Все содержимое почтового шаблона записывается текстом или html (переключается в почтовом шаблоне) в поле инфоблока Детальное описание.
Минимум наличие одного свойства типа "Строка" или "Число" с кодом TICKET_ID обязательно!
Для загруженных файлов наличие множественного свойства типа "Файл" с кодом FILES обязательно!
https://monosnap.com/image/wfhzG6FQFnzHeLjsL3yarmPMyD4O9P.png

E-mail и почтовые шаблоны

Возможность переключать вид заполнения полей в почтовом шаблоне с блочного на табличный;
Возможность задавать в настройках компонента стили к полям в почтовом шаблоне;
Возможность отправки копии сообщения посетителю с другим почтовым шаблоном и темой;
Возможность задать единую тему сообщения в настройках компонента, макросы все также поддерживаются;
Автоматический режим заполнения значений полей в почтовом шаблоне по макросу #WORK_AREA#;
Возможность задавать и выводить вручную любые поля формы в почтовом шаблоне.
Для вывода значения поля конструктора необходимо КОД ПОЛЯ из атрибута @name=КОД ПОЛЯ писать между решетками, пример: #КОД ПОЛЯ#
Почтовый шаблон для администратора и посетителя (устанавливается при установке модуля);
Служебные макросы в почтовый шаблон можно передавать через параметры компонента;
Поддержка событий OnBeforeEmailSend(), OnAfterEmailSend() в /bitrix/php_interface/init.php;
OnBeforeEmailSend - событие перед отправкой формы, можно изменить данные перед отправкой.
OnAfterEmailSend - событие после отправки формы.

Cобытия срабатывают только при отправке сообщения администратору:
Обработчики событий задаются в таком виде в файле /bitrix/php_interface/init.php
AddEventHandler("api.feedback", "OnBeforeEmailSend", "OnBeforeEmailSendHandler");
AddEventHandler("api.feedback", "OnAfterEmailSend", "OnBeforeEmailSendHandler");

Готовый пример обработчика события OnBeforeEmailSend в файле init.php:
AddEventHandler("api.feedback", "OnBeforeEmailSend", "OnBeforeEmailSendHandler");
function OnBeforeEmailSendHandler(&$event_name, &$site_id, &$arFields, &$message_id)
{
    //Т.к. событие OnBeforeEmailSend срабатывает до отправки сообщения,
    //значит вы можете изменять поля формы перед отправкой сообщения, например так:
    $arFields['EMAIL_TO'] = 'info[@]tuning-soft.ru';

    //Так вы можете распечатать в файл передаваемые данные в файл 1_txt.php в текущем каталоге init.php
    $arPrint = array('event_name' => $event_name, 'site_id' => $site_id, 'arFields' => $arFields, 'message_id' => $message_id,);
    $tttfile=dirname(__FILE__).'/1_txt.php';
    file_put_contents($tttfile, "<pre>".print_r($arPrint,1)."</pre>\n");
}

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

Номер тикета	#TICKET_ID#
Тема письма	#SUBJECT#
Заголовок страницы:	#PAGE_TITLE#
URI страницы:	#PAGE_URI#
URL страницы:	#PAGE_URL#
URL раздела:	#DIR_URL#
Заголовок формы:	#FORM_TITLE#
Имя хоста/домена:	#HTTP_HOST#
IP отправителя:	#IP#
Браузер отправителя:	#HTTP_USER_AGENT#
Дата и время:	#DATETIME#
E-mail отправителя письма:	#DEFAULT_EMAIL_FROM#
E-mail получателя письма:	#EMAIL_TO#

Как происходит подмена e-mail в поле От кого/Кому при различных настройках Битрикс и компонента

Поле "От кого":

Без многосайтовости в это поле будет подставлен e-mail из настроек "Главного модуля"
В случае многосайтовости в это поле будет подставлен e-mail из "Настроек сайта", на котором работает форма.
Если в почтовом шаблоне прописать вместо макроса e-mail в поле "От кого", то он заменит все e-mail из настроек главного модуля и из настроек сайта (в случае многосайтовости).
Т.е. с какого сайта не отправляй форму, в поле "От кого" будет один и тот же отправитель.
Вручную прописанный в этом поле e-mail имеет самый высокий приоритет!
В случае отправки письма администратору с включенной опцией "Подставлять в поле "От" e-mail посетителя" сюда подставится e-mail посетителя, иначе сюда подставится e-mail администратора, а какой именно описано в пунктах выше.
В случае отправки письма посетителю, сюда подставится e-mail администратора, а какой именно описано в пунктах выше.

Поле "Кому":

В случае отправки письма администратору, сюда подставится e-mail из настроек компонента в поле "E-mail, на который будет отправлено письмо"
В случае отправки письма посетителю, сюда подставится e-mail посетителя.

Пример почтового шаблона

Информационное сообщение сайта #SITE_NAME#
------------------------------------------
#WORK_AREA#
Служебные макросы

Номер тикета
#TICKET_ID#

Тема письма
#SUBJECT#

Заголовок страницы: #PAGE_TITLE#

URI страницы: #PAGE_URI#

URL страницы: #PAGE_URL#

URL раздела:
#DIR_URL#

Заголовок формы: #FORM_TITLE#

Имя хоста/домена: #HTTP_HOST#

IP отправителя: #IP#

Браузер отправителя: #HTTP_USER_AGENT#

Дата и время: #DATETIME#

E-mail отправителя письма: #DEFAULT_EMAIL_FROM#

E-mail получателя письма: #EMAIL_TO#

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