Guide for migrating to JSAPI 2.1

This guide contains examples that demonstrate the differences between the JavaScript API versions 2.1 and 2.0, as well as between 2.1 and 1.x. This section only covers API operations that do not have backward compatibility.

// Creating a map instance and binding it to
// a container with the id="YMapsID".
var myMap = new ymaps.Map("YMapsID", {
center: [55.76, 37.64],
zoom: 10,
type: "yandex#satellite",
// The map will be created without
// controls.
controls: []
});

By default, the map is created with the standard controls: search on map, select map type, full-screen mode, zoom slider, geolocation, and the "Traffic" button.

If you need to create the map without controls, pass an empty array in the constructor in the controls field.

See the section Controls for instructions on how to add the desired controls to the map.

Map behavior

Version 2.0

Version 2.1

The following behaviors are enabled by default: 'drag', 'multiTouch', 'dblClickZoom', and 'rightMouseButtonMagnifier'.

By default, the same behaviors are enabled as in version 2.0, plus 'scrollZoom'.

When setting a custom icon image, you must specify the layout: 'default#image' option.

Placemarks have a vector representation, so custom colors can be set for their icons (except placemarks that stretch to fit the content). Note that this feature is not supported in the IE8 browser (icons will be the standard blue color).

// Creating a placemark with a custom color.
var myPlacemark = new ymaps.Placemark(
[55.8, 37.6],
{},
{
// Placemark style as a circle.
preset: 'islands#circleIcon',
// Placemark color. The iconColor option can be
// set together with the preset option,
// if the latter does not have the value 'stretchyIcon'.
iconColor: '#00000'
}
);

When geo objects are added to the map, the corresponding elements are added to the DOM tree. They are added above the container where the subscription to map events is implemented. In this way, events that occur on a geo object are tracked on the DOM level.

When adding geo objects to the map, their corresponding elements are added to the DOM tree under the layer where subscribing to map events is implemented. This means that geo object events are not tracked on the DOM level.

Interactivity of geo objects is implemented using hotspots, which are bound to the events layer. For geo objects with the standard layout, hotspots are defined automatically.

When creating a custom geo object layout, you must independently define the hotspot shape using the iconShape option. Its fields specify the geometry type that is accepted by the hotspot (for example, rectangle or circle), as well as a description of its contour (for a circle, for example, this is the coordinates of its center and the length of its radius in pixels).

A single balloon/hint manager is created in the balloon/hint field of the clusterer.

Working with clusterer objects after adding them to the map

Version 2.0

Version 2.1

var placemarks = [
new ymaps.Placemark([44, 55]),
new ymaps.Placemark([34, 45])
];
clusterer.add(placemarks);
clusterer.events.add('objectsaddtomap', function () {
// Getting data about the state of
// an object inside the cluster.
var geoObjectState = clusterer.getObjectState(placemarks[1]);
// Checking whether the object
// is inside the map viewport.
if (geoObjectState.isShown) {
// If the object is in the cluster,
// the cluster balloon opens with the object selected.
if (geoObjectState.isClustered) {
geoObjectState.cluster.state.set('activeObject', placemarks[1]);
geoObjectState.cluster.balloon.open()
} else {
// If the object is not in the cluster,
// its own balloon is opened.
placemarks[1].balloon.open();
}
}
});

Since objects are added asynchronously by default, data processing can only be done after an event, signaling the end of adding child objects of the clusterer to the map.

var placemarks = [
new ymaps.Placemark([44, 55]),
new ymaps.Placemark([34, 45])
];
clusterer.add(placemarks);
// Getting data about the state of
// an object inside the cluster.
var geoObjectState = clusterer.getObjectState(placemarks[1]);
// Checking whether the object
// is inside the map viewport.
if (geoObjectState.isShown) {
// If the object is in the cluster,
// the cluster balloon opens with the object selected.
if (geoObjectState.isClustered) {
geoObjectState.cluster.state.set('activeObject', placemarks[1]);
clusterer.balloon.open(geoObjectState.cluster); } else {
// If the object is not in the cluster,
// its own balloon is opened.
placemarks[1].balloon.open();
}
}

The clusterer's child objects (clusters and placemarks that are not in any cluster) are added to the map synchronously.

You can also control the colors of clusters using the preset option, which specifies the key of the desired style. This option can only be set for the entire clusterer. The color will be set for the icons of all of its clusters.

cluster.options.set('preset', 'islands#redClusterIcons');

You can also change the color of the cluster icon using the preset option, which specifies the key of the desired style.

