Макеты и шаблоны

Внешний вид любых отображаемых элементов (балун, хинт, метка и пр.) определяется с помощью макетов. Макет представляет из себя объект, реализующий интерфейс ILayout, который генерирует код, отвечающий за конечное представление объекта. Макеты могут изменять DOM-дерево документа.

Чтобы изменить/задать внешний вид отображаемого объекта необходимо изменить/задать связанный с ним макет. Объекты связываются со своими макетами с помощью соответствующих опций.

var myPlacemark = new ymaps.Placemark(
    [55.8, 37.6],
    {},
    {balloonContentLayout: MyBalloonContentLayoutClass}
    // MyBalloonContentLayoutClass — класс макета балуна.
);

В отличие от опций, которые позволяют изменить только некоторые параметры отображения элемента, макет позволяет сформировать какое угодно его представление.

Реализация собственного макета «с нуля» на основе интерфейса ILayout является относительно трудоемкой задачей, решение которой выходит за рамки данного руководства. Однако API предоставляет удобный механизм, позволяющий генерировать макеты на основе шаблонов.

Шаблон представляет собой HTML-код, в который могут быть включены подстановки. Для создания макетов с помощью языка шаблонов предназначена фабрика макетов — статический объект templateLayoutFactory. Этот объект имеет единственный метод createClass, в который передается код шаблона.

var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '<h3>Макет</h3><p>Создан на основе шаблона.</p>' 
);

Часто возникает необходимость использовать данные объекта в связанном с ним макете. Например, вывести название метки в ее балуне.

Шаблоны имеют доступ к некоторым полям родительского объекта. В большинстве случаев доступны значения полей data (либо properties), options и state. Значения этих полей могут быть использованы в т. н. подстановках. Типы возможных подстановок описаны в спецификации объекта templateLayoutFactory.

var myPlacemark = new ymaps.Placemark(
    [55.8, 37.6],
    {
        name: 'Москва',
        description: 'Столица. Много людей.',
        metro: true
    },
    {balloonContentLayout: MyBalloonContentLayoutClass}
);
var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '<h3>$[properties.name]</h3>' +
    '<p>Описание: $[properties.description]</p>' +
    '<p>Население: $[properties.population|неизвестно]</p>' +
    '<p>Метрополитен: [if properties.metro]да[else]нет[endif]</p>'
);

Макеты можно размещать в специальном хранилище layout.storage и в дальнейшем извлекать их оттуда по ключу.

var myBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(...);
ymaps.layout.storage.add('my#simplestBCLayout', MyBalloonContentLayoutClass);
var myPlacemark = new ymaps.Placemark(
    ...
    {balloonContentLayout:  'my#simplestBCLayout'}
);

Шаблоны могут включать в себя определенные ранее макеты. В приведенных примерах переопределяется макет содержимого балуна, который изначально включает в себя три макета: для заголовка, тела и нижнего колонтитула.

Для включения в шаблон макета используются подстановки вида [[название_класса_макета]] и [[ключ_макета_в_хранилище]].

var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '$[[options.balloonContentLayout]]<p>...</p>$[[my#simplestBCLayout]]' 
);