JCH Optimize - 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.

	Minimum	Intermediate	Average	Deluxe	Premium	Optimum
Combine CSS files	Yes	Yes	Yes	Yes	Yes	Yes
Combine Javascript files	Yes	Yes	Yes	Yes	Yes	Yes
Gzip javascript and CSS	No	Yes	Yes	Yes	Yes	Yes
Minify CSS	No	Yes	Yes	Yes	Yes	Yes
Minify javascript	No	Yes	Yes	Yes	Yes	Yes
Minify HTML	No	Yes	Yes	Yes	Yes	Yes
Defer javascript	No	No	No	No	No	Yes
Manage combined file	Preserve execution order	Preserve execution order	Preserve execution order	Combine files in one	Place javascript at bottom	Place javascript at bottom
Exclude all extensions	Yes	Yes	No	No	No	No
Replace @import in CSS	Yes	Yes	Yes	Yes	Yes	Yes
Include PHP and external files	Yes	Yes	Yes	Yes	Yes	Yes
Include Inline CSS styles	Yes	Yes	Yes	Yes	Yes	Yes
Include Inline javascript	No	No	No	Yes	Yes	Yes
Include Inline javascript	No	No	No	No	Yes	Yes
Load javascript asynchronously	No	No	No	No	No	Yes

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.

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.
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.
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&amp;type=css&amp;gz=gz&amp;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.