Documentation

Features

Combine files

• Combine javascript/css files into one
• Gzip combined javascript or css file
• Exclude certain files from the aggregating process if these cause problems
• Exclude all files from selected components if plugin doesn't work well with them
• Can produce an aesthetic 'flat link' url for aggregated file with the use of htaccess to promote proxy caching

Minification

• Minify combined css/javascript files
• Minify HTML

Sprite Generator

• Combine select background images into a sprite
• Exclude certain images that didn't sprite well
• Include additional images not selected in sprite by default

CDN/Cookieless domain

• Loads static files from a CDN/Cookieless domain you choose
• Can choose up to 3 domains
• Select which file types are loaded by CDN

Lazy-Load Images

• Implement lazy loading technique for images embedded in the HTML
• Can exclude individual images, folder or class from Lazy load

Optimize CSS Delivery

• Eliminate CSS render-blocking

Optimize Images

• Optimize images without any visual loss of quality
• Option to rescale images prior to optimization

Some features are only available in the Pro version. Visit the downloads page to see the feature comparison between the Free and Pro version.

How the plugin works

Introduction

JCH Optimize is a Joomla! plugin written to optimize web pages by combining external CSS and JavaScript files and even background images. This has the benefit of reducing http requests to fetch and render web pages as an http request has to be made for each resource file. By reducing the amount of these requests, which is expensive in terms of the time it consumes, the download time for the webpage is reduced and the user experience enhanced. Additionally there are options to minify CSS and JavaScript files to even reduce download time further, as minification effectively reduces file size and required bandwidth by removing unnecessary comments and whitespaces. All this happens on the fly without affecting the original files so you can keep them in an 'easy-to-read' form for easy maintenance.

This plugin does not make any changes whatsoever to existing files. Any persistent change observed after the plugin is disabled or uninstalled is as a consequence of caching. In this case the original state of the website can be easily restored by flushing your Joomla!, browser, CDN and third party cache.

Combining External Resources

JavaScript Files

This plugin is called on the Joomla! onAfterRender event. At this stage the component would be already processed and all the modules and templates rendered and the HTML fully prepared to be output to the browser. The plugin makes extensive use of Regular Expressions to search for the various components of the HTML to process and modify to give the desired effect. First, all urls to external script files are removed from the HTML. These would be in script declarations such as...

<script type="text/javascript" src="/templates/beez/javascript/md_stylechanger.js"></script>

Cache

The contents of each files are read and combined together in one file and, if this option is set in the parameters, they are minified. This file is cached and is identified using the id generated above. The lifetime of the cache is the same as that set in global configurations for file caching. The next time the page reloads, the plugin will search for this cached file using the id first. If the file exists and is still valid, the file will be returned rather than spending the time again to generate it. You can find the cache file in the plg_jch_optimize folder.

/path/to/website/base/cache/plg_jch_optimize

Aggregated File URL

With everything going well so far, the browser still need to access this file for download so a link must be placed in the HTML to point to this file. The file in cache wouldn't be available for download from this location so instead a file is used to access it using the Joomla!'s API and make the contents available for download. This file is /plugins/system/jch_optimize/assets/jscss.php. This is the file that must be included in the page source HTML so, a query is appended to the url to pass information to the file regarding the information it is to access to provide for the browser. This link is placed either at

• the first found javascript link that was removed
• the last found javascript link that was removed, or
• the bottom of the page directly before the ending body tag

< script type="text/javascript"
src="/plugins/system/assets2/jscss.php?f=9acd7fbbb5367946c27893235b1fd83f&amp;type=css&amp;gz=gz&amp;d=30" ></script>

 <script type="text/javascript"
src="/plugins/system/jch_optimize/assets/gz/30/bf82248fa6fb8873a36129174656c66e.js" ></script>

CSS Links

A similar process is done for the css files with the exception that a little bit more processing has to be done with these files. CSS tends to have a lot of background images defined and the urls are likely to be relative to the original CSS files. All these urls then have to be corrected relative to the root of the site so the images can be correctly referenced from wherever the cache file is placed.

