API Mapy.cz - Manuál

Manuál

Používat API mapy.cz lze při splnění licenčních podmínek na základě vygenerovaného javascriptu , který připojíte ke stránce. API bude funkční v podporovaných prohlížečích.

Obsah

První kroky
Nastavení stupně příblížení a středu
Nastavení interakce
Přidání značky do mapy
Přidání více značek, interakce značek
Přidání ovládacích prvků
Ukázka ovládání dvou map

První kroky

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns:v="urn:schemas-microsoft-com:vml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>mapy API 0.1</title>
    <script type="text/javascript" src="http://api.mapy.cz/main?key=15f8a4181&ver=3&encoding=utf-8">
    </script>
  </head>
  <body>
    <div id="mojeMapa" style="width:640px;height:480px;border:1px solid silver;"></div>
    <script type="text/javascript">
      //<![CDATA[
      if(SZN.isSupported){
          var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
       }
      //]]>
    </script>	  
  </body>
</html>

Do stránky vložíte kód, který jste získali po vygenerování klíče, např.:
```
<script type="text/javascript" src="http://api.mapy.cz/main?key=vas_klic&ver=3&encoding=utf-8">
</script>
```
Optimální je vložít kód do sekce HEAD ve stránce

Kód nelze přidávat do stránky až po jejím načtení, (používá se v něm volání "document.write()")
Ve stránce vytvoříte HTML element, který bude obsahovat vlastní mapu:
```
<div id="mojeMapa" style="width:640px;height:480px;border:1px solid silver;"></div>
```
Prvek, který má obsahovat mapu nesmí mít žádný rozměr menší než 400px a větší než 2000px.
Na libovolné místo ve stránce za prvkem který má obsahovat mapu vložíte volání funkce, která mapu vykreslí.
Ke zjištění zda prohlížeč uživatele patří mezi podporované můžete použít vlastnost SZN.isSupported, která vrací true, pokud je prohlížeč podporován, jinak vrací false.
V případě, že není prohlížeč podporován, není dostupná žádná javascriptová funkcionalita, která je dále popisována a mapa se nezobrazí.
```
<script type="text/javascript">
  if(SZN.isSupported){
  	 var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
  }
</script>
```
K vlastnímu vykreslení mapy dojde po načtení celé stránky.

V případě, že chcete vyvolat mapu až po načtení stránky, tedy zavolat var mapa = new SZN.MapEngine(document.getElementById('mojeMapa')) až poté co dojde k události onload, musíte ještě po vytvoření instance mapy zavolat její metodu init(): mapa.init()

Funkční ukázka 1.

Nastavení středu a stupně přiblížení

Nastavíme stupeň přiblížení mapy 15 a souřadnice středu mapy 50°4'17.7"N, 14°24'2.83"E.

Kroky 1 - 3 jsou identické jako v předchozím příkladu

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns:v="urn:schemas-microsoft-com:vml">
	<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>mapy API 0.1</title>
    <script type="text/javascript" src="http://api.mapy.cz/main?key=45c81e945&ver=3&encoding=utf-8"></script>
  </head>
  <body>
    <div id="mojeMapa" style="width:640px;height:480px;border:1px solid silver;"></div>
  
    <script type="text/javascript">
    //<![CDATA[
    if(SZN.isSupported){
      var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
      // nastaveni stupne priblizeni
      mapa.zoomSet(15);

      /*
        nastaveni stredu mapy na souradnice:
        50°4'17.7"N
        14°24'2.83"E
      */
      // nejdrive prevedem souradnice na interni souradnicovy system
      var pp = mapa.wgsToPP('50d4m17.7sN','14d24m2.83sE');
      
      // a nyni nastavime novy stred
      mapa.setCenter(pp.x,pp.y);
    }
	//]]>  
    </script>    
  </body>
</html>

