Memberikan Arah Mengemudi Kepada Pelanggan Anda dengan API Google Maps

Indonesian (Bahasa Indonesia) translation by ⚡ Rova Rindrata (you can also view the original English article)

Daripada hanya menampilkan lokasi bisnis Anda di Google Map, mengapa tidak menawarkan kesempatan kepada pengguna Anda untuk mendapatkan petunjuk arah mengemudi di halaman yang sama? Tidak perlu bagi mereka untuk membuka jendela browser baru dan menemukannya sendiri, kita bisa melakukan lebih baik dari itu!

Menggunakan API Google Maps dalam situs web WordPress Anda adalah proses yang relatif sederhana dan kita akan mengeksplorasi cara melakukannya dalam tutorial ini.

Apa yang Akan Kita Lakukan dalam Tutorial Ini...

Pertama-tama, kita akan menyiapkan beberapa custom options sehingga kita dapat memasukkan informasi tentang peta kita di panel Admin WordPress.
Kemudian kita akan menggunakan shortcode untuk menghasilkan kontainer peta, field input, dan kontainer arah
Akhirnya kita akan menulis beberapa JavaScript untuk memulai Google Map

Catatan: Kita akan menulis sedikit JavaScript di sini, tapi jangan khawatir! Ini adalah tutorial WordPress jadi jangan ragu untuk mengabaikan bagian JavaScript :)

Langkah 1 Buat Direktori dan File

Buat folder di dalam tema Anda yang disebut Map
Di dalam folder ini, buat map.php
Akhirnya buat map.js

Langkah 2 Menyertakan file map.php

Dalam file functions.php Anda (terletak di direktori root tema Anda) - sertakan file map.php yang Anda buat di bagian atas.

 /* functions.php */
 include('map/map.php');

Langkah 3 Mendaftar Pengaturan

Ada 3 hal yang ingin kita edit dari area Admin.

Tempat tujuan. Kita akan menggunakan nilai Bujur dan Lintang untuk menentukan lokasi yang tepat dari tujuan Anda (rincian lebih lanjut untuk diikuti)
Konten infoWindow. Ini adalah gelembung putih yang sering Anda lihat di Google Maps - kita ingin dapat mengedit teks dalam gelembungnya!
Tingkat Pembesaran Awal dari peta - seberapa jauh peta diperbesar ketika pengguna pertama kali memuat halaman.

Di map.php, hook ke admin_init untuk mendaftarkan pengaturan kita:

 function map_init() {
   register_setting('general', 'map_config_address');
 	register_setting('general', 'map_config_infobox');
 	register_setting('general', 'map_config_zoom');
 }
 
 add_action('admin_init', 'map_init');

Sekarang kita dapat mengatur teks heading untuk bagian kita di halaman opsi dan semua masukan yang kita butuhkan.

 function map_config_option_text() {
 	echo '<p>Set Options for the Map here:</p>';
 }
 
 // Longitude, Latitude Values for the Destination
 function map_config_address() {
 	printf(('<input type="text" id="map_config_address" name="map_config_address" value="%s" size="50"/>'), get_option('map_config_address'));
 }
 
 // The text content for the InfoWindow Bubble
 function map_config_infobox() {
 	printf(('<textarea name="map_config_infobox" id="map_config_infobox" cols="30" rows="3">%s</textarea>'), get_option('map_config_infobox'));
 }
 
 // The initial Zoom Level of the map.
 function map_config_zoom() {
 	printf(('<input name="map_config_zoom" id="map_config_zoom" value="%s" />'), get_option('map_config_zoom'));
 }

Akhirnya kita menghubungkan ke admin_menu untuk menampilkan pengaturan kita di Admin WordPress:

 function map_config_menu() {
 	add_settings_section('map_config', 'Map Configuration', 'map_config_option_text', 'general');
 	add_settings_field('map_config_address', 'Address - Longitude and Latitude', 'map_config_address', 'general', 'map_config');
 	add_settings_field('map_config_infobox', 'Map InfoWindow', 'map_config_infobox', 'general', 'map_config');
 	add_settings_field('map_config_zoom', 'Map Zoom Level', 'map_config_zoom', 'general', 'map_config');
 }
 add_action('admin_menu', 'map_config_menu');

