Почему не отображаются иконки в MODX и как это исправить

Многие пользователи сталкиваются с ситуацией, когда иконки (например, эмодзи или символы шрифтов) корректно отображаются в локальном HTML-файле, но перестают работать при загрузке на сайт под управлением MODX. Проблема может быть связана с неправильными путями к файлам, кэшированием, кодировкой или настройками редактора. В этой статье мы подробно разберём основные причины и дадим пошаговые инструкции по устранению неисправности.

Основные причины, почему иконки не читаются в MODX

Некорректные пути к файлам иконок

Если вы используете шрифтовые иконки (Font Awesome, Material Icons) или спрайты, убедитесь, что пути в HTML-коде указаны относительно корня сайта, а не локальной файловой системы. В MODX часто используется ЧПУ, поэтому относительные пути могут ломаться. Рекомендуется указывать абсолютные пути, начиная с /assets/ или использовать плейсхолдеры MODX, например {{base_url}}.

Проблемы с кэшированием

MODX активно кэширует страницы и ресурсы. Если вы загрузили новые файлы иконок, но они не отображаются, попробуйте очистить системный кэш через меню «Очистить кэш» в админ-панели. Также проверьте кэш браузера - обновите страницу с помощью Ctrl+F5.

Неправильная кодировка или символы эмодзи

Эмодзи и специальные символы (✔️, ⬇️, ✅) требуют поддержки UTF-8. Убедитесь, что в настройках MODX (Системные настройки → Кодировка) стоит UTF-8, а в HTML-шаблоне прописан мета-тег <meta charset='UTF-8'>. Если символы отображаются как квадратики, возможно, шрифт на сервере не поддерживает данные глифы.

Как добавить иконки через содержимое и через код

Способ 1: Через содержимое ресурса (TV-параметры или редактор)

Если вы вставляете иконки напрямую в текст через визуальный редактор (TinyMCE, Redactor), убедитесь, что редактор не фильтрует HTML-теги. Проверьте настройки редактора - возможно, он удаляет теги <i>, <span> или классы. Для эмодзи достаточно просто скопировать символ, но если они не отображаются, попробуйте использовать HTML-сущности, например ✅ для ✅.

Способ 2: Через код в шаблоне или чанке

При вставке иконок через чанки или шаблоны MODX (например, [[$iconChunk]]) проверьте, что файл чанка сохранён в правильной кодировке. Используйте только абсолютные пути к CSS и JS библиотекам. Пример для Font Awesome:

<link rel='stylesheet' href='/assets/fontawesome/css/all.min.css'><i class='fas fa-check'></i>

После изменения не забудьте очистить кэш MODX.

Пошаговая инструкция по исправлению

• Шаг 1. Проверьте кодировку страницы - откройте исходный код браузера (Ctrl+U) и убедитесь, что есть <meta charset='UTF-8'>.
• Шаг 2. Очистите кэш MODX: Система → Очистить кэш.
• Шаг 3. Замените относительные пути на абсолютные, используя плейсхолдеры {{assets_url}}.
• Шаг 4. Если используете эмодзи, отключите фильтрацию HTML в редакторе (настройки TinyMCE: valid_elements).
• Шаг 5. Проверьте консоль браузера (F12) на наличие ошибок 404 - это укажет на отсутствующие файлы иконок.

Заключение

Чаще всего проблема с иконками в MODX возникает из-за путей к файлам или кэширования. Следуя нашей инструкции, вы сможете быстро восстановить отображение. Если символы всё ещё не показываются, проверьте поддержку шрифтов на сервере или временно используйте SVG-иконки - они гарантированно работают во всех браузерах и не зависят от кодировки.