Dokumentacja Web API ver. 2 - Integracja mapy

Mapę z punktami odbioru można osadzić na własnej stronie na 2 sposoby:

• wywołanie JavaScript do otworzenia mapy
• integracja z formularzem poprzez osadzenie pola INPUT z rozwijalną listą punktów i przyciskiem otwierania mapy

Pierwszą rzeczą do wykonania jest załadowanie biblioteki. W sekcji HEAD lub przed pierwszym użyciem strony należy załadować kod biblioteki:

<script src="https://mapa.apaczka.pl/client/apaczka.map.js"></script>

Przed rozpoczęciem integracji należy wygenerować unikalne App ID dla domeny na której będzie osadzana mapa.

Proste otworzenie mapy możemy zrealizować poprzez:

<script type="application/javascript"> var apaczkaMap = new ApaczkaMap({ app_id : '{APP_ID}', onChange : function(record) { if (record) { alert('Wybrano: ' + record.foreign_access_point_id); } } }); </script> <a href="javascript:apaczkaMap.show({});">Otwórz mapę</a> <a href="javascript:apaczkaMap1.show({filterServicesCod : true});">Otwórz mapę z pobraniem</a>

Otwórz mapę Otwórz mapę z pobraniem

Instancję mapy można otwierać wielokrotnie metodą show(). Przy każdym wywołaniu mogą zostać przekazane zmienione parametry wywołania, jak np.: dostepni przewoźnicy.

Poniższy kod wyszuka element INPUT o podanym id, ukryje go i w jego miejscu wstawi pole rozwijalne z przyciskiem otwierania mapy. Ewentualna wartość z pola INPUT zostanie wykorzystana jako wartość początkowa pola. Po wybraniu punktu przez użytkownika w pole INPUT zostanie wstawiony identyfikator wybranego pola.

<input type="text" value="WAW53AP" id="demo"> <script type="application/javascript"> var apaczkaMap2 = new ApaczkaMap({ app_id : 'demo123' }); apaczkaMap2.combobox({ point_id : 'demo' }); </script>

Możliwe jest również poprzez dodatkowe parametry podłączenie pól miasta i ulicy z formularza, tak aby mapa otworzyła się automatycznie na podanej przez użytkownika lokalizacji. Można również sformatować informacje wyświetlane w widocznym polu.

Parametry, które można przekazać tworząc obiekt ApaczkaMap.

Parametr	Typ	Opis
app_id	string	Identyfikator aplikacji wygenerowany w panelu klienta
onChange	function	Metoda zwrotna, która zostanie wywołana po wybraniu (anulowaniu wyboru) przez użytkownika
criteria	array	Tablica kryteriów ograniczających dostępne punkty. Patrz poniżej.
center	array	Tablica dwuelementowa: [latitude, longitude] z domyślnym centrum mapy. Domyślnie: [52.226376, 21.009979]
zoom	integer	Domyślny zoom mapy. Domyślnie: 12
hideServicesCod	bool	Opcjonalne ukrycie przycisku filtrowania punktów obsługujących pobranie. Może na przykład zostać wykorzystane razem z kryterium ograniczającym tylko do punktów obsługujących pobranie.
filterServicesCod	bool	Po przekazaniu wartości true przycisk filtrowania punktów obsługujących pobranie będzie automatycznie zaznaczony.

Kryteria podajemy jako tablicę obiektów z poniższymi parametrami.

Nazwa pola	Opis
field	Nazwa pola z bazy punktów
operator	Operator do ograniczenia. Dostępne operatory: eq - równość in - wartość z tablicy
value	Wartość ograniczająca pole wg operatora

Pola dostępne przy budowaniu kryteriów.

Nazwa pola	Typ pola	Opis
services_sender	bool	Punkt nadania
services_receiver	bool	Punkt odbioru
services_cod	bool	Punkt obsługujący pobranie

Przykładowe kryteria dla punktów odbioru:

{field: 'services_receiver', operator: 'eq', value: true}

Parametry do otwierania mapy przekazywane w metodzie show().

Parametr	Typ	Opis
center	array	Tablica dwuelementowa: [latitude, longitude] z domyślnym centrum mapy. Domyślnie: [52.226376, 21.009979]
zoom	integer	Domyślny zoom mapy. Domyślnie: 12
point	object	Obiekt z informacją o punkcie, który ma zostać zaznaczony na mapie. Obiekt wymaga dwóch parametrów: foreign_access_point_id - Identyfikator punktu supplier - Nazwa kodowa dostawcy
address	object	Obiekt z informacją o adresie, który zostanie wyszukany i na nim zostanie otworzona mapa. Obiekt wymaga dwóch parametrów: street - Nazwa ulicy city - Nazwa miasta

