Implementing a custom Engine

Engine is a wrapper of a map API. For example, GoogleEngine is a wrapper for Google Maps API.
All engines have common MapWrapper interface and extend the Engine class, and they call “native” Google, Yahoo, Yandex and whatever API in their implementation.

MapWrapper provides an easy way to implement your own engine.
Special attention was paid on the simplicity of this process.

One may need to implement an engine in two cases:

• If there is a Map API which is not implemented in the MapWrapper lib. For example, Wikimapia is heard to have an API (though very awkward for the time being), but MapWrapper doesn’t have an engine for it. You may want to add it.
• If you want to change the behavior of an existing engine.

The easiest way to implement a custom engine is to look into existing implementations: google_engine.js, yandex_engine.js, yahoo_engine.js. These are very simple indeed.
But anyway see below for the formal description of the Engine interface.

Extend the Engine class

GoogleEngine.prototype = new Engine()

Required fields

• codename – the name of this engine. It will be used in the DIV element where this engine’s map will be placed, and on the default switch control.

Optional fields

• icon – the link to the icon representing this engine. If initialized, It is used on the default switch control. Default engine’s implementations use favicon.ico of the map API’s site.

Required methods

• initialize(container) – call the native map constructor and place it to the container.
• setOptions(options) – apply the customization options. See Options page.
• getNativeControl() – return the map object, representing the map itself in the API you’re wrapping. It is GMap2 for Google Maps, YMaps.Map for Yandex Maps.
• addSwitchControlOnMap(switchControl) – well, add the switch control on the map. The switchControl parameter is implemented in terms of the native API. Note that you don’t need to save added or removed switch controls in the engine: it is done in Engine.addSwitchControl(), which is actually called from MapWrapper.
• removeSwitchControlFromMap(switchControl) – just remove the given switch control from the map. Note that you don’t need to check if the switch control exists – it is done in Engine.removeSwitchControl(), which is actually called from MapWrapper.
• getCenter() – return the GeoPoint object representing the center point of this map.
• setCenter(geopoint) – centralize this map on the point represented by the given geopoint object.
• getZoom() – return the current zoom value of this map. Note that zoomis a float between 0.0 and 1.0, so you might need to convert it to usually used integer level. See Zoom
• setZoom(zoom) – zoom the map to the given value. zoom is a float between 0.0 and 1.0, so you might need to convert it to usually used integer level. See Zoom

Hidden fields

You may use these fields if you need, but don’t override them, as they are heavily relied on in the MapWrapper class.
You don’t need and shouldn’t declare these fields when implementing your own engine. They are declared and initialized in MapWrapper.addEngine().

• mapWrapper – link to the MapWrapper, to which this Engine was added.
• container – the DOM element (DIV) which contains this engine. It is also passed to *Engine.initialize and is used to indicate, where the map is to be placed.