Блог API Яндекс.Карт

Текстовые шаблоны

Внешний вид объектов на карте можно менять с помощью стилей. Подробнее о работе со стилями рассказано в статье Изменение внешнего вида объектов. Однако, в стили вынесены только общие свойства объектов (смена значка у метки, стиль рисования ломанной и т.д.). Этих возможностей может не хватить, если необходимо, чтобы внешних вид объектов сильно отличался от стандартного. Эту проблему призваны решить текстовые шаблоны.

Текстовый шаблон – это HTML-строка (верстка), которая может содержать элементы вида $[имя_поля|значение_по_умолчанию]. Такие элементы заменяются данными из объекта-контекста, который передается в метод build() при разборе конкретного шаблона.

Под объектом-контекстом понимается объект, из которого должны браться данные для подстановки. Если объект не содержит данных, путь к которым указан в элементе, то элемент будет заменен пустой строкой или значением по умолчанию, если оно указано. Значение по умолчанию указывается сразу после символа "|".

Создадим свой шаблон для значка метки.

// Создание текстового шаблона для метки
var template = new YMaps.Template('<div><img src="http://info.maps.yandex.net/api/i/steelblue/dot.png"/>\
<div class="b-point-name">$[name|0]</div></div>');

Свяжем стиль с созданным текстовым шаблоном и применим его к метке.

// Создание стиля для значка метки
var styleIcon = new YMaps.Style();
 
// В конструктор стиля значка метки передается указатель на текстовый шаблон
styleIcon.iconStyle = new YMaps.IconStyle(template);
 
// Создание метки
var placemark = new YMaps.Placemark(map.getCenter(), {style: styleIcon});
placemark.name = 5;
 
// Добавление метки на карту
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

Примечание. Текстовые шаблоны можно добавлять в хранилище, тогда обращаться к ним можно будет по ключу. Это может потребоваться в том случае, если шаблоны создаются после определения стилей.
 
YMaps.Templates.add("example#customPointIcon", template);
 
Тогда создание стиля можно будет записать так:
 
styleIcon.iconStyle = new YMaps.IconStyle("example#customPointIcon");
 

Таким образом значок для метки может быть не только изображение, а любое html-содержимое, которое будет задано в текстовом шаблоне.

Например, рассмотрим следующую задачу: для каждой метки в балуне нужно выводить заголовок зеленым цветом, а под описанием объекта – размещать логотип компании.
Можно решить эту задачу, записав необходимый html для каждого объекта в поля name и desctiption. Тогда определение содержимого одной метки будет выглядеть примерно так:

// Создание метки
var placemark = new YMaps.Placemark(map.getCenter());
 
// Определение содержимое балуна метки
placemark.name = '<span style="color: green">Имя объекта</span>';
placemark.description = '<div>Описание объекта</div><img src="http://img.yandex.ru/i/m_logo.png" alt=""/>';
 
// Добавление метки на карту
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

Однако, если таких объектов будет много (например, около сотни), то для того, чтобы изменить оформление выводимой информации (например, убрать логотип компании из описания объекта), необходимо будет изменить сотню строчек кода. Это неудобно. Лучше для этих целей создать текстовый шаблон содержимого балуна и применить его ко всем меткам.

Рассмотрим подробнее текстовый шаблон балуна по умолчанию.

<b>$[name]</b><div>$[description]</div>

Элементы name и description будут браться из объекта контекста. Если вызвать метод openBalloon() у метки, то объектом-контекстом будет сама метка.

var placemark = new YMaps.Placemark(map.getCenter());
placemark.name = "Имя объекта";
placemark.description = "Описание объекта";
 
map.addOverlay(placemark);
placemark.openBalloon();

 В итоге после построения шаблона балун будет иметь следующее содержимое:

<b>Имя объекта</b><div>Описание объекта</div>

Изменим текстовый шаблон содержимого балуна и на его основе создадим стиль. Стили можно создавать как обычные объекты JavaScript, поэтому воспользуемся этой возможностью для сокращения записи.

var style = {
    balloonContentStyle : {
        template : new YMaps.Template('<b style="color: green">$[name]</b><div>$[description]</div>\
        <img src="http://img.yandex.ru/i/m_logo.png" alt=""/>')
    }
}

Теперь применим созданный стиль к метке.

var placemark = new YMaps.Placemark(map.getCenter(), {style: style});
placemark.name = "Имя объекта";
placemark.description = "Описание объекта";
 
map.addOverlay(placemark);

 Посмотреть пример на отдельной странице 

В итоге получен результат такой же, как если html был записан в поля name и description. Текстовые шаблоны позволяют избавляться от дублирования код (в текстовый шаблон можно вынести все повторяющиеся элементы, например, цвет заголовка и логотип компании).

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

Например, стоит задача: разместить на карте местоположения складов, а в балуне указывать количество единиц товара, которые на них в настоящее время присутствует. Если товара нет (количество единиц товара равно нулю), то необходимо вывести сообщение «нет в наличии». Дополнительную информацию необходимо размещать в поле metaDataProperty, чтобы избежать перекрытия стандартных полей и методов.

var style = {
    balloonContentStyle : {
        template : new YMaps.Template('<b>$[name]</b><div>$[description]</div>\
        <div>Количество товара: $[metaDataProperty.anyMetaData.count|нет в наличии]</div>')
    }
}
 
var placemark = new YMaps.Placemark(map.getCenter(), {style: style});
placemark.name = "Склад № 1";
placemark.description = "Центральный склад, расположенный в центре карты";
 
// Добавление дополнительной информации
placemark.metaDataProperty = {
    count : 100
}
 
map.addOverlay(placemark);

Если не определить поле placemark.metaDataProperty.count, то будет выведено сообщение по умолчанию «нет в наличии».
Посмотреть пример на отдельной странице

Использование текстовых шаблонов позволяет гибко изменять внешний вид объектов на карте и создавать оверлеи с уникальным внешним видом. Также в шаблоны можно вынести общую информацию и верстку для всех объектов, избавляясь от дублирования кода и делая код более гибким и универсальным