How to use the widget

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

id здания

Company id

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

id фирмы

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

Все рубрики

id рубрики