Na libovolné místo za voláním vytvoření mapy (krok 3.) vložíme volání metody mapa.zoomSet(15) tím nastavíme stupeň přiblížení 15.
Pro nastavení středu musíme nejdříve převést jeho souřadnice (ve WGS 84) na interní souřednicový systém pomocí metody var pp = mapa.wgsToPP('50d4m17.7sN','14d24m2.83sE'), ta nám vrátí horizontální a vertikální pozici nového středu jako objekt s vlastnostmi x a y.
Vypočtené interní souřadnice předáme metodě, která nastaví nový střed mapa.setCenter(pp.x,pp.y).

Funkční ukázka 2.

Nastavení interakce

Nastavení základní interakce mapy s uživatelem jako je ovládnání myší, výběr pomocí rámečku.

Kroky 1 - 3 jsou identické jako v prvním příkladu

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns:v="urn:schemas-microsoft-com:vml">
	<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>mapy API 0.1</title>
    <script type="text/javascript" src="http://api.mapy.cz/main?key=45c81e945&ver=3&encoding=utf-8"></script>
  </head>
  <body>
    <div id="mojeMapa" style="width:640px;height:480px;border:1px solid silver;"></div>
  
    <script type="text/javascript">
    //<![CDATA[
    if(SZN.isSupported){
      var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
      // nastaveni mysi
	  mapa.mouseSet(3);
	  
	  // nastaveni ramecku
	  mapa.enableSelection(1);
	}	
    //]]>  
    </script>    
  </body>
</html>

Prostřednictvím metody mapa.mouseSet() nastavujem ovládání myší. Argument metody určuje typ ovládání.

hodnota	typ ovládání
0	vypnuto
1	pouze pohyb
2	pouze zoom
3	zoom a pohyb
4	zoomovani kolečkem myši
5	zoomovani kolečkem myši a pohyb mapou
6	zoomovani kolečkem myši a klikáním
7	vše

Výběr oblasti mapy pomocí rámečku zapneme prostřednictvím volání metody mapa.enableSelection(), pokud je její argument vyhodnocen jako true (pravda, tedy je libovolné číslo kromě 0, neprázdný řetězec nebo true), zapne se výběr pomocí rámečku.

Funkční ukázka 3.

Přidání značky do mapy

Přidání předefinované značky do mapy.
Kroky 1 - 3 jsou identické jako v prvním příkladu
Krok 4 - 5 je stejný jako v ukázce s nastavením středu a stupně přiblížení.

Značku umístíme na pozici středu mapy.

<script type="text/javascript">
    //<![CDATA[
    if(SZN.isSupported){
      var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
      // nastaveni stupne priblizeni
      mapa.zoomSet(15);
      // nastaveni mysi
	  mapa.mouseSet(3);
      /*
        nastaveni stredu mapy na souradnice:
        50°4'17.7"N
        14°24'2.83"E
      */
      // nejdrive prevedem souradnice na interni souradnicovy system
      var pp = mapa.wgsToPP('50d4m17.7sN','14d24m2.83sE');
      
      // a nyni nastavime novy stred
      mapa.setCenter(pp.x,pp.y);
      
      /*
	    pridame znacku do mapy, na  jeji stred
      */
      // vytvorime znacku
      var mark = mapa.makeMark('center','Moje znacka');

      // umistime znacku do mapy na drive vypoctene souradnice 
      mapa.addMark(pp.x,pp.y,mark);      
    }
    //]]>  
    </script>

Značku vytvoříme prostřednictvím metody mapa.makeMark(), metoda nám vrátí objekt, reprezentující značku a její vlastnosti var mark = mapa.makeMark('center','Moje znacka'). První argument určuje typ značky (dostupné jsou:center,location,company), druhý argument určuje atribut title a alt vlastního HTML kódu značky.
Vložení značky do mapy provedeme prostřednictvím metody mapa.addMark(), které jako argumenty předáme polohu značky v interní souřadnicové soustavě a vlastní značku mapa.addMark(pp.x,pp.y,mark).

Funkční ukázka 4.

Přidání více značek, interakce značek

Přídání více druhů značek a značek, které budou reagovat na kliknutí zobrazením rozšiřujících informací ve vizitce.

