Several weeks ago I gave an internal presentation to Azavea developers on the fundamentals of writing OpenLayers plugins.  I have modified that presentation to serve as a quick-start guide to writing your own plugins.

Understand JavaScript

OpenLayers is a JavaScript library.  If you do not have a sound understanding of JavaScript, do not pass Go and do not collect $200.  Instead, pick up Doug Crockford’s JavaScript: The Good Parts or Stoyan Stefanov’s Object-Oriented JavaScript.  Come back here when you’re done.  We’ll wait.

Check Out the Source

The OpenLayers source code is hosted in Subversion.  Check out the source to your development directory from:

http://svn.openlayers.org/trunk/openlayers/

Get Familiar with the Source

The most important thing you can do is invest some time familiarizing yourself with the JavaScript source code including the code structure, object inheritance, and components similar to the one you want to write.

Code Structure

OpenLayers is written to be object-oriented.  As such, the code is (mostly) structured such that the base objects are located in the root directory and any children of that object are in a sub-folder of the base object’s name. You can browse the source here.

Object Inheritance

OpenLayers object inheritance could be an article in and of itself, so we’ll just stick to the highlights.

All inheritance is done via the OpenLayers.Class function and supports multiple inheritance by augmenting any number of existing object definitions with your own object literal definition.  In real life, it looks like this:

OpenLayers.MyNewObj = OpenLayers.Class(OpenLayers.MyBaseObj, {
    prop1: 1,
    prop2: 2,
    doThis: function() {
        /* doing this */
    }
});

Check out the source code of OpenLayers.Class to really understand how OpenLayers implements object inheritance.

Dig Into a Component Similar to the One You Want to Write

Odds are that you are not setting out to write a completely unique component, but rather wish to build a specific implemention of something that already exists.  Most of my plugins have been tile-based layer plugins that get content from HTTP requests.  By looking through the examples, we know that OpenLayers already supports this type of functionality in OpenLayers.Layer.WMS and others.

We can discover what functionality OpenLayers already supports by digging into the WMS source code. Start by looking at the object definition and find its base object.  For example, the WMS layer extends OpenLayers.Layer.Grid.  The source for the base object will tell you which properties and functions you will have access to by default and if there are any functions you are required to override.  But don’t stop there!  Keep investigating base objects of the base objects until you get all the way up the chain.  For WMS, you will find OpenLayers.Layer.Grid, OpenLayers.Layer.HTTPRequest, and OpenLayers.Layer.  Understanding these objects will be invaluable when debugging.

Once you have an understanding of the base objects, and assuming they have the functionality you need, take another look at the WMS layer object.  Look at each property and try to understand why the author added it.  Also look at the functions.  Is it a new function?  Why was it added?  Is it an override? How is it different than the base functionality and why?  Answering these questions will enable you to pinpoint the functionality you will need to implement for your plugin.

Code!

You now know the way of the OpenLayers plugin, grasshopper.  Go and code.  But don’t forget the code conventions!