Pergilah ke area admin Anda, Anda seharusnya sekarang melihat ini:

Langkah 4 Masukkan Tujuan Anda, teks InfoWindow dan Tingkat Pembesaran

Alamat Tujuan

API Google Maps benar-benar menerima alamat reguler seperti 'Newgate Lane, Mansfield, Nottinghamshire, UK' – Namun, Anda akan menemukan bahwa Anda akan ingin lebih tepat dengan tujuan Anda (misalnya, Anda kemungkinan besar ingin menunjukkan langsung ke bisnis Anda dan bukan hanya jalanannya). Anda dapat menggunakan Sampel API Google Maps V3 untuk mencari tujuan Anda. Seret target ke sekeliling sampai Anda menyematkan titik Anda. Bila Anda senang, salin nilai Lat/Lng: ke dalam field alamat dalam opsi – misalnya 27.52774434830308, 42.18752500000007 (hanya angka yang dipisahkan oleh koma, tanpa tanda kurung atau tanda kutip!)
Teks InfoWindow

Buat ini sesuka Anda. Nama Bisnis Anda akan menjadi ide yang bagus :)
Tingkat Pembesaran

Titik awal yang baik adalah 10.

Klik 'Save Changes' dan ketika halaman disegarkan Anda dapat memeriksa bahwa info telah disimpan. Seharusnya terlihat seperti ini sekarang:

Langkah 5 Mengatur Shortcode

Ketika kita selesai, kita akan memiliki 3 elemen: Map, Form, dan Directions – jadi dalam tutorial ini saya memutuskan untuk membaginya menjadi 3 shortcode yang terpisah. Ini akan memungkinkan kita untuk mengubah urutan/penempatan setiap item tanpa harus memodifikasi salah satu kode PHP kita. Misalnya, Anda dapat memutuskan untuk memiliki petunjuk di atas peta, bukan di bawah, atau di samping, dll.

Shortcode 1 : wpmap_map

Di sini kita mendaftarkan dan memasukkan file JavasScript API Google Maps serta file maps.js kita sendiri.

Selanjutnya kita menggunakan variabel $output untuk menyimpan div map-container bersama dengan beberapa atribut data kustom. (data-map-infowindow akan menyimpan konten untuk infowindow dan data-map-zoom akan mewakili tingkat pembesaran awal – kedua nilai ini dikembalikan menggunakan fungsi get_option WordPress).

Akhirnya kita mengembalikan HTML yang dihasilkan menjadi keluaran:

 		function wpmap_map() {
 
 			wp_register_script('google-maps', 'http://maps.google.com/maps/api/js?sensor=false');
 			wp_enqueue_script('google-maps');
 
 			wp_register_script('wptuts-custom', get_template_directory_uri() . '/map/map.js', '', '', true);
 			wp_enqueue_script('wptuts-custom');
 
 			$output = sprintf(
 				'<div id="map-container" data-map-infowindow="%s" data-map-zoom="%s"></div>',
 				get_option('map_config_infobox'),
 				get_option('map_config_zoom')
 			);
 
 			return $output;
 		}
 		add_shortcode('wpmap_map', 'wpmap_map');

Shortcode 2 : wpmap_directions_container

Di sini kita hanya mengembalikan div kosong dengan ID dir-container. Ini akan bertindak sebagai kontainer untuk arah.

 		function wpmap_directions() {
 
 			$output = '<div id="dir-container" ></div>';
 			return $output;
 
 		}
 		add_shortcode('wpmap_directions_container', 'wpmap_directions');

Shortcode 3 : wpmap_directions_input

Ini menghasilkan Markup yang diperlukan untuk formulir kita.

