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 <[EMAIL PROTECTED]> >Sent: Apr 8, 2008 9:19 AM >To: Peter Len <[EMAIL PROTECTED]> >Cc: Paul Spencer <[EMAIL PROTECTED]>, [email protected] >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 _______________________________________________ Users mailing list [email protected] http://openlayers.org/mailman/listinfo/users
