ave-cms/help/modules/related.md

Похожие материалы

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

Модуль не навязывает карточку. Результат выводится собственными HTML-шаблонами профиля либо передаётся в существующий запрос AVE.cms, где продолжают работать обычные шаблоны полей и карточек сайта.

Быстрый старт

1. Установите модуль и откройте Модули → Похожие материалы.
2. На вкладке Индекс нажмите Переиндексировать.
3. Откройте созданный профиль default и выберите стратегию и рубрики.
4. Вставьте в шаблон рубрики, документ или блок:

[mod_related:default]

5. Откройте реальный документ, содержащий ключевые слова или теги, и проверьте результат.

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

Стратегии

Стратегия	Как выбираются документы
Релевантность	По общим ключевым словам, тегам и, если включено, словам заголовка.
Кольцо	Следующие документы в заданном порядке; в конце списка подбор продолжается с начала.
Гибрид	Сначала релевантные документы, затем недостающее количество добирается кольцом.

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

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

Индекс хранит три независимых источника:

Источник	Что индексируется	Когда полезен
Ключевые слова	Фразы из document_meta_keywords, разделённые запятой, точкой с запятой или новой строкой.	Редактор явно описывает тему документа.
Теги	Значения document_tags.	На сайте уже есть единый тематический словарь.
Заголовок	Значимые слова длиной от четырёх символов после нормализации.	Ключевые слова и теги заполнены не у всех документов.

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

Заголовок по умолчанию выключен: общие слова могут давать шум. Его разумно включать для старого контента, где ключевые слова и теги заполнены не полностью.

Кольцевой подбор

Кольцо не выбирает случайные документы. Оно идёт от текущего документа дальше по одному из стабильных порядков:

• Позиция документа — ручная позиция, затем дата и ID;
• Дата публикации — от новых материалов к старым;
• ID документа — порядок создания.

Когда список заканчивается, модуль продолжает с его начала. Текущий документ и уже выбранные записи исключаются. Такой режим заменяет старый кольцевой системный блок и полезен для «Следующих материалов» или равномерной перелинковки.

Область профиля

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

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

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

Ручные связи

На вкладке Ручные связи выбираются:

1. профиль;
2. исходный документ, на странице которого выполняется подбор;
3. похожий документ;
4. порядок;
5. активность связи.

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

Теги вызова модуля

Текущий документ

[mod_related:default]

default — стабильный системный код профиля. Вместо кода допустим ID, однако код лучше переносится между установками.

Явный документ

[mod_related:default:125]

Второй аргумент — ID исходного документа. Такой вызов полезен в блоке или внешнем шаблоне, где нет текущего контекста страницы.

Совместимость со старым модулем

[mod_moredoc]

Legacy-тег вызывает профиль default для текущего документа. Это переходный синоним: новые шаблоны следует писать через [mod_related:default], поскольку он явно фиксирует профиль.

Способы вывода

Встроенные шаблоны

В этом режиме профиль хранит оболочку списка, одну карточку и необязательный HTML для пустого результата. AVE.cms не подключает публичный CSS модуля: классы, сетку и адаптивность определяет тема конкретного сайта.

Существующий запрос AVE.cms

Выберите Существующий запрос и укажите запрос с готовыми карточками. Модуль передаёт ему уже выбранные ID в рассчитанном порядке. Условия запроса повторно не выбирают документы; используются его основной шаблон, шаблон элемента, поля, системные блоки и карточки текущей темы.

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

Теги шаблона контейнера

Тег	Значение
[tag:id]	Числовой ID профиля.
[tag:code]	Стабильный системный код профиля.
[tag:title]	Название профиля, например «Похожие статьи».
[tag:description]	Описание профиля. Спецсимволы экранируются.
[tag:count]	Фактическое количество карточек.
[tag:items]	Склеенный HTML всех карточек. Этот тег нужно оставить в оболочке.

Пример:

<section class="related-content" data-profile="[tag:code]">
	<h2>[tag:title]</h2>
	<div class="related-content__grid">[tag:items]</div>
</section>

Теги шаблона карточки

Тег	Значение
[tag:index]	Номер карточки от 1 в текущем результате.
[tag:docid]	ID найденного документа.
[tag:rubric-id]	ID его рубрики.
[tag:url]	Публичный URL документа.
[tag:title]	Название документа, экранированное для HTML.
[tag:description]	Meta description; при его отсутствии используется тизер. HTML удаляется.
[tag:date]	Дата публикации в формате дд.мм.гггг.
[tag:datetime]	Дата публикации в формате гггг-мм-дд для <time datetime>.
[tag:views]	Внутренний счётчик просмотров документа.
[tag:image]	Готовый <img> разрешённого размера либо пустая строка.
[tag:image-url]	URL первого исходного изображения документа.
[tag:thumb]	URL превью из выбранного системного пресета.
[tag:score]	Числовой вес релевантности; для ручной связи имеет высокий служебный приоритет, для кольца равен 0.
[tag:matches]	Количество общих нормализованных признаков.
[tag:source]	Источник результата: manual, relevance или ring.

[tag:image] удобен для обычной карточки. Если тема использует picture, соберите его самостоятельно из [tag:image-url] и [tag:thumb].

Пример:

<article class="related-card" data-source="[tag:source]">
	<a href="[tag:url]">[tag:image]</a>
	<div>
		<time datetime="[tag:datetime]">[tag:date]</time>
		<h3><a href="[tag:url]">[tag:title]</a></h3>
		<p>[tag:description]</p>
	</div>
</article>

JSON API

GET /api/v1/related/{profile}/{document}

Пример:

/api/v1/related/default/125

Ответ использует общий контракт {success, data}. В data находятся профиль, ID исходного документа и массив items. Элемент имеет document_id, rubric_id, title, url, description, published_at, views, image, thumb, score, matches и source. API использует те же ограничения публикации и порядок, что серверный тег, но не возвращает HTML шаблона.

Хуки

related.results.resolved

Вызывается после подбора и загрузки данных документов, до HTML:

array(
	'profile' => $profile,
	'document' => $currentDocument,
	'items' => $items,
)

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

related.rendering

Вызывается после встроенного шаблона или существующего запроса:

array(
	'profile' => $profile,
	'document_id' => $documentId,
	'items' => $items,
	'html' => $html,
)

Изменяйте html, если модулю-интеграции нужно обернуть результат или полностью заменить представление.

Кеш и индекс

Результат профиля для документа кешируется на 15 минут. Кеш целиком очищается при сохранении или удалении документа, изменении профиля, ручной связи и полной переиндексации. Поэтому устаревшая карточка не должна оставаться после работы в панели.

Индекс хранит только нормализованные признаки, ID и рубрику. Полные данные карточки читаются из актуальных документов при разрешении результата. Uninstall модуля удаляет профили, индекс и ручные связи полностью.

Практические профили

Похожие новости

• стратегия: Гибрид;
• рубрика: «Новости»;
• только текущая рубрика: включено;
• ключевые слова 8, теги 6, заголовок выключен;
• лимит: 4.

Продолжить чтение

• стратегия: Кольцо;
• рубрики: «Статьи» и «Блог»;
• только текущая рубрика: выключено;
• порядок: дата публикации;
• лимит: 3.

Товарные аналоги

• стратегия: Релевантность;
• товарные рубрики;
• ключевые слова и теги;
• ручные связи включены для точного закрепления аналогов;
• вывод через запрос с эталонной карточкой товара.