Blog

Adding stylesheets, scripts, and images

There are many ways in which you can add media files to your site. You can add files using relative URLs or absolute URLs, of course you can include them inline as well. In reality what happens is that we mix all these different ways and it becomes a bit of a mess. A better way would be to use one way for all these cases and Joomla! actually offers that through the JHtml class.

Using the JHtml class you make all your links consistent and it is easy to manage them.

The JHtml class is actually a swiss-army knife with all the features it offers but in this article we will only highlight three of them as they belong together.

This article is for Joomla! 3.7.0 and later.

Location of the files

JHtml is particular about where you place your files and that is a good thing. This ensures consistency across your site. The location of the files is:

/media/extension/type/file

We can break this path down into four parts:

/mediaThis is the main media folder for Joomla

/extensionThis is the extension folder ensuring there is no conflict with other extensions

/typeThis specifies what type of file is stored in this folder. We will see the following types:

css

js

images

/fileThis is the name of the file to be linked

Stylesheet

To add a stylesheet to your output you would use the following command

stylesheetThis tells JHtml that a stylesheet file is going to be linked

com_foo/foo.cssThis tells JHtml which file is being linked.

List of optionsThis is a list of options that will influence how the link is being created.

The file that is being linked is shown as com_foo/foo.css and you may say that the path is incorrect but that is not the case. JHtml will turn this into the correct path of:

/media/com_foo/css/foo.css

The reason is because we gave the option of a relative path and then it will turn the com_foo/foo.css into a full relative path. So you don't have to remember anything else but the name of your extension and the name of the file you want to link.

The options have two settings in this example:

versionThis adds a version number to your file. This is useful for when you release a new version of your extension and the stylesheet gets a new version so the user will see the new stylesheet instead of the old cached version

relativeThe relative option makes sure that the file is set with a relative path and expanded to the full path where the file really lives

JavaScript

To add a JavaScript file to your output you would use the following command

List of optionsThis is a list of options that will influence how the link is being created.

The file that is being linked is shown as com_foo/foo.js and follows the same behaviour as with the stylesheet. JHtml will turn this into the correct path of:

/media/com_foo/js/foo.js

The reason is because we gave the option of a relative path and then it will turn the com_foo/foo.js into a full relative path. So you don't have to remember anything else but the name of your extension and the name of the file you want to link.

The options have two settings in this example:

versionThis adds a version number to your file. This is useful for when you release a new version of your extension and the JavaScript file gets a new version so the user will see the new JavaScript file instead of the old cached version

relativeThe relative option makes sure that the file is set with a relative path and expanded to the full path where the file really lives

Image

To add an image file to your output you would use the following command

JHtml::_('image','com_foo/foo.png', 'Hello Foo', null, true);

There are several parts to this command:

imageThis tells JHtml that an image file is going to be linked

com_foo/foo.pngThis tells JHtml which file is being linked.

Hello FooThis is the alt text of the image

nullThis is an array or string of attributes to add to the image

trueThis is to specify that a relative path is to be used

The file that is being linked is shown as com_foo/foo.png and the same as before, JHtml will turn that into a correct link. JHtml will turn this into the correct path of:

/media/com_foo/images/foo.png

The reason is because we gave the option of a relative path and then it will turn the com_foo/foo.png into a full relative path. So you don't have to remember anything else but the name of your extension and the name of the file you want to link.

Debugging

One extra feature that you get is that when the Debug mode is enabled in the global configuration, Joomla will append -uncompressed to the filename and thus load the uncompressed version of your JavaScript or CSS file. This makes debugging a lot easier. Of course you will have to supply a file that has the -uncompressed in the filename. In general you would have 2 versions of your file at all times, a compressed version for production and an uncompressed version for development. You can see that Joomla actually ships with these files as well if you take a look at the media/system/js folder for example.

Consistency above all

Using the above methods ensures that all your stylesheets, JavaScript files, and image files are all linked the same way. You get a few extras in the process as well to make your life easier. Go out and get them :)