Using the Yireo ScriptMerge plugin

The Yireo ScriptMerge plugin allows you to optimize your Joomla! HTML-output by merging CSS-stylesheets and JavaScript-files together as one, and therefor limiting the number of HTTP-requests needed to load the page. The plugin uses an extra component for added functionality. This tutorial shows you how to implement ScriptMerge.

Installation

1. Download both the ScriptMerge plugin as the ScriptMerge component from the download-section on this site.
2. Install both ZIP-files from within the Joomla! Administrator as regular extensions.
3. Next go to the Plugin Manager to enable the system-plugin. It is listed as "System - ScriptMerge".
4. Make sure the ScriptMerge plugin is loaded as one of the last plugins - give it a high ordering number (for instance 99).
5. Make sure the Joomla! cache directory is writable for the webserver.

ScriptMerge will only function correctly when your page is W3C-compliant. First fix your SEO, then fix performance. The component is not visible within the Joomla! backend - system options are available only in the plugin parameters.

General usage

The plugin parameters allow you to enable or disable compression of either CSS or JavaScript. Compressing CSS is generally a good idea and again saves some bandwidth. Compressing JavaScript could be troublesome if third party scrips are written with non-standard code. You need to experiment with the settings to find out which settings are right.

Tuning ScriptMerge might also require you to know which CSS and which JavaScript is loaded for which purpose. If you are able to study the HTML-source, you know the possibillities of tweaking ScriptMerge to the max. If you are not familiar with HTML-sources, you should probably hire a developer to optimize performance for you.

ScriptMerge makes use of the general Joomla! cache. If you want to clean the ScriptMerge cache you can navigate to Tools > Clean Cache in the Joomla! backend.

Plugin parameters

Through the Joomla! Plugin Manager, you can manage the settings of the ScriptMerge plugin. The following parameters are available:

• Merge Type: This can be set either to Checksum or Filelist. The default value is set to Checksum and this works fine in most environments. If you wish to implement full page caching, you will need to choose the option Filelist - but note that this issue could cause issues. See the known issues below, when you run into problems.
• Merge CSS: This option is the main functionality of ScriptMerge, and should probably be set to Yes.
• Merge JS: This option is the main functionality of ScriptMerge, and should probably be set to Yes.
• Compress CSS: The better compressed CSS is, the faster the page will load. However, third party extensions or the template might add CSS-code that is causing problems. Make sure the CSS is W3C compliant when enabling this option.
• Compress JS: Enabling this option gives as well added performance, but should be handled with care. In some cases, JavaScript files from various third party extensions cause this option to break all JavaScript on your pages. If you enable this option, make sure to check all your pages for JavaScript errors.
• Exclude CSS: This is a comma-seperated list of CSS-files to exclude from the merge-process. 
• Exclude JS: This is a comma-seperated list of JS-files to exclude from the merge-process.
• Enable in backend: The speed of the Joomla! Administrator can be improved as well, by enabling this option. However, some third party extensions might add CSS and JS that causes problems, effectively locking you out of the backend. Be careful when using this option, and make sure you know how to modify the ScriptMerge plugin parameters by using SQL-commands (for instance, through phpMyAdmin).
• Enable in Frontend: This defaults to Yes, because you most likely want to improve your site-speed for visitors. In rare cases, 
• Enable in Backend: This defaults to No, and should be handled with care.

Known issue: Full page caching

ScriptMerge gives problems with mechanisms that use full-page-caching (Joomla! Page Cache plugin, JotCache plugin). These mechanisms cache the entire page, including the HTML-header which contains the links to the merged ScriptMerge cachefiles. But if the ScriptMerge cachefiles expire and are removed before the full page cache expires, the full-page-cache refers to ScriptMerge cachefiles which are not there any more. This results in a broken page with no CSS and JavaScript.

To use ScriptMerge together with full page caching, you need to set the option Merge Type to Filelist instead of Checksum. Note that this causes all CSS-files and JS-files to be passed as an argument to the ScriptMerge component. Some webservers limit the URL-length, causing problems here.

Known issue: Third party SEF extensions

When the ScriptMerge option Merge Type is set to Filelist, the ScriptMerge component is activated and called through a Joomla! URL. When using third party SEF extensions, the original System URL is modified by that extension. Most likely that third party SEF extension has bad support for the ScriptMerge component. Therefor, modify the SEF extension to exclude the ScriptMerge component. If such an option is not available in the SEF extension, switch the Merge Type option to Checksum or choose a different SEF extension.

Known issue: Not all CSS is available in the Filelist

If a CSS-file is choosen to be included in the merging process, but that CSS-file is not ending with the css file-extension (example.css), that file will not be outputted by ScriptMerge when setting the Merge Type to Filelist. If this is the case, change this option to Checklist instead.

With JavaScript-files, the same applies for the js file-extension. This limitation is intended functionality, to prevent remote file inclusion.