Ini juga tempat kita akan menetapkan opsi kustom akhir kita – Alamat tujuan. Kali ini, kita akan menggunakan field formulir tersembunyi untuk menyimpan nilai Lintang/Bujur yang kita masukkan sebelumnya di Panel Admin.

 		function wpmap_directions_input() {
 
 			$address_to = get_option('map_config_address');
 
 			$output = '<section id="directions" class="widget">
 						<strong>For Driving Directions, Enter your Address below :</strong><br />
 						<input id="from-input" type="text" value="" size="10"/>
 						<select class="hidden" onchange="" id="unit-input">
 							<option value="imperial" selected="selected">Imperial</option>
 							<option value="metric">Metric</option>
 						</select>
 						<input id="getDirections" type="button" value="Get Directions" onclick="WPmap.getDirections();"/>
 						<input id="map-config-address" type="hidden" value="' . $address_to . '"/>
 					</section>';
 			return $output;
 		}
 		add_shortcode('wpmap_directions_input', 'wpmap_directions_input');

Sekarang kita memiliki shortcode yang sudah disiapkan, Anda dapat melanjutkan dan mengetikkannya ke halaman Contact Us (atau halaman apa pun yang Anda suka).

Jika Anda melihat pratinjau halaman sekarang, semua yang akan Anda lihat adalah field masukan formulir. Itu karena kita belum menulis JavaScript kita yang akan menginisialisasi Peta dan div untuk petunjuk arah saat ini kosong.

Catatan: Sebelum kita masuk ke JavaScript, kita hanya perlu menambahkan ini ke style.css kita:

 #map-container {
 	width: 100%;
 	height: 400px;
 }

Langkah 7 Menulis JavaScript untuk Berinteraksi dengan API Google Maps

Sekarang saatnya untuk membuat keajaiban terjadi! Saya akan memberikan perincian singkat tentang apa yang akan kita lakukan pertama kali, kemudian kita akan menggali langsung ke kodenya.

Pertama kita akan membuat objek WMmap dan menetapkan properti-properti kepadanya (beberapa di antaranya akan kita raih dari markup yang kita buat di shortcode)
Kemudian kita akan menambahkan beberapa metode untuk menangani fungsi peta dan arah.
Salah satu metode ini, init, akan bertanggung jawab untuk memuat peta dan juga untuk mengatur beberapa nilai default seperti teks infoWindow, tingkat pembesaran dan posisi penanda awal (semua dari opsi WordPress)
Akhirnya kita akan mengatur event listener untuk memuat peta kita ketika halaman sudah siap.

Siap?

Saya akan menjelaskan setiap bagian dari kode selangkah demi selangkah, tetapi jangan khawatir jika Anda tersesat, kami akan menyatukan semuanya di akhir.

Menetapkan Properti

Mari buat objek kita dan atur beberapa properti. Di sini kita hanya meminta DOM untuk mengambil elemen HTML yang berisi nilai yang kita butuhkan. Nama properti yang kita gunakan harus sangat jelas dan cukup jelas (mapContainer jelas adalah Map Container, dll :))

Di sini kita juga mendapatkan beberapa objek dari API yang akan kita gunakan nanti ketika kita berurusan dengan Directions.

 var WPmap = {
 
 	// HTML Elements we'll use later!
 	mapContainer	: document.getElementById('map-container'),
 	dirContainer	: document.getElementById('dir-container'),
 	toInput			: document.getElementById('map-config-address'),
 	fromInput		: document.getElementById('from-input'),
 	unitInput		: document.getElementById('unit-input'),
 
 	// Google Maps API Objects
 	dirService		: new google.maps.DirectionsService(),
 	dirRenderer		: new google.maps.DirectionsRenderer(),
 	map				: null,
 
 	/* continues below */
 }

Metode-metode

Ini juga merupakan bagian dari objek WPmap kita, jika Anda tidak yakin bagaimana semuanya berhubungan bersama, pastikan untuk memeriksa bagian bawah tutorial ini untuk melihat semua kode bersama-sama.

