Документация

Начало

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

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

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

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

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

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

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

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

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

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

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

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

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

Размещение

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

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

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

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

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

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

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

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

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

Оформление

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

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

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 и доставку.

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

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

CAPTCHA и данные

CAPTCHA

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

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

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

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

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

Включённое по умолчанию обезличивание обрабатывает старые заявки; исходный срок — 180 дней. Срок и активность настраиваются в модуле, выполнение зависит от работы агентов 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/. Они имеют приоритет перед общей поставкой: при различии поведения проверьте активную копию компонента, расширения и шаблона. Не удаляйте и не переносите клиентские копии автоматически.

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

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

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

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

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

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

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

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