How to use the widget

How to place it on the page
Widget parameters
Widget methods
Events
How to find object ids

How to place it on the page

A widget can be placed on a page in two ways.

An easy way

Just paste the following code into the page:


<script charset="utf-8" src="https://floors-widget.api.2gis.ru/loader.js" id="dg-floors-widget-loader"></script><script charset="utf-8">
    DG.FloorsWidget.init({
        width: '960px',
        height: '600px',
        initData: {
            complexId: '141373143573143'
        }
    });
</script>

The widget will appear on the page in the place where you inserted the code. This method is useful for simple static pages.

An advanced way

Include the widget JavaScript file in the head section of your page:


<script charset="utf-8" src="https://floors-widget.api.2gis.ru/loader.js" id="dg-floors-widget-loader"></script>

Add a div element to the page where you want to place the widget:


<div id="mywidget"></div>

Initialize the widget:


DG.FloorsWidget.init({
    container: 'mywidget',
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143'
    }
});

Notice the `container` — parameter — it accepts either the DOM element id or the DOM element itself. This method is useful for more complex cases where you need to create a dynamic widget after opening the page (by clicking a button, etc.).

Widget parameters

init method parameters

Parameter	Required	Description
`width`	yes	Widget width. Can be specified in pixels or percentage
`height`	yes	Widget height. Can be specified in pixels or percentage
`container`	no	The element within which the widget should be created. You can pass either the element itself or its id. If not specified, the widget will be created where the initialization code is located (using `document.write`).
`initData`	yes	Data for widget initialization

Data for widget initialization (initData)

Parameter	Required	Description
`complexId`	yes	id of the building to show
`options`	no	Widget options

Widget options

Parameter	Description	Default value
`locale`	Locale of the widget interface. Available values: `ru_RU`, `es_CL` or `en_US`	`ru_RU`
`initialSearchQuery`	Initializes the widget containing search results for the specified query	`undefined`
`initialRubric`	Initializes the widget containing the list of companies in the category with the specified id	`undefined`
`initialFirm`	Initializes the widget containing the card of a company with the specified id	`undefined`
`initialZoom`	Determines the zoom level at which the widget should be opened. If not specified, the scale is automatically selected to fit the entire building in the widget. This parameter is ignored if one of the parameters `initialSearchQuery` or `initialRubric is specified`	`undefined`
`initialRotation`	Specifies the rotation angle of the map at which the widget should be opened. Is specified in radians. If not specified, the angle is selected automatically	`undefined`
`initialFloor`	Determines the floor at which the widget should be opened. If not specified, the default floor will be selected	`undefined`
`rotatable`	Determines whether it is possible to rotate the map	`true`
`minZoom`	Determines the minimum zoom level of the map. If not specified, it is calculated automatically	`undefined`
`maxZoom`	Determines the maximum zoom level of the map. If not specified, it is calculated automatically	`undefined`

Examples


// Specifies widget size in percent
DG.FloorsWidget.init({
    width: '100%',
    height: '100%',
    initData: {
        complexId: '141373143573143'
    }
});

// Opens widget containing search results for the "clothes" query
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143',
        options: {
            initialSearchQuery: 'одежда'
        }
    }
});

// Opens the widget containing an open card of a cafe
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143',
        options: {
            initialFirm: '141265770712989'
        }
    }
});

// Opens the widget containing the "Coffee shops" category
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143',
        options: {
            initialRubric: '162'
        }
    }
});

// Opens the widget containing the Novosibirsk IKEA zoomed to 18
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143569821',
        options: {
          initialFirm: '141265769608851',
          initialZoom: 18
        }
    }
});

// Opens the widget on floor -1
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143',
        options: {
            initialFloor: '-1'
        }
    }
});

// Prohibition to rotate the map
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143',
        options: {
            rotatable: false
        }
    }
});

// Custom scale boundaries
DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143',
        options: {
            minZoom: 16,
            maxZoom: 25
        }
    }
});