All options for the clusterer's child objects are set with the corresponding prefixes: with the “cluster” prefix for cluster placemarks, and with the “geoObject” prefix for separate placemarks. In this way, the options of child objects are not dependent on each other.

If you need to create the map without controls, pass an empty array in the constructor in the controls field.

The controls are adaptive, meaning they can adapt to the size of the map and the size of the screen. For example, for large map sizes, the controls display both the text label and icon; for medium sizes, they only show the text; for small sizes, they only show the icon.

For more information, see the Controls section in the Developer's guide.

myMap.controls
// The control will be placed in
// the upper-right corner with the specified offset.
.add('zoomControl', {
float: 'none',
position: {top: 5,
right: 10}
})
// The control will be placed in the upper-left corner.
.add('traffic', { float: left });

Controls can be placed on top of the map in two ways, which are regulated using the float option:

Lined up in the upper-right or upper-left corner of the map (float: 'right' or float: 'left').

Positioned at a custom anchor point relative to any corner of the map (float: 'none') by setting the position option, containing the offsets in pixels from the edges of the map.

If the map has small dimensions, the balloon is displayed as a panel in the lower part of the map. If the balloon must be displayed as a pop-up window over the placemark, set the option balloonPanelMaxMapArea: 0.

Balloon that goes off the map.

Version 2.0

Version 2.1

var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
balloonContent: 'I went off the map'
}, {
// The balloon is in the container
// 'movableOuters' (not in the overlays container)
// and goes past the edge of the map.
balloonPane: 'movableOuters',
balloonShadowPane: 'movableOuters'
});

In this code fragment, the movement of the balloon's anchor point (i.e. its “tail”) is not tracked, so the balloon will be displayed even if it goes completely out of the map's boundaries.

In order to display the balloon outside of the map with a shadow, set the option balloonShadowPane: 'movableOuters'.

In this example, the balloon is displayed even if the anchor point is not in the map viewport. The sandbox has a detailed example that implements tracking the movement of the balloon's anchor point relative to the map's boundaries.

Overlays

getOverlay method

Version 2.0

Version 2.1

Returns the overlay of an entity (geo object, balloon, or hint) or null. Does not support working in asynchronous mode.

Asynchronous. Returns the promise object, which is confirmed by the overlay object at the time it is actually created, or is rejected with an appropriate error message.

Methods that return the layout (getLayout, getShadowLayout and so on)

Version 2.0

Version 2.1

Synchronous. Return the layout of an entity (control, geo object, balloon, or hint).

Asynchronous. Return the promise object, which is confirmed by the layout at the time it is actually created, or is rejected with an appropriate error message.

Migrating from version 1.x

This section contains code example for executing the main operations with the Yandex.Maps JavaScript API versions 1.1 and 2.1.

/* Determining the maximum value of the
zoom level for the specified viewport
on the map */
var maxZoom = myMap.getMaxZoom(
new YMaps.GeoBounds(
new YMaps.GeoPoint(0, 0),
new YMaps.GeoPoint(40, 40)
)
);
/* Determining the minimum value of the
zoom level for the specified viewport
on the map */
var minZoom = myMap.getMinZoom(
new YMaps.GeoBounds(
new YMaps.GeoPoint(0, 0),
new YMaps.GeoPoint(40, 40)
)
);

Getting the minimum and maximum zoom values is a synchronous operation (all necessary data is loaded when enabling the API).

The maximum and minimum zoom values are determined for the specified map viewport.

// Creating a placemark
var myPlacemark = new ymaps.Placemark([55.8,37.6]);
// Adding an object (placemark) to a collection
myCollection.add(myPlacemark);
// Adding the collection to the map
myMap.geoObjects.add(myCollection);

Deleting items from a collection

Version 1.1

Version 2.1

// Deleting a single item from a collection
myCollection.remove(myPlacemark);
// Deleting all items from a collection
myCollection.removeAll();

// Deleting a single item from a collection
myCollection.remove(myPlacemark);
// Deleting all items from a collection
myCollection.removeAll();

Setting styles for collection items

Version 1.1

Version 2.1

// Setting styles for a collection when creating it
var myCollection = new YMaps.GeoObjectCollection("default#greenPoint");
// Setting styles for a collection after creating it
myCollection.setStyle("default#redPoint")

// Setting styles for a collection when creating it
var myCollection = new ymaps.GeoObjectCollection({}, {
preset: "twirl#greenIcon"
});
// Setting styles for a collection after creating it
myCollection.options.set("preset", "twirl#redIcon");