Форма обратной связи ui.feedback.form

Форма обратной связи показывает на странице 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']);

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

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

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

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

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

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

Элемент без 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. Порядок такой:

1. Сервер отбирает формы, у которых в zones есть регион лицензии сайта.

2. Если таких форм нет, сервер отбирает формы с регионом по умолчанию: ru для регионов ru, by, kz, uz и en для остальных.

3. Если и таких форм нет, форма не выбрана.

4. Из отобранных форм сервер оставляет те, у которых lang совпадает с языком текущей страницы — константой LANGUAGE_ID.

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

6. Если и таких нет, сервер оставляет все формы, отобранные по региону.

7. Из оставшихся сервер берет первую по порядку в массиве.

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

Указать свой Битрикс24Указать свой Битрикс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Открыть форму из JavaScript

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

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

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

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.

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

• ни одна форма из 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 с одним элементом.

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

Если форма нужна редко, загрузите расширение в момент открытия методом 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(), как описано в статье Компоненты.

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

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

<?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. Ключ есть, только если настройка задана.

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

• Боковая панель main.sidepanel

• Панель инструментов ui.toolbar

• Кнопки ui.buttons

• Каталог объектов ui.entity-catalog

• Расширения

• Контроллеры