2gis-maps/dist/doc/en/manual/dg-loading.html

Interactive 2GIS maps API, based on Leaflet

<h2 id="loading-api">Loading API</h2><p><dl class="api-incut"><ul class="page-contents"><li><a href="#description">Description</a></li><li><a href="#easy-way">Easy way</a></li><li><a href="#npm">npm</a></li><li><a href="#download-on demand">Download on demand</a></li><li><a href="#connection-options">Connection options</a></li><li><a href="#dgthen-function">DG.then function</a></li></ul></dl></p>
<h3 id="description">Description</h3><p>Work with map is possible only after the code of Maps API is loaded to the browser.
There are several ways to download it.</p>
<h3 id="easy-way">Easy way</h3><p>First include the Maps API by adding the following code to the <code>head</code> section of the HTML page:</p>
<pre><code>&lt;script src=&quot;https://maps.api.2gis.ru/2.0/loader.js?pkg=full&quot;&gt;&lt;/script&gt;
</code></pre><p>Then use the <code>DG.then</code> function, into which we will place the initialization code of the map:</p>
<pre><code>DG.then(function() {
    map = DG.map(&#39;map&#39;, {
        &#39;center&#39;: [54.98, 82.89],
        &#39;zoom&#39;: 13
    });
});
</code></pre><p>Inside this function adds a handler for of the event of the page loading.
This very method was discussed in the <a href="/doc/maps/en/quickstart">Quick start</a> section.</p>
<h3 id="npm">npm</h3><p>The Maps API can be included via npm:</p>
<pre><code>$ npm i 2gis-maps
</code></pre><p>After the package is installed, enable it using <code>require</code>:</p>
<pre><code>var DG = require(&#39;2gis-maps&#39;);
var map = DG.map(&#39;map&#39;, {
    &#39;center&#39;: [54.98, 82.89],
    &#39;zoom&#39;: 13
});
</code></pre><p>Please note that when you use the npm package, there is no need to use <code>DG.then</code>.</p>
<h3 id="download-on demand">Download on demand</h3><p>You can load the Maps API at the very moment when you need the map. To do this, you need to add the
<code>lazy=true</code> parameter to the URL used to include API:</p>
<pre><code>&lt;script src=&quot;https://maps.api.2gis.ru/2.0/loader.js?pkg=full&amp;lazy=true&quot;&gt;&lt;/script&gt;
</code></pre><p>Then, at the right time (for example, when pressing the button) you must call the <code>DG.then</code> function:</p>
<pre><code>DG.then(function() {
    map = DG.map(&#39;map&#39;, {
        &#39;center&#39;: [54.98, 82.89],
        &#39;zoom&#39;: 13
    });
});
</code></pre><h3 id="connection-options">Connection options</h3><p>The following are all options that can take the URL of the Maps API loading:</p>
<table>
    <thead>
        <tr>
            <th>Option</th>
            <th>Default</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr id="loading-pkg">
            <td><code>pkg</code></td>
            <td><code>full</code></td>
            <td>Package of loadable modules. Currently, 2 packages are supported: <code>full</code> — all API modules;
                <code>basic</code> — basic functionality (popups, markers, vector objects).</td>
        </tr>
        <tr>
            <td><code>skin</code></td>
            <td><code>dark</code></td>
            <td>The theme of controls (light or dark). Takes the value <code>light</code> or <code>dark</code>.</td>
        </tr>
        <tr>
            <td><code>lazy</code></td>
            <td><code>false</code></td>
            <td>If you specify the <code>true</code> value, then the Maps API will load with delay,
                when you first call <code>DG.then</code>.</td>
        </tr>
    </tbody>
</table>

<h3 id="dgthen-function">DG.then function</h3><p>As described earlier, the function <code>DG.then</code> is responsible for tracking the moment of loading the Maps API
and adding handlers for this action. Function parameters:</p>
<table>
    <thead>
        <tr>
            <th>Function</th>
            <th>Returns</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>DG.then</b>(
                <nobr>&lt;Function&gt; <i>resolve</i>,</nobr>
                <nobr>&lt;Function&gt; <i>reject</i></nobr>&nbsp;)
            </code></td>
            <td><code>Promise</code></td>
            <td>Registers API loading handlers. Parameters: <code>resolve</code> is a function triggered
                in case of a successful loading of the Maps API, <code>reject</code> is a function triggered
                in case of server errors.</td>
        </tr>
    </tbody>
</table>

<p>The call of the <code>DG.then</code> function at any time after the API loading will be immediately executed by the handler.</p>