Additionally W3C specifications stipulate that @import declarations should be placed at the very top of CSS files so these are reordered appropriately in the aggregated CSS file. There is also an option to aggregate the contents of these imported urls if these files are internal so that http requests can be further minimized.

The URL is placed directly below the title element.

<title>Welcome to the Frontpage</title>
< link rel="stylesheet" type="text/css"
href="/plugins/system/jch_optimize/assets/gz/30/d792de74e4b0bbf53a04bb78dfb691140.css" />

The Sprite Generator

The plugin also has the option of combining background images in a sprite to further reduce http requests for individual background image files. This was achieved with slightly modified code from this online CSS sprite generator.

Requirements

• EXIF
• GD or IMAGICK

You can check your phpinfo() to see if these are installed. If not, even when you select this option the plugin will work but there'll be no sprite generation. This feature will be unavailable.

How it works

The plugin scans the combined CSS file for suitable background images to combine in the sprite. Suitable images would be background images with the no-repeat attribute set and having the default background position. That means background position of "left top", "0 0", or any combination of these values.

There are also options to exclude these images if they are diaplayed incorrectly. The multi-select option list used for the exclude settings makes it easy to find the images you want to exlude. Additionally you can include other images that were not included by default. The multi-select include option lists the other images with no-repeat attributes. Spriteme is an excellent tool that can assist in determining the images that can be optionally included in the sprite.

How to know if it's working

The sprite image files are created under the images directory from which they can be accessed using the Media Manager in the admin backend. The sprites are created and kept in a jch-optimize folder. From here images no longer used can be deleted. Additionally, you can check the combined CSS file by accessing the respective url in the page source to see the name of the sprite that replaced the background images in the file. You can identify the name of the sprite from a csg- prefix.

Plugin Options

Basic Settings

Automatic Settings

The plugin offers six pre-configured Automatic settings to make configuring the plugin easy. The settings are called Minimum, Intermediate, Average, Deluxe, Premium, and Optimum. The level of optimization increases as you go from left to right but the risks of conflicts also increase. Just try different ones and choose the highest one that works for your site without creating conflicts. Remember Optimum may not work for everyone so if that doesn't work try Premium or Deluxe instead.

The Automatic Settings automatically configure the settings in the Automatic Group. Don't try configuring these granular settings manually as you'll likely to break your website if you don't know what you're doing. If you're having trouble please try using the Automatic Settings before submitting for support. The following table indicate how the Automatic Settings configure the settings in the Automatic Group.

Utility Setting

There are some Utility Settings to perform some useful functions to ensure the plugin works smoothly and to further speed up your website. Some of these options may not be available depending on the framework you are using.

Leverage Browser Caching

This setting will add some codes to your htaccess file to instruct browsers to cache static files. You will need to have an htaccess file in your document root for this to work. If leverage browser caching codes are already in, then the plugin will not modify the file.

Fix file permissions

This setting will ensure that the permissions of all the files in the plugin installed on your server is 644 and all folders are 755. This is necessary for the proper operation of the plugin otherwise you may not be able to access the combine files and your website will appear to lose all CSS formatting.

Order Plugin

This ensures that the plugin is ordered correctly with respect to some other plugins. The order of the plugin determines the order in which the plugin is executed and important for the correct operation of the plugin. For eg., caching plugins should run after JCH Optimize, otherwise a cached page will be displayed and the plugin will not run. This setting is only available in Joomla!.

Clean Cache

This will flush all the cached files that the plugin generated and stored in cache. On some frameworks, this will also attempt to clean the page cache.

Automatic Settings Group

The settings in this group are automatically configured by the Automatic settings. Do not attempt to change these setting manually to configure the plugin. They generally would be in a collapsed div but are still made available because they are useful in troubleshooting an issue.

Automatic Basic Settings

Combine CSS files