`showDirections()`

Ini dipanggil dari dalam metode lain yang akan kita lihat nanti, pada dasarnya mengontrol penyisipan petunjuk ke halaman.

 /* within WPmap object */
 showDirections:function (dirResult, dirStatus) {
 	if (dirStatus != google.maps.DirectionsStatus.OK) {
 		alert('Directions failed: ' + dirStatus);
 		return;
 	}
 
 	// Show directions
 	WPmap.dirRenderer.setMap(WPmap.map);
 	WPmap.dirRenderer.setPanel(WPmap.dirContainer);
 	WPmap.dirRenderer.setDirections(dirResult);
 },

`getStartLatLng()`

Ini dipanggil sekali dari metode init kita. Ini akan mengatur properti startLatLng sama dengan objek google.maps.LatLng yang bisa kita gunakan nanti. Ini mengharuskan kita memberikannya nilai Lintang dan Bujur terpisah – bagaimana kita dapat melakukan ini?

Dalam shortcode kita, kita menyisipkan field formulir tersembunyi yang berisi nilai Lintang & Bujur yang kita tetapkan di Admin WordPress. Lalu kita mengambil field formulir tersembunyi dan menyimpannya di toInput. Ini berarti kita sekarang dapat mengakses nilainya menggunakan WPmap.toInput.value
Namun, nilai yang kita tetapkan dalam formulir hanyalah string dengan koma yang memisahkan angkanya. Untuk memisahkan nilai, kita dapat membagi string menggunakan .split(","). Ini akan mengembalikan array yang berisi Garis Lintang dan Bujur sebagai nilai terpisah.
Sekarang kita dapat mengakses masing-masing dengan menggunakan indeks array.

 	/* within WPmap object */
 	getStartLatLng: function () {
 		var n = WPmap.toInput.value.split(",");
 		WPmap.startLatLng = new google.maps.LatLng(n[0], n[1]);
 	},

`getSelectedUnitSystem()`

Karena kita telah mengizinkan pengguna kita untuk memilih apakah mereka akan lebih memilih arah di Metrik atau Imperial, kita menggunakan metode ini untuk mengatur DirectionsUnitSystem baik ke METRIC atau IMPERIAL.

 	/* within WPmap object */
 	getSelectedUnitSystem:function () {
 		return WPmap.unitInput.options[WPmap.unitInput.selectedIndex].value == 'metric' ?
 			google.maps.DirectionsUnitSystem.METRIC :
 			google.maps.DirectionsUnitSystem.IMPERIAL;
 	},

`getDirections()`

Ini adalah metode yang dipanggil ketika pengguna mengklik tombol Get Directions.

Pertama kita mendapatkan alamat yang dimasukkan pengguna dan menyimpannya di variabel fromStr.
Selanjutnya kita mengatur objek opsi – dirRequest. Ini akan berisi opsi yang diperlukan untuk menyediakan Driving Directions.
1. origin – Alamat yang dimasukkan pengguna.
2. destination – Objek google.maps.LatLng yang mengandung nilai Lintang dan Bujur dari tujuan Anda.
3. travelMode – Di sini kita memastikan kita hanya mengambil Driving Directions.
4. unitSystem – Menentukan unit pengukuran mana yang akan digunakan berdasarkan pilihan pengguna.
Akhirnya, kita memanggil WPmap.dirService.route – dan mengirimkan dua parameter ke dalamnya:
1. dirRequest – ini adalah objek yang berisi opsi kita.
2. WPmap.showDirections – fungsi callback yang menangani penempatan petunjuk arah ke halaman.

 	/* within WPmap object */
 	getDirections:function () {
 
 		var fromStr = WPmap.fromInput.value;
 
 		var dirRequest = {
 			origin      : fromStr,
 			destination : WPmap.startLatLng,
 			travelMode  : google.maps.DirectionsTravelMode.DRIVING,
 			unitSystem  : WPmap.getSelectedUnitSystem()
 		};
 
 		WPmap.dirService.route(dirRequest, WPmap.showDirections);
 	},

