How to force auto versioning of css and js to renew on file change within Joomla! template?

Question

I would like the version of css and js within a template to be renewed automatically on file change. I tried JHtml with auto versioning without the desired result.

JHtml::_('stylesheet', 'template.css', array('version' => 'auto', 'relative' => true));

Is version auto renew possible on file change? If not, is there a way to force updating the version manually?

Answer 1

The old and deprecated way is to place MD5SUM file in the asset folder and have it updated whenever an asset file is modified. Once you create the file, add assets without version or with md5sum as version:

JHtml::_('stylesheet', 'template.css', array('relative' => true));
JHtml::_('stylesheet', 'template2.css', array('version' => 'md5sum', 'relative' => true));

This method will not be supported in Joomla 4.0.

Since template files are final (not overridable), a simple way is to use their modification time as version:

$version = filemtime(JPATH_THEMES . '/' . $this->template . '/css/template.css');
JHtml::_('stylesheet', 'template.css', array('version' => $version, 'relative' => true));

For all others files checking modification time is more complex because they can be overridden. We can get a relative URL to file by setting pathOnly option in JHtml::stylesheet(). Then remove root path from URL and add real root path.

// Get Joomla web root path.
$root = JUri::root(true);

// Get relative URL to file.
$relative = JHtml::_('stylesheet', 'template.css', array('pathOnly' => true, 'relative' => true));

// Remove web root path if needed.
$relative = $root !== '' ? substr_replace($relative, '', 0, strlen($root)) : $relative;

// Prepend real root path.
$version = filemtime(JPATH_ROOT . $relative);

// Add the stylesheet with custom version.
JHtml::_('stylesheet', 'template.css', array('version' => $version, 'relative' => true));

Answer 2

Depends upon how you change your css files. The JHTML line you have above works, it's just that the version doesn't change unless you force it to.

In the beginning of the index.php file in the template you also need to add:

$this->setMediaVersion('x.y.z');

where 'x.y.z' is your new version string for your template. Then that string will be used for the links loading the stylesheets.

This is a manual change that you need to make anytime you change your media files. It's a manual process, but it's a simple change and lets you force cache refreshes when you've updated your templates.

I should probably note the media version is part of joomla's Version object, and not really intended for this use, but it's the simplest way to achieve the end. There is another way, using JHTML::register, but I've no idea of your appetite for writing Joomla plugins, so I stuck with the simple way.