The plugin uses Regular Expressions to identify all the links to css files in the HTML. The contents of all these files will be combined into one file and saved in cache. A link will be generated to access this file and will replace all the previous links to css files.

Combine Javascript files

The same procedure as for CSS files above is followed here. All the contents of JavaScript files are combined into one and cached.

GZip CSS and Javascript file

Selecting this option will compress the aggregated CSS and JavaScript files with Gzip for optimized download. Your server must be configured for gzip otherwise enabling this feature will have no effect.

Minify CSS

This option strips all comments and unnecessary whitespaces such as spaces, tabs, and newlines from the CSS file. This will reduce file size so the website uses less bandwidth for download. Turning this option on will also enable CSS inlined in the HTML in style tags to be minified when the HTML is being minified.

Minify Javascript

Same as for the above but with Javascript files.

Minify HTML

The HTML will be minified, ie. unnecessary whitespaces and comments will be stripped to reduce file size. If the Minify CSS and Minify JavaScript options are selected, then any CSS and javascript inlined within declaration blocks on the page will be minified respectively as well.

Defer Javascript

This option adds a defer attribute to the Javascript link. This will delay the execution of the combined javascript file until after the page is parsed. If this is not set and the asnyc attribute is absent the script will be fetched and parsed before the rest of the page is parsed. PageSpeed refers to that as "render-blocking" and advises the use of defer or async.

Javascript link with defer attribute:

<script type="text/javascript" 
src="/plugins/system/JCH_Optimize/gz/0e1482b90abc12b1ba50a3f961030833.js" defer="defer">

Manage combined files

This setting offers three options to manage how the aggregated CSS and javascript files appear in the HTML to optimize your site and try and ensure that your scripts still works.

1. Preserve Execution Order (Default) - This will split the combined file around any excluded scripts or files to ensure the original execution order of the files on the page is maintained.
2. Combine files in one - This will aggregate all the included CSS or Javascript files into one CSS or Javascript file and place them just below the title tag with the combined CSS file above the combined javascript file. This will occur regardless of if you have excluded any files from the aggregation process.
3. Place javascript at bottom - This option will place the combined javascript file at the bottom of the page just before the ending body tag. The combined CSS file will be placed just under the title tag in the head section.

Automatic Exclude Settings

Exclude all extensions

If enabled, then all the files from third party extensions will be excluded from the aggregation process. Files loaded from external domains will also be excluded. Only system files and template files are combined. This is enabled by default.

Automatic Pro Settings

These settings are only available in the Pro version.

Replace @imports in CSS

If this option is set then the plugin will also fetch the contents of any file that is called by an @import statement in the CSS and replace the @import statement with the contents. This effectively eliminates the http request required to fetch the file, optimizing the webpage even more. This will occur recursively so if the contents themselves contains @imports statements, these would also be replaced by contents from the files pointed to by the @import statements.

Include PHP and external resource files

This options allows the plugin to work with dynamic CSS or javascript provided via php files or files from external domains. This option requires your server to be configured with cURL or have the PHP configuration value 'allow_url_fopen' set to yes.

Include inline CSS styles

Inline CSS within style declaration blocks will be removed and included in the combined CSS file. This is useful in order to maintain the execution order of the CSS as it occurs on the page if you had CSS links under any style declarations. Additionally it will assist in 'Optimize CSS Delivery' if that option is set.

Include inline javascript

Inline javascript in script declaration blocks will be removed and included in the combined file. Again, this is even more important to maintain the execution order of the scripts on the page as of-times scripts will fall in between javascript links. This makes it more likely for you to be able to move the combined javascript file to the bottom of the page or to use the 'defer' or 'async' attribute to prevent render-blocking by javascript as described by PageSpeed. Inline scripts in the body section of the HTML that contains the document.write function are ignored.

Search body

By default the plugin will search the head section of the HTML to find CSS/javascript links and declarations to remove and aggregate in a single file. This extends the search to the body section of the HTML. This is in another attempt to maintain the execution order of the javascript on the page so it will be more likely to implement techniques to prevent render-blocking.

