Dynamics AX: Mapa Google do sprawdzania lokalizacji odbiorców - tutorial cz. 1

W tym artykule pokażę jak zintegrować system Microsoft Dynamics AX z mapą Google na przykładzie lokalizacji odbiorców. W części pierwszej opisana zostanie część jaką należy wykonać, aby stworzyć aplikację w technologii Flex / Flash, w drugiej natomiast zajmiemy się integracją tej aplikacji w systemie Dynamics AX.


Co nam będzie potrzebne do realizacji tego zadania?

1. Darmowe środowisko FlashDevelop lub inne komercyjne środowisko programistyczne do tworzenia aplikacji w technologii Flex. Korzystając z FlashDevelopa należy pamiętać o pobraniu Flex SDK.
2. Google Maps API for Flash i Google Maps API Key
3. System Microsoft Dynamics AX ... :)

UWAGA!
Jako, że Google w licencji do korzystania z Google Maps API nakazuje stosowanie swojego mechanizmu w aplikacjach łatwo dostępnych dla użytkownika końcowego, poniższy tutorial stanowi tylko pokaz możliwości integracji systemu Dynamics AX z komponentami w technologii Flash. Pozostałe wykorzystanie informacji zawartych w tym tutorialu może naruszać prawa korzystania z  licencji oprogramowania udostępnionego przez firmę Google. Dla zainteresowanych komercyjnym wykorzystaniem integracji z mapami oferowanymi przez Google istnieje płatna wersja API. Ponadto w wersji bezpłatnej istnieje limit dzienny na geokodowanie.


1. Na początku trzeba zainstalować i odpowiednio skonfigurować FlashDevelopa do pracy. Osoby, które posiadają już to narzędzie lub korzystają z innego środowiska mogą pominąć ten punkt. Jednak początkującym adeptom sztuki programowania komponentów Flash może przysporzyć nie lada problemów.
Jeśli masz pragnienie zapoznać się bliżej z technologią Flex polecam dwie ciekawe książki:

Przed instalacją samego FlexDevelopa najlepiej rozpakować wcześniej Flex SDK, a na chwilę pisania artykułu występuje w wersji 4.5. Po instalacji w opcjach programu w zakładce AS3Context  wskazujemy ścieżkę do zainstalowanego frameworka:

2. W następnym kroku zakładamy nowy projekt Flex 4 Project:

W wyniku założenia projektu powinna zostać stworzona struktura katalogów zawierająca skompilowane pliki (bin), biblioteki (lib) i źródła (src). Powinien też zostać utworzony pierwszy, główny plik źródłowy aplikacji o nazwie "Main.mxml" zawierający podstawową strukturę aplikacji:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
      xmlns:s="library://ns.adobe.com/flex/spark"
      xmlns:mx="library://ns.adobe.com/flex/mx">
 
 <fx:Declarations>
  <!-- Place non-visual elements (e.g., services, value objects) here -->
 </fx:Declarations>
</s:Application>

2. W następnym kroku do projektu dodajemy bibliotekę ze ściągniętego SDK Google Maps API for Flash. Plik "map_flex_1_20.swc" najlepiej rozpakować w katalogu lib projektu i z menu kontekstowego dostępnego pod prawym przyciskiem myszki zaznaczyć opcję "Add to library":

UWAGA!  
W Google Maps API for Flash występują dwie biblioteki: map_flex_1_20.swc i map_1_20.swc. Tę pierwszą użyjemy w projekcie Flexowym, tą drugą można użyć jeśli robimy prezentację w typowym Flashu.

3. Do aplikacji musimy teraz dodać komponent mapy i wyświetlić go w całym obszarze roboczym. W tym celu dodamy blok xml'owy SCRIPT, gdzie można zagnieździć kod w języku Action Script 3 wewnątrz dokumentu MXML.

<fx:Script>
   <![CDATA[  
                 
   ]]>
</fx:Script>

Następnie dodamy funkcję w języku ActionScript3, która będzie wywołana na początku działania aplikacji:

import com.google.maps.Map;
private var map:Map;

public function init():void
{
   map = new Map();
   map.key = "KLUCZ_GOOGLE_MAPS_API";
   map.height = this.height;
   map.width = this.width;
   map.addEventListener(MapEvent.MAP_READY, onMapReady);
   this.addElement(map);
}

oraz funkcję, która uruchomi się po pełnym wczytaniu obiektu map:

private function onMapReady(event:Event):void {
   map.enableScrollWheelZoom();
   map.enableContinuousZoom();
   map.addControl(new ZoomControl());
}