`init()`

Ini adalah metode yang dipanggil ketika halaman dimuat. Ini bertanggung jawab untuk:

Inisiasi peta, berpusat pada alamat Anda.
Mengambil nilai-nilai yang diperlukan untuk mengatur teks infoWindow dan tingkat Zoom awal.
Mengatur pin penanda menunjukkan alamat Anda.
Mendengarkan ketika pengguna mengklik 'Get Directions' sehingga dapat menghapus Marker awal dan infoWindow

 	init:function () {
 
 		// get the infowindow text and zoom level
 		var infoWindowContent = WPmap.mapContainer.getAttribute('data-map-infowindow');
 		var initialZoom       = WPmap.mapContainer.getAttribute('data-map-zoom');
 
 		// call the method that sets WPmap.startLatLng
 		WPmap.getStartLatLng();
 
 		// setup the map.
 		WPmap.map = new google.maps.Map(WPmap.mapContainer, {
 			zoom      : parseInt(initialZoom),
 			center    : WPmap.startLatLng,
 			mapTypeId : google.maps.MapTypeId.ROADMAP
 		});
 
 		// setup the red marker pin
 		marker = new google.maps.Marker({
 			map       : WPmap.map,
 			position  : WPmap.startLatLng,
 			draggable : false
 		});
 
 		// set the infowindow content
 		infoWindow = new google.maps.InfoWindow({
 			content : infoWindowContent
 		});
 		infoWindow.open(WPmap.map, marker);
 
 		// listen for when Directions are requested
 		google.maps.event.addListener(WPmap.dirRenderer, 'directions_changed', function () {
 
 			infoWindow.close();         //close the initial infoWindow
 			marker.setVisible(false);   //remove the initial marker
 
 		});
 	}//init
 
 };// <-- this is the end of the object.

Pilihan

Jika Anda ingin menampilkan pesan yang bagus (seperti yang terlihat di bawah) kepada pengguna Anda setelah mereka meminta petunjuk, cukup salin kode di bawah gambar ke event listener di dalam metode init.

Pesan Terima Kasih opsional:

 	// Get the distance of the journey
 	var distanceString = WPmap.dirRenderer.directions.routes[0].legs[0].distance.text;
 
 	// set the content of the infoWindow before we open it again.
 	infoWindow.setContent('Thanks!<br /> Looks like you\'re about <strong> ' + distanceString + '</strong> away from us. <br />Directions are just below the map');
 
 	// re-open the infoWindow
 	infoWindow.open(WPmap.map, marker);
 
 	setTimeout(function () {
 		infoWindow.close()
 	}, 8000); //close it after 8 seconds.

Langkah 8 Menambahkan Event Listener yang Akan Memuat Peta

Apakah Anda masih dengan saya? Kita telah berhasil sampai akhir sekarang dan yang tersisa adalah memanggil metode WPmap.init() saat halaman dimuat. Tambahkan ini ke bagian bawah map.js

 google.maps.event.addDomListener(window, 'load', WPmap.init);

Menempatkan Semua JavaScript Bersama

