jFinalizer joomla plugindocumentation, how-to and support
DownloadPlease select your version. Note that jFinalizer 2 requires joomla 1.6 or later.
Important Change on V2: jFinalizer 2.x uses a different plugin order because of joomla 1.6. As before, jFinalizer should be the last plugin in your chain. But if you use joomla's SYSTEM - CACHE plugin, this must be last even after jFinalizer. Install: right click, copy URL and paste into joomla for installing by URL. Otherwise just download the plugin and upload manually. See changelog. License: GPL, no registration required, free of charge. Component developers please see the tech notes. Please bugreport to Diese E-Mail-Adresse ist gegen Spambots geschützt! Sie müssen JavaScript aktivieren, damit Sie sie sehen können. or feel free to leave bug reports and comments below Warning: Do not install jFinalizer on PHP 4!
OverviewUse jFinalizer if you want to reduce HTTP requests to site, reduce traffic, speed up page loading or decrease HTML page size if you have big templates. On big templates, you can gain 10+ YSlow points, sometimes more than 20. There are many other libraries which do similar things, but we built and run jFinalizer because most of the templates we used would not work with other plugins. Key Features:
Do not use jFinalizer if you want the last bit of compression. Its designed for runtime performance, not for super-high compression. Do not use jFinalizer if you have components, extensions or templates which generate dynamic CSS on the fly (no - you usually don't have that, even on complex templates). Do not expect jFinalizer to work out of the box. Default settings are compatible for most sites, but tuning HTML output is a tricky task and highly depends on your template, CSS, Java Script, components, plugins and modules. Give yourself 10 minutes to get this plugin configured properly. DemoSimply right click and view the source of this page or view the source code of our corporate main site www.farbfinal.de to see what jFinalizer does. Actually, both use the same joomla! installation but different templates. DescriptionThe idea of jFinalizer is to replace tons of JS and CSS files with a single CSS and JS file. This is done by processing the final joomla output HTML. Additionally, you can compact & compress a few things and make your HTML look more compact. jFinalizer uses another approach than most libraries we've found: It does not do anything to CSS, HTML and JS code except for stripping whitespaces and stuff which is not needed. The plugin merges all CSS and JS files used in a page into a single file, preventing the loading order of the html source. Note that only CSS and JS files within the region are processed. We've found that processing body CSS and JS usually harms on complex templates. jFinalizer is designed for live performance. This requires a bit more tuning on the developer side, but reduces runtime CPU usage at runtime a lot. jFinalizer has its name not only because our company is called farbfinal, but also because its usually the last plugin in the system chain and finalizes your output. Your goal is to develop your site, then turn on jFinalizer and see what happens. If your code is clean, you're on the way to go. Even though joomla! is a great CMS, it has a few drawbacks. Joomla's flexibility is awesome, but at the same time it introduces a lot of file I/O on the application server. jFinalizer can help a little to improve that. It does not check for updated CSS or JS files since the developer knows anyway when design is changed. Imagine you have a template with 9 CSS and 7 JavaScript file includes. Makes 16 all together. jFinalizer reduces it to 2 (see limitations). This reduces Server file I/O. Since jFinalizer does not check the modified date of the source files, 14 file system calls are saved. Limitations
PerformanceIn Production mode, the plugin performs quite well and does not consume a lot of CPU. For performance analysis and before / after comparison, please use external tools such as YSlow (FF Plugin). Since jFinalizer is a system plugin we want to keep it slim, there are only a very few analyis options build into plugin (see configuration). Installation Workflow1. install the plugin and set it to plugin order "last". For joomla 1.6 only: If you use the SYSTEM.CACHE plugin, put this even after jFinalizer.
PLUGIN ORDERING: Make sure your plugin ordering chain is right. This setting must be different for different versions of joomla. Tip: Whenever you change a CSS or JS file later or install new joomla! components / plugins, turn jFinalizer into Development Site Mode and check life site again. Tip: While configuring, do one thing at a time. If you want HTML compression, start there and disable all CSS / JS processing. See HTML setup guide Don't give up tuning to fast. Allow yourself 10 minutes to get it working properly. If there is no combination to get your template working, this plugin is probably not for you. Try a different approach like CssJsCompress or JACompress. When installing a jFinalizer upgrade, simply install it. The plugin does not need to be uninstalled before. Configuration TipsIf your site does not work properly, your goal is to turn jFinalizer off, see your HTML source code, then turn the plugin on, reload, see your source code again and compare. First steps for setup could include this procedure:
Tip: Any Compacting can break layout. If your server supports runtime gZip compression, thats probably not a big deal and you can turn it off Tip: if your site uses many joomla components, make sure to also check the pages where they appear! For example, you could get a perfect layout and performance with HTML compression set to ultra, but some poorly coded component might break it or not work as expected. Tip: If HTML compression is what you want most, work the other way around. Disable CSS and JS processing first, enable HTML processing and be sure to try all available modes! If you have the system.cache plugin enabled, disable it while tuning. Try to start with DeTab mode (default). Read the HTML Setup Guide. To see an example, right click and look at the source code of this page. Farbfinal.de is run against jFinalizer with HTML processing mode set to fast using moderate compression and check contitional exceptions, JS on and optimize, CSS on and optimize, remove comments and deliver using gzip htaccess. Setup Guide: HTML compressionHTML processing is the most tricky part. Stick on this workflow to get it working. Be sure your browser reloads properly and dont try to get CSS / JS aggregation to work before HTML processing if you want both.
Tip: for bypassing HTML processing for only a specific block of Text or content plugin, wrap it with {jfbypass}My bypassed content goes here {/jfbypass} in the article editor.
Setup Guide: CSS / JS processingIf you dont want HTML output processing, try this workflow to setup CSS / JS processing properly. This may help to to get your site working a bit faster.
Setup Guide: use both togetherSee instructions above. Be sure to first get HTML compression working properly at first, then start CSS / JS file processing - not the other way arround! Optionsthe default configuration should work for most installations:
Site ModeYour most important switch while tuning and developing. Controls how jFinalizer handles its internal cache. Yes, you want cache! The cache system on jFinalizer operates independent of all joomla! cache settings, because its always content independent. Caching in jFinalizer means that JS and CSS files are stored to disk and not re-processed on every page load. HTML output is never cached by jFinalizer. Using jFinalizer without cache does not make sense because you would decrease HTTP requests but at the same time increase execution. While developing design (CSS) or functionality (JS) you want to turn Site mode into development. When your site is up, fixed, steady and running - go for production. Note: development mode reduces performance big time - your site will slow down drastically. Tip: while in designing layout in development mode, disable JavaScript & CSS compacting
process HTMLremoved in version 1.1.0. Also, Tidy support is not available in jFinalizer 1.1.0+ HTML CompressionSets the compression level of HTML output. Depending on how clean your template is, you can reach different compression levels. Compression levels also affect CPU usage on the server side a bit. Please note that the most efficient and fastest mode is ultra, but unless your template is super-clean, ultra mode will probably break your layouts. All modes try to remove as many white spaces as possible. Ultra also removes all line breaks. The difference in the operating modes is how deep the plugin digs and how much whitespace is removed. Some modes do additional checking to prevent design breaks. Please try and see which option works best for your template. The different options are available because the idea if jFinalizer is to perform as fast as possible and do as few checks as possible at runtime.
Tip: Published starting at jFinalizer 1.1.0, DeTab seems to be most compatible. Its also the current installation default setting. We did a lot of testing and performance comparison. While being much more compatible and 2x faster than our best algorithm so far, Safe mode C+, HTML size increases typically between 0.5-1% only when using DeTab compared to Safe Mode C+. Also, source code looks very clean now. So we strongly recommend DeTab now. Note: Starting from some of the next releases, only compression modes DeTab, Safe Mode C+ and Ultra will be available. Others will be removed an depreciated! HTML commentsKeep or remove HTML comments. It takes a bit CPU but usually is a good thing if you want to clean your output. Please note that multiline comments are always kept!
Pre Tag SupportNever touch <pre> tags. Don't remove linebreaks, whitespaces etc. This option is available on jFinalizer 1.0.11+. Useful for plugins like CodeCitation. If you know your site does not have any <pre> tags, turn it off for a tiny bit of extra performance.
Generator TagKeep or remove the joomla! generator meta tag. Can help a bit to not expose joomla. Note that there are other ways to do that but they require joomla ource code editing.
process JavaScriptDoes what it says. Process all JavaScript tags, read the files, merge them into one and cache them. Note that having external url (from another server) javascript within your <head> tag will probably break the script. All JavaScript files outside the header <head>...</head> tags are ignored.
compact JavaScriptremove whitespaces and other unused stuff from JS files. Usually saves a couple bytes. In some cases, compacting JS can break JavaSvript functionality. If thats the case, try disabling it. Performance note: compacting JavaScript files is usually the most time consuming task of jFinalizer. While this is not a problem in production (cache) mode, you might want to turn JS compacting off when in development mode.
jQuery NoConflict() supportresolve jQuery conflicting Ajax libraries - added by feature request, v1.1.4+ Some Ajax libraries might fight each other. The jQuery library contains a switch which can resolve this issue when used together with other libraries, such as joomla's default MooTools. However, jFinalizer has the option to inclide that switch because sometimes, 3rd Party components already call this JavaScript statement, so it's not needed a second time.
Skip FilesNever process those files. Type any phrase in there. Case unsensitive. You can manually enter a comma-separated list here to exclude specific files. These files will always be skipped. For example, the default setting tini_mce.js ensures that the joomla default TinyMCE editor will still work in the front end when users edit content. UPDATE: jFinalizer 1.x can only exclude JS files. jFinalizer 2.x can exclude both JS and CSS.
process CSSsame thing as as process JavaScript but for CSS files compact CSSsame thing as compact JS but for CSS check conditional ExceptionsCheck it the template contains conditional <!--if... --> CSS includes for client browsers. If it does, they are ignored. The option is available because if YOU KNOW your template does not have any conditional includes, you can turn this option off and save some extra performance.
gZip outputcompress cached JS and CSS files using gZip. gZipping JS & CSS files can drastically reduce file size and download time. When run in .htaccess delivery mode, additional PHP calls are bypassed and runtime compression by the delivery server (eg. apache) is skipped. This can reduce overall load and File I/O on your server. Please note that .htaccess mode is not available on all platforms. If you run a dedicated server, this option is for you to tune the last bit. The modes explained for experts: PHP delivery: the client browser calls a PHP file which delivers the JS / CSS file dynamically and adds necessary css headers. The files are already compressed, but PHP needs to be opened and a fopen() function is involved. .htaccess delivery: a .htaccess file is placed into the delivery folder (usually /cache/assets). The web server checks if gZipped content is accepted by the client and rewrites the request file name to deliver the gzipped version. Fast, no additional PHP calls. On apache, mod_rewrite must be enabled and allow_overrides must be properly set for the cache path. If Apache is set to compress .js and / or .css files by default on the fly using DEFLATE, this will be bypassed for those files saving CPU time. To customize the content of the .htaccess file depending on your server configuration, copy the file /plugins/jfinalizer/htaccess.default.php to htaccess.custom.php and edit this file. This way, your changes remain after you upgrade jFinalizer. Note: .htaccess configuratio requires jFinalizer 1.0.4+ Please note that apache knowledge is required when editing the .htaccess file contents. The goal of the .htaccess file is to check if the client accepts compressed data, and if thats the case redirect the request to the gzipped version of CSS / JS files.
cache lifetime in sAs CSS and JS files dont change once you finished designing, cache lifetime is usually set to 0 meaning the files never expire. However, you have the option to enter an amount of seconds to force rebuilding the merged files after that period. Do not confuse "expired" here with http expiring / client cache lifetime: HTTP send Headers are not touched by jFinalizer.
debugAppend some debug info comments or show performance data Debug mode help you to see what jFinalizer does and how it performs. In html comments mode, a html comment containing the name of the removed JS / CSS files is placed into placed into output HTML source code. This can be useful if you want to see what files were merged. In full and performance mode, jFinalizer displays performance data such as total runtime of the plugin, number of merged files an HTML byte savings on top of your site. Full & performance breaks design and cookies. So don't use it on a live site - or if you do, turn it off quickly again. While tuning jFinalizer compression settings, don't run full and performance since you can't see compression design breaks.
Advanced: Place Tagswhere to place output file tags in HTML. By default (auto), the first found tag (CSS / JS) in your source template is replaced by the merged output file. However, you can optimize tag placement by manually placing tags. For example, if you have a minimal template which has not a lot of JavaScript, you could move all JavaScript from the <head> to the bottom of your body. Anyways, manual template editing is necessary. If you want to do so, call the loading event at the appropriate place within your template and then switch to manual . Usually this is the section which outputs head data. It does not matter if other CSS or JS files are loaded after manual placement. The parsing and collecting always comes later. PHP Placement code CSS: $mainframe->triggerEvent('getCompressedCSS'); ($mainframe refers to the joomla mainframe object).
Advanced: Delivery Pathdelivery output path for CSS and JS files in client HTML Now thats tricky. By changing the delivery path, you can tell the client to load the merged JS and CSS files from another source path. Its great for hiding the default joomla /cache/xxx directory. Cached files are always stored physically on disk into the joomla cache directory, subfolder /assets. So, usually thats /cache/assets. You can't change that because thats the only way to clean jFinalizer cache using the joomla builtin cache manager. Re-routing the delivery path works by placing a symlink to /cache/assets. You need shell access. Login to your server and create a softlink. For example on linux, if you want you delivery path to be example.com/inc, you would create the symlink using bash># ln -s /my/absjoomlarootpath/cache/assets /my/absjoomlarootpath/inc and then insert inc/ into the delivery Path field. Note that Apache might check symlink permissions. They need to be set correctly.
Advanced: Remote File supportLet Finalizer try to include asset files that are not stored on the actual server. This option is experimental - we need feedback on this! The PHP directive allow_url_fopen must be enabled. Also, please note that any files containing a "?" or other suffixes, like style.css.php, are considered dynamic and are always skipped.
Advanced: joomla subdirectoryTell jFinalizer if joomla is installed in a subdirectory. Unfortunately, joomla might do strange things sometimes when installed in a subdirectory. Although there is a $live_site directive in joomla's configuration.php, this setting might break some 3rd party components. jFinalizer itself is not affected by that issue, but other than most joomla core components it needs to reconstruct url's that are already parsed out. So, to be more compatible, we decided to give that extra switch. Also, it accelerates a bit because we have less string processing to to. Please not the spelling: if your site is installed into www.example.com/joomlarootdir, you must enter /joomlarootdir - not joomlarootdir/, joomlarootdir, /joomlarootdir/ or example.com/joomlarootdir
tips, tricks, troubleshooting
known issues
A Primer On Compression EfficiencyWhen you apply output compression or optimization, either on HTML, JS or CSS, you have 2 things in your mind: You want to reduce server load and you want to speed up your clients page loading. Unfortunately, involving compression is always a tradeoff. No matter how efficient the algorithms are - the better the compression, the more CPU usage is needed on the server side. For example, speaking of HTML compression, this involves a lot of additional checking to make sure no inline JavaScript functionality or CSS design breaks. When we first designed jFinalizer, our goal was to reach maximum compression with minimum server CPU load while being as compatible as possible. To keep the tradeoff between compression ratio and CPU usage as balanced as possible, we have setup a reference page and kicked all algorithms which cause jFinalizer to exceed a total runtime of 5ms. We figured that it does not make sense to build a system plugin which requires Page Caching to keep performant. Since we got lots of feedback from jFinalizer users while (still) being in beta, we could evaluate many different 3rd party components and their behavior on compression. After lots of comparison, we decided to give the go for our newest DeTab compression algorithm: Compared to all others, it does not completely remove line breaks. At first, we did not like that at all. But after statistics evaluation, we were quite surprised. The total increase of HTML size is only minimal, typically between 0.5-1% compared to other algorithms. Now that was good news. Removing line breaks causes heavy problems with inline JavaScript and needs a lot of reconstructing. We have a great balance now: execution time on our reference Page reduced to <2ms and the algorithm did not break any JavaScript yet. So with the help of many jFinalizer users, we think that we have found the perfect tradeoff for jFinalizer and plan to go from beta RC to the first official release. changelog1.0.0 1.1.0 - download archive plg-system-jfinalizer-1.1.0.zip 2.0.0 2.0.1
Comments & Bug ReportsWhen posting a bug report or problem, don't forget to post the jFinalizer version. If you use HTML compression, tell us what Mode you use. |