Load javascript asynchronously

The async attribute will be added to the combined javascript file that directs the browser to load the javascript file asynchronously to prevent render-blocking and speed up the page download. This is an HTML5 feature and may not be supported by all browsers so it is used along with the 'defer' option for full cross-browser support.

Lifetime (days)

This setting specifies the life time of the cached aggregated file in days. After this time has expired, the plugin will stop using this file and generate another cache file. Ideally you want to set this as large as possible unless the plugin is generating a large amount of cache. In this case this tutorial explains how to handle that situation.

Advanced Options

Most of the settings in this section are concerned with excluding individual files or files from extensions if you're trying to resolve issues with your page not displaying well or conflicts due to the aggregation of the CSS or javascript files. The exclude settings use multi-select option lists so you can easily find and select the files you think are the problem and effectively exclude them from the aggregation process.

If you are using Joomla! 2.5 then press and hold ctrl while selecting to select or deselect multiple entries. Joomla! 3 uses javascript to enable you to select one entry at a time and provide a visual interface to facilitate the deselection of entries.

Your server configuration may prevent the plugin from creating these multi-select option lists, or the plugin for some reason may not be able to find the links. This does not adversely affect the operation of the plugin and in these cases text-areas are provided for you to type in the urls of the files you want to exclude. Comma separate multiple entries.

Selecting files for exclusion does not prevent them from showing on the page. It merely excludes them from the aggregation process so they are not combined with the rest of the files. The original link will not be altered.

Exclude all extensions

If enabled, then all the files from third party extensions will be excluded from the aggregation process. Files loaded from external domains will also be excluded. Only system files and template files are combined. This is enabled by default.

Menu item

Select the menu item that you are trying to configure the plugin or resolve conflicts for. The home page is the default and when an item is selected the page will automatically refresh. The exclude settings use multi-select option lists that will be populated with the files links, extensions or images found on the selected page respectively.

Exclude CSS

Select the files that you want to exclude from combining with the others. The links to these files will remain unchanged in the HTML of the page.

Exclude JavaScript

Similarly any number of JavaScript files can be excluded from the aggregation process.

Exclude extensions from CSS aggregation

All CSS files from the extension(s) selected will be excluded from aggregation. You can use this option to exclude individual extensions if the exclude all extensions setting is not enabled.

Exclude extensions from javascript aggregation

All javascript files from the extension(s) selected will be excluded from aggregation.

Use url rewrite

This setting requires that your server is configured with url rewriting in order to work. The auto option tries to detect if this is enabled and will automatically use rewriting to remove the query section of the link to the combined file to promote proxy caching if you're using CDN. If you're sure your server supports this and it works then you should select yes. If not, select no. Auto is selected by default.

Url to the combined file without url rewriting:

/plugins/system/jch_optimize/assets2/jscss.php?f=aad691ed89a51b17a81de66b6b6dc172&type=css&gz=gz&d=30

Url to the combined file using url rewriting:

/plugins/system/jch_optimize/assets/gz/30/02e6c75ad61ebbb6da5790d3914652cf.css

Selecting yes when your server does not support it or if it is not properly configured will cause your site to render without any CSS or javascript functionality as the plugin won't be able to find the combined CSS or javascript files.

Debug plugin

Selecting this option will add some key methods to the Joomla! profiler. If your site is taking some time to load then turn this option on along with global debug in Joomla and check the profiler information to see the time the plugin codes are taking to run. Additionally this option will insert the urls of the originating files inside the combined file so you can identify which files the contents are from. The urls are commented out and placed just above the contents that came from that file. This is useful in finding the files to exclude if you're trying to resolve conflicts as described in this tutorial.

If you're not configuring the plugin and in 'production mode' keep this option off to optimize your site.

Log caught exception

