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

Установка на сайт ​

Базовый поиск подключается одним скриптом. Всё остальное — конфигурация: адрес API, projectId и селекторы привязки вшиты в бандл при сборке, поэтому JS на странице обычно не нужен вовсе.

Перед началом

Проект должен быть создан, а фид — проиндексирован. Если это ещё не так, начните с «Фиды → Быстрый старт». Подготовьте projectId и адрес скрипта виджета (см. «Что понадобится»).

Шаг 1. Подключите скрипт виджета ​

Добавьте в <head> две строки — preconnect (ускоряет первое соединение) и сам скрипт. Скрипт грузится асинхронно и не блокирует отрисовку. Эти же две строки с подставленным адресом вашего проекта можно скопировать в личном кабинете: Виджет → «Публикация» → «Код для установки»:

html
<link rel="preconnect" href="https://platform.searchforce.ru/">
<script async src="https://platform.searchforce.ru/widget/ВАШ-PROJECT-ID/searchforce-widget.js"></script>
  • Это один файл — стили вшиты внутрь, ничего больше подключать не нужно.
  • projectId и apiUrl уже внутри бандла (заданы при сборке) — на странице их повторять не требуется.
  • Обновления виджета прилетают на тот же адрес автоматически — версию «прибивать» не нужно.

Шаг 2. Разметка ​

Скрипт сам дожидается загрузки страницы и монтирует виджет по разметке — писать код инициализации не нужно. Виджет находит два элемента:

  • поле поиска — по селектору из настроек проекта, а если он не задан — по классу sf-search-trigger (или атрибуту data-sf-autocomplete);
  • контейнер выдачи — по селектору из настроек проекта, иначе по #sf-fullpage-root (или data-sf-fullpage).

Селекторы задаются в личном кабинете: Виджет → «Привязка к странице». Если указать там селекторы вашей существующей разметки, на сайте не нужно ни добавлять классы, ни писать JS — только тег скрипта из шага 1.

Если пользуетесь хуками по умолчанию — пометьте элементы:

html
<!-- поле поиска в шапке (на всех страницах) -->
<input type="text" class="sf-search-trigger" data-sf-search-url="/search/"
       placeholder="Поиск по каталогу">

<!-- пустой контейнер на странице выдачи (например, /search/) -->
<div id="sf-fullpage-root"></div>
  • Триггером может быть любой элемент страницы. Клик по нему открывает поиск и больше ничего не делает: собственное действие элемента виджет берёт на себя, пока смонтирован. Менять вёрстку под это не нужно — без скрипта виджета элемент ведёт себя как раньше.
  • data-sf-search-url — URL страницы выдачи, куда вести по сабмиту (можно задать и в настройках проекта одним значением для всех полей). Без него виджет не делает переход, а бросает событие sf:search-submit (см. «События»).
  • data-sf-query-param — имя query-параметра (по умолчанию q). Тот же параметр читает страница выдачи; встроенный fullpage читает только ?q=.

Готовый минимум

Тег скрипта в <head>, класс sf-search-trigger на поле поиска, #sf-fullpage-root на странице выдачи — этого достаточно. Виджет поднимется сам.

Ручной режим и SPA ​

Нужна своя логика (SPA, нестандартная разметка, ленивая подгрузка) — отключите авто-подключение и вызывайте API сами. Отключить можно атрибутом data-sf-manual на теге скрипта (или переключателем в настройках проекта):

html
<script async data-sf-manual
        src="https://platform.searchforce.ru/widget/ВАШ-PROJECT-ID/searchforce-widget.js"></script>
<script>
  // ready() ждёт и загрузку скрипта, и готовность DOM
  SearchForceWidget.ready(function () {
    SearchForceWidget.autocomplete.init({ input: '.my-search', searchUrl: '/search/' });

    if (document.querySelector('#results')) {
      SearchForceWidget.fullpage.init({ container: '#results' });
    }
  });
</script>

При AJAX-навигации переинициализируйте виджет:

js
// пере-сканировать разметку и подключить новые элементы:
SearchForceWidget.autoInit();

// или точечно — снять экземпляр перед удалением его узла:
var handle = SearchForceWidget.fullpage.init({ container: '#results' });
handle.dispose();

Полный список опций .init() — в справочнике виджетов.

Рецепт: 1С-Битрикс ​

1. Скрипт виджета — в header.php внутри <head>. Атрибут data-skip-moving говорит оптимизатору Битрикса не переносить и не объединять скрипт:

html
<link rel="preconnect" href="https://platform.searchforce.ru/">
<script async data-skip-moving src="https://platform.searchforce.ru/widget/ВАШ-PROJECT-ID/searchforce-widget.js"></script>

Отдельный блок инициализации не нужен — виджет поднимется сам.

2. Страница выдачи — создайте раздел (например, /search/) с контейнером. Минимальный search/index.php:

php
<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
$APPLICATION->SetTitle("Поиск");
?>

<section class="main-products">
    <div class="container">
        <div id="sf-fullpage-root"></div>
    </div>
</section>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

3. Поисковая строка — добавьте класс sf-search-trigger полю поиска в шапке (и data-sf-search-url="/search/"), либо укажите его селектор в настройках проекта.

Демо-режим ​

Хотите поставить поиск на боевой сайт, но пока не показывать его покупателям — например, проверить на живом каталоге или показать коллегам? Включите в настройках сборки виджета галочку «Демо-режим» и опубликуйте сборку.

  • На обычных страницах сайта виджет не появляется — покупатели ничего не видят.
  • Чтобы увидеть поиск, откройте любую страницу с параметром ?sf_widget_demo=1, например https://ваш-сайт.ru/?sf_widget_demo=1. Готовую ссылку панель показывает на странице виджета.
  • Режим действует только на странице с параметром: перейдёте по ссылке без него — поиск снова пропадёт. В углу страницы видна метка «Демо-режим поиска»; кнопка «Выключить» на ней убирает параметр.
  • Чтобы открыть поиск всем, снимите галочку и опубликуйте сборку. Код на сайте менять не нужно.

Режим отключает только автоматическое подключение по разметке. Если вы подключаете виджет сами через SearchForceWidget.*.init() (см. «Ручной режим и SPA»), он работает как обычно — в этом случае показ поиска решает ваш код.

Не путайте с проверкой новой сборки до публикации: ту панель предлагает отдельной ссылкой, и она подменяет версию виджета, а не прячет его. Если включён демо-режим, ссылка проверки уже содержит оба параметра.

Проверка ​

  1. Откройте любую страницу — в DevTools → Network запрос searchforce-widget.js со статусом 200.
  2. Начните печатать в поле поиска — под ним появится панель с подсказками (запрос POST …/search со статусом 200).
  3. Нажмите Enter — переход на страницу выдачи с ?q=…, в контейнере #sf-fullpage-root отрисуются результаты с фильтрами.

Что-то не сработало — загляните в «Частые ошибки».