[Shum1kh1n / Helgring] Mention Enhancer

[Shum1kh1n / Helgring] Mention Enhancer
Аватары пользователей • Оформление никнеймов • Групповые стили • Интеграция с XenForo

Версия: 1.1.1
Разработчик: Shum1kh1n
Платформа: XenForo 2.3.x
Тип: Дополнение (Add-on)
Формат: ZIP
Статус: Stable
ID дополнения: Shum1kh1n/MentionEnhancer

О проекте
[Shum1kh1n / Helgring] Mention Enhancer — дополнение для XenForo 2.3, предназначенное для улучшения внешнего вида упоминаний пользователей в сообщениях форума.
В стандартном оформлении XenForo упоминание обычно отображается в виде кликабельного имени пользователя. Mention Enhancer дополняет привычный формат небольшим аватаром и сохраняет оформление никнейма, предусмотренное системой пользовательских групп.
В результате упоминания становятся более заметными, информативными и визуально привлекательными.
Основной принцип работы дополнения:

Упоминание → Поиск пользователя → Аватар → Оформление никнейма → Готовый результат

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

Отображение аватаров
Основная особенность Mention Enhancer — автоматическое добавление аватара пользователя непосредственно перед его никнеймом.
При обработке корректного упоминания дополнение определяет пользователя, получает его аватар стандартными средствами XenForo и добавляет изображение к отображаемому имени.
Особенности реализации:

Используется аватар именно упомянутого пользователя.
Изображение выводится в компактном размере через стандартный механизм XenForo.
Аватар и никнейм объединяются в один визуальный элемент.
Сохраняется привычная ссылка на профиль пользователя.
Не требуется вручную вставлять изображения или оформлять каждое упоминание.

Упоминания формируются автоматически при обработке соответствующего BBCode штатным HTML-рендерером XenForo.

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

Администраторы — собственное оформление никнеймов.
Модераторы — оформление, установленное для группы модераторов.
VIP-пользователи — индивидуальные групповые стили.
Обычные участники — стандартное отображение в соответствии с настройками форума.

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

Интеграция со стандартными упоминаниями
Mention Enhancer работает с существующей системой BBCode-упоминаний XenForo.
Для обработки используется расширение штатного HTML-рендерера:

Код:

XF\BbCode\Renderer\Html

Дополнение расширяет метод обработки пользовательских упоминаний renderTagUser().
Пример исходного BBCode:

Код:

[USER=1]Shum1kh1n[/USER]

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

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

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

В таких ситуациях дополнение возвращает исходный результат стандартной обработки, а не пытается сформировать неполную HTML-разметку.
Это позволяет сохранить совместимость с обычным отображением упоминаний XenForo.

Обработка пользователей и производительность
При формировании упоминаний используются штатные компоненты XenForo и дополнительное внутреннее кеширование найденных пользователей.
В рамках одного PHP-запроса ранее полученный пользователь может быть повторно использован при обработке нескольких упоминаний одного и того же аккаунта.
Это позволяет избегать повторного выполнения одного и того же поиска пользователя через дополнительный код при каждом упоминании.
Дополнение не создаёт собственных таблиц базы данных и не требует отдельного фонового процесса для работы.

Настройка внешнего вида через LESS
В комплект входит отдельный LESS-шаблон, отвечающий за расположение аватара и имени пользователя.
Название шаблона:

Код:

hgg_mention_enhancer.less

Для оформления используются собственные CSS-классы:

Код:

.hggMentionEnhancer
.hggMentionEnhancer-avatar
.hggMentionEnhancer-name

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

Код:

display: inline-flex;
align-items: center;
gap: 6px;
white-space: nowrap;
vertical-align: middle;

Что можно изменить самостоятельно:

Расстояние между аватаром и никнеймом.
Выравнивание элементов.
Высоту строки и визуальное положение имени.
Дополнительные отступы и оформление через собственные CSS/LESS-правила.

В текущей версии расстояние между аватаром и никнеймом составляет 6 px, а для имени задан параметр line-height: 2.2.
Редактирование выполняется непосредственно в LESS-шаблоне. Отдельная страница настроек дополнения в административной панели не предусмотрена.

Интеграция с шаблонами XenForo
Для подключения оформления используется штатная система модификаций шаблонов XenForo.
Дополнение регистрирует модификацию:

Код:

hgg_mention_enhancer_css

Модификация работает с шаблоном:

Код:

PAGE_CONTAINER

Она добавляет подключение LESS-файла в секцию head страницы:

Код:

<xf:css src="hgg_mention_enhancer.less" />

Благодаря этому стили Mention Enhancer подключаются через механизм шаблонов XenForo.
Отдельное ручное добавление данного подключения в PAGE_CONTAINER при штатной установке не требуется.
Если используется сильно модифицированный сторонний стиль, рекомендуется проверить корректность применения модификации и внешний вид упоминаний.

Локальная обработка данных
Mention Enhancer использует существующие данные пользователей и стандартные механизмы XenForo.
Для своей работы дополнение:

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

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

