documenting that Layer.VirtualEarth requires restrictedExtent to be set, and changing the examples accordingly. p=marcjansen (closes #3123)

git-svn-id: http://svn.openlayers.org/trunk/openlayers@11503 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

examples/bing.html

@@ -14,7 +14,16 @@
         var map;
  
         function init(){
-            map = new OpenLayers.Map("map");
+            // setting restrictedExtent so that we can use the 
+            // VirtualEarth-layers, see e.g. 
+            // http://dev.openlayers.org/apidocs/files/OpenLayers/Layer/VirtualEarth-js.html
+            var restrictedExtent = new OpenLayers.Bounds(-20037508, -20037508, 
+                20037508, 20037508);
+            
+            map = new OpenLayers.Map("map", {
+                restrictedExtent: restrictedExtent
+            });
+            
             map.addControl(new OpenLayers.Control.LayerSwitcher());
 
             var shaded = new OpenLayers.Layer.VirtualEarth("Shaded", {

examples/spherical-mercator.html

@@ -24,107 +24,111 @@
     <script src="../lib/OpenLayers.js"></script>
     <script type="text/javascript">
 
-        // make map available for easy debugging
+// make map available for easy debugging
-        var map;
+var map;
 
-        // increase reload attempts 
+// increase reload attempts 
-        OpenLayers.IMAGE_RELOAD_ATTEMPTS = 3;
+OpenLayers.IMAGE_RELOAD_ATTEMPTS = 3;
 
-        function init(){
+function init(){
-            var options = {
+    var maxExtent = new OpenLayers.Bounds(-20037508, -20037508, 20037508, 20037508),
-                projection: new OpenLayers.Projection("EPSG:900913"),
+        restrictedExtent = maxExtent.clone(-20037508, -20037508, 20037508, 20037508),
-                displayProjection: new OpenLayers.Projection("EPSG:4326"),
+        maxResolution = 156543.0339;
-                units: "m",
-                numZoomLevels: 18,
-                maxResolution: 156543.0339,
-                maxExtent: new OpenLayers.Bounds(-20037508, -20037508,
-                                                 20037508, 20037508.34)
-            };
-            map = new OpenLayers.Map('map', options);
     
-            // create Google Mercator layers
+    var options = {
-            var gmap = new OpenLayers.Layer.Google(
+        projection: new OpenLayers.Projection("EPSG:900913"),
-                "Google Streets",
+        displayProjection: new OpenLayers.Projection("EPSG:4326"),
-                {'sphericalMercator': true}
+        units: "m",
-            );
+        numZoomLevels: 18,
-            var gsat = new OpenLayers.Layer.Google(
+        maxResolution: maxResolution,
-                "Google Satellite",
+        maxExtent: maxExtent,
-                {type: G_SATELLITE_MAP, 'sphericalMercator': true, numZoomLevels: 22}
+        restrictedExtent: restrictedExtent
-            );
+    };
-            var ghyb = new OpenLayers.Layer.Google(
+    map = new OpenLayers.Map('map', options);
-                "Google Hybrid",
-                {type: G_HYBRID_MAP, 'sphericalMercator': true}
-            );
 
-            // create Virtual Earth layers
+    // create Google Mercator layers
-            var veroad = new OpenLayers.Layer.VirtualEarth(
+    var gmap = new OpenLayers.Layer.Google(
-                "Virtual Earth Roads",
+        "Google Streets",
-                {'type': VEMapStyle.Road, 'sphericalMercator': true}
+        {sphericalMercator: true}
-            );
+    );
-            var veaer = new OpenLayers.Layer.VirtualEarth(
+    var gsat = new OpenLayers.Layer.Google(
-                "Virtual Earth Aerial",
+        "Google Satellite",
-                {'type': VEMapStyle.Aerial, 'sphericalMercator': true}
+        {type: G_SATELLITE_MAP, sphericalMercator: true, numZoomLevels: 22}
-            );
+    );
-            var vehyb = new OpenLayers.Layer.VirtualEarth(
+    var ghyb = new OpenLayers.Layer.Google(
-                "Virtual Earth Hybrid",
+        "Google Hybrid",
-                {'type': VEMapStyle.Hybrid, 'sphericalMercator': true}
+        {type: G_HYBRID_MAP, sphericalMercator: true}
-            );
+    );
 
-            // create Yahoo layer
+    // create Virtual Earth layers
-            var yahoo = new OpenLayers.Layer.Yahoo(
+    var veroad = new OpenLayers.Layer.VirtualEarth(
-                "Yahoo Street",
+        "Virtual Earth Roads",
-                {'sphericalMercator': true}
+        {'type': VEMapStyle.Road, sphericalMercator: true}
-            );
+    );
-            var yahoosat = new OpenLayers.Layer.Yahoo(
+    var veaer = new OpenLayers.Layer.VirtualEarth(
-                "Yahoo Satellite",
+        "Virtual Earth Aerial",
-                {'type': YAHOO_MAP_SAT, 'sphericalMercator': true}
+        {'type': VEMapStyle.Aerial, sphericalMercator: true}
-            );
+    );
-            var yahoohyb = new OpenLayers.Layer.Yahoo(
+    var vehyb = new OpenLayers.Layer.VirtualEarth(
-                "Yahoo Hybrid",
+        "Virtual Earth Hybrid",
-                {'type': YAHOO_MAP_HYB, 'sphericalMercator': true}
+        {'type': VEMapStyle.Hybrid, sphericalMercator: true}
-            );
+    );
 
-            // create OSM layer
+    // create Yahoo layer
-            var mapnik = new OpenLayers.Layer.OSM();
+    var yahoo = new OpenLayers.Layer.Yahoo(
-            // create OAM layer
+        "Yahoo Street",
-            var oam = new OpenLayers.Layer.XYZ(
+        {sphericalMercator: true}
-                "OpenAerialMap",
+    );
-                "http://tile.openaerialmap.org/tiles/1.0.0/openaerialmap-900913/${z}/${x}/${y}.png",
+    var yahoosat = new OpenLayers.Layer.Yahoo(
-                {
+        "Yahoo Satellite",
-                    sphericalMercator: true
+        {'type': YAHOO_MAP_SAT, sphericalMercator: true}
-                }
+    );
-            );
+    var yahoohyb = new OpenLayers.Layer.Yahoo(
+        "Yahoo Hybrid",
+        {'type': YAHOO_MAP_HYB, sphericalMercator: true}
+    );
 
-            // create OSM layer
+    // create OSM layer
-            var osmarender = new OpenLayers.Layer.OSM(
+    var mapnik = new OpenLayers.Layer.OSM();
-                "OpenStreetMap (Tiles@Home)",
+    // create OAM layer
-                "http://tah.openstreetmap.org/Tiles/tile/${z}/${x}/${y}.png"
+    var oam = new OpenLayers.Layer.XYZ(
-            );
+        "OpenAerialMap",
-
+        "http://tile.openaerialmap.org/tiles/1.0.0/openaerialmap-900913/${z}/${x}/${y}.png",
-
+        {
-            // create WMS layer
+            sphericalMercator: true
-            var wms = new OpenLayers.Layer.WMS(
-                "World Map",
-                "http://world.freemap.in/tiles/",
-                {'layers': 'factbook-overlay', 'format':'png'},
-                {
-                    'opacity': 0.4, visibility: false,
-                    'isBaseLayer': false,'wrapDateLine': true
-                }
-            );
-
-            // create a vector layer for drawing
-            var vector = new OpenLayers.Layer.Vector("Editable Vectors");
-
-            map.addLayers([gmap, gsat, ghyb, veroad, veaer, vehyb,
-                           yahoo, yahoosat, yahoohyb, oam, mapnik, osmarender,
-                           wms, vector]);
-            map.addControl(new OpenLayers.Control.LayerSwitcher());
-            map.addControl(new OpenLayers.Control.EditingToolbar(vector));
-            map.addControl(new OpenLayers.Control.Permalink());
-            map.addControl(new OpenLayers.Control.MousePosition());
-            if (!map.getCenter()) {map.zoomToMaxExtent()}
         }
+    );
+
+    // create OSM layer
+    var osmarender = new OpenLayers.Layer.OSM(
+        "OpenStreetMap (Tiles@Home)",
+        "http://tah.openstreetmap.org/Tiles/tile/${z}/${x}/${y}.png"
+    );
+
+
+    // create WMS layer
+    var wms = new OpenLayers.Layer.WMS(
+        "World Map",
+        "http://world.freemap.in/tiles/",
+        {'layers': 'factbook-overlay', 'format':'png'},
+        {
+            'opacity': 0.4, visibility: false,
+            'isBaseLayer': false,'wrapDateLine': true
+        }
+    );
+
+    // create a vector layer for drawing
+    var vector = new OpenLayers.Layer.Vector("Editable Vectors");
+
+    map.addLayers([gmap, gsat, ghyb, veroad, veaer, vehyb,
+                   yahoo, yahoosat, yahoohyb, oam, mapnik, osmarender,
+                   wms, vector]);
+    map.addControl(new OpenLayers.Control.LayerSwitcher());
+    map.addControl(new OpenLayers.Control.EditingToolbar(vector));
+    map.addControl(new OpenLayers.Control.Permalink());
+    map.addControl(new OpenLayers.Control.MousePosition());
+    if (!map.getCenter()) {map.zoomToMaxExtent()}
+}
 
     </script>
   </head>

lib/OpenLayers/Layer/VirtualEarth.js

@@ -13,6 +13,10 @@
 
 /**
  * Class: OpenLayers.Layer.VirtualEarth
+ * Instances of OpenLayers.Layer.VirtualEarth are used to display the data from
+ *     the Bing Maps AJAX Control (see e.g. 
+ *     http://msdn.microsoft.com/library/bb429619.aspx). Create a VirtualEarth 
+ *     layer with the <OpenLayers.Layer.VirtualEarth> constructor.
  *     
  * Inherits from:
  *  - <OpenLayers.Layer.EventPane>
@@ -94,6 +98,22 @@ OpenLayers.Layer.VirtualEarth = OpenLayers.Class(
 
     /** 
      * Constructor: OpenLayers.Layer.VirtualEarth
+     * Creates a new instance of a OpenLayers.Layer.VirtualEarth. If you use an
+     *     instance of OpenLayers.Layer.VirtualEarth in you map, you should set 
+     *     the <OpenLayers.Map> option restrictedExtent to a meaningful value,
+     *     e.g.:
+     * (code)
+     * var map = new OpenLayers.Map( 'map', {
+     *     // other map options
+     *     restrictedExtent : OpenLayers.Bounds(-20037508, -20037508, 20037508, 20037508)
+     * } );
+     * 
+     * var veLayer = new OpenLayers.Layer.VirtualEarth (
+     *     "Virtual Earth Layer"
+     * );
+     * 
+     * map.addLayer( veLayer );
+     * (end)
      * 
      * Parameters:
      * name - {String}