Перейти к содержанию

Интерфейс Algolia Pro

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

Чтобы попасть в эти настройки, откройте пункт меню Algolia Pro, затем на вкладке Algolia Indexes выберите один из перечисленных индексов.

В конце страницы настройки вы найдёте раздел User Interface Parameters.

Параметры интерфейса

![Настройка интерфейса](frontend-options-1.png?classes=shadow)

  • Built-in CSS Style → Загружать ли встроенный CSS (~15 КБ / ~3,68 КБ в gzip)
  • Debounce Search → Добавляет задержку 250ms между поисковыми запросами. Это помогает довольно сильно сократить число операций поиска в Algolia. Минус в том, что интерфейс может ощущаться чуть менее отзывчивым. Когда выключено, поиск идёт сразу по мере ввода, но это существенно увеличивает число операций поиска в Algolia. Большинство сайтов справляется с мгновенным поиском, поэтому Algolia Pro поставляется с выключенным Debounce по умолчанию.
  • Accent Color → Меняет акцентный цвет интерфейса. Это включает курсор в поле, выделенный текст, выбранную вкладку пагинации и строку выбранного результата. (По умолчанию: #3b82f6).
  • Appearance → Стиль оформления всего интерфейса. Может быть Light, Dark или System. В режиме System (по умолчанию) он автоматически переключается между Light и Dark по настройкам операционной системы клиента.
  • Results Statistics → Показывает статистику результатов поиска для запроса (например, 428 results found in 7m). ! Использует виджет <ais-stats> в шаблоне hits.html.twig
  • Display Subtitle (TOC Anchor) → Когда включено и используется Page TOC, заголовок результатов показывается с подзаголовком-якорем в скобках. Этот параметр позволяет показывать или скрывать подзаголовок.
  • Warm Connection → По умолчанию Algolia автоматически выполняет начальный поиск в фоне, как только загружается страница. Это ускоряет последующие запросы пользователей, потому что заранее убирает разрешение DNS, рукопожатие SSL, предварительную загрузку API и так далее. Настоятельно рекомендуется оставлять включённым, но при желании эту оптимизацию можно выключить.
  • Language Strings → Определение языковых строк для шаблонов Twig. По умолчанию встроенные термины указывают на языки Grav, поэтому всё совместимо с многоязычностью. При желании можно задать любые конкретные термины. Их также можно полностью настроить на уровне страницы. ! Ссылаться на языковую строку из шаблона через глобальную переменную настроек так:
    {{ settings.interface.lang.placeholder|t }}

Параметры предпросмотра

![Параметры предпросмотра](frontend-options-2.png?classes=shadow)

  • Preview Results → Когда включено, наведение на элемент результатов поиска открывает панель предпросмотра, где можно заглянуть на найденную страницу. Панель предпросмотра включает путь хлебных крошек, заголовок, краткое содержание и список «On This Page». ! Использует блок Twig hits_preview, на который ссылается шаблон hits.html.twig
  • "On This Page" list → Когда включено и имеет смысл, этот параметр показывает список заголовков, относящихся к выбранному результату. Список отображается в панели предпросмотра, но не показывается, если выбранный элемент — фрагмент заголовка, даже если параметр включён. ! Ссылается из шаблона hits.html.twig

![Параметры подвала](frontend-options-3.png?classes=shadow)

Дополнительные параметры

![Дополнительные параметры](frontend-options-4.png?classes=shadow)

  • Expose Global JS Object → Открывает глобальный объект window.AlgoliaPro

Использование

Чтобы подключить Algolia Pro на сайте, сначала нужно загрузить шаблон, а затем назначить один или несколько элементов, которые будут открывать интерфейс поиска.

Это очень просто. Давайте посмотрим подробнее.

Загрузка шаблона

Лучшее место для загрузки шаблона — подвал шаблона base.html.twig, чтобы он гарантированно загружался на каждой странице.

Всё, что нужно, — одна строка Twig:

{% include 'partials/algolia-pro/instantsearch.html.twig' ignore missing with { index: 'pages' } %}

Index — обязательный параметр, и он должен совпадать с настроенным Index Name. Он также определяет, какую настройку интерфейса загрузить для поиска.

Когда шаблон загружен на сайте, можно назначать элемент-триггер для взаимодействия с ним.

Предупреждение

На странице можно загрузить только один экземпляр шаблона instantsearch.

Назначение элемента-триггера

Algolia Pro не поставляется со встроенным элементом интерфейса для поля поиска. По замыслу всё нужное находится внутри модального окна, которое открывается, включая поле поиска.

Всё, что действительно нужно, — открывать интерфейс поиска Algolia Pro через действие пользователя. Это может быть любой элемент сайта. Поле ввода, кнопка, текстовая ссылка, изображение. Решать вам, и это позволяет по-настоящему бесшовно встроить Algolia Pro.

Поскольку дизайн у каждого сайта разный, мы сделали назначение элемента для открытия поиска предельно простым. Нужно только решить, какой элемент (или элементы) должен срабатывать, и добавить им атрибут data-algolia-pro-trigger. Algolia Pro найдёт эти элементы и повесит на них обработчик клика. Теперь каждый раз, когда пользователь нажимает на элемент, Algolia Pro открывается.

Пример

Предположим, на вашем сайте есть поле поиска в правом верхнем углу шапки и кнопка «Search» в боковой панели.

До

<!-- поле ввода в шапке -->
<label for="search">Search</label>
<input type="text" name="search" id="search">

<!-- кнопка в боковой панели -->
<button type="button">Search</button>

После

<!-- поле ввода в шапке -->
<label for="search">Search</label>
<input type="text" name="search" id="search" data-algolia-pro-trigger>

<!-- кнопка в боковой панели -->
<button type="button" data-algolia-pro-trigger>Search</button>

Переопределение шаблонов Twig

Интерфейс поиска Algolia Pro — это приложение Vue, построенное на шаблонах Twig, блоках Twig и виджетах Vue InstantSearch. Шаблоны разделены так, чтобы упростить переопределение отдельных частей интерфейса и добавление новых фич.

Даже если вы не знакомы с Vue или JS в целом, вам будет очень просто что-то изменить или расширить, если есть базовые знания системы переопределения шаблонов Grav и Twig.

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

![Наложение структуры шаблонов](twig-structure-overlay.png?class=overlay-on) ![Структура шаблонов](twig-structure.png?class=overlay-on)

instantsearch.html.twig

Это главный шаблон, тот, который вы включаете на сайте, чтобы загрузить интерфейс.

Здесь виджет <ais-instant-search> инициализируется со всей настройкой и параметрами, которые Algolia Pro определил и сузил для вашей страницы.

В эту страницу включаются ещё несколько шаблонов: специальный шаблон assets.html.twig и шаблон instantsearch-scopes.html.twig, оба нужны для стилей и включения остальных шаблонов.

Виджет <ais-instant-search> также привязан к собственному приложению Vue, которое поставляется с Algolia Pro: там мы используем собственные middleware и реактивные переменные вроде isOpen для отрисовки интерфейса. Подробнее о приложении Vue, реактивных переменных и программном взаимодействии с Algolia Pro — ниже.

Если вы решите переопределить этот шаблон, нужно понимать, что сейчас делает виджет <ais-instant-search>, чтобы повторить это в своём шаблоне. Скорее всего, менять здесь что-либо вам никогда не понадобится.

instantsearch-scopes.html.twig

Этот шаблон — простой промежуточный контейнер, где импортируются и определяются основные blocks Twig. Он намеренно оставлен простым, чтобы легко переопределять его, если понадобится новый блок и Twig.

Обратите внимание, что здесь также загружается второй специальный шаблон configure.html.twig. Если вы переопределяете этот шаблон, учтите, что как минимум нужно включить блок «configure».

searchbox.html.twig

Шаблон searchbox предоставляет блок searchbox и служит обёрткой для поля поиска, куда вводятся запросы, и кнопки отмены.

searchbox_input.html.twig

Этот шаблон предоставляет блок searchbox_input и содержит всю логику показа поля поиска для ввода запросов и запуска результатов.

Этот блок использует виджет <ais-search-box> и сильно настроен через слоты.

Поле ввода в этом блоке запускает каждый запрос и держит состояние приложения Algolia Pro синхронизированным с сервисом Algolia. Переопределяя этот шаблон, учитывайте события и логику слотов, заданные по умолчанию.

hits.html.twig

Шаблон hits предоставляет блок hits и служит обёрткой для шаблона результатов поиска (hits_items) и предпросмотра выбранного результата (hits_preview). Этот блок также показывает статистику результатов, если параметр включён.

Статистика рисуется через виджет <ais-stats>.

hits_items.html.twig

Этот шаблон перебирает все результаты поиска и рисует их. Здесь много логики JavaScript (Vue), но в основном всё сводится к отрисовке элементов определённым образом в зависимости от состояния приложения.

Как и searchbox_input, этот шаблон сильно настроен через слоты.

Давайте на высоком уровне посмотрим, какая логика JavaScript/Vue в этом шаблоне отвечает за отрисовку результатов.

Пустые и непустые результаты

Первая часть логики проверяет, есть ли вообще результаты для показа. Это можно сделать, проверив, пуст ли слот items.

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

<template slot-scope="{ items }">
  <span v-if="!Object.keys(items).length">Empty</span>
  <span v-else>Non Empty</span>
</template>
Цикл

Когда установлено, что результаты есть, их нужно перебрать и нарисовать по одному.

Мы перебираем их обычной логикой Vue v-for и рисуем каждый элемент как <li>. Важно также всегда связывать с каждым элементом уникальный key, как рекомендует Vue.

<ul v-if="Object.keys(items).length">
  <li 
    v-for="(item, index) in items" 
    :key="item.objectID"
  >
    <a :href="`{{ uri.rootUrl }}${item.url}`">
      [[ item.title ]]
    </a>
  </li>
</ul>

Здесь происходит несколько вещей. Во-первых, можно заметить атрибуты с двоеточием :. Это поведение Vue: оно говорит фреймворку вычислить содержимое атрибута. Без двоеточия они были бы просто строками, что нам не нужно.

Во-вторых, для отрисовки заголовка используется синтаксис [[ item.title ]]. Обычно Vue оборачивает переменные в фигурные скобки {{ item.title }}. Но поскольку Twig и Grav тоже используют фигурные скобки, система шаблонов Algolia Pro настроена на двойные квадратные скобки.

Наконец, обратите внимание на синтаксис значения href. Про двоеточие в атрибуте мы уже знаем. А в значении видна смесь Twig и JavaScript. Используются шаблонные литералы JavaScript с обратными кавычками (`), вычисление URI Twig/Grav {{ uri.rootUrl }} и, наконец, вставка значения Vue item.url через синтаксический сахар ${item.url}.

Совет

Данные объекта, доступные для каждого элемента, соответствуют полям вашего индекса. Например, title, url, summary, headers и другие.

Выбранное состояние

Приложение Vue Algolia Pro несёт глобальную переменную состояния selected, с помощью которой можно по-разному рисовать отдельные части интерфейса. Оно также предоставляет метод isSelected, определяющий, выбран ли элемент.

Давайте немного изменим наш <li> из цикла выше и поменяем поведение элемента при наведении мыши.

<li 
  v-for="(item, index) in items" 
  :key="item.objectID"
  @mouseenter="selected = item"
  :class="{
    'is-selected': isSelected(item)  
  }"
>

Теперь элемент слушает наведение мыши (@mouseenter), и когда это происходит, глобальная переменная состояния selected получает этот item.

Кроме того, если на элемент действительно навели мышь, ему добавляется класс is-selected благодаря тому, что isSelected(item) возвращает true. Если элемент не выбран, метод isSelected возвращает false, и имя класса не добавляется.

Подсветка результатов

Можно подсветить часть текста по запросу. Например, если искать «colle», мы ожидаем, что результаты со словом «Collection» будут подсвечены как «Collection».

Это очень просто сделать с помощью виджета <ais-highlight>. Передав виджету объект item и свойство, которое нужно подсветить, вы получите корректно подсвеченный HTML-элемент.

Давайте возьмём элемент из предыдущих разделов и вместо простой отрисовки текста [[ item.title ]] сделаем так, чтобы он подсвечивался при необходимости.

<ul v-if="Object.keys(items).length">
  <li 
    v-for="(item, index) in items" 
    :key="item.objectID"
    @mouseenter="selected = item"
    :class="{
      'is-selected': isSelected(item)  
    }"
  >
    <a :href="`{{ uri.rootUrl }}${item.url}`">
      <ais-highlight
        attribute="title"
        :hit="item"
        highlighted-tag-name="span"
        :class-names="{
          'ais-Highlight-highlighted': 'bg-yellow text-black'
        }"
      ></ais-highlight>
    </a>
  </li>
</ul>

Теперь элементы рисуют заголовок внутри тегов span и правильно подсвечивают части текста при совпадении с запросом, добавляя классы bg-yellow text-black.

Заключение

Синтаксис и логика, объяснённые выше, используются во всём интерфейсе; их понимание очень пригодится, если вы решите расширить и создать собственный интерфейс. Структура и гибкость шаблонов и приложения позволят вам использовать разные подходы, если следовать стандартам JavaScript и Vue.

hits_preview.html.twig

Шаблон hits_preview предоставляет блок Twig, который показывает панель предпросмотра с подробностями выбранного элемента результатов поиска.

Как мы узнали в разделе Выбранное состояние, selected — глобальная переменная состояния, доступная нам во всех шаблонах интерфейса, чтобы определять, выбран ли элемент. Панель предпросмотра пользуется этим, оборачивая весь контейнер в условие, которое это проверяет.

<div v-if="selected">[... preview panel HTML ...]</div>

В отличие от раздела цикла hits_items, панели предпросмотра не нужно перебирать элементы. Вместо этого можно показать подробности об элементе, ссылаясь на объект selected.

Если вы хотите показать заголовок и краткое содержание выбранного элемента, сделайте так:

<div v-if="selected">
  <h1>[[ selected.title ]]</h1>
  <p>[[ selected.summary ]]</p>
</div>

Совет

Вы можете подсветить текст объекта selected при совпадении с запросом, используя виджет <ais-highlight>. Подробнее

Примечание

В этом блоке также находится логика раздела «On This Page».

Подвал — нижняя область интерфейса, и его можно полностью отключить в настройках «Footer Options».

Помимо простого HTML и логики Twig для показа и скрытия элементов подвала, шаблон также включает блок pagination. Он вынесен в отдельный шаблон, чтобы лучше разделить логику html/twig и виджет Vue.

pagination.html.twig

Этот блок — отрисовка виджета <ais-pagination>, и он полностью настроен через слоты.

Специальные шаблоны

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

assets.html.twig

Шаблон assets отвечает за загрузку CSS и JavaScript, которые заставляют интерфейс работать. Без них на фронтенде вряд ли что-то будет работать и выглядеть как надо.

Шаблон содержит логику загрузки встроенных стилей, которые при необходимости можно отключить, и добавляет на сайт динамическую CSS-переменную для акцентного цвета.

Там же есть логика загрузки JavaScript из скомпилированной версии (обычно этого достаточно) или через Webpack HMR, если вы решите с ним разрабатывать.

Tailwind CSS

Интерфейс Algolia Pro построен на популярном CSS-фреймворке TailwindCSS. Если на вашем сайте уже есть Tailwind CSS, стоит отключить встроенный CSS в настройках.

Кроме того, нужно перекомпилировать CSS вашей темы. Для этого убедитесь, что папка плагина algolia-pro входит в источники содержимого в tailwind.config.js вашей темы.

// Tailwind 2
purge: {
  content: [
    // ...
    '../../plugins/algolia-pro/**/*.twig',
  ]
}

// Tailwind 3
content: [
  // ...
  '../../plugins/algolia-pro/**/*.twig',
]

Примечание

Возможно, придётся поправить родительские пути .. в зависимости от расположения tailwind.config.js относительно папки user.

configure.html.twig

Шаблон configure служит посредником между настройками Algolia Pro и сервисом Algolia InstantSearch. Это происходит в блоке configure и через виджет <ais-configure>.

Предоставленная реализация перебирает все настройки в конфигурации Search Parameters (settings.search) и передаёт их в <ais-configure>. Если вы не уверены в том, что делаете, менять этот шаблон не рекомендуем.

Примечание

Атрибуты, разделённые дефисами, нужно преобразовывать модификатором .camel. Например, hits-per-page должен рендериться как hits-per-page.camel.

JavaScript и программное взаимодействие

Как разработчику вам может пригодиться возможность взаимодействовать с классом фронтенда Algolia Pro. Algolia Pro позволяет это, открывая глобальный массив экземпляров AlgoliaPro в window.

Глобальный объект не открыт по умолчанию и может вернуть строку protected вместо ожидаемого объекта. Если он нужен из вашего JavaScript, включите параметр Expose Global JS Object.

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

Обращаясь к объекту, используйте индекс 0 массива. Сейчас Algolia Pro предоставляет и тестирует только один экземпляр. Ниже список свойств и методов, доступных из глобального объекта window.AlgoliaPro[0]:

Свойства

Некоторые свойства реактивны: вы можете менять их значения и влиять на состояние приложения. Например, чтобы открыть модальное окно программно, напишите window.AlgoliaPro[0].isOpen = true.

  • isOpen → (реактивное) Состояние модального окна Algolia Pro, открыто оно или нет. Задайте true или false, чтобы открыть или закрыть.
  • warmConnection → Текущая настройка тёплого соединения. См. настройку.
  • selected → (реактивное) Текущий выбранный элемент. Содержит объект Algolia со всеми подробностями элемента. Задайте null, чтобы снять выбор.
  • query → Текущий запрос поиска.
  • appearance → Текущий параметр оформления. См. настройку.
  • activeAppearance → Текущая фактически активная тема с автоматическим вычислением, если задана система. Может быть light или dark.
  • isDark → Тёмная ли тема оформления.
  • mq → Объект Media Query List, на котором висит событие change системной цветовой схемы.
  • searchClient → Экземпляр поискового клиента Algolia. Это основной объект InstantSearch, который делает всю магию. Документация
Методы
  • isSelected(item) → Проверяет, выбран ли переданный объект элемента.
  • setAppearance(appearance) → Меняет тему оформления поиска. Может быть light, dark или system.

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