OpenLayers is a powerful open source JavaScript client that is often used to create AJAX "slippy" maps in an open source stack (see our previous technical overview). OpenLayers supports a wide range of data sources, layer types, and languages; and this list keeps growing with each release. Unfortunately this constant growth has a downside: the standard JavaScript file is now 711K in size!

This article shows you how to make your OpenLayers map applications more efficient by drastically reducing the size of this script file.

In the two years since I started to use OpenLayers, it has doubled in size to 711K (version 2.8). This growth has been due to the addition of a growing number of data sources, layer types, standard controls, and languages. These are all useful things which increase the utility of OpenLayers, but they also result in code bloat. Few if any applications use more than a small number of the available features. Of course each application uses a different subset of features! Would it not be great if we could cut OpenLayers.js down to just include the features that we require? We can, by using the build scripts which are provided with OpenLayers.

The standard OpenLayers package can be downloaded from the main OpenLayers website. In addition to the main OpenLayers.js script, this package includes a complete set of component scripts and a build environment. We shall use the scripts in this build environment to create a custom OpenLayers.js with just the support that we require. The following examples assume you are working with OpenLayers v2.8. You may need to change the exact directory names to match the version you are using.

Make sure you also have Python installed because this is used by the main build script. You will also need to use a command line environment. The Windows command prompt should be usable, but I used FreeBSD (as used by my web host).

Download and uncompress the latest version of OpenLayers. Navigate to the OpenLayers root directory (~/OpenLayers-2.8 in this example). Note that this directory holds the standard build of OpenLayers.js along with auxiliary files (eg. the standard theme). It also holds other directories that you might find useful, such as the documentation and source components. We are interested in the build sub-directory. Navigate to this. You will see a number of explanatory text file notes, three cfg configuration files, and two Python scripts called build.py and buildUncompressed.py. These simply build a new OpenLayers.js using a particular configuration file. Normally, you will use build.py which compresses the final output, but buildUncompressed.py might be useful if you wish to edit or otherwise amend the resulting script.

Running the script is very simple. In a Unix-like shell, simply run "./build.py yourconfig.cfg" where yourconfig.cfg is the name of the configuration file to use. The script takes a few seconds to run, and provides a list of the included components, and further components that are required by these. The resulting OpenLayers.js is written to the build directory.

Three standard configurations ship with OpenLayers:

• full.cfg : This is the full build with all file components.
• lite.cfg : A small subset of OpenLayers, designed for integration into other applications. Supports WMS, but excludes all of the standard controls.
• library.cfg : Includes everything except for vector support.

You will probably want to create your own configuration file. Here is the one I created for the OpenLayers/MapServer map at EcoMapCostaRica.com:

Comment lines start with a '#' character. This configuration file is split into groups: first, last, include, and exclude. We only use the first and exclude sections. The first section includes all of the core components. We then switch individual components off with the exclude section. All of the non-English language support is excluded because the parent website currently only uses English.

Our exclude section is probably a lot larger than it needs to be. OpenLayers contains a lot of components and their inter-dependencies are often complex. Many of the component names are easy to understand (eg. OpenLayers/Layer/WMS.js provides WMS layer support), but it is harder to determine if many are required. I therefore used a trial-and-error approach excluding about half a dozen components at a time, and checking that the resulting build worked in the final application. Many of the excluded components are actually included because other essential components require on them. The output from build.py was useful in identifying possible components to exclude.

And the result? The final OpenLayers.js has shrunk more than 50% from 711KB to 343KB. This will reduce the website bandwidth requirements, but more importantly, it will result in a web map that loads and becomes active more quickly for the end user.

A similar process was applied to Equal-Area-Maps.com (URL), but GeoRSS layer support was included and Vector layer support was excluded.

The trial-and-error approach to building a configuration file that produces a minimal but usable OpenLayers.js, is time consuming to say the least. Tom MacWright is in the process of solving this with his OpenLayerer online build tool. Simply select the checkboxes for the required components, press the Generate button, and an OpenLayers.js script is ready for download. I tried using this, but I was not able to produce a usable OpenLayers.js script for my online maps. It would appear that OpenLayerer automatically excludes some rendering components: I was not able to use the OpenLayers.js script even with all checkboxes checked. So a "work in progress" but something which should make the process of creating small, efficient OpenLayers scripts a lot quicker and easier.

Comments (3)

Subscribe to this comment's feed

HTTP compression
written by -, October 05, 2009

How about enabling HTTP compression? That should reduce the needed bandwidth by about 90%.

• 
• +0
• 
• 

Use include instead of exclude
written by Paul Spencer, October 05, 2009

If you are going for a minimalist build, try using include to keep the things you know you want rather than exclude the things you don't. The advantages are that the list will (probably) be shorter, you know you have what you just what you need plus dependencies, and you don't need to change when updating to a newer version that has new things to be excluded.

• 
• +0
• 
• 

Thanks for the suggestions
written by Richard Marsden, October 06, 2009

Thanks for the suggestions. If anyone has any recommendations for speeding OpenLayers, then feel free to add them to this thread.

"Anonymous": Good idea. Also the build script does "compress" the Javascript by removing all pretty printing. HTTP compression would cut this further, and also speed many of the data downloads (eg. KML).

Paul: Yes in theory this is a much better approach. However, when starting from scratch it is difficult to know exactly which components are required. Some are obvious (eg. I needed the GML layer support for KML) but others are not, so a trial&error approach is still required. The [first] section would also have to be cut back, and it would be a case of adding lots of things until it works. It is easier to start with something that works, rather than to try to keep adding things until it does.

Perhaps the output from my build script could be used as a basis of a script along the lines that you describe. The end result would then be the more stable build (as you describe).

• 
• +1
• 
• 

Name

Email

Website

Title

Comment

smaller | bigger

Subscribe via email (Registered users only)

I have read and agree to the Terms of Usage.

Write the displayed characters

Add Comment