Wyszukiwanie miejscowości

Funkcja searchCity(cityName, country, page, order, isDescend, results[, callback])

Wyszukuje miejscowości.

Przyjmowane parametry

1. cityName - Nazwa (lub jej fragment) miejscowości, której szukamy,
2. country - Nazwa państwa w którym szukamy,
3. page - Numer strony wyników wyszukiwania (zaczynajac od zera),
4. order - Kolejność sortowania wyników. Dopuszczalne wartości: name oraz size,
5. isDescend - Zwracanie wyników w kolejności malejącej. Przy sortowaniu po rozmiarze zazwyczaj wybieramy true, przy sortowaniu po nazwie false,
6. results - Liczba wyników wyszukiwania na stronie,
7. callback - Funkcja wywoływana po pobraniu wyników. Jeśli nie zostanie zdefiniowana, to wywołana zostanie funkcja callBacks.searchCity z obiektu konfiguracyjnego API, która prezentuje na mapie pierwszy wyszukany wynik. Domyślne działanie jest wyzwalane również wtedy, gdy funkcja ta zwróci inny wynik niż false, więc jeśli chcemy uniknąć zmiany widoku mapy należy zadbać o zwrócenie w swojej własnej metodzie wyniku false.

W celu przechwycenia wyników wyszukiwania i prezentacji ich np. w HTML'u należy zdefiniować w konfiguracji funkcję callBack.

Funkcja callBack przyjmuje dwa parametry:

1. ret - Status odpowiedzi,
   

   
   ret = {
     failed: false, //wartość boolowska, czy pobranie danych zawiodło
     errDesc: null, //ciąg znaków, opis ewntualnego błędu
     exception: null //ewentualny obiekt wyjątku XMLHttpRequest
   }
   

2. response - Odpowiedź,
   

   
   response = {
     "count" :  11, //łączna liczba pasujących wyników
     "resultsPerPage" :  5, //liczba pobranych wyników
     "pageNo" :  0, //numer strony pobranych wyników
     "cityPrefix" :  "Gd", //Szukana fraza
     "countryName" :  "Polska", //państwo w którym szukaliśmy
     "data": [ ... ] //dane wyszukanych miast
   }
   

   Każdy obiekt z tablicy response.data ma postać:

   
   city = {
     "localityId" :  48855, //identyfikator miejscowości
     "countryName" :  "Polska", //nazwa państwa
     "county" :  "Pomorskie", //województwo
     "commune" :  "Gdańsk", //powiat
     "district" :  "Gdańsk", //gmina
     "name" :  "Gdańsk", //nazwa miejscowości
     "localityGeom" :  {
       "lat" :  54.30644, //szerokość geograficzna
       "lon" :  18.63004 //długość geograficzna
     },
     "zoom" :  10, //sugerowany poziom zoomu
     "size" :  1617 //rozmiar miasta jako liczba ulic w mieście
   }
   

Przykładowy kod i efekt jego zastosowania:

<div id="map" style="width:800px; height:600px; "></div>
<script type="text/javascript">
//<![CDATA[
	jQuery(document).ready(function() {
		DoCelu.loadMap(document.getElementById('map'), null, function() {
			function searchCityCallback(ret, response) {
			  if (ret.failed) {
				//wystąpił błąd
			  } else {
				var $searchedCitiesDiv = jQuery('#searchedCities');
				$searchedCitiesDiv.html('Znaleziono ' + response.count + ' miejscowości.');
				var $list = jQuery(document.createElement('ul'));
				for (var i in response.data) {
				  var text = response.data[i].name + " (woj. " + response.data[i].county + ", pow." +
			response.data[i].commune + ", gm." + response.data[i].district + ")";
				  //poniższych parametrów nie będziemy wypisywać, ale posłużyć mogą do
				  //pokazania wyniku na mapie po kliknięciu bądź wyszukiwania ulic
				  //var localityId = response.data[i].localityId;
				  //var lon = response.data[i].localityGeom.lon;
				  //var lat = response.data[i].localityGeom.lat;
				  //var zoom = response.data[i].zoom;
				  jQuery(document.createElement('li')).html(text).appendTo($list);
				}
				$list.appendTo($searchedCitiesDiv);
			  }
			  //zwracamy null - wynik pojawi się na mapie
			  return;
			}
			var config = {
			  callBacks : {
				searchCity : searchCityCallback
			  }
			};
			jQuery('#test').mousedown(function() {
			  DoCelu.searchCity("Gd", "Polska", 0, "size", true, 5);
			});
		});
	});
//]]>
</script>
	

Funkcję wywołaliśmy z parametrami:

DoCelu.searchCity("Gd", "Polska", 0, "size", true, 5);

Wyszukane miejscowości