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

[Peter Len]

Christopher,

Thanks for info.  I definitely see where you are coming from and now that you have supplied me with a link to some docs that list non-API items, I am good.  At least now I can see what other things are available.

Thanks - Peter

-----Original Message-----
>From: Christopher Schmidt <crschmidt at metacarta.com>
>Sent: Apr 8, 2008 9:19 AM
>To: Peter Len <peteralen at earthlink.net>
>Cc: Paul Spencer <pagameba at gmail.com>, users at openlayers.org
>Subject: Re: [OpenLayers-Users] How to obtain reference to map layer in 2.5????
>
>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