Форма обратной связи показывает на странице CRM-форму Битрикс24: пользователь заполняет ее, а результат приходит в CRM того Битрикс24, где форма создана. Форма открывается в боковой панели шириной 600 пикселей или встраивается прямо в разметку страницы.

Используйте форму, когда нужно собрать отзыв, заявку или сообщение об ошибке со страницы своего модуля, а обрабатывать ответы — в CRM. Сама форма с полями, согласиями и капчей хранится в Битрикс24: расширение загружает ее оттуда, а ответы на сайте не сохраняет.

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

За форму отвечают:

JavaScript-расширение ui.feedback.form модуля ui — открывает форму методом BX.UI.Feedback.Form.open(),
компонент bitrix:ui.feedback.form того же модуля — выводит кнопку, которая открывает форму, или встраивает форму в страницу.

Метод Form.open() работает только для авторизованных пользователей и открывает форму в момент вызова, с данными этого момента. Компонент выбирает форму при выводе страницы и работает и для гостей сайта.

Подключить расширение

Если вы открываете форму из своего JavaScript-кода, загрузите расширение ui.feedback.form и расширение боковой панели main.sidepanel.

\Bitrix\Main\UI\Extension::load(['main.sidepanel', 'ui.feedback.form']);

Внимание

Расширение ui.feedback.form зависит только от main.core и боковую панель не подключает. Без main.sidepanel на странице метод Form.open() прерывается ошибкой TypeError: объекта BX.SidePanel.Instance нет.

Если вы работаете в модульном JavaScript, импортируйте класс Form из расширения.

import { Form } from 'ui.feedback.form';

Вне модульного JavaScript тот же класс доступен как BX.UI.Feedback.Form.

Компоненту отдельная загрузка не нужна: его шаблон подключает ui.feedback.form, а для кнопки — еще боковую панель и кнопки ui.buttons.

Описать набор форм

И метод Form.open(), и компонент принимают не одну форму, а массив форм. Каждый элемент массива описывает CRM-форму объектом с полями.

|

|| Поле | Тип | Описание || || id | number | Обязательное. Числовой идентификатор CRM-формы в Битрикс24 || || sec | string | Обязательное. Код безопасности формы || || lang | string | Язык формы. Сервер сравнивает его с языком текущей страницы. По умолчанию ru для регионов лицензии ru, by, kz, uz и en для остальных || || zones | Array | Регионы лицензии, для которых предназначена форма. По умолчанию ['ru'] для регионов лицензии ru, by, kz, uz и ['en'] для остальных || |#

Элемент без id или sec сервер пропускает. Оба значения есть в коде встраивания CRM-формы — в атрибуте data-b24-form вида inline/<id>/<sec>.

Регион лицензии — код региона, для которого выпущена лицензия продукта: ru, by, kz, en, de и другие. Регион своего сайта возвращает метод getRegion() объекта лицензии. Если регион не определен, метод возвращает null, и сервер выбирает форму как для региона en.

$region = \Bitrix\Main\Application::getInstance()->getLicense()->getRegion();

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

const forms = [
    { id: 12, sec: 'a1b2c3', lang: 'ru', zones: ['ru', 'by', 'kz'] },
    { id: 14, sec: 'd4e5f6', lang: 'en', zones: ['en'] },
];

Порядок выбора формы

Одну форму из набора выбирает сервер — класс Bitrix\UI\Form\FeedbackForm. Порядок такой:

Сервер отбирает формы, у которых в zones есть регион лицензии сайта.
Если таких форм нет, сервер отбирает формы с регионом по умолчанию: ru для регионов ru, by, kz, uz и en для остальных.
Если и таких форм нет, форма не выбрана.
Из отобранных форм сервер оставляет те, у которых lang совпадает с языком текущей страницы — константой LANGUAGE_ID.
Если совпадений по языку нет, сервер оставляет формы с языком по умолчанию: ru или en по тому же правилу, что и регион.
Если и таких нет, сервер оставляет все формы, отобранные по региону.
Из оставшихся сервер берет первую по порядку в массиве.

Отбор по региону идет первым, по языку — только среди форм, которые его прошли. Форма с подходящим языком, но другим регионом в выбор не попадет. Чтобы форма открывалась в любом регионе, добавьте в набор форму с регионом en и форму с регионом ru.

Указать свой Битрикс24

