[OpenLayers-Users] Control documentation incomplete, inconsistent and misleading

[Andreas Hocevar]

P Kishor wrote:
> Per the docs for Control
>
> "Controls by default are added to the map they are contained within
> however it is possible to add a control to an external div by passing
> the div in the options parameter."
>
> which is followed by the example
>
> "var control = new OpenLayers.Control({div: myDiv});"
>
> That leads me, the user, to do the following to display MousePosition
> in an external div
>
> # in my html
> <div id="map"></div>
> <div id="coords"></div>
> <div id="scale"></div>
>
> # in my javascript -- this does not work
> var ctrl_coords = new OpenLayers.Control({div: "coords"});
> ctrl_coords.MousePosition();
> map.addControl(ctrl_coords);
>
> # in my javascript -- this also does not work
> var ctrl_coords = new OpenLayers.Control.MousePosition({div: "coords"});
> map.addControl(ctrl_coords);
>
> # in my javascript -- this is the only thing that works
> # but the mouse position is displayed on the map
> var ctrl_coords = new OpenLayers.Control.MousePosition();
> map.addControl(ctrl_coords);
>
>
> So, it turns out, I have to write my code like so
>
> # in my javascript
> map.addControl(new OpenLayers.Control.MousePosition({div:
> document.getElementById("coords")}));
>
> Now, if I want to display the scale also in an external div, things
> get even more bizarre
>
> # in my javascript -- the following doesn't work
> map.addControl(new OpenLayers.Control.MousePosition({div:
> document.getElementById("scale")}));
>   

You mean

map.addControl(new OpenLayers.Control.Scale({div:
document.getElementById("scale")}));

This will not work, because Control.Scale has a different constructor. 
See 
http://dev.openlayers.org/releases/OpenLayers-2.8/doc/apidocs/files/OpenLayers/Control/Scale-js.html

So other than OL.Control and OL.Control.MousePosition, the 
OL.Control.Scale constructor takes two arguments.

> # in my javascript -- the only thing that works is
> var ctrl_scale = new OpenLayers.Control.Scale();
> ctrl_scale.div = document.getElementById("scale");
> map.addControl(ctrl_scale);
>   

The intended way to do this would be

var ctrl_scale = new OpenLayers.Control.Scale(document.getElementById("scale"));


Now looking at 
http://dev.openlayers.org/releases/OpenLayers-2.8/doc/apidocs/files/OpenLayers/Control/Scale-js.html, 
I admit that this could use some better explanation.

So to answer your follow-up question on what to patch, I think the docs 
for the Control.Scale constructor would be something that could use some 
love.

> After battling with this for about 5 hours, I was able to figure the
> above out via archived mailing list post for an earlier version of OL.
> Is it possible to update the documentation to reflect the above, or to
> fix OL so it behaves consistently?
>   

The former is easy with your help. The latter looks like it would break 
the API, and hence cannot happen before OL 3.0. Our promise to the 
community is to not change the API for minor releases.

So if you are still willing to contribute, a patch for that would be 
nice. If you do not want to follow the procedure on 
http://trac.openlayers.org/wiki/HowToContribute, then please let me know 
what you would like to read in the docs for the constructor arguments, 
and I will change the docs.

Regards,
Andreas.

-- 
Andreas Hocevar
OpenGeo - http://opengeo.org/
Expert service straight from the developers.