Enabling this option will log a message to plg_jch_optimize.errors.php in the logs folder if an exception occurs. If you enable the plugin and it doesn't seem to work because there is no change to the HTML of the page then most likely that is caused by an error. Check the logs folder to see the message that will help us to pinpoint the reason for the error.

If you're not trying to debug the plugin to find errors keep this option off to avoid creating a huge log file.

Pro Options

Download ID

The Download ID is an authenticating facility that enables automatic upgrades of the Pro Version using Joomla!'s update system. It is a md5 sum including the username and encrypted password of the user making it unique for each user. Think of it as a code that can be used to authenticate a user other than a username/password combination. Log into your account on this website to find your download id from the "My Account" -> "Download ID" menu item.

Order the plugin automatically

The published order of the plugin is important and can in some instances determine how well the plugin performs with other third party component. To see the published order, filter for system plugins in Plugin Manager. The plugin should be low in the order with only the system cache plugin and a few select plugins under. Read this FAQ knowledgebase article on more information on how this plugin should be ordered.

Two icons are provided for this setting option, one to order the plugin automatically and the other to clean your cache. The 'Order Plugin' icon will attempt to order the plugin automatically. The 'Clean Cache' icon will delete the plugin and page folders in Cache.

Optimize CSS delivery

With this option enabled the plugin will attempt to load only the CSS that is required on the page in the head and the rest of the CSS will be loaded asynchronously via javascript. This is another render-blocking prevention technique as it significantly reduces the amount of CSS the web page has to load initially in order to start displaying the web page above the fold.

This is an experimental feature that may not work on your site. It will be improved in future releases so use cautiously for now and enable only after you've finished configuring your site to see if it works for you. If you're experiencing issues with your site not displaying correctly, disable this feature first before requesting support.

Exclude scripts

Inline scripts that were included in the aggregated file can be excluded using this option. The multi-select option will list the scripts using the first few minified characters found in the script. Compare these with the beginning of the script declarations in the source of your page to determine which item in the list to select the exclude the script you have determined is not combining well.

Load individual javascript files asynchronously

Instead of excluding javascripts that are not combining well, you can try to load them asynchronously individually. This will resolve the issue of combining them but still prevent render-blocking.

Sprite Generator

Enable sprite generator

If your server meets the requirements then the plugin will attempt to grab background images and save them in a file called a sprite. The CSS will be updated to point the correct elements to the right images on the sprite using the sprite file name and background positioning. Selecting this option will also cause your css files to be aggregated.

Image file type

This determines the format of the generated sprite so choose the one you prefer. Currently the options are PNG and GIF

Build sprite direction

• Vertical - All the images in the sprite will be placed in a vertical fashion. This is appropriate if your images are the same height of the HTML element but the element is wider. This is the default setting.
• Horizontal - All the images in the sprite will be placed in a horizontal manner. Appropriate if your images are the same width of the HTML element but the element is taller.

You could try either options and see which works best for you.

Wrap images

Opera (9.0 and below) has a bug which prevents it recognising offsets of less than -2042px. If your sprite is longer than 2000px then the images will be wrapped into an adjoining column or row.

Include additional images in sprite

If you chose minimum amount of images you can add additional images in this areas. Just the image file names should be placed here complete with the file extension. Multiple images can be accommodated.

Exclude images from sprite

If some images being displayed incorrectly, you can exclude the offending file from the sprite by selecting it in the multi-select exclude option list. This lists contains all background images with no-repeat attribute and background position 'left top' or '0 0' or any combination of these values.

Include additional images in sprite

You can try to add additional images in the sprite to see if it works to reduce more http requests. This lists contains all other images with no-repeat set but with background position other than that stated above. Bear in mind that the images listed here were not chosen by default because based on their background positions may not work well in a sprite since the generator doesn't compensate for the offsets in the background position. use with caution.

Please note that even though the image appears in the exclude options list and therefore was selected for inclusion in the sprite by the plugin, there's no guarantee that it actually made it to the sprite. For eg. the file could be corrupted and therefore could not be manipulated by the image library installed on your server. In these cases the image declarations will be left untouched in the CSS. You'll have to check the image in Media Manager or in the CSS file to confirm which images are in fact included in the sprite.

