úterý 10. března 2009

Google Mapplets API

Úvodem

Google Mapplety jsou malé aplikace, kterými můžete rozšířit Google Maps. Mapplety umožňují na mapu přidat různé informace – aktuální počasí, ceny benzínu, ...
V tomto článku si nastíníme, jak Google Mapplety fungují a ukážeme si, jak jednoduchý Mapplet vytvořit.

... Pokračování


Seznam dostupných Mappletů můžete najít na:
http://maps.google.com/ig/directory?synd=mpl&pid=mpl&features=sharedmap,geofeed&backlink=http:%2F%2Fmaps.google.com%2Fmaps%2Fmm

Pro možnost přidávání Mappletů na mapu, je potřeba mít u Google účet (klasický Google account, který je zdarma možné zřídit na https://www.google.com/accounts/NewAccount).

Po přihlášení se na Google Maps (maps.google.com) máte k dispozici záložku My Maps s možností vytvářet vlastní obsah mapy nebo přidávat obsah již vytvořený někým jiným.

My maps


Než vytvoříme vlastní Mapplet

Mapplety jsou XML soubory, které obsahují jednoduché stránky. Tyto stránky mohou obsahovat html, javascript nebo flash, stejně jako běžné webové stránky.

Jak to funguje
Na Váš webserver umístíte xml soubor a poté ho načtete přes Google Maps Directory (http://maps.google.com/ig/directory?synd=mpl&pid=mpl&features=sharedmap,geofeed&backlink=http%3A%2F%2Fmaps.google.com%2Fmaps%2Fmm)
Vedle pole pro vyhledávání se nachází odkaz "Add by URL":



Poté se objeví pole pro vložení adresy Mappletu:



Pokud zadáte adresu Mappletu (http://www.domena.cz/.../mapplet.xml), kliknete na "Add" a vrátíte se zpět na Google Maps, pod záložkou My Maps naleznete i tento nový Mapplet.
Pokud nemáte vlastní stránku, doporučujeme využít Google Sites (http://sites.google.com).

Sdílení Mappletu s ostatními
Pokud chcete vytvořený Mapplet sdílet s ostatními, můžete jim dát k dispozici adresu Mappletu pro přidání přes Google Maps Directory, nebo jim dát adresu pro přímou instalaci Vašeho Mappletu ve tvaru:
http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=<URL Vašeho Mappletu>

Pokud chcete přidat Váš Mapplet do Google Maps directory, je možné použít formulář na http://maps.google.com/ig/submit?synd=mpl&pid=mpl
Google poté Váš Mapplet vyhodnotí a případně přidá do Google Maps Directory.

Vývoj vlastního Mappletu
Ještě před samotným vývojem doporučujeme přidat do svých Mappletů následující dva od Google:

Developer Mapplet
Tento Mapplet přidává k ostatním Mappletů tlačítko "Reload". Toto tlačítko slouží ke znovunačtení Mappletu a jeho spuštění.
Tento Mapplet rozhodně doporučujeme. Google totiž při prvním použití Mappletu stáhne celý Mapplet na svůj server gmodules.com odkud jej pak spustí (důvodem a výhodou je ušetření na datových přenosech z Vašeho webu). Toto cachovaní trvá až několik hodin. Tato vlastnost však znamená, že pokud vyvíjíte Mapplet a na svůj web nahrajete novou verzi, Google Maps spouští stále verzi uloženou na gmodules.com. Tento Mapplet obejde cache a spustí Váš aktuální Mapplet z Vaší stránky.

Developer Mapplet si do svých My Maps můžete přidat přes http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=http://www.google.com/ig/modules/geodeveloper.xml

Mapplet Scratch Pad
Přes tento Mapplet můžete spouštět kód mappletů přímo, bez nutnosti ukládání Vašich Mappletů "někam" na server a jejich načítání. Opět tento Mapplet rozhodně doporučujeme!
Mapplet je možné přidat do svých My Maps přes http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=http://www.google.com/ig/modules/geoscratchpad.xml

Tlačítko "Preview" spustí vložený kód, všimněte si tlačítka Reload nahoře vpravo pro načtení celého Mappletu znovu


Dole v Mappletu můžete načíst již vytvořený xml soubor, stačí zadat url:

Načtení Hello World Mappletu ze stránky Google


Pozdravme svět
Následující kód zobrazí zprávu Ahoj světe!:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Ahoj světe"
      description="Zobrazí zprávu Ahoj světe!"
      author="Vaše jméno"
      author_email="vas-email@domena.cz"
      height="150">
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Ahoj světe!</h2>

]]></Content>
</Module>


Pokud kód vložíte do xml souboru a načtete nebo jej vložíte do Mappletu Scratch Pad a spustíte, zobrazí se Vám "Ahoj světe!":





Celý kód spustíte také přes odkaz:
http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=<www.gug.cz/mapplety/ahojsvete.xls>

Rozeberme si kód postupně:

<?xml version="1.0" encoding="UTF-8"?>
Je hlavička xml dokumentu, kódování volíme UTF-8 pro bezproblémovou práci s různými znakovými sadami

<Module>
Začínám vytvářet modul

<ModulePrefs title="Ahoj světe"
Vlastnosti modulu, nadpis

      description="Zobrazí zprávu Ahoj světe!"
Popis modulu

      author="Vaše jméno"
Jméno autora

      author_email="vas-email@domena.cz"
Email autora

      height="150">
Výška Mappletu

</ModulePrefs>
Ukončení části vlastností modulu

<Content type="html"><![CDATA[
Samotný obsah modulu, tady to bude html

<h2>Ahoj světe!</h2>
Html kód

]]></Content>
</Module>

Uzavření části obsahu modulu a samotného modulu.

Interakce s Google mapou

Pokud chcete pracovat přímo s mapu, prvním krokem je načtení API k mapě. To se provede pomocí
<Require feature="sharedmap"/>

Tento řádek je potřeba vložit do části Module Prefs:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Nadpis"
      description="Popis..."
      ...
      <Require feature="sharedmap"/>
</ModulePrefs>

<Content type="html"><![CDATA[
...
]]></Content>
</Module>


Složitější kód
Podívejme se na trochu složitější kód. Na začátku jsou opět informace o xml a Mappletu:
<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Značka"
      description="Zobrazí značku a zprávu"
      author="Jméno autora"
      author_email="vas-email@domena.cz"
      height="150">


Tentokrát již budeme pracovat s mapu, musíme tedy načíst API:
 <Require feature="sharedmap"/>
</ModulePrefs>


Budeme pracovat s html:
<Content type="html"><![CDATA[

Text zobrazený Mappletem:
<h2>Značka je tam někde venku...</h2>

Začátek scriptu pro práci s mapou:
<script>

Vytvoříme novou mapu:
 var mapa = new GMap2();
Při použití GMap2(), API automaticky sváže tuto proměnou s Google Mapou

Vytvoříme objekt GLatLnd, který má koordináty 49.79545 a 15.732422:
 var bod = new GLatLng(49.79545,15.732422);

Tento objekt poté předáme jako parametr novému objektu značka:
 var znacka = new GMarker(bod);

Kterou obratem vykreslíme na mapu:
 mapa.addOverlay(znacka);

A zobrazíme nad ní okno s informací:
 znacka.openInfoWindowHtml("Tady je značka!");

Uzavřeme script, obsah i modul:
</script>
]]></Content>
</Module>


Celý kód pak vypadá nějak takto:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Značka"
      description="Zobrazí značku a zprávu"
      author="Jméno autora"
      author_email="vas-email@domena.cz"
      height="150">
 <Require feature="sharedmap"/>
</ModulePrefs>
<Content type="html"><![CDATA[
<h2>Značka je tam někde venku...</h2>
<script>
 var mapa = new GMap2();
 var bod = new GLatLng(49.79545,15.732422);
 var znacka = new GMarker(bod);
 mapa.addOverlay(znacka);
 znacka.openInfoWindowHtml("Tady je značka!");
</script>
]]></Content>
</Module>


A výsledek takto:



Odkaz na spustitelnou verzi:
http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=<www.gug.cz/mapplety/znacka.xls>

Pozn.:
Protože pracujeme s již nastavenou mapu (Google mapa), není nutné ji inicializovat pomocí metody setcenter(). Stejně tak není potřeba ověřovat kompatibilitu prohlížeče (přes GBrowserIsCompatible), protože se předpokládá, že pokud uživatel načte Mapplet, může používat i Google Maps.

Asynchronní komunikace s mapou

Komunikace mezi Google mapou a obsahem Mappletu probíhá asynchronně. Metody, které mění mapu, fungují jako každé jiné. Metody, které ale vrací nějakou hodnotu, musí mít definovánu návratovou funkci. Tyto metody ke svému jménu přidávají "Async". Příkladem může být kód, který otevře informační okno na středu zobrazené mapy:
var mapa = new GMap2();
mapa.getCenterAsync(function(center) {
 mapa.openInfoWindowHtml(center, "Tady je střed mapy!");
});


Použitelné funkce

Obecně platí, že většina funkcí z Google Maps API jde použít i v Mappletech.
Referenční seznam funkcí naleznete na: http://code.google.com/apis/maps/documentation/mapplets/reference.html

Mapplety používají starší rozhraní, kde se metody pojmenovávají ve tvaru: Gjménometody. Pokud již máte zkušenosti s Google Maps API a používali jste novější rozhraní s namespace google.maps, funkce zůstávají zachovány – stačí pouze "google.maps." nahradit právě písmenem "G".

Informační okno
Z bezpečnostních důvodů nelze v informačním okně zobrazit/spustit libovolný kód. Přehled povolených značek naleznete na http://code.google.com/apis/maps/documentation/mapplets/infowindowallowed.html

Užitečné odkazy:
Domovská stránka Google Maps: http://maps.google.com
Domovská stránka Google Mapplets: http://code.google.com/apis/maps/documentation/mapplets/
Dokumentace Google Mapplets:
http://code.google.com/apis/maps/documentation/mapplets/guide.html

Seznam povolených značek v okně Mappletu: http://code.google.com/apis/maps/documentation/mapplets/infowindowallowed.html


Zdroj: code.google.com

Žádné komentáře: