Тематические блоки

Что делает дополнение

«Тематические блоки» подбирают подходящие записи из нескольких типов контента и вставляют их карточки внутрь статьи или новости при показе страницы. Исходный текст материала в базе не изменяется. Для двух блоков ориентиры — первая и вторая треть длины текста; вставка идёт перед подходящими заголовками.

Кандидаты всех источников сравниваются вместе. Две наиболее релевантные разработки могут оказаться из одного каталога. Повтор одной записи внутри подбора исключён; одинаковые ID в разных типах считаются разными записями.

Установка

1. Установите полученный пакет через «Дополнения → Установка» в админке InstantCMS.
2. Перейдите в «Виджеты и страницы», выберите страницу показа отдельных материалов и действующую тему.
3. В палитре «Тематические блоки» разместите виджет на используемой позиции схемы. Он вставляет карточки в текст; отдельного блока на этой позиции не появится. Не используйте позицию «Неиспользуемые».

Не требуется менять ядро, создавать PHP-код в статье или переносить материалы в другой тип контента.

Лицензия и пробный период

После установки покупатель получает 72 часа для проверки. В разделе «Лицензия» укажите ник на OCMarket или номер заказа. После подтверждения автором лицензия становится бессрочной для одного домена; сайт больше не обращается к серверу лицензий. Ключ вводить не требуется.

Без подтверждения тематические вставки мягко выключаются, тексты и настройки сохраняются. При недоступности сервера новые установки работают 72 часа с первого запуска. Если хостинг блокирует исходящие запросы, автор выдаёт строку для ручного ввода. Стенды localhost, *.local, *.test и IP работают без лицензии. Переезд на другой домен требует нового подтверждения.

Серверу автора передаются код продукта, домен, случайный идентификатор установки, версии дополнения, InstantCMS и PHP и пометка покупателя. Тексты материалов и данные пользователей не передаются.

Настройки виджета

Во вкладке «Подбор» выберите тип материалов, в которые вставляются блоки, и поле их текста. Один экземпляр обслуживает один тип; для новостей и статей можно создать отдельные экземпляры.

Откройте настройки кнопкой редактирования экземпляра в схеме «Виджеты и страницы»: появится штатное всплывающее окно CMS. Во вкладке «Источники карточек» выберите тип контента из списка и нажмите «Добавить». Раскройте добавленный источник нажатием на его название. Здесь выбираются только его собственные поля заголовка, ключевых слов, тегов, изображения и короткого описания. Кнопка «Убрать» исключает источник; изменения вступают в силу после сохранения виджета. Один тип добавляется один раз. Для нового источника сразу подставляются первое поле-изображение и поле анонса (teaser, description или content), если они есть; любое можно сменить или очистить. В «Дополнительных полях» выберите, что ещё показать в карточке: цену, версию, автора и любые другие поля типа. Они выводятся штатными обработчиками CMS; ограничения чтения сохраняются.

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

Источники с отсутствующим или недоступным полем не подставляют другое поле автоматически. «SEO — ключевые слова» соответствует системному полю seo_keys. Остальные поля выбираются из реальной конфигурации сайта.

Подсказка в настройках ведёт в этот раздел руководства.

Подбор из своего типа и исключения

В источники можно добавить тот же тип, в котором размещаются блоки. Например, статья может предлагать другие статьи. Текущая запись автоматически исключается; ID совпавших записей других типов сохраняются.

«Исключить записи источника» задаётся отдельно для каждого источника: введите ID через запятую или пробел. «Не вставлять блоки в материалы» относится к целевому типу. Штатные наборы позволяют ограничивать источник категориями, полями и другими фильтрами.

При равном балле можно оставить стабильный порядок или выбрать свежие записи по дате публикации. Балл всегда важнее даты. Поле сравнения заголовков задаётся независимо от отображаемого заголовка карточки.

Релевантность

Режимы: ключевые слова, теги, слова заголовка или несколько полей вместе. Поля источника сравниваются с соответствующими полями текущего материала. Текст статьи сам по себе ключевые слова не заменяет.

Ключевые слова и теги разделяются запятыми, точкой с запятой или переводом строки. Фраза «поисковые системы» — один ключ. Регистр, повтор одинакового ключа, лишние пробелы и ё/е не влияют. Совпадение полное: API не совпадает с rapid. Повтор ключа не увеличивает балл.

В режиме заголовков сравниваются отдельные слова; распространённые служебные слова исключаются. Морфология, синонимы и внешние AI-сервисы не используются.

В совместном режиме каждый сигнал имеет настраиваемый вес; вес 0 отключает его вклад. Если все веса равны 0, каждое поле считается с весом 1, чтобы блоки не пропали незаметно. Минимальный балл отсекает слабые результаты. При равенстве баллов порядок стабилен: системное имя типа, затем ID.

Если совпадений нет, блоки не показываются. Нерелевантные случайные карточки не добавляются.

Если общий тег вроде «SEO» стоит почти у всех записей и подтягивает лишнее, поднимите минимальный балл до 2 или используйте более точные теги.

Где вставляются блоки

