Introduction to Google’s Closure Tools

I’ve recently been looking into Google’s Closure Tools, I thought I’d firstly post a simple tutorial on how the library works, what it is, how to set it up and provide a simple project. This tutorial isn’t designed to replace the excellent Getting Started Tutorial already provided by Google, but serves as the first part of a 3 closure tutorials I’m going to write.

The second tutorial will be about how to use Google Closure Tools in an automated environment, and describe how to use ANT to automate Javascript compilation and dependancy files. The third will describe how to use google closure in a real world application, we’ll build a simple application utilising only google closure tools.

You may be asking, another JavaScript library? What’s the point? Years ago, (around 2002) I wrote a pretty large DHTML (as it was known then) search engine for a client using only native javascript, it was a nightmare, the code was ugly, and the sheer amount of exceptions and conditionals that were required to make it work across multiple browsers was simply staggering.

Frameworks finally provided us with the needed unification of these browsers, we could now use one line of code to add and event listener, another 1 line to remove it, manipulate the DOM or perform Async requests. In short frameworks for Javascript are a god send. I started off using Prototype, and moved onto MooTools before finally (like many other developers) settling on JQuery as my framework of choice. However, I’m from a Java, AS3, and PHP background, and JavaScript projects with JQuery are just plain messy, and almost impossible to keep organised.

Now, I’m not saying JQuery is a bad framework, in fact I think it’s a tour-de-force of what can be achieved using JavaScript and the web has become a better place for it (when used properly). However, JQuery through solving loads of problems with Javascript still doesn’t solve the fundamental issue with JavaScript: Scalability, Team Management and Reusability.

When working on large javascript applications in large teams, using JQuery becomes hard if not impossible to manage, and the only way to work is either to keep the JavaScript modular and insert it on a page by page basis, have millions of includes for different scripts and packages, or ditch it all together and go for some Dojo / JQuery hybrid.

Enter Google Closure; Closure provides a set of tools, libraries and compilers which allow JavaScript to be developed in a proper Object-Orientated style, you can now split projects up into packages, compile this code into a flat singular file. Also, with the inclusion of a proper coding linter, you can even error-check and debug your JavaScript against Google Standards. This makes for not only easy to manage projects, but generally better code in the long run, it also helps developers iron out those easy to make mistakes.

The two main draws for using Google closure for me are code organisation and the ability to ‘Compile’ Javascript. Closure Compiler traverses the whole tree of your JavaScript project and compounds the code into a single file, this file will include all of your code, that has been minified and obfuscation and also includes all of the google closure code that you reference. This means in a production site you can basically include one single Javascript file that represents your whole project.

Google Closure is used in pretty much all of google’s major products including Gmail, Calendar and Contacts, so it’s definitely been tested and used in the real world.

So for the uninitiated Closure tools is a tools set consisting of 4 major components :

1. Closure Library – A javascript library with strict object typing and general javascript cross-browser functionality, it provides all the features of other libraries like JQuery, Prototype or MooTools with the Object and Dependancy management of libraries such as Dojo. The closure library is server agnostic, and is designed to work with the Closure Compile, the closure library is provided with a set of Python scripts which help in automating certain parts of the closure library.
2. Closure Compiler – A java based compiler, that minifies and obfuscates Javascript sources files into a single source. The compiler also traverses the natural path of the Javascript logic, and only includes the relevant sources that are needed for the application. This greatly reduces the need for multiple requests, and removes any unused code from the full project.
3. Closure Templates- A full HTML c engine for use with closure compiler, the templating engine uses a standard syntax, and generates native Javascript source files, making it easier to write complex Dom structures in a JavaScript application.
4. Closure Linter- A style checker and code fixer that checks and offers up improvements, warnings and errors that it finds in the code.

In this tutorial I’ll briefly explain how to create simple Closure application, and explain the way I like to organise my code in projects. We’ll then look at creating packages and classes, how to use google’s automated dependancy management, and finally execute closure compiler on our project to create a single Javascript source file that we can use for production and release environments.

The Project

So the first step is to create folder structure, I like to organise my projects in the following structure:

• bin - The final destination of the compiled site, I use this folder as a place to keep the latest stable version of the fully compiled source and site (more on this in the next tutorial)
• lib - The lib folder is where I store all the external libraries I’m using that do not need
  to be included in the final product, it’s here I extract the closure tools and closure library.
• src - The src folder (and the focus of this tutorial) is where I add all the source files for this project.

In the source folder (src) I create 2 folders js_uncompiled (for my raw uncompiled source) and js (for the compiled source).

Now on with the tutorial:

So the first step is to create the folder structure mentioned above, and load up your favourite text editor.

The Closure Tools

Next if you haven’t already you’ll need to get the closure tools, you can grab these from SVN by executing the following command in your terminal or command prompt.