Без параметра адреса расширение загружает форму с сервиса обратной связи Битрикс: https://product-feedback.bitrix24.ru для регионов ru, by, kz, uz и https://product-feedback.bitrix24.com для остальных. Свои CRM-формы хранятся в вашем Битрикс24, поэтому его адрес передавайте всегда: в параметре portalUri метода Form.open() или в параметре PORTAL_URI компонента.

Расширение дописывает к адресу путь /bitrix/js/crm/form_loader.js и загружает по нему загрузчик CRM-форм. Задавайте адрес со схемой https:// и без косой черты в конце.

Открыть форму из JavaScript

Метод Form.open(options) открывает форму в боковой панели. Метод отправляет запрос к действию ui.feedback.loadData, получает от сервера выбранную форму и загружает ее в панель.

Параметры метода:

|

|| Параметр | Тип | Описание || || id | string | Обязательный. Идентификатор формы на странице, непустая строка. По нему метод находит форму, открытую раньше || || forms | Array | Набор форм, из которого сервер выбирает одну. Состав элемента описан в разделе Описать набор форм || || portalUri | string | Адрес Битрикс24, где созданы формы. По умолчанию — сервис обратной связи Битрикс || || title | string | Заголовок над формой в панели. По умолчанию Обратная связь на языке страницы || || presets | Object | Значения, которые уходят вместе с заполненной формой. Описаны в разделе Передать данные вместе с формой || || defaultForm | Object | Одна форма в том же формате, что и элемент forms. Сервер берет ее, если из forms не подошла ни одна. Параметр устарел: серверный метод, который его обрабатывает, помечен @deprecated. Задавайте формы для всех регионов в forms || |#

Пример. Кнопка на странице открывает форму отзыва о списке документов.

import { Event } from 'main.core';
import { Form } from 'ui.feedback.form';

Event.bind(document.getElementById('documents-feedback'), 'click', () => {
    Form.open({
        id: 'documents-feedback',
        portalUri: 'https://example.bitrix24.com',
        title: 'Отзыв о списке документов',
        forms: [
            { id: 12, sec: 'a1b2c3', lang: 'ru', zones: ['ru', 'by', 'kz'] },
            { id: 14, sec: 'd4e5f6', lang: 'en', zones: ['en'] },
        ],
        presets: {
            source: 'documents-list',
        },
    });
});

Метод ничего не возвращает. Панель открывается сразу и остается пустой до ответа сервера. Затем в ней появляются заголовок и индикатор загрузки, а когда загрузится CRM-форма, индикатор пропадает.

Условия запроса к серверу

Действие ui.feedback.loadData принимает только POST-запрос авторизованного пользователя с CSRF-токеном. Метод Form.open() отправляет запрос через BX.ajax.runAction(), а тот добавляет токен в заголовок X-Bitrix-Csrf-Token.

Внимание

Для неавторизованного пользователя метод Form.open() не работает: сервер отклоняет запрос, расширение пишет ошибку в консоль браузера, а панель остается пустой. Форму для гостей сайта выводите компонентом: он готовит данные формы при выводе страницы, без отдельного запроса.

Панель остается пустой и в двух других случаях:

ни одна форма из forms не подошла по региону и параметр defaultForm не передан,
параметр id не передан или пустой.

Повторное открытие

Метод Form.open() запоминает созданную форму по значению id. Повторный вызов с тем же id открывает ту же форму. Если первая загрузка прошла успешно, новый запрос к серверу метод не отправляет. Новые forms, presets и title в таком вызове не применяются: форма остается с параметрами первого вызова.

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

Пример. Форма получает новый идентификатор при каждом открытии, поэтому в presets всегда уходит код текущего раздела.

import { Form } from 'ui.feedback.form';

function openSectionFeedback(sectionCode)
{
    Form.open({
        id: `section-feedback-${sectionCode}-${Date.now()}`,
        portalUri: 'https://example.bitrix24.com',
        forms: [
            { id: 12, sec: 'a1b2c3', lang: 'ru', zones: ['ru', 'by', 'kz'] },
            { id: 14, sec: 'd4e5f6', lang: 'en', zones: ['en'] },
        ],
        presets: {
            section: sectionCode,
        },
    });
}

Одновременно открыта только одна форма. Пока панель с формой открыта, новые вызовы Form.open() ничего не делают — даже с другим id. Следующая форма откроется после того, как пользователь закроет панель.

