Як підключити стилі та скрипти в joomla 6

У Joomla 6 (як і в 5-й версії) підхід до підключення скриптів та стилів кардинально змінився. Хоча старий метод JHtml (або HTMLHelper) все ще може працювати для зворотної сумісності, правильний шлях зараз — це використання WebAssetManager.

Joomla тепер використовує систему "активів" (Assets), яка дозволяє керувати залежностями (наприклад, щоб ваш скрипт не завантажився раніше за jQuery).

Ось як це реалізувати:

1. Сучасний спосіб через WebAssetManager (Рекомендовано)

WebAssetManager у Joomla 6 працює інакше, ніж старий JHtml. Він не шукає файл за ім'ям на диску автоматично — він шукає зареєстрований актив у своєму "реєстрі" (Registry).

Замість того, щоб просто вказувати файл, ви "реєструєте" його в системі. Це робиться у файлі index.php вашого шаблону. 

Коли ти пишеш $wa->useStyle('template.css'), Joomla шукає в системі запис із назвою template.css. Оскільки ти його ще не зареєстрував, вона видає помилку "There is no asset".

Реєструвати файли можна двома способами:

Спосіб 1: Реєстрація "на льоту" (найшвидший)

Тобі потрібно спочатку розповісти менеджеру, де лежить файл, а потім дати команду його використовувати. Додай цей код у твій index.php:

<?php 
// 1. Отримуємо менеджер активів
$wa = $this->getWebAssetManager();
// 2. РЕЄСТРУЄМО файл (вказуємо логічну назву та шлях)
// 'my-template-style' — це просто будь-яке ім'я, яке ми вигадали
// 'template.css' шукатиметься в media/templates/site/ваш_шаблон/css/
$wa->registerStyle('my-template-style', 'template.css', ['version' => 'auto', 'relative' => true]);
// 3. ТЕПЕР ВИКОРИСТОВУЄМО його за цією назвою
$wa->useStyle('my-template-style');
// Аналогічно для JS:
// 'template.js' шукатиметься в media/templates/site/ваш_шаблон/js/
$wa->registerScript('my-template-script', 'template.js', ['version' => 'auto', 'relative' => true]);
$wa->useScript('my-template-script');
?>

Спосіб 2: Через файл joomla.asset.json (професійний)

Це спосіб, який Joomla 6 "любить" найбільше. Тобі не потрібно писати register у PHP, ти один раз описуєш файли в JSON.

  1. У папці твого шаблону створи файл joomla.asset.json.
  2. Наповни його таким змістом:
{
"$schema": "https://developer.joomla.org/schemas/asset-listing/1.0.json", "name": "template.yourname", "version": "1.0.0", "assets": [
{
"name": "template.main-css", "type": "style", "uri": "template.css", "inherited": true
}, {
"name": "template.main-js", "type": "script", "uri": "template.js", "inherited": true
} ]
}

Тепер у твоєму index.php достатньо лише трьох рядків:

<?php 
$wa = $this->getWebAssetManager();
$wa->useStyle('template.main-css');
$wa->useScript('template.main-js'); 
?>

Чому це важливо для твого сайту?

Коли сайт виросте, тобі може знадобитися підключити, наприклад, бібліотеку для галереї або мап. Через WebAssetManager ти зможеш вказати залежність (dependency).

Наприклад, твій template.js не запуститься, поки не завантажиться jquery (якщо він тобі потрібен), і Joomla сама розставить їх у правильному порядку в коді.

Де мають лежати файли?

Переконайся, що файли лежать саме тут:

  • media/templates/site/назва_твого_шаблону/css/template.css
  • media/templates/site/назва_твого_шаблону/js/template.js

Чому це краще?

  • Автоматична версія: Joomla сама додасть хеш версії (замість version => auto).
  • Керування чергою: Ви можете вказати, що скрипт має завантажуватися в footer або тільки після того, як завантажиться інша бібліотека.

2. Використання файлу joomla.asset.json

Це найбільш "чистий" спосіб для Joomla 6. Ви створюєте JSON-файл у папці шаблону, де описуєте всі файли.

Приклад файлу joomla.asset.json:

{
"assets": [ {
"name": "template.main-style",
"type": "style",
"uri": "template.css"
}, {
"name": "template.main-script",
"type": "script",
"uri": "template.js",
"attributes": {
"defer": true
}
}
] }

Після цього в index.php достатньо просто написати:

<?php 
$this->getWebAssetManager()->useStyle('template.main-style');
$this->getWebAssetManager()->useScript('template.main-script');
?>

3. Якщо потрібно "по-старому" (через PHP)

Якщо ви хочете зберегти логіку, подібну до вашої попередньої, але адаптовану під нові класи (Joomla 6 використовує HTMLHelper замість JHtml):

<?php 
use Joomla\CMS\HTML\HTMLHelper; // Підключаємо CSS HTMLHelper::_('stylesheet', 'template.css', ['version' => 'auto', 'relative' => true]); // Підключаємо JS HTMLHelper::_('script', 'template.js', ['version' => 'auto', 'relative' => true]);
?>

На що звернути увагу для сайту:

  1. Атрибут defer: Для скриптів у Joomla 6 за замовчуванням часто додається defer. Це добре для швидкості завантаження (Google PageSpeed це любить), бо скрипт не блокує відображення сторінки.
  2. Шлях до файлів: У Joomla 6 файли шаблону мають лежати в системній папці media:
    • CSS: media/templates/site/назва_шаблону/css/
    • JS: media/templates/site/назва_шаблону/js/
  3. Оптимізація: Оскільки сайт роблиться також для мобільних користувачів, намагайтеся не підключати важкі бібліотеки без потреби. Нативним JS (Vanilla JS) зараз можна зробити майже все, що раніше робили на jQuery.