Утилиты

• Описание
• DG.Class
  • Наследование
  • Опции
  • Включения
  • Статика
  • Фабрики классов
  • Зацепки конструктора
• DG.Browser
• DG.Util
  • Методы
  • Свойства
• DG.Locale
  • Пример использования
• DG.LineUtil
• DG.PolyUtil

Описание

Служебный функционал, необходимый для работы API карт и разработки собственных модулей.

DG.Class

DG.Class предоставляет возможность использовать ООП подход в разработке функционала API карт, используется для реализации большинства классов, приведенных в этой документации.

Кроме реализации простой классической модели наследования имеются несколько свойств для удобной организации кода, такие как options, includes и statics.

var MyClass = DG.Class.extend({
    initialize: function (greeter) {
        this.greeter = greeter;
        // конструктор класса
    },

    greet: function (name) {
        alert(this.greeter + ', ' + name)
    }
});

// создает объект класса MyClass и передает "Hello" в конструктор
var a = new MyClass("Hello");

// вызывает метод greet, который показывает всплывающее окно с текстом "Hello, World"
a.greet("World");

Наследование

Для определения новых классов используется конструкция DG.Class.extend, также метод extend можно использовать в любом классе, который наследуется от DG.Class:

var MyChildClass = MyClass.extend({
    // ... новые свойства и методы
});

Данный код создаст класс, который наследует все методы и свойства родительского класса (через цепочку прототипов), также возможно добавление или переопределение родительских методов и свойств. Кроме того, корректно обрабатывается оператор instanceof:

var a = new MyChildClass();
a instanceof MyChildClass; // true
a instanceof MyClass; // true

Вы можете вызывать родительские методы (включая конструктор) из потомков (так, как вы бы делали это с помощью вызова super в других языках программирования) с помощью JavaScript функций call или apply:

var MyChildClass = MyClass.extend({
    initialize: function () {
        MyClass.prototype.initialize.call("Yo");
    },

    greet: function (name) {
        MyClass.prototype.greet.call(this, 'bro ' + name + '!');
    }
});

var a = new MyChildClass();
a.greet('Jason'); // выведет "Yo, bro Jason!"

Опции

options — это специальное свойство, которое в отличии от других объектов передаваемых через extend будет слито с аналогичным свойством родителя, вместо полного переопределения, это позволяет управлять конфигурацией объектов и значениями по умолчанию:

var MyClass = DG.Class.extend({
    options: {
        myOption1: 'foo',
        myOption2: 'bar'
    }
});

var MyChildClass = DG.Class.extend({
    options: {
        myOption1: 'baz',
        myOption3: 5
    }
});

var a = new MyChildClass();
a.options.myOption1; // 'baz'
a.options.myOption2; // 'bar'
a.options.myOption3; // 5

Также имеется метод DG.Util.setOptions, который позволяет сливать опции переданные в конструктор с изначально заданными опциями:

var MyClass = DG.Class.extend({
    options: {
        foo: 'bar',
        bla: 5
    },

    initialize: function (options) {
        DG.Util.setOptions(this, options);
        ...
    }
});

var a = new MyClass({bla: 10});
a.options; // {foo: 'bar', bla: 10}

Включения

includes — это специальное свойство, которое подмешивает объекты в класс (такие объекты называются mixin-ами).

 var MyMixin = {
    foo: function () { ... },
    bar: 5
};

var MyClass = DG.Class.extend({
    includes: MyMixin
});

var a = new MyClass();
a.foo();

Также вы можете подмешивать объекты в процессе выполнения программы с помощью метода include:

MyClass.include(MyMixin);

Статика

statics — это свойство, в котором описываются статические элементы класса, удобно использовать для определения констант:

var MyClass = DG.Class.extend({
    statics: {
        FOO: 'bar',
        BLA: 5
    }
});

MyClass.FOO; // 'bar'

Фабрики классов

Для создания новых объектов классов используются фабричные методы, которые имеют такое же название, как и у класса, но начинаются с нижнего регистра. Это аналог ключевого слова new, то есть, данные строки кода эквивалентны:

new DG.Map('map');
DG.map('map');

Реализовать фабричный метод в собственных классах довольно просто, например:

DG.map = function (id, options) {
    return new DG.Map(id, options);
};

Зацепки конструктора

Если вы разрабатываете модуль к API, тогда велика вероятность того, что вам понадобится выполнить дополнительные действия при инициализации объектов существующих классов (например, при инициализации объекта DG.Polyline). Для подобного рода задач имеется метод addInitHook:

MyClass.addInitHook(function () {
    // ... выполнить дополнительные действия при вызове конструктора
    // например, добавить обработчики событий, установить значения свойств и т.п.
});

Также можно использовать сокращенную запись, если необходимо вызвать лишь один метод при инициализации:

MyClass.addInitHook('methodName', arg1, arg2, …);

DG.Browser

Объект со свойствами, необходимыми для определения браузера/фичи, например:

if (DG.Browser.ie6) {
    alert('Вам срочно нужно обновить свой браузер!');
}

DG.Util

Общие служебные методы и свойства.

Методы

Свойства

DG.Locale

Функционал, с помощью которого осуществляется перевод пользовательского интерфейса.

Подмешивает в карту два метода: setLang и getLang. Также имеется объект DG.Locale, который можно подмешать в любой внешний модуль, после чего в нем появится метод t, с помощью которого можно осуществить перевод. Классы модулей, к которым примешивается DG.Locale должны содержать внутри себя свойство _map и статическое свойство Dictionary.

Базовым для всех словарей является словарь DG.Dictionary, в котором хранятся правила перевода слов во множественные формы (plural rules). При создании модуля, использующего свои словари, необходимо их разместить в папке lang. К примеру, если вы будете использовать итальянский и русский языки, тогда необходимо создать файлы lang/it.js и lang/ru.js. Примеры создания словарей рассмотрены ниже.

Пример использования

Подмешивание (mixin) функционала локализации в модуль:

DG.LocaleExample = DG.Control.extend({
    includes: DG.Locale,
    statics: {
        Dictionary: {}
    }
    ...
}

Подписка на событие langchange:

this._map.on('langchange', this._updateText, this);

Перевод строки на текущий язык карты:

container.innerHTML = this.t("{n} people", 16700000) + ' ' + this.t("regularly use 2GIS");

Создание собственных словарей на итальянском и русском языках:

Cодержимое файла lang/it.js:

DG.LocaleExample.Dictionary.it = DG.extend({
    "{n} people" : ["{n} utente", "{n} utenti"],
    "regularly use 2GIS" : "utilizzano regolarmente 2GIS"
}, DG.Dictionary.it);

Cодержимое файла lang/ru.js:

 DG.LocaleExample.Dictionary.ru = DG.extend({
    "{n} people" : ["{n} пользователь", "{n} пользователя", "{n} пользователей"],
    "regularly use 2GIS" : "регулярно используют 2GIS"
}, DG.Dictionary.ru);

DG.LineUtil

Набор методов для обработки ломаных.

DG.PolyUtil

Набор методов для обработки точек многоугольников.