Important

Статус распространения
[Shum1kh1n / Helgring] Mention Enhancer 1.1.1 — стабильная версия дополнения.
Дополнение предназначено для XenForo 2.3.0 и новее и распространяется в виде установочного ZIP-архива.
Версия 1.1.1 содержит обновлённую структуру дополнения, авторские метаданные, русскоязычное описание и новую фирменную иконку Shum1kh1n / Helgring.
Основная функциональность оформления упоминаний сохранена.
Перед установкой на действующий форум рекомендуется выполнить проверку на тестовой копии.

Установка дополнения
Для установки потребуется XenForo версии 2.3.0 или новее.
Установка через административную панель:

Скачать ZIP-архив актуальной версии дополнения.
Открыть административную панель XenForo.
Перейти в раздел Дополнения.
Выбрать установку дополнения из архива, если данный механизм включён на сервере.
Загрузить установочный ZIP и завершить установку.
Проверить, что дополнение активно и имеет версию 1.1.1.

Ручная установка:

Распаковать архив дополнения.
Открыть каталог upload.
Скопировать его содержимое в корневую папку установленного XenForo с сохранением структуры каталогов.
Перейти в административную панель XenForo и выполнить установку обнаруженного дополнения.
Проверить работу упоминаний в тестовом сообщении.

Расположение дополнения:

Код:

upload/src/addons/Shum1kh1n/MentionEnhancer/

ID дополнения:

Код:

Shum1kh1n/MentionEnhancer

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

Важная информация при обновлении
В версии 1.1.1 изменился идентификатор дополнения.
Старый ID:

Код:

Helgring/MentionEnhancer

Новый ID:

Код:

Shum1kh1n/MentionEnhancer

Для XenForo это два разных дополнения. Поэтому переход со старой версии 1.1.0 на новую 1.1.1 не является обычным обновлением.
Если ранее использовалось дополнение со старым ID, рекомендуется:

Создать резервную копию файлов форума и базы данных.
Сохранить собственные изменения LESS-шаблона, если они выполнялись.
Отключить старое дополнение и проверить работу форума.
Удалить старую версию через административную панель XenForo.
Удалить оставшийся старый каталог файлов, если он присутствует.
Установить новую версию с ID Shum1kh1n/MentionEnhancer.
Проверить отображение упоминаний и работу стилей.

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

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

Рядом с никнеймом отображается аватар.
Имя пользователя остаётся кликабельным.
Оформление имени соответствует настройкам групп XenForo.
Несколько упоминаний в одном сообщении отображаются корректно.
Текст сообщения не содержит нарушенной HTML-разметки.
На используемом стиле форума не возникает проблем с расположением аватаров и текста.

Если оформление не применяется, рекомендуется проверить:

Активность дополнения в административной панели.
Регистрацию расширения XF\BbCode\Renderer\Html.
Применение модификации шаблона PAGE_CONTAINER.
Наличие LESS-шаблона hgg_mention_enhancer.less.
Актуальность кэша стилей XenForo.
Отсутствие конфликтующих CSS-правил используемого оформления.

Структура дополнения
Основные файлы релиза расположены следующим образом:

Код:

upload/
└── src/
    └── addons/
        └── Shum1kh1n/
            └── MentionEnhancer/
                ├── addon.json
                ├── hashes.json
                ├── icon.png
                ├── XF/
                │   └── BbCode/
                │       └── Renderer/
                │           └── Html.php
                └── _data/
                    ├── class_extensions.xml
                    ├── template_modifications.xml
                    ├── templates.xml
                    └── ...

Назначение основных компонентов:

addon.json — метаданные, версия, автор и требования дополнения.
Html.php — основная логика обработки упоминаний.
class_extensions.xml — регистрация расширения HTML-рендерера XenForo.
template_modifications.xml — подключение стилей через PAGE_CONTAINER.
templates.xml — экспорт LESS-шаблона оформления.
icon.png — фирменная иконка дополнения.
hashes.json — контрольные хеши файлов дополнения.

Версия 1.1.1
Версия 1.1.1 посвящена обновлению структуры проекта, авторской маркировки и подготовке дополнения к дальнейшему развитию.
Основные изменения:

Новое название — [Shum1kh1n / Helgring] Mention Enhancer.
Изменён ID дополнения на Shum1kh1n/MentionEnhancer.
Обновлена структура каталогов исходного кода.
Изменены PHP namespace и регистрация расширения класса XenForo.
Добавлено полноценное русскоязычное описание дополнения.
Обновлена ссылка на профиль разработчика.
Сохранена прежняя ссылка технической поддержки.
Добавлена новая универсальная фирменная иконка Shum1kh1n / Helgring.
Обновлён файл контрольных хешей hashes.json.
Сохранены существующие CSS-классы и логика оформления упоминаний.

Функциональная основа версии 1.1.1 осталась прежней: дополнение продолжает отображать аватары рядом с никнеймами и использовать стандартные механизмы XenForo для формирования ссылок и группового оформления.