Kroky 1 - 3 jsou identické jako v prvním příkladu.
Krok 4 - 5 je stejný jako v ukázce s nastavením středu a stupně přiblížení.
Navíc použijeme mapu se zapnutým ovládáním pomocí myši

    <script type="text/javascript">
    //<![CDATA[
      if(SZN.isSupported){
		  var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
	      mapa.mouseSet(3);
		  mapa.zoomSet(10);
	      var pp = mapa.wgsToPP('50d4m17.7sN','14d24m2.83sE');
	      mapa.setCenter(pp.x,pp.y);
	      
	      /*
		   pridame vice znacek do mapy a nektere opatrime je vizitkami
	     */
	     // vypocitame souradnice pro umisteni znacek
	     var pp0 = mapa.wgsToPP('50d4m17.7sN','14d24m2.83sE'); // Seznam.cz
	     var pp1 = mapa.wgsToPP('50°5m41.86"N','14°24m9.03"E'); // Prazsky hrad
	     var pp2 = mapa.wgsToPP('50°4m40.21"N','14°27m39.1sE');  // Flora
	     
		// vytvorime znacky
		// tato znacka je obycejna neinteraktivni 
		var mark0 = mapa.makeMark('center','Seznam.cz');
		mapa.addMark(pp0.x,pp0.y,mark0);
		
		
		/*
			definujeme si funkci, kterou budeme volat po kliknuti na znacku
			bude volana se tremi argumenty
			e - udalost
			elm - html element na ktterem je zavesen posluchac udalosti
			mark - odkaz objekt znacky, na kterou se kliklo
		*/
		function markClick(e,elm,mark){
			var id = mark.getId();
			var cardData = cardDataFolder[id];
			var crd = new SZN.Visual.BaseCard(mark.pos.x,mark.pos.y,cardData,null,null,null)
			mapa.addCard(crd);
		}
		
		/* 
			definujeme si objekt s daty pro vizitky
			jednotlive vlasrnosti objektu budou pojmenovany shodne jako id znacek
		*/
		var cardDataFolder  = {
			mark1 : {obsah:[{title:'Prazsky hrad',cont:'Tato znacka ukazuje na:<br /><b>Prazsky hrad</b>'},{cont:'<br>Ahoj ja jsem dalsi zajimavy text k prazskemu hradu'}]},
			mark2 : {obsah:[{title:'Flora',cont:'Tady se nachazi:<br /><b>Flora</b><br />a spousta zajimavych mist'}]}
		}
		
		/*
		 tato znacka je interaktivni a po kliku na znacku ukazeme
		 vizitku s rozsirenym obsahem
		*/
		var mark1 = mapa.makeMark('company','Prazsky hrad','1','mark1');
		/* aktivujeme znacku */
		mark1.setAction(window,markClick);
		/* pridame znacku do mapy */
		mapa.addMark(pp1.x,pp1.y,mark1);
		
	   /*
	    tato znacka je interaktvni a po kliknuti zobrazi vizitku s
		jednoduchym textovym obsahem 
	   */
	   var mark2 = mapa.makeMark('location','Flora','2','mark2');
	   /* aktivujeme znacku */
	   mark2.setAction(window,markClick);
	   /* pridame znacku do mapy */
	   mapa.addMark(pp2.x,pp2.y,mark2);
	} 
    //]]> 
    </script>

