My favorites ▼ | English ▼ | Sign in

Closure Library

Getting Started with the Closure Library

This Hello World exercise introduces the process of using the Closure Library in a web page. To do this exercise you need to have some familiarity with JavaScript, as well as a Subversion client. You may already have a Subversion client. You can tell whether you have a Subversion client by trying to execute the command in step 1.

Hello Closure

To get started with the Closure Library, use Closure JavaScript functions in a simple web page by following these steps:

Step 1: Download the Closure Library

Download the Closure Library from the Subversion repository by executing the following command from the command line: 

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

You need a Subversion client to execute this command, but you may already have one. Try the command, and if it doesn't work download and install a Subversion client.

After executing this command you should have a directory named closure-library that contains the Closure Library code.

Step 2: Create a JavaScript file that uses the Closure Library

Save the following JavaScript in a file called hello.js. Place this file next to the closure-library directory. 

goog.require('goog.dom');

function sayHi() {
  var newHeader = goog.dom.createDom('h1', {'style': 'background-color:#EEE'},
    'Hello world!');
  goog.dom.appendChild(document.body, newHeader);
}

Step 3: Create an HTML file

Save the following HTML in a file called hello.html. Place this file next to the closure-library directory and the hello.js file. 

<html>
  <head>
    <script src="closure-library/closure/goog/base.js"></script>
    <script src="hello.js"></script>
  </head>
  <body onload="sayHi()">
  </body>
</html>

Step 4: Say Hello to the Closure Library

Open the HTML file in a browser. You should see the words "Hello world!":

How Does This Example Work?

The hello.js JavaScript uses two functions it doesn't define: goog.dom.createDom() and goog.dom.appendChild(). Where do these functions come from?

These functions are defined in the Closure Library that you downloaded in Step 1, in the file closure-library/dom/dom.js.

To make use of these functions, the example does two things:

  • It includes the statement goog.require('goog.dom') at the beginning of the JavaScript in Step 2.
  • It includes the Closure Library bootstrap file base.js in the HTML in Step 3.

The base.js file defines the function goog.require(). The function call goog.require('goog.dom') loads the JavaScript file that defines the functions in the goog.dom namespace, along with any other files from the Closure Library that those functions need.

The Closure Library loads these files by dynamically adding a script tag to the document for each needed Closure Library file. So, for example, the statement goog.require('goog.dom') causes the following tag to be added to the document, where path-to-closure is the path from the HTML file to the directory that contains base.js: 

<script src="path-to-closure/dom/dom.js"></script>

Typically a single goog.require() statement will load only a fraction of the Closure Library codebase.

Note: Do not put your goog.require() statements in the same script tag as the entry point to code that uses the goog.required functions or classes. A goog.require() call adds code to the document after the script tag containing the call. For example, this code works: 

<script src="closure-library/closure/goog/base.js"></script>
<script>
  goog.require('goog.dom');
</script>
<script>
  var newHeader = goog.dom.createDom('h1');
</script>

The goog.require() call adds the code for goog.dom.createDom() immediately before the script tag containing the line var newHeader = goog.dom.createDom('h1').

In contrast, the following code produces an error: 

<script src="closure-library/closure/goog/base.js"></script>
<script>
  // DON'T DO THIS.
  goog.require('goog.dom');
  var newHeader = goog.dom.createDom('h1');
</script>

This goog.require() call adds the code for goog.dom.createDom() in a script tag that won't be interpreted until after a call to goog.dom.createDom() has already been made.

Note that this restriction does not apply when you use the dependency calculation script.

Including base.js isn't the only way to include Closure Library code, but it is the easiest way to get started. No matter how you grab Closure Library code, however, you will always use goog.require() to declare the parts of the Closure Library that you need.

Next Steps

This example illustrates one way of getting just the parts of the Closure Library that you need: including base.js in your web page and calling its function goog.require().

The Closure Library also provides a tool for assembling just the parts of the library you need into a single JavaScript file. To find out more about this tool, read Using the Dependency Calculation Script.