Что метод не принимает

Метод Form.open() передает серверу только параметры из таблицы выше. Остальные параметры он отбрасывает без ошибки:

showTitle — заголовок над формой в панели всегда виден,
button и node — привязка к кнопке и встраивание в страницу работают только в компоненте,
form — одну готовую форму без выбора метод не принимает, используйте forms с одним элементом.

Внимание

Конструктор new BX.UI.Feedback.Form(options) устарел. Он продолжает работать и принимает уже выбранную форму, адрес и presets в готовом виде — так его вызывает шаблон компонента. Для своего кода используйте метод Form.open(): он сам выбирает форму на сервере.

Загрузить расширение по требованию

Если форма нужна редко, загрузите расширение в момент открытия методом BX.Runtime.loadExtension(). Метод возвращает промис с экспортами расширения, среди них класс Form.

Пример. Функция загружает расширение только в момент вызова, например по нажатию кнопки.

import { Runtime } from 'main.core';

async function openFeedback(options)
{
    const { Form } = await Runtime.loadExtension('ui.feedback.form');

    Form.open(options);
}

Расширение main.sidepanel при этом должно быть на странице заранее.

Вывести кнопку компонентом

Компонент bitrix:ui.feedback.form выбирает форму при выводе страницы и рисует кнопку. Нажатие на кнопку открывает форму в боковой панели. Запроса к серверу при этом нет, поэтому кнопка работает и для неавторизованного пользователя.

Подключают компонент методом $APPLICATION->IncludeComponent(), как описано в статье Компоненты.

Параметры компонента:

|

|| Параметр | Тип | Описание || || ID | string | Обязательный. Идентификатор формы на странице. Из него компонент собирает id кнопки: <ID>-button || || FORMS | array | Обязательный. Набор форм, из которого компонент выбирает одну. Элементы — массивы с ключами id, sec, lang, zones, как в разделе Описать набор форм || || PORTAL_URI | string | Адрес Битрикс24, где созданы формы. По умолчанию — сервис обратной связи Битрикс || || TITLE | string | Текст кнопки и заголовок над формой. По умолчанию Обратная связь на языке страницы || || PRESETS | array | Значения, которые уходят вместе с заполненной формой || || VIEW_TARGET | string или false | Имя области отложенного вывода, куда шаблон помещает кнопку. По умолчанию pagetitle. Значение false выводит кнопку на месте вызова компонента || || air | bool | Со значением true рисует кнопку в air-оформлении. Имя параметра пишется строчными буквами || || USE_UI_TOOLBAR | string | Со значением Y добавляет кнопку в панель инструментов ui.toolbar, а не выводит в разметку. Работает только вместе с air = true || || INLINE | bool | Со значением true встраивает форму в страницу вместо кнопки. Описан в разделе Встроить форму в страницу || || SHOW_TITLE | string | Со значением N скрывает заголовок над встроенной формой. Работает только вместе с INLINE = true || |#

Пример. Кнопка отзыва выводится на месте вызова компонента.

<?php

global $APPLICATION;

$APPLICATION->IncludeComponent(
    'bitrix:ui.feedback.form',
    '',
    [
        'ID' => 'documents-feedback',
        'PORTAL_URI' => 'https://example.bitrix24.com',
        'TITLE' => 'Отзыв о списке документов',
        'FORMS' => [
            ['id' => 12, 'sec' => 'a1b2c3', 'lang' => 'ru', 'zones' => ['ru', 'by', 'kz']],
            ['id' => 14, 'sec' => 'd4e5f6', 'lang' => 'en', 'zones' => ['en']],
        ],
        'PRESETS' => [
            'source' => 'documents-list',
        ],
        'VIEW_TARGET' => false,
    ]
);

Компонент ничего не выводит, если параметр ID пустой, параметр FORMS пустой или не массив, или ни одна форма не подошла по региону. Параметра для запасной формы, как defaultForm у метода Form.open(), у компонента нет.

Выбрать место для кнопки

По умолчанию шаблон компонента выводит кнопку в область отложенного вывода pagetitle: оборачивает разметку в вызовы SetViewTarget('pagetitle') и EndViewTarget(). Кнопка появится там, где шаблон сайта вызывает $APPLICATION->ShowViewContent('pagetitle'). Если шаблон сайта эту область не выводит, кнопки на странице не будет.