Kita telah membahas banyak hal di sini, jadi mari kita lihat bagaimana tampilannya ketika semuanya disatukan.

 var WPmap = {
 
 	// HTML Elements we'll use later!
 	mapContainer   : document.getElementById('map-container'),
 	dirContainer   : document.getElementById('dir-container'),
 	toInput        : document.getElementById('map-config-address'),
 	fromInput      : document.getElementById('from-input'),
 	unitInput      : document.getElementById('unit-input'),
 	startLatLng    : null,
 
 	// Google Maps API Objects
 	dirService     : new google.maps.DirectionsService(),
 	dirRenderer    : new google.maps.DirectionsRenderer(),
 	map:null,
 
 	showDirections:function (dirResult, dirStatus) {
 		if (dirStatus != google.maps.DirectionsStatus.OK) {
 			alert('Directions failed: ' + dirStatus);
 			return;
 		}
 
 		// Show directions
 		WPmap.dirRenderer.setMap(WPmap.map);
 		WPmap.dirRenderer.setPanel(WPmap.dirContainer);
 		WPmap.dirRenderer.setDirections(dirResult);
 	},
 
 	getStartLatLng:function () {
 		var n = WPmap.toInput.value.split(",");
 		WPmap.startLatLng = new google.maps.LatLng(n[0], n[1]);
 	},
 
 	getSelectedUnitSystem:function () {
 		return WPmap.unitInput.options[WPmap.unitInput.selectedIndex].value == 'metric' ?
 			google.maps.DirectionsUnitSystem.METRIC :
 			google.maps.DirectionsUnitSystem.IMPERIAL;
 	},
 
 	getDirections:function () {
 
 		var fromStr = WPmap.fromInput.value; //Get the postcode that was entered
 
 		var dirRequest = {
 			origin      : fromStr,
 			destination : WPmap.startLatLng,
 			travelMode  : google.maps.DirectionsTravelMode.DRIVING,
 			unitSystem  : WPmap.getSelectedUnitSystem()
 		};
 
 		WPmap.dirService.route(dirRequest, WPmap.showDirections);
 	},
 
 	init:function () {
 
 		// get the content
 		var infoWindowContent = WPmap.mapContainer.getAttribute('data-map-infowindow');
 		var initialZoom       = WPmap.mapContainer.getAttribute('data-map-zoom');
 
 		WPmap.getStartLatLng();
 
 		// setup the map.
 		WPmap.map = new google.maps.Map(
 			WPmap.mapContainer,
 			{
 				zoom: parseInt(initialZoom),     //ensure it comes through as an Integer
 				center: WPmap.startLatLng,
 				mapTypeId: google.maps.MapTypeId.ROADMAP
 			}
 		);
 
 		// setup the red pin marker
 		marker = new google.maps.Marker({
 			map: WPmap.map,
 			position: WPmap.startLatLng,
 			draggable: false
 		});
 
 		// set the infowindow content
 		infoWindow = new google.maps.InfoWindow({
 			content:infoWindowContent
 		});
 		infoWindow.open(WPmap.map, marker);
 
 		// listen for when Directions are requested
 		google.maps.event.addListener(
 			WPmap.dirRenderer,
 			'directions_changed',
 			function () {
 
 				infoWindow.close();         //close the first infoWindow
 				marker.setVisible(false);   //remove the first marker
 
 				// setup strings to be used.
 				var distanceString = WPmap.dirRenderer.directions.routes[0].legs[0].distance.text;
 
 				// set the content of the infoWindow before we open it again.
 				infoWindow.setContent('Thanks!<br /> Looks like you\'re about <strong> ' + distanceString + '</strong> away from us. <br />Directions are just below the map');
 
 				// re-open the infoWindow
 				infoWindow.open(WPmap.map, marker);
 				setTimeout(function () {
 					infoWindow.close()
 				}, 8000); //close it after 8 seconds.
 
 			}
 		);
 	}//init
 };
 
 google.maps.event.addDomListener(window, 'load', WPmap.init);

Catatan Tutorial

Pastikan untuk meneliti apa pun yang tidak Anda pahami di Situs Web API Google Maps
Saat menulis tutorial ini, saya menguji kode saya menggunakan TwentyEleven WordPress Theme bawaan. Sesuatu menyebabkan panah di bagian bawah InfoWindow di peta untuk ditampilkan dengan tidak benar. Itu karena .entry-content img pada baris 857 memiliki satu set max-width. Ini mengacaukan cara Google membuat infoWindow. Untuk memperbaikinya, masukkan ini di suatu tempat di bawah ini:
```
 			#map-container img { max-width: none; }
```