# Квэлп: Всплывающие формы

Полное руководство из встроенной справки qwelp.popups. Версия 1.0.0, сверка 11.10.2026.

## Начало

Навигация модуля находится в левом меню: «Формы и шаблоны», журнал заявок, «Настройки» и последняя ссылка «Документация». Общие параметры задаются в собственных настройках модуля; штатная страница «Настройки → Настройки продукта → Настройки модулей» содержит только вкладку «Доступ». В карточке формы вкладки сохраняют введённые значения до сохранения. Для примера подключения нажмите «Копировать»; если браузер запрещает доступ к буферу, выделенный код можно скопировать вручную.

Модуль «Квэлп: Всплывающие формы» собирает обращения посетителей, показывает товарные формы и позволяет создавать формы со своими полями. Заявки доступны в административном разделе сайта.

1. Откройте «Формы и шаблоны». Выберите готовую форму или нажмите «Добавить форму». Укажите сайт, название, поля и адрес получателя, затем сохраните.
2. В карточке сохранённой формы откройте «Размещение на сайте». Скопируйте готовый пример на PHP-страницу между подключением шапки и подвала. Или добавьте компонент «Qwelp → Всплывающая форма» через редактор страницы.
3. На сайте откройте форму, заполните поля и отправьте тестовое обращение. Проверьте результат в разделе «Все заявки» и получение письма.

Для первого знакомства подойдёт «Заказать звонок»: товар и настройки заказа для неё не нужны. Заказ в один клик создаёт настоящий заказ, а «Намекнуть о подарке» отправляет письмо указанному получателю — проверяйте эти формы на тестовом сайте с собственными контактами.

:::details Какие формы доступны

| Форма | Результат |
| --- | --- |
| Заказать звонок | Заявка с контактами и выбранным способом связи. |
| Купить в 1 клик | Заказ Bitrix выбранного товара или предложения и запись в журнале. |
| Нашли дешевле / Подобрать аксессуар | Обращение, связанное с товаром. |
| Намекнуть о подарке | Письмо получателю и заявка. |
| Отзыв о магазине | Оценка и текст авторизованного посетителя в журнале заявок. |
| Произвольная форма | Обращение с заданными вами полями. |

:::

## Настройка форм

### Создать форму

1. Откройте «Формы и шаблоны» → «Добавить форму».
2. Задайте код, например `consultation`, название и сайт. Код уникален для всей установки: до 20 строчных латинских букв, цифр и подчёркиваний, первый символ — буква.
3. Добавьте поля, настройте подписи, обязательность, подсказки и порядок. Заполните текст кнопки, сообщение об успешной отправке и адрес получателя.
4. Сохраните форму и откройте вкладку «Размещение на сайте».

Форма работает только на выбранном сайте и при включённой активности. Удаление формы сохраняет уже полученные заявки. Для стандартной формы сначала выберите нужный сайт: поля, активность и шаблон настраиваются отдельно по сайтам.

### Редактор полей

На вкладке «Поля формы» задайте название, код и тип. Флажки «Показывать поле» и «Обязательно» находятся рядом с действиями. Стрелки меняют порядок полей; крайние направления отключены. «Убрать» удаляет поле из редактора, изменения применяются после сохранения формы.

«Дополнительные параметры» раскрывают подсказку и текст ошибки обязательного поля. Заполненные параметры открываются при загрузке; сворачивание сохраняет значения. Для типа «Список» варианты доступны отдельно, по одному на строку. Новые поля имеют то же оформление и доступные флажки.

| Тип поля | Применение |
| --- | --- |
| Строка / Многострочный текст | Имя, тема и описание обращения. |
| Телефон / Email / Ссылка | Контакты и адрес страницы; сервер дополнительно проверяет формат. |
| Список | Введите допустимые варианты по одному в строке. |
| Чекбокс | Подтверждение или отдельный выбор посетителя. |

:::details Ограничения и служебные поля

До 100 полей в форме и 100 вариантов в списке. Код поля — до 40 строчных латинских букв, цифр и подчёркиваний, с буквы. Подпись и вариант списка — до 200 символов, подсказка и текст ошибки — до 500. Служебные коды заняты модулем и не могут использоваться для новых полей. Поля `name`, `phone`, `email` также выводятся в основных колонках журнала. Остальные ответы видны в карточке заявки.

У стандартных полей нельзя менять тип. В форме подарка поле контакта получателя должно оставаться включённым и обязательным. Согласие на обработку данных не заменяется произвольным чекбоксом.

:::

### Купить в один клик

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

## Размещение

Готовый пример для конкретной формы находится в её карточке на вкладке «Размещение на сайте». Произвольную форму сначала сохраните. В товарных формах укажите реальный ID товара и при необходимости ID предложения.

### Через компонент

В визуальном редакторе выберите «Qwelp → Всплывающая форма». Для PHP-страницы вставьте следующий код после подключения шапки; замените `consultation` кодом своей формы.

