Using the Yireo ScriptMerge plugin
- Download both the ScriptMerge plugin as the ScriptMerge component from the download-section on this site.
- Install both ZIP-files from within the Joomla! Administrator as regular extensions.
- Next go to the Plugin Manager to enable the system-plugin. It is listed as System - ScriptMerge.
- Make sure the ScriptMerge plugin is loaded as one of the last plugins - give it a high ordering number (for instance 99).
- Make sure the Joomla! cache directory is writable for the webserver.
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.
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.
- Skip Compressed: This option tries to detect whether a certain file is already compressed or not. If it is already compressed, it will not be compressed again. But it will also not be included in the merged file, but served as a separate file instead.
- Remove Mootools: Enable this to get rid of MooTools. Note that you should not be running Joomla extensions that require MooTools.
- Follow CSS imports: When CSS-files are merged, ScriptMerge can follow @import rules to include other stylesheets as well. This option allows you to enable or disable this feature.
- Hashing method: If you use the Checksum as Merge Type, ScriptMerge will determine a checksum to see whether the cache is still unique. If you set this to Simple, the cache will not be refreshed when CSS files change - you will need to manually clear your cache. If you set this to Advanced, the cache will expire as soon as the CSS files change. However, this causes a little extra overhead (milliseconds).
- 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.
- 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.
- Exclude CSS: This is a comma-seperated list of CSS-files to exclude from the merge-process. Names can be partially matched as well. For instance, you could exclude all files from your template by entering the template-folder.
- Exclude JS: This is a comma-seperated list of JS-files to exclude from the merge-process. Names can be partially matched as well. For instance, you could use the keyword mootools or jquery to exclude files of that type.
- Exclude Menu-Items: Instead of defining a manual list of files, you can also select the Menu-Items which should not be handled by ScriptMerge.
- Exclude Components: This option allows you to disable ScriptMerge for a specific component.
- Expiration: This value determines the cache-time of merged files when the merge-type is set to Checksum.
- Version: This value is appended to the merged URLs, allowing you to tell browsers to fetch a new version of the file if browser caching is enabled.
- Data URIs: When CSS or HTML is parsed, and ScriptMerge encounters images, the path of these images is normally renamed to point to the new path of the merged output. Instead of changing the path, the entire image can also be read into a Base64 stream and outputted within the HTML or CSS itself. This makes the CSS or HTML larger, but also requires one less HTTP Request. Very cool.
- Data URI Filesize: The maximum size at which ScriptMerge converts images into Base64 streams. You can set this a few kilobytes, but do not set this higher than 20Kb or so, otherwise your CSS or HTML will grow out of proportion.
- Use WebP: If WebP is supported in your hosting environment, ScriptMerge can also try to convert the normal JPGs and PNGs into WebP images, resulting in up to 50% size reduction.
- cwebp Binary: Path to the cwebp binary. Required for using WebP.
- jsmin Binary: Path to the jsmin binary. Required for using JSMIN.
- Merged CSS Option: Option to place the new merged CSS tag in the header, the bottom of the body or the bottom of the header.
- Include CSS: This option allows you to implement critical CSS on your pages. You can use a tool like https://jonassebastianohlsson.com/criticalpathcssgenerator/ to determine and extract your critical CSS. Next you can remove those lines from your Joomla template, and insert those lines here within ScriptMerge.
When testing out these settings, make sure to check the browsers Error Console for any errors. If errors occur, you probably configured something that does not work on your site. Make sure to test things site-wide as well.
The ScriptMerge component is not accessible from the Joomla! backend and contains no parameters.
Notes on minification and copyright
The Closure Compiler API works over HTTP and requires your firewall to allow outgoing connections. Do not use this with the Merge Type set to Filelist. Also try to set the Skip compressed option to Yes, because the service gives bad results when both MooTools as jQuery compressed versions are included.
Tip: Make sure your CSS is working first
Before testing our plugin, make sure CSS is working as well. Use the W3C CSS validator to make sure there are no CSS lines that will break the rest.
- jce (use this as keyword to match all JCE scripts)
Known issue: Unable to access site
You might have installed ScriptMerge and started playing with it. Sure this is possible, but with a valid backup, right? And on a testing environment, right? If no, something really is wrong with the procedure to safeguard your site. Anyway, if you have played with some settings: For instance, enabling ScriptMerge for the backend sounds really cool. But there are tons of experimental options that might or might not work, and if they do not work, they might cause your backend to stop working. Nothing unexpected.
Solution: Restore your backup. If you don't have a backup, that's your real problem. As a last resort, try removing the ScriptMerge plugin-files from the Joomla! folder system/plugins. After you have gained access to your Joomla! backend, remove the ScriptMerge extension. Optionally reinstall it. Create a backup first.
Known issue: Full page caching
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.
Known issue: Googlebot excludes sources from robots.txt
When using some of the online tools of Google, Google will report that some of the resources that Google needs to interpret the page are excluded from the robots.txt file. The caching files of ScriptMerge are stored in /cache and if this folder is defined in the robots.txt of your site, this error is given. If you want the checks to behave properly, open up the robots.txt and temporarily remove the /cache folder. We recommend you re-add the entry once you're done.