Число блоков задаёт верхнюю границу. В равномерном режиме N блоков получают ориентиры k/(N+1) длины видимого текста. Затем выбираются наиболее близкие заголовки с соблюдением порядка и минимального расстояния. Блоки не создают дополнительных H2 и не меняют ID существующих заголовков.

Можно выбрать H2, H3 или H4, пропустить первые заголовки, задать минимальный объём текста до первого блока и между блоками. Другой режим вставляет перед каждым N-м подходящим заголовком: при шаге 2 — перед 2-м, 4-м, 6-м. Незакрытый абзац перед заголовком в импортированном HTML не мешает вставке.

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

Если выбрано несколько карточек в блоке, лимит карточек статьи равен числу блоков, умноженному на число карточек в блоке. Недостаток кандидатов уменьшает вывод.

Шаблоны и поля карточки

Во вкладке «Дизайн» выберите штатный «Шаблон виджета»: blocks — горизонтальные карточки; blocks_grid — сетка; blocks_carousel — горизонтальная прокрутка с привязкой к карточкам. Карусель работает без внешней библиотеки: пальцем, колесом и переходом клавиатурой между ссылками.

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

Обложка карточки тоже ведёт на запись и загружается отложенно, когда читатель до неё долистает.

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

Наборы и доступ

Каждый источник может ограничиваться существующим штатным набором своего типа контента. Набор применяется до подбора релевантности; набор другого типа не используется. Его настройки сортировки не заменяют итоговую сортировку по совпадениям.

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

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

Откройте «Компоненты → Тематические блоки → Предпросмотр подбора». Выберите сохранённый экземпляр виджета и ID статьи в настроенном типе. Штатная таблица CMS покажет кандидатов, тип, ID, баллы и конкретные совпадения. Есть фильтры, сортировка и страницы; предпросмотр ограничен первыми 100 релевантными кандидатами.

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

Ручное закрепление или исключение карточки у отдельной статьи в этой версии не предусмотрено. Для исключения страницы используйте штатную отрицательную маску URL виджета.

Пример настройки

Статья про llms.txt: тип материалов articles, поле текста content, режим «Ключевые слова», поле SEO keywords. Источники — icms и products, в каждом выбранное поле ключей; например llms.txt, SEO, индексация. Укажите 2 блока, по 1 карточке, распределение по длине и заголовки H2.

Для icms выберите поле иконки, для products — обложку; описание задайте отдельным полем в каждом источнике. Это пример, а не предустановленные имена полей или ID. Настраивайте по фактическим полям своего сайта.

Если блоки не появились

1. Проверьте публикацию кандидатов, выбранные источники и совпадение ключевых слов.
2. Убедитесь, что поле текста выбрано правильно и доступно для показа на странице статьи.
3. Проверьте подходящие H2, пропуск заголовков, минимальное расстояние и ограничение до первого блока.
4. Проверьте привязку виджета к странице и активной теме, его доступ, язык, устройство и исключения URL.
5. Посмотрите результат предпросмотра.

Если тема переписывает HTML поля после обработки CMS или выводит один и тот же текст статьи дважды, безопасная вставка пропускается. Компонент не ищет «похожий» текст в шапке или подвале страницы. Сжатие HTML после события render_page совместимо.

Если другое дополнение переписывает текст статьи на событии render_page раньше «Тематических блоков» (автоссылки, типограф, отложенная загрузка картинок), вставка тоже пропускается без ошибок. Проверьте страницу после подключения таких дополнений.

Подбор сначала отбирает в базе только записи, где встречаются слова из ключей, тегов или заголовка статьи, и затем точно сравнивает их. Для гостей результат хранится в штатном кэше CMS, если кэш включён, и сбрасывается при изменении записей источника. Для полей, которые нельзя отфильтровать в базе (виртуальные поля), выполняется полный просмотр источника.

Свой шаблон

Скопируйте файл из templates/default/controllers/thematicblocks/widgets/blocks/ в такую же папку дочерней темы. Имя варианта начинается с blocks, например blocks_custom.tpl.php; выбор варианта делает штатная CMS. Разметка одной карточки общая для всех вариантов и лежит отдельно: templates/default/controllers/thematicblocks/cards.tpl.php — её тоже можно переопределить в дочерней теме.

Данные: widget — объект cmsWidget; groups — группы карточек; body_html — обработанный HTML поля статьи; placement_options — параметры распределения; identity — идентификатор экземпляра и статьи.

Карточка содержит id, ctype_name, title, url, image_html, teaser, fields (name, title, html), score и matches. Экранируйте title, teaser, url и подписи. image_html и fields.html уже получены штатным обработчиком. Соберите по одной HTML-строке на группу и передайте их thematicBlocksRuntime::register(body_html, blocks, placement_options, identity). Шаблон не должен печатать эти строки на позиции схемы.

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

Отключение и удаление

Чтобы временно убрать вставки, отключите привязку виджета или компонент. Тексты материалов останутся неизменными. Удаление компонента убирает его виджет, привязки и события; исходные типы контента и записи не удаляются.

После штатного удаления CMS показывает собственные файлы дополнения для ручного удаления. Общую папку docs/_shared не удаляйте: её используют другие руководства.