```php
$APPLICATION->IncludeComponent('qwelp:popup.form', '.default', [
    'FORM_CODE' => 'consultation',
    'BUTTON_TEXT' => 'Получить консультацию',
    'PRODUCT_ID' => 0,
    'OFFER_ID' => 0,
], false);
```

На странице появится кнопка. Содержимое окна, CAPTCHA и данные посетителя загружаются при открытии. Параметр шаблона `.default` использует оформление, выбранное для формы.

:::details Использовать свою HTML-кнопку

Подключите ресурсы один раз в PHP-коде страницы или шаблона, вне кешируемого фрагмента:

```
if (\Bitrix\Main\Loader::includeModule('qwelp.popups')) {
    \CJSCore::Init(['ajax']);
    \Bitrix\Main\UI\Extension::load('qwelp.popups');
}
```

В нужном месте HTML добавьте кнопку с кодом формы:

```
<button type="button" data-sl-popup="consultation">Получить консультацию</button>
```

Для товарной формы дополнительно используйте `data-sl-product-id` и `data-sl-offer-id`. Не вставляйте токены сессии и персональные данные в общий кеш. Если компонент находится внутри кешируемого родителя, подключение ресурсов выше должно выполняться и при попадании родителя в кеш.

:::

### Проверить после сохранения

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

## Оформление

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

1. Добавьте на страницу компонент `qwelp:popup.form` с нужным исходным шаблоном.
2. В режиме правки выберите «Копировать шаблон компонента» и создайте свою копию в `/local/templates/ваш_шаблон/components/qwelp/popup.form/my_form/`.
3. Измените файлы копии. В параметрах компонента или настройках формы укажите `my_form`.
4. Проверьте окно, ошибки, успешную отправку, закрытие и мобильный экран.

| Файл | Назначение |
| --- | --- |
| `template.php`, `button.php` | Форма и кнопка размещения. |
| `fields.php`, `contact.php`, `product.php` | Поля, способы связи и товар. |
| `agreement.php`, `captcha.php` | Согласие и проверка CAPTCHA. |
| `close.php`, `success.php` | Закрытие и результат отправки. |
| `style.css`, `script.js`, `lang/` | Собственные стили, поведение и переводы. |

:::details Контракт своего шаблона

Сохраните `form[data-form-type]`, `data-custom-form`, имена полей, `input[name="agree"]`, контейнеры ошибок `.sl-popup__field-error` и `.sl-popup__form-error`, кнопки `.sl-popup__form-submit` и `.sl-popup__close`. Для успешного состояния нужны `template[data-popup-success]`, `data-success-title` и `data-success-description`.

Стили ограничивайте селектором `.sl-popup__modal[data-popup-template="my_form"]`. Сохраняйте внутреннюю прокрутку, безопасные отступы экрана и доступность закрытия при клавиатуре. Обработчики добавляйте один раз на экземпляр формы:

```
document.addEventListener('qwelp:popup:ready', function (event) {
    if (event.detail.formCode !== 'consultation') return;
    const form = event.detail.form;
    if (!form || form.dataset.consultationReady === 'Y') return;
    form.dataset.consultationReady = 'Y';
    // Добавьте обработчики полей этой формы.
});
```

:::

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

## Заявки и письма

### Обработать обращение

1. Откройте «Все заявки» или нужный тип формы в меню.
2. Используйте фильтры и откройте карточку заявки. Здесь находятся контакты, товар, страница обращения и дополнительные ответы.
3. После обработки измените статус. Для массовой операции отметьте нужные записи и выберите действие.

Права модуля: «Доступ закрыт», «Только просмотр», «Полный доступ». Просмотр не даёт права менять заявки, формы и настройки. Права назначаются группам в настройках модуля; учитывайте, что журнал доступен в пределах назначенного права на модуль.

### Настроить письма

1. В карточке формы задайте адрес получателя.
2. На вкладке обработки проверьте почтовые события и шаблоны для выбранного сайта. При сохранении формы недостающие почтовые ресурсы создаются автоматически; кнопка создания также доступна отдельно.
3. При изменении стандартного письма добавьте переменную `#FORM_FIELDS#`, чтобы получить дополнительные поля.
4. Отправьте тестовое обращение на свой адрес и проверьте почтовую очередь Bitrix и доставку.

:::details Заявка есть, письма нет

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

:::

Заявка, связанные записи заказа или обратного звонка и письма в очереди сохраняются одной операцией базы данных. При ошибке изменения этой отправки отменяются; для подарка это относится к обоим письмам. Успех означает запись в очередь, доставка зависит от почтового транспорта. Письма администратору содержат REQUEST_ID и REQUEST_URL; старые шаблоны FAQ и обратной связи поддерживаются.

После ошибки сервера CAPTCHA обновляется в текущей форме, введённые поля сохраняются. Если адрес политики не задан, текст согласия отображается законченной фразой без пустой ссылки.

## CAPTCHA и данные

### CAPTCHA

