Peter Robins, his website

Class structure

Because JS was originally intended for small-scale use in browsers, it has little formal structure in the way that most programmers are familiar with from other object-oriented languages. There is no class structure and, though any function can serve as a template for instantiating objects, there's no real way of distinguishing these from any other function (apart possibly from use of the 'this' keyword). Although you can cater for inheritance via the protocol property and the apply() method, there's no real structure to this either, as there's no way of knowing which objects inherit from which others.

OL is quite a large system, and so needs a formal structure so people can find their way around it easily. This it provides through its own simple class and inheritance system, which you will find in BaseTypes/Class.js. You don't need to know exactly what this is doing; all you need to do is use it as indicated in the documentation at the top:

MyClass = OpenLayers.Class(Class1, Class2, prototype);

i.e. MyClass inherits from Class1 and Class2. In the Class() function, you will see references to the initialize() method, which is the constructor function run when the object is instantiated.

For an example, see Layer/Google.js, which you can see inherits from 2 classes, EventPane and FixedZoomLevels. If you scroll down to the initialize() function, you can see that it applies the arguments to the prototype property of the parent class(es). You will find this structure throughout OL, and you can extend OL classes in your own programs using it.

Each Class object has a final property CLASS_NAME, e.g.

CLASS_NAME: "OpenLayers.Strategy.Fixed"

Note that the class structure is planned for removal in version 3.

Objects

A feature of JS that's not always appreciated is that there are 2 basic types of object. First, the instantiated object created from a function template; and second, a 'hash' object of key:value pairs. I have seen the latter described as 'static objects' but, whilst they are static in the sense of not being instantiated, they are not static in the usual meaning of 'unchanging' as you can change them whenever you please.

As instantiated objects in OL are created from classes, the documentation in OL's classes denotes them by <OpenLayers.classname>; so, for example, in Layer.js, the 'map' property is an <OpenLayers.Map> object/instance. The 'options' property (see below), on the other hand, is a hash object, shown as {Object}. This can be somewhat confusing. A StyleMap for example is a hash of Style instances, each one composed of a symbolizer hash object. If you look at StyleMap.js, you will see that the constructor initialize() can be passed a style hash or a OpenLayers.Style object or for that matter a mix of the two.

Options object

Generally, when you instantiate one of OL's classes, you pass an options (hash) object in as a parameter. A common question from beginners is 'what are the options?', but there's no simple answer to this. It's generally used for setting the object properties pre-defined in the class, but you can really change or set any property you please. Unlike some rigidly defined languages, JS has no requirement to use accessor methods (getters and setters), and you can change a property in a hash object by simply setting it:

myobj.newproperty = 'newvalue';

If you include this in your options object:

var options = {newproperty: newvalue}

newproperty will be set on the new instance. This can be an existing property or a new one of your own invention. You can also supply a function to set a method in that instance.

Altering a class method

Normally, though, if you want to change a class method, you change the class object prototype so it is applied to all instances of that class. For example, if you insert:

OpenLayers.Control.KeyboardDefaults.prototype.defaultKeyPress = function ...

at the top of your application (i.e. after the OL file as loaded but before your code runs), then that will override the defaultKeyPress method of OpenLayers.Control.KeyboardDefaults for any instances of that control. You can use this technique for example to tailor a method or as a patch to correct a bug that is affecting your application but has not yet been incorporated in the official release.

API properties and methods

If you look through a class source file, you will see that in the documentation for each property, some are labeled 'APIProperty' and some 'Property'; similarly, methods are labeled 'APIMethod' or 'Method'. This is intended as a sort of private/public; those marked 'APIProperty' or 'APIMethod' are public, whereas those without the 'API' are private. In practice, of course, there's no real difference, but those marked 'API' are intended as being a fixed part of the class, continuing to be present in future versions, whereas those not 'API' may change or be removed at some point in the future. It must be said, though, that implementation of this is not always consistent in all classes.