Templates

Templates are used for generating custom HTML representations of geo objects, balloons and hints. For example, if you need to display markers using not only an image with a shadow, but with text as well, you will need to construct an appropriate template for the text and enable it in the style that is used for displaying markers.

To define the template, use the repr:Template element, which contains the HTML code (the template body) inside the repr:text container.

<repr:Template gml:id="hintTemplate">  <repr:text><div style="color:blue">Hint</div></repr:text></repr:Template>

In many cases, the style does not allow you to change the visual appearance of an object in any other way, besides using a template (for example, see repr:balloonContentStyle).

The template is an integral part of the style that the geographical object or collection references.

When using a template, the value of any XML element that is located inside a ymaps:GeoObject or ymaps:GeoObjectCollection element can be accessed by calling the corresponding variable.

To define variables, use strings of the type $[variable_name|default_value].

The variable name is the location of this XML element inside the element that the style is applied to. The location is set by listing in order the names of all the parent elements and the name of the element itself; a dot is used as a separator.

Let's assume that the description of the geographical object looks like this:

<GeoObject>
  <gml:name>Офис Яндекса в Стамбуле</gml:name>
  <gml:metaDataProperty>
     <AnyMetaData>
       <address>Büyükdere Caddesi No. 191, Levent, 34330, Istanbul, Turkey (Apa Giz Plaza, Kat 21)</address>
       <phone>212 386 87 60</phone>
       <fax>212 284 46 48</fax>
      </AnyMetaData>
  </gml:metaDataProperty>
  <gml:Point>
    <gml:pos>29.011798 41.079515</gml:pos>
  </gml:Point>
</GeoObject>

Then the balloon template that displays the name of the object, the address, and the phone number of the office, might look like this:

<Template gml:id="balloonTemplate">
  <text>
    <div style="font-size:12px;">
      <div style="color:#ff0303;font-weight:bold">$[name]</div>
      <div>Address: $[metaDataProperty.AnyMetaData.address]</div>
      <div>Telephone: $[metaDataProperty.AnyMetaData.phone|none]</div>
  <text>
</Template>

If the office phone is not specified (i.e. delete the "phone" element from the example provided), the string “none” will be displayed in place of the phone number.

There are several rules restricting the use of certain HTML elements and attributes in template text. The list of restrictions is provided in the following table.

Restrictions on HTML usage in templates
Script and iframe elements are ignored

Any script and iframe elements are removed together with their contents.

Example:

<div><script>alert(\"XSS\")"</script></div>

is replaced with

<div />
Attributes that are responsible for calling event handlers are ignored

Attributes that are responsible for calling event handlers (onclick, onchange, onkeypress, etc.) are removed from elements together with their contents.

Example:

<div onclick="alert(\"XSS\")">$[name]</div>

is replaced with

<div>$[name]</div>
The class attribute is ignored

The class attribute is removed from elements together with its contents.

Example:

<div class="login">$[name]</div>

is replaced with

<div>$[name]</div>
The schema must be defined in the href attribute of the link URL; the javascript schema is ignored

If the link URL does not specify the schema (protocol) or uses the javascript schema, the href attribute is removed together with its contents.

Example:

<a href="$[metaDataProperty.AnyMetaData.test.a]">link</a>

is replaced with

<a>link</a>
The "position:absolute" property for the "style" attribute is ignored

If the "style" attribute contains the "position:absolute" property, this property is removed.

Example:

<div style="position:absolute">$[name]</div>

is replaced with

<div>$[name]</div>
CSS expressions are ignored

If the "style" attribute contains CSS expressions (only supported by Internet Explorer up to version 8), it is removed together with its contents.

Restrictions on HTML usage in templates
Script and iframe elements are ignored

Any script and iframe elements are removed together with their contents.

Example:

<div><script>alert(\"XSS\")"</script></div>

is replaced with

<div />
Attributes that are responsible for calling event handlers are ignored

Attributes that are responsible for calling event handlers (onclick, onchange, onkeypress, etc.) are removed from elements together with their contents.

Example:

<div onclick="alert(\"XSS\")">$[name]</div>

is replaced with

<div>$[name]</div>
The class attribute is ignored

The class attribute is removed from elements together with its contents.

Example:

<div class="login">$[name]</div>

is replaced with

<div>$[name]</div>
The schema must be defined in the href attribute of the link URL; the javascript schema is ignored

If the link URL does not specify the schema (protocol) or uses the javascript schema, the href attribute is removed together with its contents.

Example:

<a href="$[metaDataProperty.AnyMetaData.test.a]">link</a>

is replaced with

<a>link</a>
The "position:absolute" property for the "style" attribute is ignored

If the "style" attribute contains the "position:absolute" property, this property is removed.

Example:

<div style="position:absolute">$[name]</div>

is replaced with

<div>$[name]</div>
CSS expressions are ignored

If the "style" attribute contains CSS expressions (only supported by Internet Explorer up to version 8), it is removed together with its contents.