Що таке: addHeadLink та HTMLHelper. Як це працює в joomla

При роботі з Joomla 6, ми стикаємося з сучасним API для управління метаданими та ресурсами через WebAssetManager та Document.

Наприклад для додавання favicon (іконки сайту) у секцію <head> сторінки:

$this->addHeadLink(HTMLHelper::_('image', 'joomla-favicon.svg', '', [], true, 1), 'icon', 'rel', ['type' => 'image/svg+xml']); 

Розбір конструкції

Загальна логіка така: HTMLHelper генерує шлях до картинки, а addHeadLink каже системі: "Додай це в тег <head> як лінк".

1. Внутрішня частина:htmlhelper::_('image', ...)

Це стандартний метод Joomla для створення правильних шляхів до медіафайлів.

  • 'image': Ми кажемо, що хочемо отримати шлях до зображення.
  • 'joomla-favicon.svg': Назва файлу. Joomla автоматично шукатиме його в папці images/ вашого шаблону або в папці media/templates/site/ваш_шаблон/images/.
  • true (п'ятий параметр): Дуже важливий прапорець. Він каже Joomla шукати файл спочатку в папці шаблону (overrides), а вже потім у загальних папках.
  • 1 (шостий параметр): Повертає відносний шлях до файлу (наприклад, /media/templates/site/my_template/images/favicon.svg).

2. Зовнішня частина: $this->addheadlink(...)

Цей метод об'єкта Document додає тег <link> у верстку.

  • Перший параметр (URL): Сюди підставляється результат роботи HTMLHelper (шлях до картинки).
  • 'icon': Це значення для атрибута rel. Тобто браузер зрозуміє, що це іконка.
  • 'rel': Це назва атрибута, який ми щойно визначили.
  • ['type' => 'image/svg+xml']: Масив додаткових атрибутів. У даному випадку ми явно кажемо браузеру, що це SVG-графіка.

Як це виглядатиме в HTML

Після виконання цього PHP-коду, у вихідному коді сторінки (у "шапці") з'явиться приблизно такий рядок:

<link href="/media/templates/site/your_template/images/joomla-favicon.svg" rel="icon" type="image/svg+xml" />

На що звернути увагу (Поради)

  1. Joomla 6 та WebAssetManager: Хоча метод addHeadLink робочий, у Joomla 5/6 частіше використовують файл joomla.asset.json у шаблоні. Проте для іконок та швидких маніпуляцій у файлі index.php шаблону — це нормальна практика.
  2. SVG: Використання саме .svg для лого та фавікона — це топ-рішення. Воно буде чітким на будь-якому екрані (Retina), що додає сайту професійності.
  3. Змінна $this: Переконайся, що цей код викликається всередині головного файлу шаблону index.php, де $this є екземпляром класу HtmlDocument.

Маленька підказка: Якщо ти хочеш додати звичайну іконку .ico (для старих браузерів), код буде майже такий самий, тільки type зміниться на image/x-icon.

Щоб змусити Joomla шукати файл в іншому місці, тобі потрібно змінити підхід до формування шляху.

Метод HTMLHelper::_('image', ...) з параметром true спеціально заточений під стандартну ієрархію Joomla (спочатку папка шаблону, потім системна папка media).

Якщо твоя іконка лежить у нестандартному місці, у тебе є два основні шляхи:

1. Пряме вказання шляху (найпростіший варіант)

Ти можеш просто передати рядок зі шляхом від кореня сайту замість використання HTMLHelper.

// Якщо файл лежить у папці /custom_folder/icons/
$faviconPath = 'custom_folder/icons/my-icon.svg';
$this->addHeadLink($faviconPath, 'icon', 'rel', ['type' => 'image/svg+xml']);

У цьому випадку Joomla не буде нічого "шукати", вона просто вставить цей текст у тег <link href="/...">.

2. Використання URI (більш "правильний" шлях для PHP)

Якщо ти хочеш, щоб шлях генерувався динамічно (наприклад, з урахуванням домену), краще використовувати клас Uri.

use Joomla\CMS\Uri\Uri;
// Отримуємо повний шлях до кореня сайту + твоя папка
$faviconPath = Uri::root() . 'assets/design/favicon.svg';
$this->addHeadLink($faviconPath, 'icon', 'rel', ['type' => 'image/svg+xml']);

Як працює пріоритет у HTMLHelper (важливо для розуміння)

Коли ти використовуєш HTMLHelper::_('image', 'file.svg', '', [], true), Joomla працює за таким алгоритмом "пошуку":

  1. templates/ваш_шаблон/images/file.svg
  2. media/templates/site/ваш_шаблон/images/file.svg (це стандарт для Joomla 4/5/6)
  3. images/file.svg (загальна папка медіа)

Чому не варто виносити іконку в зовсім іншу папку? Для сайту, де ти використовуєш Joomla 6, найкраща практика — тримати все в папці media/templates/site/назва_шаблону/. Це дозволяє Joomla правильно кешувати ресурси та підтягувати їх при оновленнях.

Порада для розробника

Якщо ти зараз на етапі дизайну та верстки шаблону, я раджу використовувати відносні шляхи через Uri::base(true). Це гарантує, що якщо ти перенесеш сайт з локального сервера (наприклад, localhost/site/) на реальний хостинг (site.com), усі картинки та іконки не "зламаються".

// Uri::base(true) поверне підпапку, якщо сайт не в корені
$path = Joomla\CMS\Uri\Uri::base(true) . '/my_custom_folder/icon.svg';