Documentation
Reference
2.1.38 (current version)
collection
interactivityModel
Interfaces

Modular system

The Yandex.Maps API was developed using a modular concept. This allows you to configure the API for specific tasks and gives you the ability to regulate the amount of download traffic.

The modules are separate named entities, such as classes, static objects, and functions. A list of API modules is provided in the Reference guide.

By default, enabling the API loads the set of main modules necessary for using the API (package.full).

Note. Some public modules are not in package.full (for example, overlay.Placemark). The API loads these modules when they are actually used. These entities usually do not have a public constructor. They are created by special factories (for example, objects with the router.Route type are created by the router), or by accessing asynchronous storage by key (for example, overlay.storage). Direct instantiation of such objects is not recommended, but the ability to get the direct constructor is provided in the API. To do this, specify the module name explicitly when enabling the API (in the load parameter) or via modules.require.

In order to minimize traffic, only load the modules that are necessary. There are two ways to do this: when initializing the API, or on demand via the modules.require function. These methods are examined in detail below.

Note. When enabling modules, you only need to specify the ones that will be accessed in the code via the ymaps namespace. The module system is designed so that when initializing the main modules, all the data they need is loaded automatically.

The API allows you to add new modules to the module system and redefine existing modules.

Loading modules when enabling the API

The modules to load are set in the HTTP parameter load in the string for enabling the API. You can specify multiple modules by separating them with spaces. By default, the load parameter takes the package.full value, meaning it loads all the main modules that are needed by the API.

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&load=Map,Placemark" type="text/javascript"></script>

The loaded modules will be enabled in the public namespace ymaps.

If additional modules are required for the given modules to work, they will be loaded automatically.

The Sandbox has an example of loading modules via the load parameter.

Loading modules on demand

Sometimes a module needs to be loaded on demand. Use the modules.require function for this purpose:

if (!ymaps.Map) {
    ymaps.modules.require('Map, Placemark', function (Map, Placemark) {
         // Adding a class manually to the global viewport, since this does not happen when using the module system's "require" method.
        ymaps.Map = Map;
        var map = new ymaps.Map('map', { 
              center: [55.76, 37.64], 
              zoom: 10    
            }),
            // The Placemark class was not added to the public viewport.
            placemark = new Placemark([55.55, 37.00]);
        map.geoObjects.add(placemark);
    })
    /* The placemark will not be created, because the Placemark class is not included in ymaps.
    var newPlacemark = new ymaps.Placemark([55.50, 37.00]); 
    */
}

Since these modules may require loading additional modules in order to work, the modules.require function supports asynchronous mode. When the data needed by the specified modules is ready, it calls the callback function with the loaded modules.

The Sandbox has an example of loading modules on demand.

Enabling add-ons

Displaying a geo object's balloon and hint is performed using the balloon and hint fields for the GeoObject class. To initialize these fields, you must enable the modules geoObject.addon.balloon and geoObject.addon.hint. If you need to open a balloon or hint that belongs to the map, you need to enable the map.addon.balloon and map.addon.hint modules.

If you need to be able to edit a geo object's geometry, you should enable geoObject.addon.editor.

The Sandbox has an example of enabling add-ons.

Creating custom modules

You can use the API module system to create custom programmatic modules. This is useful when writing large-scale applications based on the Yandex.Maps API.

The module is declared using the modules.define method. The Sandbox has an example of declaring and using a custom module.

The module declaration can be made before calling the ymaps.ready handler.

After the module has been declared in the module system, it can be used in an application.

Note. Custom modules are not added automatically in the general namespace with the API modules. A declared module can be accessed via the asynchronous modules.require method, which returns a promise object.

ymaps.modules.require(['PlacemarkButton'])
  .spread(function (PlacemarkButton) {
    myMap.controls.add(new PlacemarkButton('Click to add a placemark'));
});