Blog

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 HTMLHelper class.

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

The HTMLHelper 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.

Location of the files

HTMLHelper 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:

• /media
  This is the main media folder for Joomla
• /extension
  This is the extension folder ensuring there is no conflict with other extensions
• /type
  This specifies what type of file is stored in this folder. We will see the following types:
  • css
  • js
  • images
• /file
  This is the name of the file to be linked

Stylesheet

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

HTMLHelper::_(
    'stylesheet',
    'com_foo/foo.css', 
    ['version' => 'auto', 'relative' => true]
);

There are several parts to this command:

• stylesheet
  This tells HTMLHelper that a stylesheet file is going to be linked
• com_foo/foo.css
  This tells HTMLHelper which file is being linked.
• List of options
  This 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. HTMLHelper 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:

• version
  This 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
• relative
  The 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

HTMLHelper::_(
'script',
'com_foo/foo.js',
['version' => 'auto', 'relative' => true]
);

There are several parts to this command:

• script
  This tells HTMLHelper that a JavaScript file is going to be linked
• com_foo/foo.js
  This tells HTMLHelper which file is being linked.
• List of options
  This 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 behavior as with the stylesheet. HTMLHelper 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:

• version
  This 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
• relative
  The 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

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

There are several parts to this command:

• image
  This tells HTMLHelper that an image file is going to be linked
• com_foo/foo.png
  This tells HTMLHelper which file is being linked.
• Hello Foo
  This is the alt text of the image
• null
  This is an array or string of attributes to add to the image
• true
  This 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, HTMLHelper will turn that into a correct link. HTMLHelper 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 :)