svn checkout http://closure-library.googlecode.com/svn/trunk/ closure-library

Execute this command in the your usual libs or sdks directory where you keep other libraries and sdks, if like me you’re not a fan of all the SVN junk that comes down, and just want a clean set of files for usage in your project, you can export the closure library instead:

svn export http://closure-library.googlecode.com/svn/trunk/ closure-library

Once svn has finished exporting (or checking out) the files you should have the following folder and files:

The next thing to do is copy these files into your libs directory in your project structure that we created previously.

Creating the First Class

Next we’ll create our first Closure class, I like to create a single init class that I can use to initialise the rest of my application. This makes it easier to give closure a single entry point, Google seem to recommend this method as well, and it works well when building larger projects.

So lets create a file in the js_uncompiled directory called init.js, the source for this file is as follows :

	goog.provide('closureexample.init');
	goog.require('goog.dom');

	closureexample.init = function( appTitle, parent ){
		var header =  {'style':'background:#FF0000'};
		var content = "Application " + appTitle + " Starting"
		var element = goog.dom.createDom( 'div', header, content );
		goog.dom.appendChild( parent, element );
	};

This class basically takes 2 parameters, a string variable and a dom element, it then creates a div element with a red background and appends the text : “Application App Title Starting” and then adds this to the provided dom element.

Now for a line by line explanation :

 goog.provide('closureexample.init'); 

This creates an object for us called ‘closureexample.init’. This declaration can be for an object or just a function (remember in JavaScript functions are objects).

 goog.require('goog.dom'); 

This is a dependancy call and calls the closure library and requests access to the class ‘goog.dom’, the goog.dom class provides an interface for interacting with the Document Object, and allows us to inject and manipulate HTML on the page.

 closureexample.init = function( appTitle, parent ){}; 

This declares the result of the closureexample.init object (or function) that was created, we store in this variable a function, and pass in 2 parameters, the application title, and a parent div for us to insert the content.

var header =  {'style':'background:#FF0000'};
var content = "Application " + appTitle + " Starting"
var element = goog.dom.createDom( 'div', header, content );

In these 3 lines we create the dom element that will be inserted, the static function goog.dom.createDom accepts 3 arguments : the tag of the element to create, any header parameters and the innerHTML content to insert. Here we create the content string using the passed in appTitle variable, and we add the style attribute and set a style value of background to red.

 goog.dom.appendChild( parent, element ); 

The goog.dom.appendChild function takes 2 arguments, the parent element and the element to append. In this line we append the created element to the parent element provided as a parameter to the init function.

Loading the Framework and Using the First Class

Now it’s time to use this class. Create a index.html file in the src directory with the following source code :

<!DOCTYPE html>
<html>
	<head>
		<title>Closure Test</title>
		<script type="text/javascript" src="../lib/closure/goog/base.js"></script>
		<script type="text/javascript" src="js_uncompiled/init.js"></script>
	</head>
	<body>
		<div id="main"></div>
		<script type="text/javascript">
			closureexample.init( 'Test', document.getElementById('main') );
		</script>
	</body>
</html>

I’m not going to line by line on this one, as it’s mostly HTML, but the most important parts are firstly the imports :

<script type="text/javascript" src="../lib/closure/goog/base.js"></script>
<script type="text/javascript" src="js_uncompiled/init.js"></script>

The important thing here is that we firstly include the Closure base, and then our class. Remember: This is only the debug version, once we compile the code we will only need to include the compiled code, and not the whole closure library. Google Closure only needs to add these 2 files and will automatically insert all the other needed files.

closureexample.init( 'Test', document.getElementById('main') );

The secondly this line, which calls our previously created file, and passes in the App Title ‘Test’ and a reference to a div with the ID ‘main’.

Testing the Code

So now it’s time to run the code, navigate to the URL on your local (or remote system) where you’ve stored the html file and you should see the following on you’re screen :

Using chrome’s debugger console, you can see that the Closure Library has injected a bunch more files into the DOM:

Adding a Class

So now it’s time to create our first Google Closure class, I like to use package structure similar to the way google lay out their code, so lets firstly create a package folder and call it foo.

Then lets create a new javascript source file and call it bar.js.

Your file structure should look like this now :

Now for the file itself :

goog.provide('closureexample.foo.Bar');
goog.require('goog.dom');
/**
* @constructor
*/
closureexample.foo.Bar = function( parent ){
	this.parent = parent;
}

closureexample.foo.Bar.prototype.showContent = function(){
	var element = goog.dom.createDom( 'div', {'style':'background:#FFFF00'}, "This was created in the Bar class" );
	goog.dom.appendChild( this.parent, element );
}

Lets look at this line by line :