První značku (mark0) vytvoříme stejně jako v předchozí ukázce.
Mejdříve si připravíme definice obsahů značek uložené v objektu cardDataFolder
```
var cardDataFolder  = {
	mark1 : {obsah:[{title:'Prazsky hrad',cont:'Tato znacka ukazuje na:<br /><b>Prazsky hrad</b>'},{cont:'<br>Ahoj ja jsem dalsi zajimavy text k prazskemu hradu'}]},
	mark2 : {obsah:[{title:'Flora',cont:'Tady se nachazi:<br /><b>Flora</b><br />a spousta zajimavych mist'}]}
}
```
Potom si nadefinujeme funkci, která se bude volat po kliknutí na značku markClick
```
function markClick(e,elm,mark){
	var id = mark.getId();
	var cardData = cardDataFolder[id];
	var crd = new SZN.Visual.BaseCard(mark.pos.x,mark.pos.y,cardData,null,null,null)
	mapa.addCard(crd);
}
```
Druhou značku (mark1) vytvoříme podobným způsobem, pouze předáme metodě další argumenty, které určují obsah značky (pouze u značek "location" a "company"), a její identifikátor, který bude vracet metoda značky [znacka].getId().
var mark1 = mapa.makeMark('company','Prazsky hrad','1','mark1');.
Dále značku aktivujeme mark1.setAction(window,markClick);

Značku do mapy přidáme opět pomocí metody mapa.addMark().
Poslední značka (mark2), se přidá stejným způsobem jako předchozí.

Funkční ukázka 5.

Přidání ovládacích prvků

Použijeme mapu vytvořenou shodně jako v první ukázce, a navíc zapneme ovládání prostřednictvím myši

    <script type="text/javascript">
    //<![CDATA[
if(SZN.isSupported){
	var mapa = new SZN.MapEngine(document.getElementById('mojeMapa'));
	mapa.mouseSet(5);
	mapa.zoomSet(10);
	mapa.enableSelection(1);
	
	// box pro pridani ovladacich prvku
	var layoutBox = mapa.getDefaultLayoutBox()
	
	// vytvoreni a pridani ovladaciho prvku pro pohyb s mapou
	var moveControl = new SZN.Visual.MoveControl();
	var move = mapa.addControls(moveControl,layoutBox,10,12);
	
	// vytvoreni a pridani ovladaciho prvku pro nastaveni priblizeni
	var zoomControl = new SZN.Visual.ZoomControl('full');
	// vypocteme si vertikalni polohu pro umisteni 
	var pos = mapa.getControlById(move).getSize().height + 17;
	mapa.addControls(zoomControl,layoutBox,25,pos);
	
	// zapnuti ukazatele severu
	mapa.setNorthRuler(1);
	
	// zapnuti ukazatele meritka
	mapa.setScaleRuler(1);
} 
    //]]> 
    </script>

Nejdříve si vytvoříme layoutBox, do kterého budeme ovládací prvky přidávat. v naší ukázce použijeme výchozí layoutBox var layoutBox = mapa.getDefaultLayoutBox()
Vytvoříme prvek pro ovládání pohybu var zoomControl = new SZN.Visual.ZoomControl('full'); a do mapy ho přidáme pomocí metody mapa.addControls(moveControl,layoutBox,10,12), metodě předáme přidávaný prvek, layoutBox, do kterého chceme prvek přidat a sořadnice posunutí prvku vůči poloze layoutBoxu
Prvek pro ovládání stupně přiblížení vztvoříme analogicky.
Nejdříve vytvoříme vlastní prvek var zoomControl = new SZN.Visual.ZoomControl('full');
Protože budeme prvek přidávat do stejného layoutBoxu jako předchozí, vzpočteme si výšku předchozího prvku var pos = mapa.getControlById(move).getSize().height + 17; a přidáme ho mapa.addControls(zoomControl,layoutBox,25,pos);
Ukazatel severu přidáme do mapy prostřednictvím volání metody mapa.setNorthRuler(1)
Ukazatel severu přidáme do mapy prostřednictvím volání metody mapa.setScaleRuler(1)

Ukazatel severu a měřítka se aktualizují dle stupně přiblížení a polohy středu mapy.

Funkční ukázka 6.

Ukázka ovládání dvou map

Mezi mapami se přepínáme pravým hornim rozbalovacím boxem.
Do políčka "jednoduchý pohyb" lze zadat jednu z hodnot ss, sz, sv, zz, vv, jv, jj, jz.
Do políček "přesný pohyb" lze zadat počet pixelů, o který se má mapa vertikálně a horizontálně posunout

Funkční ukázka 7.