Parametry do integracji z formularzem przekazywane w metodzie combobox().

Parametr	Typ	Opis
point_id	string	ID elementu INPUT z identyfikatorem wybranego pola. Pole zostanie ukryte i w to miejsce wstawiona lista rozwijana. Po wybnraniu punktu przez użytkownika wskazany element INPUT otrzyma nowy identyfikator wybranego pola.
supplier_id	string	ID elementu INPUT/SELECT z nazwą kodową przewoźnika. Przy wyświetlaniu mapy z wybranym punktem z tego pola zostanie pobrana nazwa kodowa przewoźnika. Po wybraniu punktu pole zostanie również zaktualizowane.
street_id	string	ID elementu INPUT z nazwą ulicy adresu. Przy wyświetlaniu mapy bez wybranego punktu z tego pola jak i pola z miastem zostanie pobrany domyślny obszar mapy do wyświetlenia. Do wykorzystania gdy klient podał swój adres i umozliwiamy mu znalezienie najbliższego punktu odbioru. Pole nie jest modyfikowane.
city_id	string	ID elementu INPUT z nazwą miasta adresu. Przy wyświetlaniu mapy bez wybranego punktu z tego pola jak i pola z ulicy zostanie pobrany domyślny obszar mapy do wyświetlenia. Do wykorzystania gdy klient podał swój adres i umozliwiamy mu znalezienie najbliższego punktu odbioru. Pole nie jest modyfikowane.
height	integer	Wysokość rozwijanej listy. Domyślnie: 300
placeholder	string	Tekst wyświetlany w polu, gdy żaden punkt nie został jeszcze wybrany.
formatDisplay	function	Metoda do formatowania pola wyświetlającego wybrany punkt. Domyślnie wyświetlany jest tylko numer punktu. Metoda dostaje w parametrze rekord ze wszystkimi informacjami wybranego punktu i powinna zwrócić wartość string do wyświetlenia.

Poprzez metodę setFilterSupplierAllowed() można zmodyfikować listę dostępnych przewoźników. W pierwszym parametrze przekazywana jest tablica dostępnych przewoźników, a w drugim opcjonalnie ograniczona tablica domyślnie aktywnych przewoźników.

apaczkaMap.setFilterSupplierAllowed( ['DHL_PARCEL', 'DPD', 'INPOST', 'POCZTA', 'UPS'], ['INPOST'] );

Nazwa kodowa przewoźnika
DHL_PARCEL
DPD
INPOST
POCZTA
UPS

Poprzez metodę setSupplier() można ustawić aktualnie wybranego przewoźnika. W takiej sytuacji użytkownikowi przy innym przewoźniku pojawi się przycisk "Wybierz i zmień przewoźnika" zamiast "Wybierz".

apaczkaMap3.setSupplier('INPOST');

Dodatkowo po załadowaniu widgetu możemy za pomocą metody setFilterServicesCod() włączyć lub wyłączyć programowo stan filtru punktów obsługujących pobranie.

apaczkaMap3.setFilterServicesCod(true);

<p> Ulica: <input type="text" id="demo3_street" value="Klimczaka 1"> </p> <p> Miasto: <input type="text" id="demo3_city" value="Warszawa"> </p> <p> Pobranie: <input type="checkbox" onclick="apaczkaMap3.setFilterServicesCod(this.checked);"> </p> <p> Przewoźnik: <input type="text" id="demo3_supplier" readonly></input> </p> <p> Punkt dostawy: <input type="text" id="demo3_foreign_access_point"> </p> <script type="application/javascript"> var apaczkaMap3 = new ApaczkaMap({ app_id : 'demo123', criteria : [ {field: 'services_receiver', operator: 'eq', value: true} ] }); apaczkaMap3.combobox({ point_id : 'demo3_foreign_access_point', supplier_id : 'demo3_supplier', street_id : 'demo3_street', city_id : 'demo3_city', placeholder: 'Wybierz punkt dostawy...', formatDisplay : (record) => { let display = record.foreign_access_point_id; if (record.name && record.name.length > 0) { display += ' - ' + record.name; } return display; } }); apaczkaMap3.setSupplier('INPOST'); apaczkaMap3.setFilterSupplierAllowed( ['DHL_PARCEL', 'DPD', 'INPOST', 'POCZTA'], ['INPOST'] ); </script>