Przed deklaracją funkcji init należy dokonać dołączenia biblioteki z Google Maps poleceniem import.
Funkcja init inicjuje obiekt Map i przypisuje mu klucz, który należy pobrać na stronie Google Maps API. Następnie ustalane są rozmiary tego komponentu do rozmiarów okna aplikacji i dodawana jest obsługa zdarzenia MapEvent.MAP_READY. Metodą addElement dodawany jest ten komponent do kontenera aplikacji. Aby metoda init zadziałała potrzebne jest jeszcze zdefiniowanie zdarzenia creationComplete w drugiej linijce kodu:

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
      xmlns:s="library://ns.adobe.com/flex/spark"
      xmlns:mx="library://ns.adobe.com/flex/mx" creationComplete="init()"  >

W funkcjo onMapReady włączana jest możliwość korzystania ze scrolla wbudowanego w myszkę oraz dodawana jest możliwość powiększania i pomniejszania mapy wraz z kontrolką ZoomControl.

Tak skonstruowana aplikacja Flexowa powinna nam się skompilować i uruchomić. Jeśli jednak wystąpiły problemy proponuję jeszcze wspomóc się tymi linkami:

• http://groups.google.com/group/google-maps-api-for-flash/browse_thread/thread/952dfbde3deb7865/f06623a03ba664e8?pli=1
• http://code.google.com/intl/pl/apis/maps/documentation/flash/tutorial-flex.html#DeclaringMaps
• http://www.jamesrichards.com/post/2009/09/30/Use-Open-Source-FlashDevelop-IDE-with-Google-Maps-API-for-Flash.aspx
• http://www.flashdevelop.org/community/viewtopic.php?f=9&t=4101

Na wyjściu powinniśmy ujrzeć taką mapę:

Na ekranie widać, że komponent sugeruje byśmy uzupełnili właściwość sensor. Jeśli chcemy wykorzystywać mapy Google do śledzenia za pomocą odbiorników GPS, właściwość tą ustawiamy na TRUE, jeśli nie to FALSE. Niestety nie jest dla mnie zrozumiałe, dlaczego akurat ta właściwość jest typu String, a nie Boolean, no ale nie wymagajmy od Google cudów ;), w końcu dwa dodatkowe cudzysłowy i błąd kompilacji to jeszcze nie koniec świata:

map.sensor = 'false';

4. Czas na funkcję geokodującą, czyli zamieniającą dane adresowe na współrzędne. Warto tutaj jeszcze raz przypomnieć, że w darmowej wersji Google nakłada ograniczenia na geokodowanie w ilości 1000 zapytań w ciągu dnia. Przed dodaniem odpowiednich funkcji musimy dołączyć (zaimportować) referencje do odpowiednich klas, których użyjemy:

import com.google.maps.overlays.Marker;
import com.google.maps.services.ClientGeocoder;
import com.google.maps.services.GeocodingEvent;
import com.google.maps.MapMouseEvent;
import com.google.maps.MapType;
import com.google.maps.InfoWindowOptions; 
import com.google.maps.controls.ZoomControl;
import mx.controls.Alert;

Następnie dodajemy dwie metody doGeocode i geocodeSuccess:

private function doGeocode(address:String):void
  {
   var geocoder:ClientGeocoder = new ClientGeocoder();

   // obsługa sukcesu geokodowania
   geocoder.addEventListener(GeocodingEvent.GEOCODING_SUCCESS, geocodeSuccess);

   // obsługa błędu geokodowania
   geocoder.addEventListener(
     GeocodingEvent.GEOCODING_FAILURE,
     function(event:GeocodingEvent):void {
    Alert.show("Geocoding failed");
     });
     
   // uruchomienie funkcji geokodującej
   geocoder.geocode(address);
  }
   
  private function geocodeSuccess(event:GeocodingEvent):void
  {
    var placemarks:Array = event.response.placemarks;
    if (placemarks.length > 0) {
   map.setCenter(placemarks[0].point, 14, MapType.NORMAL_MAP_TYPE);
   var marker:Marker = new Marker(placemarks[0].point);
   
   marker.addEventListener(MapMouseEvent.CLICK, function (event:MapMouseEvent):void {
    marker.openInfoWindow(new InfoWindowOptions({content: placemarks[0].address}));
   });
   map.addOverlay(marker);
    }
  }

5. Na koniec części pierwszej tutoriala, możemy sprawdzić jak działa geokodowanie. Dla takich testów w metodzie onMapReady wprowadzimy przykład użycia metody doGeocode:

private function onMapReady(event:MapEvent):void {
 map.enableScrollWheelZoom();
 map.enableContinuousZoom();
 map.addControl(new ZoomControl());
    
 this.doGeocode("Warszawa, ul. Aleje Jerozolimskie");
}

A taki jest wynik po skompilowaniu i uruchomieniu aplikacji:

Koniec części 1. Część 2.