goog.provide('closureexample.foo.Bar');
goog.require('goog.dom');

The first line tells the closure library to create our class, in this example the class is called ‘closureexample.foo.Bar’. We also use the goog.require library to gain access to the goog.dom package which we can use for DOM manipulation.

/**
* @constructor
*/
closureexample.foo.Bar = function( parent ){
	this.parent = parent;
}

In these lines we create our constructor, we assign a function object with a parent variable (which we’ll use for inserting HTML into the DOM object). We also must include the @constructor parameter in the block comments, this notifies the Closure Linter that this is a constructor, without this tag the Closure Linter will throw an error because of our unsafe usage of the ‘this’ keyword.

closureexample.foo.Bar.prototype.showContent = function(){
	var element = goog.dom.createDom( 'div', {'style':'background:#FFFF00'}, "This was created in the Bar class" );
	goog.dom.appendChild( this.parent, element );
}

In these lines we declare a function ‘showContent’ this function just appends the text “This was created in the Bar class” to the parent element passed into the constructor. We create the function by using the class.prototype.function javascript paradigm and assign a function object to it.

Using the Class

We’ll now go back to our original init.js file and edit it so we can utilise our newly created class, the new source code is as follows :

goog.provide('closureexample.init');
goog.require('goog.dom');
goog.require('closureexample.foo.Bar');

closureexample.init = function( appTitle, parent ){
	var header =  {'style':'background:#FF0000'};
	var content = "Application " + appTitle + " Starting"
	var element = goog.dom.createDom( 'div', header, content );
	goog.dom.appendChild( parent, element );

	var bar = new closureexample.foo.Bar(parent);
	bar.showContent();
};

The first line we needed to add was:

goog.require('closureexample.foo.Bar');

This tells the google closure library to load our class, allow us to create and instantiate an object from the loaded class:

var bar = new closureexample.foo.Bar(parent);
bar.showContent();

Here we create a new object from our class, and store in in the bar variable, we then call the ‘showContent’ function we created earlier.

Dependancy Management

You may notice if you try and run index.html presently you’ll get a few errors :

Chrome states that it could not find the class ‘closureexample.foo.Bar’ and this breaks our closureexample.init object.

The reason for this is the closure library does not know where our class is, now you could add the following above your init.js import statement in index.html (you’ll need to add it above because init.js requires it before it can function) :

<script type="text/javascript" src="js_uncompiled/foo/bar.js"></script>

However, imagine if you had a multi-class package structure, ensuring that all the import statements are in order would be a mammoth task and would basically negate the point in using the library.

This is where the google dependancy writer comes in. The dependancy writer script traverses a given javascript application and figures out which files are needed by the application as a whole, it then creates a new javascript file and when you import this file it subsequently imports all the other files for you, and works out the appropriate order of importing so you don’t have to.

Let’s create that file now, if you added the script tag to the class above your init.js script tag remove it now. You’ll find the the deps writer in the following directory “closure/bin/build/depswriter.py” as we already imported the closure library into our project you should be able to execute this quite easily by executing the following command (replacing %your_project% with your actual project directory) :

cd %your_project%
./lib/closure/bin/build/depswriter.py \
--root_with_prefix="src ../../../src" \
--output_file=src/js_uncompiled/deps.js

The python script takes two arguments, firstly the directory to scan for our application and root prefix to attach to our files (this lets closure know where our files are in relation to the closure tools, in this case it’s 3 directories down and one up to src), the second is the file name to output the dependancy file information (if you don’t provide this argument the dependancies are printed to screen). If you get a permissions error, you might need to allow your current terminal user to execute the depswriter.py executable. Do this by executing the following on your directory :

