Yandex.Maps API Guide to the YMapsML language 15.05.2015 Yandex.Maps API. Guide to the YMapsML language. Version 1.0 Document build date: 15.05.2015. This volume is a part of Yandex technical documentation. Yandex helpdesk site: http://help.yandex.ru © 2008—2015 Yandex LLC. All rights reserved. Copyright Disclaimer Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support, and usage of the service Yandex.Maps API. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws. You may use Yandex.Maps API or its components only within credentials granted by the Terms of Use of Yandex.Maps API or within an appropriate Agreement. Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws. Contact information Yandex LLC http://www.yandex.com Phone: +7 495 739 7000 Email: [email protected] Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021 Contents Overview .............................................................................................................................................................................................. 4 GML, YMapsML and KML ................................................................................................................................................................ 4 YMapsML usage .................................................................................................................................................................................. 4 Structure of YMapsML ..................................................................................................................................................................... 8 Geographical objects and collections ......................................................................................................................................... 10 Metadata ..................................................................................................................................................................................... 12 Geometric and geographical data ............................................................................................................................................... 13 Representation of maps and objects on a map ........................................................................................................................... 13 Map parameters .................................................................................................................................................................................. 14 Rendering geographical objects ...................................................................................................................................................... 18 Setting geometric and geographical data ................................................................................................................................... 18 Setting the visual appearance of displayed objects ............................................................................................................... 20 Styles .................................................................................................................................................................................. 20 Templates ........................................................................................................................................................................... 23 Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 4 Overview YMapsML (Yandex Maps Markup Language) is a language developed by the company Yandex for describing geographical data. The term "geographical data" refers to any data that is geographically connected with a place. YMapsML is used as the format for transferring data between Yandex.Maps services and third-party software. Data in YMapsML format can be displayed on Yandex.Maps, and the geocoding service uses the same format for returning information about the location of objects. YMapsML is an open XML format; the formal specification (schema) is available at http://maps.yandex.ru/ schemas/ymaps-1.x/ymaps.xsd, and a description is provided in the YMapsML Reference. For editing data in YMapsML format, you can use any text editor; for processing data, choose from the wide variety of software available for working with XML. GML, YMapsML and KML The industry standard for describing geographical data is GML — Geographic Markup Language. GML is developed and maintained by the OGC (Open Geospatial Consortium) and is an international ISO standard. The first version of the language was released in 2000, and the third, most recent version, in 2007. GML contains a large number of elements and geographical objects can be described in great detail. However, the price to be paid for universality is a complex language, a significant amount of data to transfer, and more computing resources. There are two main ways to adapt GML to specific tasks: profiling, and developing “application schemas”. With the first method, the necessary subset of elements is pulled out of the GML schema using GML's own resources. With the second method, a new schema is created that contains its own elements along with GML elements. The first method is for creating simpler versions of GML, while the second is for creating formats that are optimized for particular tasks. Recently, KML (Keyhole Markup Language) has become more popular as a language for describing geographical data; it was developed by the company Keyhole for the Keyhole Earth Viewer. In 2004, Google acquired Keyhole, and Keyhole Earth Viewer was renamed Google Earth. KML is not an application schema or a GML profile; the KML specification is defined by its native schema. This schema borrows several elements from GML that describe the geometry of geographical objects. KML is used as a geographical data format for Google Earth and the Google Maps services. Parallel to the development of KML, which was a closed format until recently, Yandex was developing the YMapsML language as a GML application schema for its own geoinformation services. In 2008, KML was published as an OGC standard. In the same year, the YMapsML specification and the Yandex.Maps API were published, enabling the use of this language when accessing Yandex geoinformation services. When compared with KML, the distinctive features of YMapsML are its simplicity and better stylization, which uses a system of styles and templates to define the visual appearance of objects being displayed. The simplicity of YMapsML is due to the lack of three-dimensional descriptions of geographical data (KML is used in Google Earth, which works with 3D models). Data in YMapsML format is handled correctly by most software that works with the third version of GML. YMapsML usage YMapsML is an open, documented and simple XML language for describing geographical data. The Yandex.Maps JavaScript API provides ways to automatically load information from YMapsML files and display it on a map. Yandex projects that involve cartographic services use this format to exchange data. The Yandex.Maps geocoding service accepts calls over the HTTP protocol and returns the response in YMapsML format. Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 5 Based on the information provided here, we can define the main uses for YMapsML: 1. Generating a YMapsML file and displaying the information contained in it via the JavaScript API. Creating a YMapsML file is easy — just use any text editor to enter the necessary information in accordance with the language specification. To get an idea of what a YMapsML file looks like, see the examples provided in this guide. These examples are convenient to use as starting points for your own experiments. Of course, manual editing of YMapsML files is fairly rare. The files are usually generated automatically, for example, based on the information contained in a database. YMapsML is an XML format. Almost all modern programming languages and development environments include tools for presenting data in XML. So automatic generation of YMapsML files is not a particularly difficult task. Currently, a large amount of geographical data is presented in XML formats. This can be shown by the large number of languages that are GML application schemas or profiles. It doesn't require much effort to display this type of data on Yandex.Maps — it is sufficient to convert them to YMapsML format (for example, using XSLT). On the Examples page you can see an example of Yandex.Maps displaying earthquake information, where the earthquake data is originally supplied in GeoRSS format. YMapsML is used as a transitional format that is easy to convert GeoRSS feeds to. 2. Exporting information from user maps in the My Maps service. The My maps service gives users the opportunity to create and save personal maps that display sections of an area with markers placed on them. 3. Getting information from the geocoding service via HTTP request. The geocoding service can determine the coordinates of a geographical object and get information about it, based on its name or address. And vice-versa, the address of an object on a map can be determined by its coordinates — reverse geocoding. Results are returned in YMapsML format. This means that objects that are found can immediately be placed on Yandex.Maps. In addition, the resulting data is easy to analyze visually or extract using software. 4. Displaying geographical data in YMapsML by third-party geoinformation services. Since YMapsML is a standard GML application schema, data in this format can be displayed and processed using software that supports GML version 3, such as Gaia, Mapserver, or OpenLayers. 5. Using YMapsML as a storage format for geographical data. YMapsML can be used when geographical data needs to be in a format that is convenient for both use and storage. Geographical data is often stored in databases, or in the internal notation of various software. If it is necessary to make reserve copies or transfer data to “external” programs, the issue arises of choosing a format for representing the information. In this case, YMapsML could be the right decision. Data in this format is easy to analyze visually, and can be processed by the Yandex.Maps API as well as software that supports GML 3.x. As an example, let's examine a basic YMapsML file. We will make this file accessible over HTTP, for example, at the address http://api.yandex.com.tr/maps/ymapsml/examples/xml/intro.xml. <?xml version="1.0" encoding="windows-1251"?> <ymaps:ymaps xmlns:ymaps="http://maps.yandex.ru/ymaps/1.x" xmlns:repr="http:// maps.yandex.ru/representation/1.x" xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maps.yandex.ru/schemas/ymaps/1.x/ymaps.xsd"> <ymaps:GeoObjectCollection> <gml:name>Mosques</gml:name> <gml:featureMembers> <ymaps:GeoObject> <gml:name>Sultan Ahmed Mosque</gml:name> Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 6 <gml:description>The Sultan Ahmed Mosque is popularly known as the Blue Mosque for the blue tiles adorning the walls of its interior.</ gml:description> <gml:Point> <gml:pos>28.976896 41.005346</gml:pos> </gml:Point> </ymaps:GeoObject> </gml:featureMembers> </ymaps:GeoObjectCollection> </ymaps:ymaps> The file contains information about the geographical object where Mikhail Bulgakov's novel begins. The position of the object is marked on the map by a dot with the specified geographical coordinates. To display the information, we will use the JavaScript API, which has built-in tools for displaying YMapsML files. To do this, we create the following HTML page (http://api.yandex.com.tr/maps/ymapsml/examples/ intro.html). <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http:// www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>YMapsML Examples. Displaying a geographical object</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script src="http://api-maps.yandex.ru/2.0/?load=package.full&lang=en-US" type="text/javascript"></script> <script type="text/javascript"> window.onload = function () { ymaps.ready(function () { var myMap = new ymaps.Map('map', { center: [41.010993, 28.966627], zoom: 8 }); //After the data in the YMapsML file is loaded, a callback function is called ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/ intro.xml") .then(function (res) { //Add a collection of geo objects to the map myMap.geoObjects.add(res.geoObjects); }, function (error){ // Called if the YMapsML file failed to load alert('Error: ' + error); }); }); } </script> </head> <body> <div id="map" style="width:600px;height:400px"></div> </body> </html> To load the YMapsMl file, the load method is used. After the data are loaded, the load method transforms them into a GeoObjectCollection object and passes the object reference to the handler function. When viewed in a browser, this page will look like this: Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 7 Yandex.Maps API Guide to the YMapsML language 8 Structure of YMapsML YMapsML documents consist of elements belonging to five namespaces: http://maps.yandex.ru/ymaps/1.x, http://maps.yandex.ru/representation/1.x, http://www.opengis.net/gml, http://maps.yandex.ru/attribution/1.x and http://www.w3.org/2005/Atom. We will assume that the prefixes ymaps, repr, gml, attr and atom correspond to these namespaces, and we will be identifying the namespaces by their prefixes. The table below shows the original namespaces: Namespace Schema URL Definition ymaps http://maps.yandex.ru/ymaps/1.x A language for representing geographical data in the form of abstract geographical objects and collections. gml http://www.opengis.net/gml GML – the geography description standard. repr http://maps.yandex.ru/representation/ 1.x Contains rules for displaying geographical objects on Yandex maps. attr http://maps.yandex.ru/attribution/1.x Contains details on who provided information about an organization that is shown on Yandex maps. atom http://www.w3.org/2005/Atom Atom is a syndication format for describing sets of web resources. Each YMapsML element contains either one or more elements from the specified namespaces, or text, which in any case can include HTML code. HTML markup is always “shown on the screen”, meaning it is displayed as text in the browser. The exception is HTML code that is contained in the gml:description and repr:text elements located inside repr:Template. This code is interpreted by the browser and rendered as formatted text. Let's look at the structure of a YMapsML document. Yandex.Maps API Guide to the YMapsML language 9 The root element of a document is the ymaps:ymaps element. It can contain attr:Attribution elements, one ymaps:GeoObjectCollection element and one repr:Representation element. Any of these elements may be omitted, or even all three may be omitted. The last case is a bit exotic. An “empty” document is usually used as a draft to be filled in later. The top-level ymaps:GeoObjectCollection element is a container for all the geographical objects and their collections that are included in the document. The repr:Representation element is used for defining the visual appearance of these objects, as well as for setting map parameters. The attr:Attribution element contains details on who provided information about an organization that is shown on Yandex maps. The YMapsML document that is provided as an example in the section YMapsML usage contains the ymaps:GeoObjectCollection element, but does not contain the repr:Representation element. This means that Yandex.Maps API Guide to the YMapsML language 10 when displaying this document via the JavaScript API, the map display parameters and the visual appearance of geographical objects will be determined automatically. Geographical objects and collections To describe geographical objects in YMapsML, we use the ymaps:GeoObject element. A population of geographical objects can be put together in a collection, using the ymaps:GeoObjectCollection element to describe it. To provide compatibility with the GML standard, each of these elements is wrapped in one of the container elements — gml:featureMember or gml:featureMembers. The only exception is the ymaps:GeoObjectCollection element, which is located in the ymaps:ymaps root element. The difference between these containers consists of the following. The gml:featureMember element can contain either a single object description (ymaps:GeoObject), or a single collection description (ymaps:GeoObjectCollection). The gml:featureMembers element can contain any number of descriptions of geographical objects or collections. The structure of a ymaps:GeoObject element containing a description of a geographical object appears as follows. Yandex.Maps API Guide to the YMapsML language 11 Yandex.Maps API Guide to the YMapsML language 12 The geographical object can be matched to the following data: 1. Metadata. 2. Geometric and geographical data. 3. Information about the visual representation of a geographical object. 4. Information about who provided data about an organization. Collections can be used to group together both geographical objects and collections themselves. Considering the information above that ymaps:GeoObject and ymaps:GeoObjectCollection elements are enclosed in gml:featureMember and gml:featureMembers containers, the structure of the ymaps:GeoObjectCollection elements will look rather predictable. Metadata When working with geographical objects and collections, it is often helpful to give them names and descriptions and supply them with other additional information. Any data that describes geographical objects or groups of them and is not related to geometric or geographical data will be referred to as metadata. Yandex.Maps API Guide to the YMapsML language 13 The following elements are provided for placing metadata about geographical objects and collections in YMapsML: 1. gml:name — Name of a geographical object or collection. 2. gml:description — Description of a geographical object or collection. May contain HTML code. Restrictions on using HTML code in the gml:description element are the same as the restrictions that apply to using HTML code in templates. 3. gml:metaDataProperty — Any other metadata in XML format describing a geographical object or collection. The gml:metaDataProperty element contains ymaps:AnyMetaData, where data is placed. Geometric and geographical data The following elements are used for describing geometric properties of objects and their geographical coordinate positioning: 1. gml:Point — Geometric point. It is used in cases when the shape and size of a geographical object are not important. The position of the point is set using geographical coordinates. 2. gml:LineString — Polyline (line). Defined by setting the geographical coordinates of its points. 3. gml:LinearRing — Closed polyline (line). Defined by setting the geographical coordinates of its points. It is automatically closed by connecting the first and last points. 4. gml:Polygon — Polygon. A shape that has closed polylines for both its interior and exterior edges. It is defined by setting the geographical coordinates of the points on the polylines that make up the polygon boundaries. All polylines are automatically closed by connecting the first and last points. Note: The GML standard assumes that the first and last points of closed polylines are the same. Automatically closing polylines is a feature of the Yandex.Maps JavaScript API. All the elements listed can be displayed using built-in tools in the JavaScript API. Another type of geographical data is a polygon outline. A polygon outline of an object or collection is a polygon that has a geographical object (or all the objects in a collection) inside it. To create this type of polygon, the gml:boundedBy element is used. If this element is located inside the ymaps:GeoObject and ymaps:GeoObjectCollection elements, it is purely informative and does not directly affect the display of objects on the map. If the gml:boundedBy element is inside the repr:View element, it determines the map viewport. Representation of maps and objects on a map YMapsML has elements that let you define map parameters and the visual appearance of objects displayed on a map. To set map parameters, the repr:View element is used. You can use it to set the map type and viewport. When displaying YMapsML via the JavaScript API, each geographical object that has geographical and geometric data specified is represented by one or more visual objects: markers, polylines or polygons. The visual appearance of geographical objects is preset, but you can change it by using styles and templates. Styles let you define or redefine certain parameters for displaying geographical objects, as well as create custom HTML representations using templates. To set styles, the repr:Style element is used; for templates, the repr:Template element is used. Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 14 Map parameters You can use YMapsML to set the map type and viewport. The repr:View element is intended for this. The Yandex.Maps API supports showing three built-in types of maps: • MAP — “Roadmap” map type. Schematic view of the objects in an area. Used by default. • SATELLITE — “Satellite” map type. A satellite map of the area. • HYBRID — “Hybrid” map type. Satellite map of an area with names of geo objects overlayed on it. The repr:mapType element can contain one of the map type identifiers provided in the list. The map viewport is a rectangular area that is defined by setting the coordinates of the upper and lower points. To set the viewport for a map, the gml:boundedBy element is used. Consider the following example. We'll put all the map types that are supported by the service on the HTML page for the map — “roadmap”, “satellite” and “hybrid” — and set a viewport for each of them. maptypes.html (http://api.yandex.com.tr/maps/ymapsml/examples/maptypes.html) <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http:// www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>YMapsML examples. Map parameters</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <script src="http://api-maps.yandex.ru/2.0/?load=package.full&lang=en-US" type="text/javascript"></script> <script language="JavaScript" type="text/javascript"> window.onload = function () { ymaps.ready(function() { // The "Map" map type var mapMap = new ymaps.Map('mapTypeId', { center: [39.92751, 32.86437], zoom: 8 }); ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/ maptype.xml") .then(function (res) { if (res.mapState) { // Changes the map parameters res.mapState.applyToMap(mapMap); } }); // The "Satellite" map type var mapSatellite = new ymaps.Map('satelliteTypeId', { center: [39.92751, 32.86437], zoom: 8 }); ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/ satellitetype.xml") Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 15 .then(function (res) { if (res.mapState) { // Changes the map parameters res.mapState.applyToMap(mapSatellite); } }); // The "Hybrid" map type var mapHybrid = new ymaps.Map('hybridTypeId', { center: [39.92751, 32.86437], zoom: 8 }); ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/ hybridtype.xml") .then(function (res) { if (res.mapState) { // Changes the map parameters res.mapState.applyToMap(mapHybrid); } }); }); } </script> </head> <body> <div id="mapTypeId" style="width:640px; height:400px;"></div> <div id="satelliteTypeId" style="width:315px; height:200px; float: left; margin: 10px 10px 0 0"></div> <div id="hybridTypeId" style="width:315px; height:200px; float: left; margin: 10px 0 0 0"></div> </body> </html> maptype.xml (http://api.yandex.com.tr/maps/ymapsml/examples/xml/maptype.xml) <?xml version="1.0" encoding="UTF-8"?> <ymaps:ymaps xmlns:ymaps="http://maps.yandex.ru/ymaps-1.x" xmlns:gml="http:// www.opengis.net/gml"> <repr:Representation xmlns:repr="http://maps.yandex.ru/representation-1.x"> <repr:View> <repr:mapType>MAP</repr:mapType> <gml:boundedBy> <gml:Envelope> <gml:upperCorner>32.765636 39.978172</gml:upperCorner> <gml:lowerCorner>32.95927 39.89288</gml:lowerCorner> </gml:Envelope> </gml:boundedBy> </repr:View> </repr:Representation> </ymaps:ymaps> satellitetype.xml (http://api.yandex.com.tr/maps/ymapsml/examples/xml/satellitetype.xml) Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 16 <?xml version="1.0" encoding="UTF-8"?> <ymaps:ymaps xmlns:ymaps="http://maps.yandex.ru/ymaps-1.x" xmlns:gml="http:// www.opengis.net/gml"> <repr:Representation xmlns:repr="http://maps.yandex.ru/representation-1.x"> <repr:View> <repr:mapType>SATELLITE</repr:mapType> <gml:boundedBy> <gml:Envelope> <gml:upperCorner>32.823858 39.951596</gml:upperCorner> <gml:lowerCorner>32.893553 39.916715</gml:lowerCorner> </gml:Envelope> </gml:boundedBy> </repr:View> </repr:Representation> </ymaps:ymaps> hybridtype.xml (http://api.yandex.com.tr/maps/ymapsml/examples/xml/hybridtype.xml) <?xml version="1.0" encoding="UTF-8"?> <ymaps:ymaps xmlns:ymaps="http://maps.yandex.ru/ymaps-1.x" xmlns:gml="http:// www.opengis.net/gml"> <repr:Representation xmlns:repr="http://maps.yandex.ru/representation-1.x"> <repr:View> <repr:mapType>HYBRID</repr:mapType> <gml:boundedBy> <gml:Envelope> <gml:upperCorner>32.823858 39.951596</gml:upperCorner> <gml:lowerCorner>32.893553 39.916715</gml:lowerCorner> </gml:Envelope> </gml:boundedBy> </repr:View> </repr:Representation> </ymaps:ymaps> When viewing the maptypes.html file in a browser, the map will look as follows. Yandex.Maps API Guide to the YMapsML language Guide to the YMapsML language 17 Yandex.Maps API Guide to the YMapsML language 18 Rendering geographical objects The Yandex.Maps service lets you put visual objects on maps: geo objects (markers, polylines and polygons), as well as balloons and popup hints. All YMapsML elements that are for describing geometric and geographical data have visual representations and are displayed using geo objects. The table shows the relationship between YMapsML elements and geo objects. YMapsML element and corresponding geometric Geo object and its name shape gml:Point ymaps.Placemark geometric point marker gml:LineString ymaps.Polyline polyline polyline gml:LinearRing ymaps.Polyline closed polyline polyline gml:Polygon ymaps.Polygon polygon polygon Setting geometric and geographical data The section Geometric and geographical data lists the elements that are used for defining geometric properties of geographical objects. Each element corresponds to a geometric shape and a geo object that is used for displaying this shape on the map. The geometric shape is bound to a locality by setting the coordinates of corresponding points. For a geometric point, its coordinates are set; for a polyline, the coordinates of its points; for a polygon, the coordinates of the points of the closed polylines that make up its exterior and interior edges. The coordinates of points and polyline points are set using the gml:pos and gml:posList elements. To specify coordinates that define the viewport or a polygon outline, the gml:lowerCorner and gml:upperCorner elements are used. To set the coordinates of a point, its longitude and latitude are listed in order and separated by a space. For example, <gml:pos>55.0298 82.9197</gml:pos>. This is how coordinates are set for points that are described using the gml:pos, gml:lowerCorner and gml:upperCorner elements. When setting coordinates for a sequence of points using the gml:posList element, pairs of point coordinates are separated by a space in the same way. For example, <gml:posList>55.0298 82.9197 55.0496 82.9694</ gml:posList>. Polyline and closed polyline To set the points of a polyline, either two or more gml:pos elements or the gml:posList element can be used. <ymaps:GeoObject> <gml:name>Polyline</gml:name> <gml:description>The coordinates for points on a polyline can be defined using two or more gml:pos elements</gml:description> <gml:LineString> <gml:pos>32.199411 58.601185</gml:pos> <gml:pos>32.189411 58.595185</gml:pos> </gml:LineString> </ymaps:GeoObject> Example: Yandex.Maps API Guide to the YMapsML language 19 YMapsML file: http://api.yandex.com.tr/maps/ymapsml/examples/xml/linestring.xml. HTML page: http://api.yandex.com.tr/maps/ymapsml/examples/linestring.html. <ymaps:GeoObject> <gml:name>Closed polyline</gml:name> <gml:description>The coordinates for points on a polyline can also be defined using the gml:posList element</gml:description> <gml:LinearRing> <gml:posList>37.178027 55.486953 38.040535 55.486953 38.040535 56.018499 37.178027 56.018499</gml:posList> </gml:LinearRing> </ymaps:GeoObject> Example: YMapsML file: http://api.yandex.com.tr/maps/ymapsml/examples/xml/linearring.xml. HTML page: http://api.yandex.com.tr/maps/ymapsml/examples/linearring.html. Polygon The exterior boundary of a polygon consists of a closed polyline, which is described using the gml:LinearRing element. <ymaps:GeoObject> <gml:name>Polygon</gml:name> <gml:description>The exterior boundary of a polygon consists of a closed polyline</gml:description> <gml:Polygon> <gml:exterior> <gml:LinearRing> <gml:posList>37.178027 55.486953 38.040535 55.486953 38.040535 56.018499 37.178027 56.018499</gml:posList> </gml:LinearRing> </gml:exterior> </gml:Polygon> </ymaps:GeoObject> In this example, the gml:LinearRing element is located inside the gml:exterior container. This reflects the fact that a polygon can have not only an exterior edge, but an interior edge as well (a "hole" inside the polygon). In addition, the number of interior holes is unlimited. The interior boundary of a polygon is also set using a closed polyline. The gml:LinearRing element is wrapped in the gml:interior container. In the current version of the Yandex.Maps API, the contents of the gml:interior element are not interpreted. A feature for processing interior edges of polygons is planned for one of the upcoming versions of the API. Example: YMapsML file: http://api.yandex.com.tr/maps/ymapsml/examples/xml/polygon.xml. HTML page: http://api.yandex.com.tr/maps/ymapsml/examples/polygon.html. Viewport and polygon outline The viewport and polygon outline of a geographical object or collection are described using the gml:boundedBy element. These areas are defined by setting the point coordinates of the lower left and upper right corners. To set point coordinates for the lower left corner, the gml:lowerCorner element is used, and for the upper right corner, the gml:upperCorner element is used. Yandex.Maps API Guide to the YMapsML language 20 <ymaps:GeoObject> <gml:name>Polyline</gml:name> <gml:description>A polygon outline can be set for a geographical object or collection</gml:description> <gml:boundedBy> <gml:Envelope> <gml:lowerCorner>45 60</gml:lowerCorner> <gml:upperCorner>30 50</gml:upperCorner> </gml:Envelope> </gml:boundedBy> <gml:LineString> <gml:pos>32.199411 58.601185</gml:pos> <gml:pos>32.189411 58.595185</gml:pos> </gml:LineString> </ymaps:GeoObject> An example of setting the viewport on a map is provided in the section Map parameters. Setting the visual appearance of displayed objects YMapsML lets you determine the visual appearance of objects displayed on a map. Since visualization of YMapsML elements is performed using geo objects that have a preset appearance, we are basically talking about changing the standard method of displaying geo objects. To change the visual appearance of displayed objects via YMapsML, styles are used. Styles let you set certain parameters for displaying geo objects and create a custom HTML representation using templates. To define styles, the repr:Style element is used; for templates, the repr:Template element is used. To specify which style should be applied when displaying a geographical object or collection, use the ymaps:style element. <ymaps:GeoObject> <gml:style>#customStyle</gml:name> <gml:Point> <gml:pos>27.431259 38.621162</gml:pos> </gml:Point> </ymaps:GeoObject> Here, #customStyle is a link to the ID of the repr:Style element that contains the style description. The link to the style ID is always prefixed by the “#” symbol. The link can reference a style located not only in the current file, but also in external YMapsML files that can be accessed over HTTP. In this case, the link to the style has the format <YMapsML file URL>#<template ID or inherited style ID>. <repr:style> http://api.yandex.com.tr/maps/ymapsml/examples/xml/ overlays_styles.xml#manisa </repr:style> An example of loading a style from an external file is provided on the http://api.yandex.com.tr/maps/ymapsml/ examples/ page. When defining a geographical object or collection, you can link to a style, but not to a template; in other words, it is incorrect to link to the repr:Templateelement. Templates are used to define the HTML representation of geo objects that use styles. Techniques for using templates are described in the section Templates. Styles Styles are used for changing the parameters of the standard representation of geo objects. For example, you can set the thickness of polyline lines or the fill color for polygons. styles.html (http://api.yandex.com.tr/maps/doc/doc/jsapi/2.x/examples/ymapsml/styles.html) Yandex.Maps API Guide to the YMapsML language 21 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http:// www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>YMapsML examples. Using styles</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <script src="http://api-maps.yandex.ru/2.0/?load=package.full&lang=en-US" type="text/javascript"></script> <script language="JavaScript" type="text/javascript"> window.onload = function () { ymaps.ready(function () { var myMap = new ymaps.Map('map', { center: [39.919948, 32.868109], zoom: 16 }); // Calls a callback function after the YMapsML data is loaded ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/ styles.xml") .then(function (res) { // Adds a collection of geo objects to the map myMap.geoObjects.add(res.geoObjects); }, function (error) { alert("Error when loading styles: " + error); }); }); } </script> </head> <body> <div id="map" style="width:640px; height:400px;"></div> </body> </html> styles.xml (http://api.yandex.com.tr/maps/doc/ymapsml/1.x/examples/xml/styles.xml) <?xml version="1.0" encoding="UTF-8"?> <ymaps:ymaps xmlns:ymaps="http://maps.yandex.ru/ymaps/1.x" xmlns:repr="http://maps.yandex.ru/representation/1.x" xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maps.yandex.ru/schemas/ymaps/1.x/ymaps.xsd"> <repr:Representation> <repr:Style gml:id="customStyle"> <repr:lineStyle> <repr:strokeColor>FF9911</repr:strokeColor> <repr:strokeWidth>7</repr:strokeWidth> </repr:lineStyle> </repr:Style> <repr:Style gml:id="customStyle1"> <repr:parentStyle>#customStyle</repr:parentStyle> <repr:lineStyle> <repr:strokeColor>FF0000</repr:strokeColor> </repr:lineStyle> </repr:Style> </repr:Representation> <ymaps:GeoObjectCollection> <gml:name>A polyline and its style</gml:name> <gml:featureMembers> <ymaps:GeoObject> <gml:name>Route</gml:name> <gml:description>A route shown as a polyline</gml:description> <gml:LineString> <gml:pos>32.86689 39.920241</gml:pos> <gml:pos>32.867639 39.919722</gml:pos> <gml:pos>32.868598 39.919121</gml:pos> Yandex.Maps API Guide to the YMapsML language 22 <gml:pos>32.868802 39.919052</gml:pos> <gml:pos>32.869596 39.918895</gml:pos> <gml:pos>32.870851 39.918681</gml:pos> <gml:pos>32.871474 39.918595</gml:pos> </gml:LineString> <ymaps:style>#customStyle1</ymaps:style> </ymaps:GeoObject> </gml:featureMembers> </ymaps:GeoObjectCollection> </ymaps:ymaps> When viewed in a browser, the styles.htm file will look as follows. Each type of geo object has its own YMapsML element (child of the repr:Style element) that is used for setting its display parameters. So, for example, to set display parameters for polylines and closed polylines, the repr:lineStyle element is used, while for markers, the repr:iconStyle or repr:iconContentStyle elements are used. Element defining a geo object Elements that define the appearance of geo objects, as well as balloons and hints gml:Point — Geometric point. Displayed using a marker repr:iconStyle — Marker icon parameters repr:iconContentStyle — Marker icon content repr:hintContentStyle — Link to a template that defines the contents of a popup hint that appears when hovering over the marker with the mouse repr:ballonContentStyle — Link to a template that defines the contents of a balloon that appears when clicking on the marker gml:LineString — Polyline repr:lineStyle — Line parameters repr:hintContentStyle — Link to a template that defines the contents of a popup hint that appears when hovering over the line with the mouse repr:ballonContentStyle — Link to a template that defines the contents of a balloon that appears when clicking on the line Yandex.Maps API Guide to the YMapsML language 23 Element defining a geo object Elements that define the appearance of geo objects, as well as balloons and hints gml:LinearRing — Closed polyline repr:lineStyle — Parameters of a line that connects the points of a polyline repr:hintContentStyle — Link to a template that defines the contents of a popup hint that appears when hovering over the closed polyline with the mouse repr:ballonContentStyle — Link to a template that defines the contents of a balloon that appears when clicking on the closed polyline gml:Polygon — Polygon repr:polygonStyle — Parameters of closed polylines that define the boundaries of a polygon and its background color repr:hintContentStyle — Link to a template that defines the contents of a popup hint that appears when hovering over the polygon with the mouse repr:ballonContentStyle — Link to a template that defines the contents of a balloon that appears when clicking on the polygon YMapsML supports style inheritance. This makes it possible for a style to use parameters and templates defined earlier in a different style. To indicate an inherited style, the repr:parentStyle element is used. <repr:Style gml:id="styleHospital"> <repr:parentStyle>#commonStyle</repr:parentStyle> </repr:Style> An example of style inheritance is provided on the http://api.yandex.com.tr/maps/doc/ymapsml/1.x/examples/ page. Styles can link to templates. If a style links to a template, the parameters that are set in it do not affect the visual appearance of the object being displayed using this style. However, these parameters can be used in the template itself. A link to a template is set using the repr:template element. <repr:Style gml:id="offices"> <repr:balloonContentStyle> <repr:template>#balloonTemplate</repr:template> </repr:balloonContentStyle> </repr:Style> The template and inherited style can be located not only in the current file, but also in external YMapsML files that can be accessed over HTTP. In this case, the link to them has the format <YMapsML file URL>#<template ID or inherited style ID>. <repr:template> http://api.yandex.com.tr/maps/ymapsml/examples/xml/ ballooncontentstyle.xml#balloonTemplate </repr:template> or <repr:parentStyle> http://api.yandex.com.tr/maps/ymapsml/examples/xml/ ballooncontentstyle.xml#offices </repr:parentStyle> 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. Yandex.Maps API Guide to the YMapsML language 24 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>Yandex office on Samokatnaya street</gml:name> <gml:metaDataProperty> <AnyMetaData> <address>1 Samokatnaya Street, building 21, Moscow, 111033</address> <phone>+7 495 739-70-00</phone> <fax>+7 495 739-70-70</fax> </AnyMetaData> </gml:metaDataProperty> <gml:Point> <gml:pos>37.678514 55.758255</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 /> Yandex.Maps API Guide to the YMapsML language 25 Attributes that are responsible for calling event handlers Attributes that are responsible for calling event handlers are ignored (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 If the link URL does not specify the schema (protocol) or uses URL; the javascript schema is ignored 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 If the "style" attribute contains the "position:absolute" is ignored property, this property is removed. Example: <div div> style="position:absolute">$[name]</ is replaced with <div>$[name]</div> CSS expressions are ignored Yandex.Maps API If the "style" attribute contains CSS expressions (only supported by Internet Explorer up to version 8), it is removed together with its contents. Guide to the YMapsML language Yandex.Maps API Guide to the YMapsML language 15.05.2015
© Copyright 2024