2 ----------------------------------
3 ADVANCED CSS/JS AGGREGATION MODULE
4 ----------------------------------
13 - JavaScript Bookmarklet
14 - Technical Details & Hooks
15 - How to get a high PageSpeed score
23 **Advanced CSS/JS Aggregation core features**
25 - On demand generation of CSS/JS Aggregates. If the file doesn't exist it will
26 be generated on demand.
27 - Stampede protection for CSS and JS aggregation. Uses locking so multiple
28 requests for the same thing will result in only one thread doing the work.
29 - Fully cached CSS/JS assets allow for zero file I/O if the Aggregated file
30 already exists. Results in better page generation performance.
31 - Smarter aggregate deletion. CSS/JS aggregates only get removed from the
32 folder if they have not been used/accessed in the last 30 days.
33 - Smarter cache flushing. Scans all CSS/JS files that have been added to any
34 aggregate; if that file has changed then flush the correct caches so the
35 changes go out. The new name ensures changes go out when using CDNs.
36 - Url query string to turn off aggregation for that request. ?advagg=0 will
37 turn off file aggregation if the user has the "bypass advanced aggregation"
38 permission. ?advagg=-1 will completely bypass all of Advanced CSS/JS
39 Aggregations modules and submodules. ?advagg=1 will enable Advanced CSS/JS
40 Aggregation if it is currently disabled.
41 - Button on the admin page for dropping a cookie that will turn off file
42 aggregation. Useful for theme development.
43 - Gzip support. All aggregated files can be pre-compressed into a .gz file and
44 served from Apache. This is faster then gzipping the file on each request.
46 **Included submodules**
49 Smartly groups files together - given a target number of CSS/JS aggregates,
50 this will try very hard to meet that goal.
52 Load CSS or JavaScript libraries from a public CDN; currently only supports
53 jQuery and jQuery UI with either Google's or Microsoft's CDN.
55 Minify the compiled CSS files using a 3rd party minifier; currently
56 supports YUI (included).
58 Compress the compiled JavaScript files using a 3rd party minifier;
59 built in support for a number of minifiers.
61 Includes additional tweaks that may not work for all sites:
62 - Force preprocessing for all CSS/JS.
63 - Move all JS to footer.
64 - Add defer tag to all JS.
65 - Inline all CSS/JS for given paths.
66 - Use a shared directory for a unified multisite.
68 Validate all CSS files using jigsaw.w3.org. Check all CSS files with CSSLint.
69 Check all JS files with JSHint.
75 Settings page is located at:
76 `admin/config/development/performance/advagg`
80 - Enable Advanced Aggregation: Check this to start using this module. You can
81 also quickly disable the module here. For testing purposes, this has the same
82 effect as placing ?advagg=-1 in the URL. Disabled by default.
83 - Create .gz files: Check this by default as it will improve your performance.
84 For every Aggregated file generated, this will create a gzip version of file
85 and then only serve it out if the browser accepts gzip files compression.
87 - Use Cores Grouping Logic: Leave this checkbox enabled until you are ready to
88 begin exploring the AdvAgg Bundler sub-module which overrides Core's
89 functionality. This groups files just like Core does so should just work.
90 Enabled by default. You will also have to disable this checkbox if you wish
91 to enable some of the CSS Options below on this settings page.
92 - AdvAgg Cache Settings: As a reference, core takes about 25 ms to run.
93 Development will scan all files for a change on every page load. Normal is
94 fine for all use cases. Aggressive should be fine in almost all use cases;
95 if your inline css/js changes based off of a variable then the aggressive
96 cache hit ratio will be low; if that is the case consider using
97 Drupal.settings for a better cache hit ratio.
99 **CSS Options & JS Options**
101 - Combine CSS files by using media queries: "Use cores grouping logic" needs to
102 be unchecked in order for this to work. Also noted is that due to an issue
103 with IE9, compatibility mode is forced off if this is enabled by adding this
104 tag in the html head:
107 <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
111 - Prevent more than 4095 CSS selectors in an aggregated CSS file: Internet
112 Explorer before version 10; IE9, IE8, IE7, & IE6 all have 4095 as the limit
113 for the maximum number of css selectors that can be in a file. Enabling this
114 will prevent CSS aggregates from being created that exceed this limit. For
116 http://blogs.msdn.com/b/ieinternals/archive/2011/05/14/10164546.aspx Disabled
118 - Fix improperly set type (CSS/JS): If type is external but does not start with
119 http, https, or // change it to be type file. If type is file but it starts
120 with http, https, or // change type to be external.
124 located at `admin/config/development/performance/advagg/info`. This page
125 provides debugging information. There are no configuration options here.
126 - Hook Theme Info: Displays the process_html order. Used for debugging.
127 - CSS files: Displays how often a file has changed.
128 - JS files: Displays how often a file has changed.
129 - Modules implementing AdvAgg CSS/JS hooks: Lets you know what modules are
131 - AdvAgg CSS/JS hooks implemented by modules: Lets you know what advagg hooks
133 - Hooks And Variables Used In Hash: Show what is used to calculate the 3rd hash
134 of an aggregates filename.
135 - Get detailed info about an aggregate file: Look up detailed array about any
136 CSS or JS file listed.
140 located at `admin/config/development/performance/advagg/operations`. This is a
141 collection of commands to control the cache and to manage testing of this
142 module. In general this page is useful when troubleshooting some aggregation
143 issues. For normal operations, you do not need to do anything on this page below
144 the Smart Cache Flush. There are no configuration options here.
146 - Flush AdvAgg Cache: Scan all files referenced in aggregated files. If
147 any of them have changed, increment the counters containing that file and
150 - Aggregation Bypass Cookie
151 - Toggle The "aggregation bypass cookie" For This Browser: This will set or
152 remove a cookie that disables aggregation for the remainder of the browser
153 session. It acts almost the same as adding ?advagg=0 to every URL.
155 - Cron Maintenance Tasks
156 - Remove All Stale Files: Scan all files in the advagg_css/js directories and
157 remove the ones that have not been accessed in the last 30 days.
158 - Clear Missing Files From the Database: Scan for missing files and remove
159 the associated entries in the database.
160 - Delete Unused Aggregates from Database: Delete aggregates that have not
161 been accessed in the last 6 weeks.
162 - Delete orphaned/expired advagg locks from the semaphore database table.
165 - Clear All Caches: Remove all data stored in the advagg cache bins.
166 - Remove All Generated Files. Remove all files in the advagg_css/js
168 - Increment Global Counter: Force the creation of all new aggregates by
169 incrementing a global counter.
173 The following settings are not configurable from the admin UI and must be set in
174 settings.php. In general they are settings that should not be changed. The
175 current defaults are shown.
177 // Display a message that the bypass cookie is set.
178 $conf['show_bypass_cookie_message'] = TRUE;
180 // Skip the 404 check on status page.
181 $conf['advagg_skip_404_check'] = FALSE;
183 // Run advagg_url_inbound_alter().
184 $conf['advagg_url_inbound_alter'] = TRUE;
186 // Pregenerate aggregate files. If disable the browser requesting the file
187 // will cause the generation to happen. If advagg 404 handling is broken
188 // then setting this to false will break your site in bad ways.
189 $conf['advagg_pregenerate_aggregate_files'] = TRUE;
191 // Value for the compression ratio test.
192 $conf['advagg_js_compress_max_ratio'] = 0.9;
194 // Value for the compression ratio test.
195 $conf['advagg_js_compress_ratio'] = 0.1;
197 // Skip far future check on status page.
198 $conf['advagg_skip_far_future_check'] = FALSE;
200 // Skip preprocess and enabled checks.
201 $conf['skip_enabled_preprocess_check'] = FALSE;
203 // Default root dir for the advagg files; see advagg_get_root_files_dir().
204 $conf['root_dir_prefix'] = 'public://';
209 The AdvAgg JS Minify module can take advantage of jsmin.c. JavaScript parsing
210 and minimizing will be done in C instead of PHP dramatically speeding up the
211 process. JsMin C extension can be found at https://github.com/sqmk/pecl-jsmin.
214 JAVASCRIPT BOOKMARKLET
215 ----------------------
217 You can use this JS code as a bookmarklet for toggling the AdvAgg URL parameter.
218 See http://en.wikipedia.org/wiki/Bookmarklet for more details.
220 javascript:(function(){var loc = document.location.href,qs = document.location.search,regex_off = /\&?advagg=-1/,goto = loc;if(qs.match(regex_off)) {goto = loc.replace(regex_off, '');} else {qs = qs ? qs + '&advagg=-1' : '?advagg=-1';goto = document.location.pathname + qs;}window.location = goto;})();
223 TECHNICAL DETAILS & HOOKS
224 -------------------------
226 **Technical Details**
228 - Files are generated by this pattern:
230 css__[BASE64_HASH]__[BASE64_HASH]__[BASE64_HASH].css
232 The first base64 hash value tells us what files are included in the
233 aggregate. Changing what files get included will change this value.
235 The second base64 hash value is used as a sort of version control; it changes
236 if any of the base files contents have changed. Changing a base file's content
237 (like drupal.js) will change this value.
239 The third base64 hash value records what settings were used when generating
240 the aggregate. Changing a setting that affects how aggregates get built
241 (like toggling "Create .gz files") will change this value.
243 - Aggressive Cache Setting: This will fully cache the rendered html generated
244 by AdvAgg. The cache ID is set by this code:
246 $hooks_hash = advagg_get_current_hooks_hash();
247 $css_cache_id_full = 'advagg:css:full:' . $hooks_hash . ':' . drupal_hash_base64(serialize($full_css));
249 $hooks_hash = advagg_get_current_hooks_hash();
250 $js_cache_id_full = 'advagg:js:full:' . $hooks_hash . ':' . drupal_hash_base64(serialize($js_scope_array));
252 The second and final hash value in this cache id is the css/js_hash value.
253 This takes the input from drupal_add_css/js() and creates a hash value from
254 it. If a different file is added and/or inline code changed, this hash value
257 The first hash value will take the current_hooks_hash value which is the
258 third base64 hash value listed above in this section (Technical Details) as
259 the first part of the hash. This means that if any value is changed in this
260 nested array a different cache id will be used. You can see the contents of
261 this nested array by going to
262 `admin/config/development/performance/advagg/info` under
263 "Hooks And Variables Used In Hash". An example of this being properly used is
264 if you enable the core locale module the language key will appear in the
265 array. This is needed because the locale_css_alter and locale_js_alter
266 functions both use the global $language variable in determining what css or
267 js files need to be altered. To add in your own context you can use
268 hook_advagg_current_hooks_hash_array_alter to do so. Be careful when doing so
269 as including something like the user id will make every user have a different
270 set of aggregate files.
274 Modify file contents:
275 - advagg_css_contents_alter. Modify the data of each file before it
276 gets glued together into the bigger aggregate. Useful for minification.
277 - advagg_js_contents_alter. Modify the data of each file before it
278 gets glued together into the bigger aggregate. Useful for minification.
280 Modify file names and aggregate bundles:
281 - advagg_current_hooks_hash_array_alter. Add in your own settings and hooks
282 allowing one to modify the 3rd base64 hash in a filename.
285 - advagg_hooks_implemented_alter. Tell advagg about other hooks related to
287 - advagg_get_root_files_dir_alter. Allow other modules to alter css and js
289 - advagg_modify_css_pre_render_alter. Allow other modules to modify $children
290 & $elements before they are rendered.
291 - advagg_modify_js_pre_render_alter. Allow other modules to modify $children
292 & $elements before they are rendered.
293 - advagg_changed_files. Let other modules know about the changed files.
294 - advagg_removed_aggregates. Let other modules know about removed aggregates.
295 - advagg_scan_for_changes. Let other modules see if files related to this file
296 has changed. Useful for detecting changes to referenced images in css.
297 - advagg_scan_file_alter. Let other modules modify information about
298 the base CSS/JS files.
299 - advagg_context_alter. Allow other modules to swap important contextual
300 information on generation.
301 - advagg_bundler_analysis. If the bundler module is installed allow for other
302 modules to change the bundler analysis.
305 HOW TO GET A HIGH PAGESPEED SCORE
306 ---------------------------------
308 Go to `admin/config/development/performance/advagg`
309 - uncheck "Use cores grouping logic"
310 - check "Combine CSS files by using media queries"
312 Install AdvAgg Modifier if not enabled and go to
313 `admin/config/development/performance/advagg/mod`
314 - Under "Move JS to the footer" Select "All"
315 - set "Enable preprocess on all JS/CSS"
316 - set "Move JavaScript added by drupal_add_html_head() into drupal_add_js()"
317 - set "Move CSS added by drupal_add_html_head() into drupal_add_css()"
318 - Enable every checkbox under "Optimize JavaScript/CSS Ordering"
320 Install AdvAgg Minify Javascript if not enabled and go to
321 `admin/config/development/performance/advagg/js-minify`
322 - Select JSMin if available; otherwise select JSMin+
324 **Other things to consider**
326 On the `admin/config/development/performance/advagg/mod` page there is the
327 setting "Remove unused JavaScript tags if possible". This is a backport of D8
328 where it will not add any JS to the page if it is not being used.
329 https://drupal.org/node/1279226
331 The AdvAgg Bundler module on the
332 `admin/config/development/performance/advagg/bundler` page. The bundler provides
333 intelligent bundling of CSS and JS files by grouping files that belong together.
334 This does what core tried to do; group CSS & JS files together that get used
335 together. Using this will make your pagespeed score go down as there will be
336 more css/js files to download but if different css/js files are used on
337 different pages of your site this will be a net win as a new full aggregate will
338 not have to be downloaded, instead a smaller aggregate can be downloaded,
339 ideally with only the css/js that is different on that page. You can select how
340 many bundles to create and the bundler will do it's best to meet that goal; if
341 using browser css/js conditionals (js browser conditionals backported from D8
342 https://drupal.org/node/865536) then the bundler might not meet your set value.