Using the ClientDependency Framework in Umbraco Blog post

Umbraco

Minification is the process of removing unnecessary whitespace and characters from your website assets (typically JavaScript and CSS) without changing the functionality. This is desirable as it helps make your pages load quicker which, in turn, helps keep visitors happy and also can improve your SEO. Sounds great, huh?

The trouble is that whilst it reduces the size of your files it can also make them very difficult to read and work with. If you've ever looked at the minified versions of jQuery then you'll know that it's unreadable. So, whilst it's desirable to minify files, it's something that many people don't bother with because of the hassle it can cause when you need to make modifications.

Wouldn't it be Great if There Was an Easier Way?

One of the lesser known features of Umbraco is that is ships with something called the ClientDependency Framework (CDF). You may have seen a strange folder in your /App_Data/TEMP/ directory called ClientDependency, full of strange looking files. But what are these and what is the CDF? Well, the website for the CDF describes it thus:

"ClientDependency will not only manage the inter-dependencies of scripts and styles between all your views, controls and pages but has the added benefit of managing all of the file compression, combination & minification for you. It will even detect and process script/styles that aren't registered with the framework and other requests such as json that can be minified/compressed"

In other words, what the CDF can do is enable you to include all assets (JS & CSS) easily and also combine them into single files which are then minified. Combining files is just as essential as minification if you want to reduce page load speeds as it reduces the number of HTTP requests being made.

The developers of Umbraco realised this and have used it to compress and reduce the number of scripts being used in the Umbraco back-end. The files you see in /App_Data/TEMP/ClientDependency/ are the cached versions of the minified scripts that the CDF has created.

So How do I use the ClientDependency Framework?

Note: This is an old post and applies to Umbraco 4 (4.5 and up) using Web Forms. If you are using Umbraco 6 or 7 with MVC then you should read the documentation Wiki instead

Luckily, since the CDF comes pre-installed with Umbraco then you can use it too without any real effort. Let's look at the make-up of a typical (but very simplified) master page in Umbraco:

<[email protected] Language="C#" MasterPageFile="/umbraco/masterpages/default.master" AutoEventWireup="true" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<htmlxmlns="http://www.w3.org/1999/xhtml"xml:lang="en"lang="en">
<head>
<title></title>
<link rel="stylesheet"href="/css/main.css"type="text/css"/>
<link rel="stylesheet"href="/css/blog.css"type="text/css"/>
<script type="text/javascript"src="/scripts/main.js"></script>
<script type="text/javascript"src="/scripts/jquery.plugin.js"></script>
<script type="text/javascript"src="/scripts/default.js"></script>
</head>
<body>
....
</body>
</html>

As you can see there are two CSS files and three JavaScript files being included. To perform the same task using the CDF you would change your master page to look something like this:

<%@Master Language="C#" MasterPageFile="/umbraco/masterpages/default.master" AutoEventWireup="true" %>
<%@Register Namespace="ClientDependency.Core.Controls"Assembly="ClientDependency.Core" TagPrefix="CD" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   
<head>
     
<title></title>
     
       
<CD:ClientDependencyLoader runat="server" id="Loader">
           
<Paths>
               
<CD:ClientDependency PathName="Styles" Path="/css"/>
               
<CD:ClientDependency PathName="Scripts" Path='/scripts'/>
           
</Paths>
       
</CD:ClientDependencyLoader>
       
       
<CD:CssInclude runat="server"FilePath="/css/main.css"/>
       
<CD:CssInclude runat="server"FilePath="/css/blog.css"/>

       
<CD:JsInclude runat="server"FilePath="/scripts/main.js"/>
       
<CD:JsInclude runat="server"FilePath="/scripts/jquery.plugin.js"/>
       
<CD:JsInclude runat="server"FilePath="/scripts/default.js"/>

   
</head>
   
<body>
        ....
   
</body>
</html>

If you run this and view the source you'll see how the five CSS and JavaScript have been combined and minified into just two files. These are then cached for future use.

How Does This Work?

There are three main steps to this:

  • First you need to register the CDF controls assembly with a standard Register directive.
  • Then you add the ClientDependencyLoader control that basically acts as a placeholder for where your scripts will be "injected". In other words, place this where you would like your files to be included.
  • Lastly you use the CssInclude and JsInclude files to include your resources. The beauty is you can place these anywhere you like in your page, the files will be included where the ClientDependencyLoader is. You can also programatically include files, too.

Note that the CDF doesn't alter your original files - it generates it's own combined and minified versions of your originals.

For more details please check the CDF Documentation.

One imporant thing to note is that the files are only minified and cached when you have debug="false" in your web.config file. However, once they are minified then your files are also cached for performance reasons. The downside of this is that you need to clear the cache if you change any of your original source files. This is why it's recommended to have debug="true" when developing and then disable it once you "go live". However, if you need to clear the cache you can:

  • Change the version number in the ClientDependency config
  • Delete the ClientDependency folder from App_Data
  • You DO NOT have to restart the app pool to clear ClientDependency cache

The CDF offers far more features, such as registering files from "code behind" or via Razor CSHMTL scripts, "rogue" script detection and more, but I'd recommend reading the documentation for how to do this. You can, of course, use the CDF outside of Umbraco too - there are no dependencies.

As I mentioned, this post specifically refers to Umbraco 4, but the basic principles will probably apply to 5 too - check the documentation on registering the CDF in MVC applications.


6 Comments


Doug Robar Avatar

Nice, Dan!

If you change the filenames included, by adding a version number to the end (such as the way jquery does it), when you upload a new version of your scripts and css the CD cache will update automatically even if you have debug="false" without having to change the CD config version number or delete the CD folder from app_data.

This might be easier in some situations.

cheers, doug.


James Drever Avatar

That's really helpful, Dan, thankyou. Like a lot of great Umbraco features, its properly underused due to the lack of formal documentation - so thanks for filling the gap!


Anthony Candaele Avatar

Thanks a lot Dan,

Thanks to your excellent blogpost I could use the Client Dependency Framework in my an Umbraco website in less than 15 minutes.

greetings,

Anthony


John Walker Avatar

Hi Dan,

Great post. I had previously been using Chirpy to minify files, without realisizing this could already been done using the built in ClientDependancy Framework, I will definitely give this a go on my next project. To resolve the cache issue possibly adding a querystring to the file names such as ?v=1.01 then just upping that when you push amends may force the browser to download a new version not sure how the ClientDependancy Framework will handle that though.

John


Robert Avatar

Hoping the author still watches this post. I added the code exactly as you wrote above. When I reload the site I get a standard IIS error: Parser error: Exception message: Unknown server tag 'CD:ClientDependency'. Thoughts?


Dan Diplo Avatar

Robert, I do still watch :) However, this is an old post and only relevant to Umbraco 4 when using masterpages. If you are using a newer version of Umbraco check out github.com/Shazwazza/ClientDependency/wiki instead.

Just fill in the form and click Submit. But note all comments are moderated, so spare the viagra spam!

Tip: You can use Markdown syntax within comments.