[[PageOutline]]

= !OverviewMap Control = 
 * Class Definition: [source:trunk/openlayers/lib/OpenLayers/Control/OverviewMap.js]
 * API Reference: http://dev.openlayers.org/apidocs/files/OpenLayers/Control/OverviewMap-js.html
 * Family Tree:
   * !OpenLayers.Control.!OverviewMap
     * [wiki:Control OpenLayers.Control]
 * Related Links: 

----

This control provides a locator or overview map linked to another map.  By default, the overview map shows up in the lower right of the main map and can be expdaned with the '+' button.  To add an overview map with the default behavior to an existing map, use the following syntax (assuming that your main map is assigned the variable name 'map'):
{{{
    map.addControl(new OpenLayers.Control.OverviewMap());
}}}
This overview map will clone the base layer from the main map as its own base layer.  

== Custom layers ==
If you'd like to have an overview map with layers other than the base layer of your main map, the control can be constructed with additional options.  The following code creates an overview map with a base layer from NASA JPL:
{{{
    var jpl_wms = new OpenLayers.Layer.WMS( "NASA Global Mosaic",
                "http://wms.jpl.nasa.gov/wms.cgi", 
                {layers: "modis,global_mosaic"});
    var options = {layers: [jpl_wms]};
    map.addControl(new OpenLayers.Control.OverviewMap(options));
}}}
''Note that the base layer for your overview map must be in the same projection as the base layer from your main map.''

== Custom map options - projections, extents, etc. == 
If you construct your main map with any non-default options, send these same options to the overview map control (as the mapOptions property of the options argument).  This includes non-default projections and maxExtent.  For example:
{{{
    // Construct overview map with non-default projection, units, and extent
    var options = {
        projection: "EPSG:26912",
        units: 'm',
        maxExtent: new OpenLayers.Bounds(455402, 4967657, 473295, 4984095)
    };

    map.addControl(new OpenLayers.Control.OverviewMap({mapOptions: options}));
}}}

Or for a custom tile size 
{{{
    // Construct overview map with non-default tile size
    var options = {
        tileSize: new OpenLayers.Size(200, 200)
    };

    map.addControl(new OpenLayers.Control.OverviewMap({mapOptions: options}));
}}}

The thing to keep in mind here is that the !OverviewMap control is a control, not a map.  This is an important distinction.  The !OverviewMap control ''has'' a map, but ''it is not'' a map itself.  To set options on the control, use properties of the options object as you would with other controls.  To set properties on the little map that the !OverviewMap control controls, use the special {{{mapOptions}}} property of the options object.

== Custom zoom behavior ==
The overview map will zoom in or out depending on the state of your main map.  The minRatio and maxRatio properties of the overview map determine when this zooming takes place.  The default minRatio is 8 and the default maxRatio is 32.  These ratios refer to the resolution of the overview map divided by the resolution of the main map.  So, by default, if the resolution of your overview map is less than 8 times the resolution of your main map, the overview map will zoom farther out (to increase its resolution).  Similarly, if the resolution of your overview map is greater than 32 times the resolution of your main map, the overview map will try to zoom farther in.

This typically works well and decreases the number of times that the overview map has to redraw its layers.  If you want to change this behavior, add in minRatio and/or maxRatio properties to the control's options when it is constructed:
{{{
    var options = {minRatio: 16, maxRatio: 64};
    map.addControl(new OpenLayers.Control.OverviewMap(options));
}}}
''Note that terrible things will likely happen if your minRatio is greater than your maxRatio.''

If you'd like to have an overview map that doesn't zoom in and out at all, give it just one zoom level:
{{{
  var options = {mapOptions: {numZoomLevels: 1}};
  map.addControl(new OpenLayers.Control.OverviewMap(options));
}}}
''Note that in this case, you might want to be using an [wiki:Layer/Image Image Layer].''

== Custom layout ==
By default, the overview map is added to the map viewport (as with the other controls).  If you wish to add the overview map to another element in your document, you can send that element as the div property of the options argument when you construct the control.  This is better explained by an example.  Say you want the overview map in an element with an id of 'overviewmap' (this might have been created with a tag like <div id="overviewmap"></div>).  Construct your overview map control as follows:
{{{
  var options = {div: $('overviewmap')};
  map.addControl(new OpenLayers.Control.OverviewMap(options));
}}}
''Note that the options property is always called 'div' - even if you are putting the overview map in a <td> or <blink> element.  An overview map outside the viewport will not get minimize/maximize buttons.  You are responsible for this and any other styling of the elements.

== Advanced usage ==
Looking at the source for the control, you can see that there are a number of additional customizations possible.  For example, if you'd like to change the criteria by which the overview map decides when to update itself, you can override the isSuitableOverview() method.  To do this, first construct the control, then modify any properties/methods, then add the control to your map:
{{{
    var ovControl = new OpenLayers.Control.OverviewMap();
    ovControl.isSuitableOverview = function() {
        return false;
    };
    map.addControl(ovControl);
}}}
This will cause the overview map to update itself with each move of the main map - so the extent rectangle will always stay centered.  If the same function always returns true, then the overview map will never zoom or recenter itself.

== Known Issues ==

The Overview Map does not work in Safari before 2.4.