Widget methods

DG.FloorsWidget.init method returns an object with several methods available for calling.

Method	Description
`search(query)`	Opens the search results for the given query
`showFirm(firmId)`	Opens the company card with the given id
`showRubric(rubricId)`	Opens the list of companies in the category with the given id
`zoomIn()`	Increases the zoom of the map
`zoomOut()`	Decreases the zoom of the map
`showFloor(floor)`	Switches the map to the given floor. Accepts a string with the floor name.

Examples


var widget = DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143'
    }
});

// Open the search results for "food" query
widget.search('Еда');

// Open the card of a firm
widget.showFirm('141265770712989');

// Open the "Coffee shops" category
widget.showRubric('162');

// Increase the zoom
widget.zoomIn();

// Switch floor to -2
widget.showFloor('-2');

Events

The widget object generates events that can be subscribed to. This allows you to execute some function when something happens with the widget. The following methods are used to manage events:

Method	Description
`on(type, handler)`	Adds a `handler` function to a particular event `type`
`off(type, handler)`	Removes a previously added `handler` from an event `type`
`off(type)`	Removes all handlers from an event `type`
`off()`	Removes all handlers from all event types

The following event types are available:

Name	Description	Event data
`init`	Fired when the map is inited	`floorList`, `firmList`
`click`	Fired when the user clicks a firm (a room or an icon) on the map	`firmIds`
`zoomend`	Fired at the end of a zoom animation	`state`
`floorswitch`	Fired when the displayed floor of the map changes	`state`

Event data

floorList

Array containing all floor names in the bottom-to-top order

firmList

Array containing all firms in the building. Elements of this array are objects with the following properties:

Name	Type	Description
`id`	`string`	Firm id
`floor`	`string`	Name of the floor on which the firm is located

state

Object containing data about the current state of the map. Has the following properties:

Name	Type	Description
`floor`	`string`	Name of the current floor
`zoom`	`number`	Current zoom
`minZoom`	`number`	Lower zoom limit
`maxZoom`	`number`	Upper zoom limit

firmIds

Array containing ids of the firms that have been clicked. Can't be empty. Can have more than one element if the user clicked a room with multiple firms in it.

Examples


const widget = DG.FloorsWidget.init({
    width: '960px',
    height: '600px',
    initData: {
        complexId: '141373143573143'
    }
});

// 'init' event
widget.on('init', (event) => {
    console.log(event.type); // 'init'
    console.log(event.floorList); // ['-2', '-1', '1', '2', '3', '4']
    console.log(event.firmList); // [{id: '12345', floor: 0, floorName: '-2'}, ...]
});

// 'click' event
widget.on('click', (event) => {
    console.log(event.type); // 'click'
    console.log(event.firmIds); // ['1234', '5678']
});

// 'zoomend' event
widget.on('zoomend', (event) => {
    console.log(event.type); // 'zoomend'
    console.log(event.state); // {floor: 2, zoom: 18, minZoom: 17.5, maxZoom: 21.6}
});

// 'floorswitch' event
widget.on('floorswitch', (event) => {
    console.log(event.type); // 'floorswitch'
    console.log(event.state); // {floor: 3, zoom: 18, minZoom: 17.5, maxZoom: 21.6}
});

// Adding an event handler and removing it
const handler = (event) => console.log(event);
widget.on('click', handler);
widget.off('click', handler);

// Removing all handlers from 'click' event
widget.off('click');

// Removing all handlers from all events
widget.off();

How to find object ids

Building id

1. Open the card of a building you need on 2gis.ru
2. Hover your mouse over the address
3. id will be displayed in the tooltip that appears

Company id

1. Open the card of a company you need on 2gis.ru
2. id will be displayed in the address bar

Category id

1. Open 2gis.ru
2. Open "All categories"
3. Select the category you need and open it
4. id will be displayed in the address bar