Подключение и размещение CSS стилей, JavaScript и изображений в Joomla

Дмитрий Рекун

Использование класса HTMLHelper гарантирует, что подключение CSS, JavaScript и изображений в Joomla будет происходит одинаковым образом.

Расположение файлов в Joomla

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

/media/extension/type/file

Мы можем разбить этот путь на четыре части:

/media

Это основная папка для хранения медиа (CSS, JavaScript и изображений) в Joomla.

/extension

Это папка расширения, гарантирующая отсутствие конфликтов с другими расширениями.

/type

Здесь указывается, какой тип файла хранится в этой папке. Мы можем использовать следующие типы: css, js и images.

/file

Это имя файла, который необходимо подключить.

Подключение стилей CSS в Joomla

Для подключения CSS в Joomla используется следующий код:

HTMLHelper::_(
    'stylesheet',
    'com_foo/bar.css', 
    ['relative' => true],
    ['data-foo' => 'value']
);

Параметр	Тип	По умолчанию	Описание
`stylesheet`	string		Тип ресурса, в данном случае CSS.
`com_foo/bar.css`	string		Путь подключаемого файла.
`['relative' => true]`	array	`[]`	Список опций.
`['data-foo' => 'value']`	array	`[]`	Список атрибутов.

Обратите внимание на то, как указан путь до файла - com_foo/bar.css. Вы можете подумать, что путь неверен, но это не так. HTMLHelper преобразует этот путь в правильный:

/media/com_foo/css/bar.css

Дело в том, что мы указали в опциях, что путь относительный - ['relative' => true]. HTMLHelper преобразует com_foo/bar.css в полный относительный путь. Таким образом, вам не нужно запоминать ничего, кроме имени расширения и имени файла, который вы хотите подключить.

Кроме того, при указании относительного пути появляется возможность переопредления файла - HTMLHelper автоматически проверит его наличие в шаблоне по пути /templates/{template_name}/css/com_foo/bar.css и подключит его.

Ещё одной важной опцией является version, которая добавляет номер версии к вашему файлу. Это полезно, когда вы выпускаете новую версию вашего расширения, при этом файл получает новую версию, а пользователь получит новый CSS вместо старой кэшированной версии.

Подключение JavaScript в Joomla

Для подключения Javascript файла в Joomla используется следующий код:

HTMLHelper::_(
    'script',
    'com_foo/bar.js', 
    ['version' => 'auto'],
    ['async' => 'async']
);

Подключение Javascript аналогично тому, как мы подключаем CSS. Отличие только в типе ресурса - для подключения Javascript используется script.

Подключение изображений в Joomla

Для подключения изображения в Joomla используется следующий код:

HTMLHelper::_(
    'image',
    'com_foo/bar.png', 
    'Привет bar',
    null,
    true
);

Параметр	Тип	По умолчанию	Описание
`image`	string		Тип ресурса, в данном случае изображение.
`com_foo/bar.png`	string		Путь подключаемого файла.
`Привет bar`	string		Текст для атрибута `alt` изображения.
`null`	array		Список атрибутов, типа `['width' => '500']`.
`true`	boolean	`false`	Флаг для указания поиска по относительному пути.

В отличии от подключения CSS или Javascript в Joomla, при подключении изображения мы отдельно передаём текст для alt атрибута изображения и отдельно указываем флаг для указания поиска по относительному пути.

Отладка

Есть ещё одна дополнительная возможность, которую вы получаете при использовании HTMLHelper - когда в глобальной конфигурации включен режим отладки, Joomla будет добавлять -uncompressed к имени файла и таким образом загружать несжатую версию вашего Javascript или CSS. Это значительно облегчает отладку. Естественно, вам придется предоставить файл, в имени которого есть -uncompressed. В общем, у вас всегда будет две версии: сжатая версия для использования в продакшн и несжатая версия для разработки.

HTMLHelper переопределение Javascript CSS

Последнее обновление: 20 декабря 2021.