Documentation
Installation
The module is dependent on the Helpful Libraries module, so make sure to install it first!Combinator needs at least Orchard 1.5!
The module's admin settings
After installation the module adds a settings page to the Settings menu. You can also empty the cache there.
Note: Currently the module preserves a combined resource forever, without updating it if the resources have changed. If you have modified a stylesheet or javascript file (or its resource's settings, like conditions) and want to see the updates you should empty the cache. If the list of resource for a specific page changes, however (e.g. from Script1.js, Script2.js to include Script3.js too), Combinator will produce a new resource.
Exclusion filters and why they matter
You can set exclusion filters (regular expressions) on combination, minification and image embedding.
- Sometimes a resource does not play well with combination: e.g. WYSIWYG editors (like TinyMCE) tend to load scripts on the fly, based on relative paths to the script's location. Combinator can do nothing with such mechanisms, so it's better not to touch them: therefore, excluding from combination is the way to go.
- Javascript minification is not bullet-proof, there are rare cases (mostly with already minified scripts) when the produced script is syntactically incorrect. To overcome this, you can exclude such scripts from minification.
- Excluding stylesheets from embedding their images is useful for conditional stylesheets specifically targeted at browsers that don't support data urls.
Development best practices
- Don't have Combinator always enabled in your development (and testing) environment, as combined resources make it harder to find bugs in resources. Only enable Combinator steadily in the live environment.
- You should, however, always test the impact of the module on your site. Try all pages where distinct sets of resources are used.
- When testing in the development environment, don't have Shape Tracing enabled.
- Always empty the cache in the live environment when you push resource changes to it.
- Unless you adjust the urls to be the same, you can't push combined resources to the live environment (since Combinator adjusts relative paths, these will include the url of your development environment; however if you don't have AppPath set you should be able to publish to live, but if you have one, like the default "OrchardLocal", resources should be recompiled in live). Therefore, it's best to publish changes with the cache emptied and let combination happen on the live site (which will only cause a performance impact on the first views of pages with unique set of resources).
Troubleshooting
If something fails, Combinator returns the original set of resources for a specific resource type (like head scripts) or even for all resources, depending on the type of failure. So if looking at the html source you see that nothing has changed then something has gone wrong. Possible causes are that a local or remote resource was not found or an exclusion regex was erroneous. Take a look at the log file to see what happened. If you're in doubt what have caused the failure, don't be afraid to ask.
Who's using it?
Among others Combinator speeds up the
Orchard Gallery, the
Hungarian Orchard Community site and the
Associativy home page. If you use and like Combinator, let me know and your site will be listed here.
Many thanks
To randompete, Sebastien Ros (for the incredible overridden stylesheet discovery) and Znowman for their valuable contributions!