Time for action – creating a combined build

There are a few steps we need to take to create a combined build. These are as follows:

First, we will remove our JavaScript code from the HTML page and create a separate file for it. Go ahead and copy the contents of the <script> tag that contains all the JavaScript code into a file and save it as flickr_combined.js. You can, of course, call it something different but the remainder of this example will refer to it by this name. If you choose a different name, make sure to change all the references appropriately.
Now, delete the JavaScript and the script tag from your HTML file. At this point, we can create a new <script> tag to load flickr_combined.js and everything should work as before. If you want to try this, go ahead but remember to remove the script tag afterwards. We won't be using flickr_combined.js directly.
In order for the closure compiler to find the exact parts of OpenLayers that our application needs, we need to tell it what parts we are using. The closure compiler then removes any code we won't need and produces an optimal build. When creating an all-in-one build, the mechanism for doing this is to add goog.require statements to our JavaScript file. Let's go ahead and do that now. Add the following at the top of your flickr_combined.js file:
```
goog.require('ol.Feature');
goog.require('ol.geom.Point');
goog.require('ol.interaction.Select');
goog.require('ol.layer.Tile');
goog.require('ol.layer.Vector');
goog.require('ol.Map');
goog.require('ol.proj');
goog.require('ol.source.OSM');
goog.require('ol.source.Vector');
goog.require('ol.style.Icon');
goog.require('ol.View');
```
If you are using the ol-debug.js build of OpenLayers, then this change will continue to work. If you are using ol.js, however, it will not work as the goog namespace is not exported in the optimized build of OpenLayers.
The OpenLayers build tool runs inside the OpenLayers directory. The easiest way for OpenLayers to find your code is to copy it into the ol3 directory. Go ahead and copy flickr_combined.js into the ol3/build directory now.

Next, we need to create a configuration file that is used by the build tool to control what the Closure Compiler does. Create a file called flickr_combined.json file within the ol3/build directory and give it the following content. We'll go over the parts of this file afterwards:

{
  "exports": [],
  "src": ["src/**/*.js", "build/flickr_combined.js "],
  "compile": {
    "externs": [
      "externs/closure-compiler.js",
      "externs/geojson.js",
      "externs/jquery-1.7.js",
      "externs/oli.js",
      "externs/olx.js",
      "externs/proj4js.js",
      "externs/vbarray.js"
    ],
    "define": [
      "goog.dom.ASSUME_STANDARDS_MODE=true",
      "goog.DEBUG=false"
    ],
    "jscomp_error": [
      "accessControls",
      "ambiguousFunctionDecl",
      "checkEventfulObjectDisposal",
      "checkRegExp",
      "checkStructDictInheritance",
      "checkTypes",
      "checkVars",
      "const",
      "constantProperty",
      "deprecated",
      "duplicateMessage",
      "es3",
      "es5Strict",
      "externsValidation",
      "fileoverviewTags",
      "globalThis",
      "internetExplorerChecks",
      "invalidCasts",
      "misplacedTypeAnnotation",
      "missingGetCssName",
      "missingProperties",
      "missingProvide",
      "missingRequire",
      "missingReturn",
      "newCheckTypes",
      "nonStandardJsDocs",
      "suspiciousCode",
      "strictModuleDepCheck",
      "typeInvalidation",
      "undefinedNames",
      "undefinedVars",
      "unknownDefines",
      "uselessCode",
      "visibility"
    ],
    "extra_annotation_name": [
      "api", "observable"
    ],
    "compilation_level": "ADVANCED",
    "output_wrapper": "// OpenLayers 3. See http://ol3.js.org/\n(function(){%output%})();",
    "use_types_for_optimization": true,
    "manage_closure_dependencies": true
  }
}

Now, we have the parts we need to build our combined file. Open a command prompt or terminal and change to the ol3 directory. Execute the following command:
```
node tasks/build.js build/flickr_combined.json build/flickr_combined.built.jsgit status
```
Copy the resulting file named flickr_combined.built.js back into the working directory of your application code.
Change the <script> tag that loads the ol-debug.js script to point to the new JavaScript file, for instance:
```
<script src="flickr_combined.built.js"></script>
```
Reload your application page and everything should still be working.

What just happened?

We created a custom build of OpenLayers combined with our application code using the provided build tools. We'll review the steps but first, let's take a look at the resulting file sizes:

	Files Used	Net Size
Before (debug build)	`ol-debug.js` (3.3 MB) `flickr_combined.js` (3.7 KB)	3.3 MB
Before (optimized build)	`ol.js` (382 KB) `flickr_combined.js` (3.7 KB)	385.7 KB
After	`flickr_combined.built.js` (153 KB)	153 KB

Files Used

Net Size

Before (debug build)

ol-debug.js (3.3 MB)

flickr_combined.js (3.7 KB)

3.3 MB

Before (optimized build)

ol.js (382 KB)

flickr_combined.js (3.7 KB)

385.7 KB

After

flickr_combined.built.js (153 KB)

153 KB

As you can see, our final built file is less than half the size of the full OpenLayers build. Okay, now let's review how we did it.

For the OpenLayers build tools to work, they need our application's JavaScript and a configuration file. We first extracted the JavaScript from our HTML into a separate file, then added some extra lines of code to help the Closure compiler understand what parts of OpenLayers we use by adding goog.require statements. Figuring out what you are using from OpenLayers can be a bit tricky in larger applications, but using searching for ol. (that's ol followed by a period) will identify the correct things.

The next step, was to create a configuration file for the build tool. This configuration file is written in the JSON format, which looks a lot like JavaScript. The configuration file has several parts to it:

exports: This identifies specific objects and methods in the OpenLayers library that should not be renamed when creating an optimized build. We'll see how this works in the next example, but for this example, we left it empty because we are combining our application code with OpenLayers.
src: This identifies all the source JavaScript files that the compiler should consider when creating the optimized build. We say consider because not all the code will be included in the output. In our configuration file, we can specify the path to the OpenLayers source files (src/**/*.js) and our application file (build/flickr_combined.js).
compile: This contains directives specific to the Closure compiler. Modifying this section requires advanced knowledge of the Closure compiler and we won't be covering it in this book. It is normally sufficient just to copy this section to each new configuration file that you create. The one exception is the externs array. The externs array identifies files that contain type hints for the closure compiler. If you are using a third-party library in your application code, you will need to provide an externs file for that library to prevent the compiler from renaming function and property names in your code. For instance, we are using jQuery with our application and have included the jQuery-1.7.js externs file provided with OpenLayers. Externs for other libraries can be found at https://github.com/google/closure-compiler/tree/master/contrib/externs.

With our application code prepared and a configuration file, we then run the command-line build tool providing it the name of the configuration file and the name of the JavaScript file to create:

node tasks/build.js build/flicker_combined.json build/flickr_combined.built.js

We then copied the resulting file, flickr_combined.built.js, back into our application folder and updated the script tag to load this file instead of ol-debug.js. The net result is an impressive drop in file size and the elimination of one JavaScript file to load.

Note

In large applications, it is not uncommon to have your JavaScript code separated out into different files based on some logical breakdown of the code. OpenLayers, for instance, has 330 separate JavaScript files. When you have a lot of different files, the net effect of combining them all into a single file is much more apparent to the user.

Previous Chapter

Creating a combined build

Next Chapter

Creating a separate build

Table of Contents for OpenLayers 3 : Beginner's Guide

Time for action – creating a combined build

What just happened?

Note

Table of Contents for
OpenLayers 3 : Beginner's Guide