Bundling & Minification
Created by Orckestra
How to bundle and minify scripts and styles on your website
With the package installed, you can optimize XML and Razor based templates and XSLT and Razor functions as well as scripts / style includes in content HTML (see "Important notes" below).
For this, you need to "wrap" the content with the Composite.Web.BundlingAndMinification function by specifying the content in the Page parameter of the function.
- Edit a CMS template, CMS Page or a CMS Function and copy the content you want to have optimized.
- Insert the Composite.Web.BundlingAndMinification function ( Insert / Function) or add the following code ( Insert / Function Markup):
Expand code - In the Page parameter, specify (or paste in) the content to be optimized.
- Save your changes.
Handling scripts
Please note that:
- Bundling and minification work for all scripts except inline scripts.
- The link to the resulting bundle is inserted at the end of
<body>. - The inline scripts are moved to the end of the
<body>and inserted after the link to the bundle.
You can manage the way scripts are processed by using these attributes on scripts:data-c1-nomove="nomove"
The script will be kept in <head> and will not be bundled and minified and moved to the end of <body>.
data-c1-nobundle="nobundle"
The script will not be bundled and minified but will be moved to the end of <body>.
Handling styles
Likewise, you can disable bundling and minification for a specific stylesheet via the data-c1-nobundle attribute :
data-c1-nobundle="nobundle"
Thus, the styles in linked CSS, LESS or SCSS will not be bundled and minified.
Expand codeHow to disable bundling and minification
Important. The Bundling and Minification package is automatically turned off on pages hosting ASP.NET controls (like embedding ASP.NET User Controls or using the Composite.Forms. Renderer package). It gets deactivated due to the ”ordering of events”. It runs at a point where HTML from ASP.NET Controls have not yet been rendered and errors can occur in such a situation.
Note. Whenever you are logged into the CMS Console, the optimization is disabled and you deal with the original optimized files. However, the visitors on your website will get the optimized pages unless they are logged in, too.
You can also disable the optimization altogether via Web.config:
- Edit Web.config.
- Set
system.web/compilation/@debugto "true":
Expand code - Save the changes.
Bundle caching
Bundles set the HTTP Expires Header one year from when the bundle is created.
If any file (JS, CSS) in the bundle changes, the ASP.NET optimization framework will generate a new token, guaranteeing that browser requests for the bundle will get the latest bundle.
Note. If your site uses LESS style files, then corresponding parsed CSS files will be included into the bundle. When you change your LESS files, the corresponding bundle will not be refreshed automatically.
To have it refreshed you can:
- either remove generated CSS files located where the corresponding LESS files are located and named as [LESS file name].min.css
- or restart the site.
Important notes
- The Composite.Web.BundlingAndMinification function does not work on templates based on ASP.NET Master Pages and it will have no effect on User Control Functions. As a result, it's deactivated on pages based on Master Pages and/or containing User Control Functions or ASP.NET user controls in general.
It works well, though, with XML and Razor based templates and CMS Functions based on ASP.NET Razor, ASP.NET MVC, XSLT and on scripts / style includes in content HTML. - This packages is based on Microsoft ASP.NET Web Optimization Framework (please see the example in "Bundling and Minification").
- It works for Styles files (CSS, LESS, SCSS) and JavaScript files:
- Styles files (css, less) are included into one bundle with virtual name "~/Bundles/Styles[page_files_key]"
- JavaScript files are included into bundle with virtual name "~/Bundles/Scripts[page_files_key]"
- It skips CDN links.
- It requires Composite.Web.Css.Less (v. 1.2.4 or later) be installed.
- Bundling and minifying are disabled when the user is logged into the CMS Console (see also "How to disable bundling and minification" above).