Стили и скрипты

Стили и скрипты в Joomla не подключают тегами link и script вручную. Этим занимается менеджер ресурсов — Web Asset Manager. Он не выведет один файл дважды, расставит зависимости в правильном порядке и добавит к адресу номер версии, чтобы браузер не держал старый файл в кеше.

Где лежат файлы

Всё, что отдаётся браузеру напрямую, хранится в папке media сайта — в подпапке с именем расширения. Создайте файлы вручную:

media/mod_hello/
├── css/
│   └── style.css
└── js/
    └── hello.js

/* media/mod_hello/css/style.css */
.mod-hello {
    padding: 12px;
    border-left: 4px solid #1d6fb8;
}

Подключение в макете

<?php
// modules/mod_hello/tmpl/default.php
 
defined('_JEXEC') or die;
 
$wa = $app->getDocument()->getWebAssetManager();
$wa->registerAndUseStyle('mod_hello.style', 'mod_hello/style.css');
?>
<div class="mod-hello">
    <p><?php echo htmlspecialchars($greeting, ENT_QUOTES, 'UTF-8'); ?></p>
</div>

Первый аргумент — имя ресурса, второй — путь. Запись mod_hello/style.css означает файл media/mod_hello/css/style.css: папку css Joomla подставляет сама по расширению файла. Обновите сайт — у блока появилась синяя полоса слева, а в коде страницы — тег link.

Скрипт

// media/mod_hello/js/hello.js
document.querySelectorAll('.mod-hello').forEach((block) => {
    block.addEventListener('click', () => block.classList.toggle('is-open'));
});

// modules/mod_hello/tmpl/default.php
$wa->registerAndUseScript('mod_hello.script', 'mod_hello/hello.js', [], ['defer' => true]);

Третий аргумент — параметры ресурса, четвёртый — атрибуты тега: defer откладывает выполнение скрипта до загрузки страницы.

Файл joomla.asset.json

Когда ресурсов несколько, их описывают один раз в файле media/mod_hello/joomla.asset.json:

{
  "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
  "name": "mod_hello",
  "version": "1.0.0",
  "assets": [
    {
      "name": "mod_hello.style",
      "type": "style",
      "uri": "mod_hello/style.css"
    },
    {
      "name": "mod_hello.script",
      "type": "script",
      "uri": "mod_hello/hello.js",
      "dependencies": ["core"],
      "attributes": {"defer": true}
    }
  ]
}

В макете остаётся загрузить этот файл и назвать нужные ресурсы по имени:

// modules/mod_hello/tmpl/default.php
$wa = $app->getDocument()->getWebAssetManager();
$wa->getRegistry()->addExtensionRegistryFile('mod_hello');
$wa->useStyle('mod_hello.style')
    ->useScript('mod_hello.script');

dependencies — ресурсы, которые нужно вывести раньше: core — основной скрипт Joomla. У компонента файл joomla.asset.json загружается автоматически, для модулей и плагинов нужен вызов addExtensionRegistryFile().

Раздел media в манифесте

Чтобы при установке из архива файлы попали в папку media, их перечисляют в манифесте:

<!-- modules/mod_hello/mod_hello.xml -->
<media destination="mod_hello" folder="media">
    <filename>joomla.asset.json</filename>
    <folder>css</folder>
    <folder>js</folder>
</media>

В архиве эти файлы лежат в папке media рядом с манифестом, а установщик копирует их в media/mod_hello сайта. При разработке на месте вы уже положили файлы туда сами.

Методы менеджера

Частая ошибка

Файлы стилей кладут в папку самого модуля — modules/mod_hello/css — и пишут тег link в макете. Такой файл подключится несколько раз, если модулей на странице два, и не попадёт в общий порядок ресурсов. Статические файлы — только в media, подключение — только через менеджер.