Каждая форма защищена CAPTCHA. Переключатель в карточке формы выбирает Яндекс SmartCaptcha; если он выключен, используется штатная CAPTCHA Bitrix. Bitrix также используется при запрете внешних запросов или незаполненных ключах Яндекса. Выбор одинаков для отображения и серверной проверки.

1. В настройках выберите допустимый режим внешних запросов.
2. Для Яндекс SmartCaptcha укажите клиентский и серверный ключи. Серверный ключ хранится на сервере и не предназначен для HTML страницы.
3. В карточке формы выберите Яндекс SmartCaptcha или оставьте переключатель выключенным для Bitrix и проверьте публичную страницу.

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

### Персональные данные

Перед отправкой посетитель подтверждает согласие. Укажите действующую страницу политики сайта. В журнале сохраняются введённые контакты, ответы, согласие и контекст обращения. Ограничьте доступ к журналу рабочими группами.

Включённое по умолчанию обезличивание обрабатывает старые заявки; исходный срок — 180 дней. Срок и активность настраиваются в модуле, выполнение зависит от работы агентов Bitrix. Обезличивание удаляет контакты и ответы произвольных полей из заявки.

:::details Границы обезличивания и удаления

Журнал заявок, заказ Bitrix, связанный инфоблок, доставленные письма и резервные копии — разные хранилища. Обезличивание записи журнала не следует считать удалением всех этих копий. Учитывайте их в собственном порядке хранения данных. Удаление определения формы сохраняет обращения; удаление модуля предлагает отдельный выбор сохранения данных.

:::

## Установка

### Перед установкой

Нужны PHP 8.2 и Bitrix с модулями main 23.0+, iblock, catalog и sale. Для товарных форм настройте каталог, цены и предложения, для заказа — интернет-магазин. Сделайте резервную копию файлов и базы.

1. Установите «Квэлп: Всплывающие формы» через раздел Marketplace административной панели Bitrix.
2. Откройте «Квэлп → Всплывающие формы», задайте права групп, настройки и получателей писем.
3. Разместите форму и проверьте публичную страницу, заявку и письмо.

### Пути и несколько сайтов

Полная поставка рассчитана на общие пути `/bitrix/modules/qwelp.popups/`, `/bitrix/components/qwelp/popup.form/`, `/bitrix/js/qwelp/popups/` и собственные страницы `/bitrix/admin/qwelp_popups_*.php`. На втором сайте используется общий Bitrix; общий каталог `/local/` не требуется.

Клиент может держать собственные переопределения в `/local/`. Они имеют приоритет перед общей поставкой: при различии поведения проверьте активную копию компонента, расширения и шаблона. Не удаляйте и не переносите клиентские копии автоматически.

### Обновление и удаление

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

:::details Проверка после установки

Откройте документацию и форму на каждом сайте. Проверьте русскую и английскую версии, загрузку стилей и скриптов, права просмотра и изменения, повторное открытие окна, обычный кеш и Композит. При переносе со старой разработки в `/local/` отдельно согласуйте активную копию: установка не должна молча мигрировать клиентские файлы.

:::

## Справка и проверка

| Параметр компонента | Значение |
| --- | --- |
| `FORM_CODE` | Код формы. По умолчанию `callback`. Для произвольной формы используйте сохранённый код. |
| `BUTTON_TEXT` | Текст кнопки. Пустое значение берёт название формы. |
| `PRODUCT_ID` | Положительный ID товара для товарных форм; для обычной формы — 0. |
| `OFFER_ID` | ID предложения для заказа, если требуется; иначе 0. |
| Шаблон | `.default` использует настройку формы. Доступны `callback`, `oneclick`, `cheaper`, `gift`, `accessory`, `review` и собственные копии. |

### Форма не открывается

1. Проверьте активность, код и сайт формы.
2. Проверьте подключение расширения `qwelp.popups` и отсутствие ошибок загрузки JS/CSS.
3. Для товарной формы проверьте доступность товара и права на каталог; для отзыва — авторизацию посетителя.
4. Проверьте активное переопределение в `/local/` и путь своего шаблона.

### Проверить перед открытием посетителям

- Пустые обязательные поля, неверный email, отказ CAPTCHA и отсутствие согласия показывают понятную ошибку.
- Повторное открытие, две кнопки на странице и вставка через AJAX не создают дублирующих окон.
- После прогрева кеша смена настроек и выключение формы учитываются при следующем открытии.
- На узком экране и с клавиатурой закрытие и отправка доступны, фон страницы не прокручивается.
- Сохранение параметров редактором без изменений и с новым текстом кнопки сохраняет рабочий вывод.
- На втором сайте используются назначенные ему форма, настройки и почтовые шаблоны.

Поддержка: обращение разработчику через карточку решения в Marketplace. Приложите версию модуля, PHP и Bitrix, код формы, шаги и обезличенный текст ошибки. Пароли, ключи, cookies и данные посетителей не отправляйте.