Чтобы кнопка встала на место вызова компонента, передайте 'VIEW_TARGET' => false. Чтобы кнопка попала в другую область, передайте ее имя.

На страницах с панелью инструментов ui.toolbar кнопку добавляют в панель параметрами 'air' => true и 'USE_UI_TOOLBAR' => 'Y': компонент передает ее методу Toolbar::addButton(). Без air параметр USE_UI_TOOLBAR не действует: компонент выводит обычную кнопку в разметку.

Открыть форму компонента из своего кода

Компонент создает в JavaScript объект формы с идентификатором из параметра ID. Метод Form.getById(id) возвращает этот объект или null, если формы с таким идентификатором нет. Метод openPanel() объекта открывает форму в боковой панели — так же, как нажатие на кнопку.

Пример. Пункт меню открывает форму, которую на странице вывел компонент с 'ID' => 'documents-feedback'.

import { Form } from 'ui.feedback.form';

const form = Form.getById('documents-feedback');

if (form)
{
    form.openPanel();
}

Метод getById() сравнивает идентификатор строго, вместе с типом. Компонент приводит ID к строке, поэтому и в getById() передавайте строку.

Встроить форму в страницу

Параметр 'INLINE' => true переключает компонент на шаблон встроенной формы. Вместо кнопки компонент выводит пустой блок с id вида <ID>-node и сразу загружает в него CRM-форму. Боковая панель в этом режиме не нужна.

Компонент сравнивает значение строго: строка 'Y' встроенную форму не включает, и вместо нее появится кнопка.

Пример. Форма встроена в страницу без заголовка.

<?php

global $APPLICATION;

$APPLICATION->IncludeComponent(
    'bitrix:ui.feedback.form',
    '',
    [
        'ID' => 'documents-feedback-inline',
        'PORTAL_URI' => 'https://example.bitrix24.com',
        'FORMS' => [
            ['id' => 12, 'sec' => 'a1b2c3', 'lang' => 'ru', 'zones' => ['ru', 'by', 'kz']],
            ['id' => 14, 'sec' => 'd4e5f6', 'lang' => 'en', 'zones' => ['en']],
        ],
        'INLINE' => true,
        'SHOW_TITLE' => 'N',
    ]
);

Встроенная форма выводится на месте вызова компонента: параметр VIEW_TARGET в этом режиме не действует. Без 'SHOW_TITLE' => 'N' над формой стоит заголовок из параметра TITLE.

Передать данные вместе с формой

Параметр presets метода Form.open() и параметр PRESETS компонента передают в форму пары «ключ — значение». Расширение отдает их загрузчику CRM-формы, и форма отправляет их вместе с результатом заполнения. Так в CRM попадает контекст: раздел, из которого открыли форму, код объекта, режим работы страницы. Ключи и значения выбираете вы, например source или section из примеров выше.

К вашим значениям сервер добавляет системные. Если ключ совпадает с системным, остается системное значение. Системные ключи:

c_id — идентификатор текущего пользователя.
c_name — имя текущего пользователя, а если имя не заполнено — логин.
c_email — адрес электронной почты текущего пользователя.
hosturl — адрес сайта со схемой.
hostname — имя хоста сайта без схемы.
db_name — имя базы данных сайта.
b24_plan — тариф: в облачном Битрикс24 — тип лицензии, в коробочной установке — коды лицензии через запятую.
b24_plan_date_to — дата окончания лицензии.
b24_partner_id — идентификатор партнера, который обслуживает сайт. Пустая строка, если партнера нет.
b24_partner_name — название партнера. Пустая строка, если партнера нет.
business — значение настройки CJM-business модуля bitrix24. Ключ есть, только если настройка задана.

Внимание

Системные значения уходят в тот Битрикс24, адрес которого указан в portalUri или PORTAL_URI: почта и имя пользователя, адрес сайта, имя базы данных. Если адрес не задан, они уходят на сервис обратной связи Битрикс.

Подключить расширение

Описать набор форм

|

Порядок выбора формы

Указать свой Битрикс24

Открыть форму из JavaScript

|

Условия запроса к серверу

Повторное открытие

Что метод не принимает

Загрузить расширение по требованию

Вывести кнопку компонентом

|

Выбрать место для кнопки

Открыть форму компонента из своего кода

Встроить форму в страницу

Передать данные вместе с формой

Связанные материалы