chmod 755 lib/closure/bin/build/*

After you’ve executed this command you should now see a deps.js file has been created in the ‘js/js_uncompiled/’ directory, it should look something like this:

// This file was autogenerated by ./lib/closure/bin/build/depswriter.py.
// Please do not edit.
goog.addDependency('../../../src/js_uncompiled/foo/bar.js', ['closureexample.foo.Bar'], ['goog.dom']);
goog.addDependency('../../../src/js_uncompiled/init.js', ['closureexample.init'], ['closureexample.foo.Bar', 'goog.dom']);

Now all we have to do is add the following JavaScript import to our index.html file above the line where we import our initial initialisation class:

<script type="text/javascript" src="js_uncompiled/deps.js"></script>

When running the file you should now see the following two messages :

That’s about it, as you can see Closure provides a powerful way to manage dependancies and as you create more classes and utilise these methods you’ll see you can create vastly complex applications and only import the bare minimum of files into your project.

But what about compiling?

Compiling the Code

The closure library has one more major trick up it’s sleeve: The Closure Compiler, this compiles all of the source code for our project into one easily distributable file. The final file is small, obstructed and has no other dependancies, and doesn’t load any other files than itself. Google does this by traversing your application (in our example init.js and the underlying structure) and calculates all of the dependancies, finally a file is created that only includes the code required by the application as a whole. The upshot of this is your final application is as small as it can possibly be, and you don’t need to make the user load the whole framework every-time they visit your site. This modular aspect is what I think the main draw of using Google Closure in your projects.

As we saw in the dependacy file our application only really makes use of the Bar class, init class and the goog.dom class. In fact it only really makes use of the goog.dom.createDom and goog.dom.appendChild functions. Closure compiler will figure this out, and only include the source for the classes we’ve used and the goog.dom functions we utilised not the whole goog.dom package.

Firstly you’ll need to get the closure compiler.jar file, you can grab it from this URL: http://closure-compiler.googlecode.com/files/compiler-latest.zip drop this java archive file into your project ‘/libs’ directory.

Now we’re ready to compile the code. To use the compiler you can call arguments on the compiler.jar file, or you can use the closure builder helper script located at ‘/lib/closure/bin/build/closurebuilder.py’. The compile function is quite a big one! Execute the following commands in your terminal (again replacing %your_project% with your actual project directory):

note: don’t close your terminal after you’ve run the command as you’ll need to run this again in a minute:

cd %your_project%
./lib/closure/bin/build/closurebuilder.py \
--root=lib/closure/ \
--root=lib/third_party/ \
--root=src/js_uncompiled \
--namespace=closureexample.init \
--output_mode=compiled \
--compiler_jar=lib/compiler.jar \
--compiler_flags=--compilation_level=ADVANCED_OPTIMIZATIONS \
--output_file=src/js/example.js

I’d recommend checking out the google closure docs for more info about this command but here’s a brief explanation of the arguments :

• –root= Adds a library for google closure compiler to scan (you need to add the actual closure and third_party libraries as well as your own source directory)
• –namespace= Adds the namespace of the project class that google closure can start to scan for dependancies and decide which files to include (you can add more than one)
• –output_mode= Sets the output mode to ‘compiled’ the other this tells the closure builder to create a single compiled file. Other options are ‘list’ for a list of files, and ‘script’ for all the scripts simply combined and not compiled.
• –compiler_jar= A link to the Java file we downloaded earler
• –compiler_flags= Allows us to set compiler flags to be passed to the closure compiler, we’ve passed through ADVANCED_OPTIMIZATION which will obfuscate and minimise our code to the maximum level closure compiler provides.
• –output_flat= The output file name for our compiled file.

After executing this command you should now have a fully compiled file which you’ll find in the ‘src/js/’ directory named ‘example.js’. We should now test this file by importing it into our index.html file, because this file is a complete implementation of our full we can also remove (or comment out) the old source tags as they are no longer needed. The new index.html code is as follows:

<!DOCTYPE html>
<html>
	<head>
		<title>Closure Test</title>
		<!-- Uncompiled
		<script type="text/javascript" src="../lib/closure/goog/base.js"></script>
		<script type="text/javascript" src="js_uncompiled/deps.js"></script>
		<script type="text/javascript" src="js_uncompiled/init.js"></script>
		-->
		<script type="text/javascript" src="js/example.js"></script>
	</head>
	<body>
		<div id="main">
		<script type="text/javascript">
			closureexample.init( 'Test', document.getElementById('main') );
		</script>
	</body>
</html>

If you run this now, you may noticed that it now claims that closureexample is missing.

If you look at the example.js file outputted by the closure compiler you’ll see the compiler has not only removed all non-dependant code but has also replaced and renamed all of the classes and functions to smaller names (i.e var c=this.function), this is great for speed and reliability, but doesn’t help us if we want to refer to a class by name. As we need to be able to call our initial function via it’s normal name ‘closureexample.init’ we have to somehow tell Closure compiler to keep this name and not rename it.

Luckily for us the closure library provides such a mechanism, add the following line to the bottom of init.js :

goog.exportSymbol('closureexample.init', closureexample.init);

This notify the closure library that we want this symbol retained after compilation. You now need to re-run the closure compiler function mentioned above to recompile your source.

If you now refresh your page you should see the same result before, but as you can see this whole project including all of the source code is not being delivered via one simple small file :

Next Steps

So that’s the end of this tutorial, in the next tutorial I’ll be showing you how I automate this whole proces using Apache ANT and Eclipse, so you don’t have to constantly type these commands or create the files, then after that we’ll create an application that actually does something using the closure tools.

Here’s the completed project in case you need it: Tutorial Files

I’d recommend experimenting with the code base, creating a few more classes and start to play with some of the libraries Google Closure provides (no pun intended). Let me know what you think of Google Closure.

Till next time