Introduction

About JCH Optimize

JCH Optimize is an add-on plugin for use on some Content Management Systems (CMS) that performs several front-end optimizations to speed up your website. These optimizations include, combining css and javascript files into one to reduce http requests, minifying the combined files and HTML to reduce page size, generating sprite from select background images to further minimize http requests, lazy loading images, providing CDN support for static resources, optimizing CSS delivery, and optimizing images. Some of these features are only available in the Pro version of the plugin. JCH Optimize is currently available for websites running on Joomla!, WordPress, Magento, and Drupal.

Front-end optimizations refer to modifications you make to the HTML and files downloaded by the browser to make your web page download faster. These actions generally result in reduced http requests by the browser, smaller page sizes and ultimately, shorter page load times. This is very important for website owners who are interested in retaining visitors to their site as research has shown that visitors tend to leave the site if the page takes more than 4 seconds to download.

As a rule of thumb, every 10 http requests adds one second to your download time. Using a CMS, it is not unusual to see a website requiring approximately 100 http requests as the website grows and the administrator adds plugins to provide more features and pages expand to boast numerous images. JCH Optimize provides an easy way to do these optimizations automatically, which otherwise would be tedious and error-proned to do manually, without making any changes to your original code or files. With an easy-to-configure interface, the plugin makes faster websites a reachable goal for even non-technical users.

How it Works

A Content Management System will generate the HTML to be sent to the browser using some server side script like PHP. The plugin intercepts the generated HTML in the CMS before it is sent to the browser and optimizes it, then sends it to the browser. It uses Regular Expressions to find the links to the CSS and javascript files in the HTML and removes them. An example link to a javascript file would look like this:

<script type="text/javascript" src="/templates/beez/javascript/md_stylechanger.js"></script>

JCH Optimize uses the links to access the contents of these files and after minifying the contents, it combines them all in one file respectively and saves them in cache. The plugin generates a link to access the cached file and inserts this link in the HTML in place of the links it previously removed. The generated link by JCH Optimize might differ slightly based on the CMS it is running on. The following shows what the javascript links might look like based on the CMS used. The CSS links would be similar:

Joomla!

<script src="/media/plg_jchoptimize/assets/gz/1/0/2ee14a780ae90820956b94bd8e8ced79.js"></script>

WordPress

<script src="http://localhost/wp-content/plugins/jch-optimize/assets/wp-content/plugins/gz/1/0/3238d2219d061b694aa587964e1c391f.js"></script>

Magento

<script src="/js/jch_optimize/assets/gz/30/0/1b6d7e1158492ee20c302713697fb8e9.js"></script>

Drupal

<script src="/sites/all/modules/jch_optimize/assets/sites/all/modules/nz/30/0/d5971aff44c89a0657dbced470282ab7.js"></script>

Now when the HTML is sent to the browser, it encounters only one link for the CSS files and one link for the javascript files. It uses these links to access the combined file that was generated by the plugin. The combined file, ofcourse, would contain the combined content of all the files that were previously on the page. So by making only one http request, as opposed to several for the individual files, the download time of the page is optimized.

This is a relatively over-simplified explanation of how the plugin works but it gives the general idea. Combining files can be considered the core feature of the plugin and this feature is available in both the Free and Pro versions. The other optimization features are performed in a similar manner, where the HTML is intercepted in the CMS and regular expressions are used to identify the areas of interest to do modifications to the HTML before it is sent to the browser.

These optimizations may sound time-consuming of themselves and one would wonder if they are actually gaining on one end but losing on another. Well the plugin uses state of the art techniques that were developed in house to perform these optimizations at blazing speed. Additionally the plugin caches time-consuming tasks so the optimizations are not done on every page load. Typically it would take 2-3 seconds to optimize the page but on subsequent requests, the plugin should run in less than 100 milliseconds on an average server.