[OpenLayers-Users] How to obtain reference to map layer in 2.5????

[Christopher Schmidt]

On Tue, Apr 08, 2008 at 08:54:10AM -0400, Peter Len wrote:
> Paul,
> 
> Thanks for the reply.  That worked fine but my frustration with some of this is that the API (http://dev.openlayers.org/releases/OpenLayers-2.5/doc/apidocs/files/OpenLayers/Map-js.html) does not list a "layers" property for the map object.  How is someone suppose to know that it is available to use?

Peter,

In general, we take a very conservative position as to what is an API
property vs. what is not an API Property. The reason for this is that in
general, we have no specific ideas on how we might need to change the
code in the future to support a particular use case.

As an example:

In OpenLayers 2.5, we had controls which had multiple '.fooHandler'
properties. Things like 'zoomWheelHandler', etc. In 2.6, in order to
protect ourselves against memory leaks, we moved these handlers into a
'.handlers' object, with multiple keys ('foo', 'bar', 'baz'), so that
they could be automatically destroyed by the base control class, thus
ensuring that their DOM elements were properly decoupled from the
Javascript.

If we had made the .fooHandler property an API property, we wouldn't
have been able to make this change, and would have had to make a much
more significant change which was more fragile.

This is the case despite the fact that using handlers as an API property
is absolutely useful -- I use it in some of my own applications.

The lack of something being an API property does not mean "Absolutely do
not use it." It means "This may change in a future release of
OpenLayers: you should use it with caution."

For that reason, we include a full set of documentation of the *other* 
properties on objects:
http://dev.openlayers.org/releases/OpenLayers-2.5/doc/devdocs/files/OpenLayers/Map-js.html#OpenLayers.Map.layers
, in this particular case. 

If you are not comfortable with the fact that something is *not* an API
property, then the right thing to do is to make a proposal to the dev
list that it be made an API property.

In the case of map.layers, I have no problem making it an API property
upon being asked: the biggest reason we don't make things API properties
is so that people *will* ask, and we'll know what they're doing with it.

By doing this, for example, we were able to determine that what people
actually typically want is not direct access to the layers object
itself, but instead the ability to, for example, fetch a list of layers
by name. So OpenLayers 2.6 -- while keeping map.layers out of the API --
adds an OpenLayers.Map.getLayersBy() function, which allows for you to
get a layer by any property it has: for example:

  map.getLayersBy("name", "My WMS Layer");

Additionally, since getLayersByName seems a common use case, we have a
wrapper:

  map.getLayersByName("My WMS Layer");

Now, if we find out in the future we need to split layers into
.baseLayers and .overlayLayers for some reason, we can do so -- and we
haven't broken the API. Additionally, we've added functionality which is
common to more than one application, and I believe we've met most of the
needs that an application would have to loop through the layers
property, without exposing ourselves to possible holes in backwards
compatibility. 

This conservatism has served us well through many releases, and although
I understand that it may make life slightly more difficult, we do our
best to meet both sets of needs: those who need a very stable API
between versions can use the API properties, those who are willing to
take a bit more risk and do testing before upgrades to ensure their
application still works can do so, and the developers can make the
explicit decision to include things in the API as they become neccesary,
rather than simply by guessing what makes sense ahead of time.

Hopefully this helps to explain our policy such that it is reasonably
understandable without causing too much difficulty.

Best Regards,
-- 
Christopher Schmidt
MetaCarta