Modular system

The Yandex Maps API was developed using a modular concept.

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

Note

When enabling modules, you only need to specify the ones that will be accessed in the code via the ymaps namespace.

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

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/?apikey=Your API key&lang=en_US&**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 the class manually to the global viewport, since this doesn't 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 wasn't added to the public viewport.
            placemark = new Placemark([55.55, 37.00]);
        map.geoObjects.add(placemark);
    })
    /* The placemark won't be created because the Placemark class isn't included in ymaps.
    var newPlacemark = new ymaps.Placemark([55.50, 37.00]); 
    */
}
</script>

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'));
});