Template

Templating engine. The Yandex Maps API supports the base syntax for the Twig/Django Templates languages. The following operations are supported:

  • Substitution value - {{ field_name }}.

  • If the requested data field is missing or has an empty value you can provide the default value - {{ field_name|default:default_value }} The default value can be a number, a string (in quotes) or a different data field.

  • By default the value is processed by the escape function to prevent XSS vulnerabilities. To undo this behavior, add the "raw" filter - {{ field_name|default: default_value|raw }}.

  • You can use the template.filtersStorage to create your own filters and use them as described above.

  • To insert a sub layout, use a construction like {% include field_name_or_key %}. The templating engine when it founds such a construction, will try to use the value in the field as a key of the nested layout.

  • The condition is written as:

    {% if condition %} ... {% else %} ... {% endif %}
    

    or you can ommit the else or elseif block. You can use any constructions of the template language inside if, else and elseif blocks.

  • Use the for construction to iterate an array or an object.

    {% for value in array_or_hash %} ... {% endfor %}
    

    You can use any constructions of the template language inside the for block.

  • To obtain the iteration index in the array or the field name in the hash, use the following construction:

    {% for key, value in array_or_hash %} ... {% endfor %}
    
  • You can turn on an additional security check for dangerous 'onload' and 'onerror' attributes by including the sanitize comment in your template. With this comment template builder will throw error if it meets one of these attributes, without it there will be a warning in console.

Constructor | Methods

Constructor

Template(text)

Parameters:

Parameter

Default value

Description

text*

Type: String

Template string

* Mandatory parameter/option.

Examples:

1.

// Getting the user name from the data manager data.Manager.
// If the name is not specified, the result string will be "Unregistered user".
var data = new ymaps.data.Manager({
    user: {
        name: "Viktor",
        age: 25
    },
    home: [55.72725771214265, 37.640390506634006]
});

var template = new ymaps.Template('{{ user.name |default: "Unregistered user"}}');
var result = template.build(data);
console.log(result.text); // Outputs "Viktor" to the console.

2.

// Let's assume we have 3 user groups and we need to print an individual greeting for each group.
var data = new ymaps.data.Manager({
    groups: {
        administrator: {
            id: 1,
            name: "administrator"
        },
        moderator: {
            id: 2,
            name: "moderator"
        },
        user: {
            id: 3,
            name: "user"
        }
    },
    userGroupId: 2
});
var template = new ymaps.Template('Hi, \
    {% if (userGroupId == 1) %}{{ groups.administrator.name }}\
    {% elseif (userGroupId == 2) %}{{ groups.moderator.name }}\
    {% elseif (userGroupId == 3) %}{{ groups.user.name }}\
    {% else %}guest{% endif %}!'
);

var result = template.build(data);
console.log(result.text); // Outputs "Hi, moderator!" to the console.

3.

// Using sanitize comment
var template = new ymaps.Template('<!--sanitize--><div>Hello!</div>');

Methods

Name

Returns

Description

build(data)

Object

Returns object with following fields:

  • {String} text — the result of templating.
  • {Object[]} renderedValues - an array with the used data from the manager.

Methods details

build

{Object} build(data)

Returns object with following fields:

  • {String} text — the result of templating.
  • {Object[]} renderedValues - an array with the used data from the manager.

Parameters:

Parameter

Default value

Description

data*

Type: IDataManager

Data manager.

* Mandatory parameter/option.

Example:

// Get a house address from the existing coordinates and follow the template to output
// all its inhabitants in the format: "name: age".
var data = new ymaps.data.Manager({
    users: [
        {name: "Vitaly", age: 40},
        {name: "George", age: 20}
    ],
    home: {
        coords: [55.736652, 37.620589],
        address: null
    }
});
var template = new ymaps.Template('{{home.address}}: <ul>{% for user in users %}<li>{{user.name}}: {{user.age}}</li>{% endfor %}</ul>');

// Perform reverse geocoding using geocode.
ymaps.geocode(data.get('home.coords')).then(function (res) {
    var address = res.geoObjects.get(0).properties.get('name');
    // Set the obtained address in the manager.
    data.set('home.address', address);

    // Fill in the template with the obtained data.
    var result = template.build(data);
    // Output the result to the console.
    console.log(result.text);
});