TMT4 P1 jQuery Mobile Plugin for Google Maps: Route Finder App

jQuery Mobile / Google Maps on Android

This Two-Minute Tutorial (TMT4 Part1) shows how to use a plugin with AppLaud to extend the functionality of jQuery Mobile available to an Android mobile web app. The plugin used acts as a wrapper for google maps, providing a simplified API for accessing Google Maps from jQuery Mobile: jQuery Google Maps plugin by Johan Säll Larsson. The sample app demonstrates an easy way to show a dynamic route map in a mobile web app and provide interactive directions using the device’s geolocation.

jQuery Google Maps Plugin (UI and Mobile)

The jQuery Google Maps plugin Version 3 is a jQuery plugin written to take away some of the headaches from working with the Google Map v3 JS API. Instead of having to use Google event listeners for simple events like tap, you can use jQuery touch events on the map and markers. It is also very flexible, highly customizable, lightweight (< 4KB) and works out of the box with jQuery Mobile. The plugin is well-documented and supported, and provides the most common functionality available from Google maps. The jQuery Google Maps plugin documentation integrates links to google maps APIs, classes and methods, shortening the learning curve for including google maps in a mobile web app. 

• jquery-ui-map documentation
• jquery-ui-map mobile examples
• jquery-ui-map forum
• jquery-ui-map download
  

Sample App Summary

Use dynamic location to provide map and directions to business location using Google Maps and PhoneGap geolocation:

• small map showing the location of a business on home screen
• full screen google interactive route map: current location to business location
  
• interactive written directions using google maps

Both maps and the directions are identical in every way (look and functionality) to Google’s version 3 maps, because they are google maps!

Prerequisites

• Installation of the latest MDS AppLaud plugin, see Get Started
• Complete TMT0 or equivalent (create project, edit files, run app on device or AVD)

Prep

• Download the attached zip file tmt4p1.zip
  
• /src directory contains:
  
• index.html - jQuery Mobile included, all pages and divs needed for app
  
• mapapp.js - skeleton javascript file, add javascript code to it in tutorial
  
• mapapp.complete.js - the complete javascript file, provided for convenience
  
• mapapp.css - important styling for map display
  
• /src/jquery.ui.map contains:
• jquery.ui.map.min.js - minified, version 3 plugin (basic map plugin functionality)
  
• jquery.ui.map.js - non-minified, version 3 plugin
  
• jquery.ui.map.services.min.js - non-minified, version 3 plugin (maps services functionality)
• jquery.ui.map.services.js - non-minified, version 3 plugin

Recommended Reading

• The jQuery Google Maps plugin documentation
• Complete API documentation with links to all google maps classes and methods
• jQuery Mobile Docs and Demos
• Google Maps Geocoding - post on MDS' forum titled "How To: Geocoding, Google Maps..." talks about geocoding with references to Google's excellent documentation on the subject
  

1. Create a new AppLaud project
 
Using the project creation wizard, create a new project that includes:

• Built-In PhoneGap
• jQuery Mobile Libraries
• Project Contents: locate the /src directory (see Prep step above)
  

Finish creating the project in the second window: fill in project name, etc. Upon completion the new project's /assets/www/ directory should appear as below.

2. Add Google Maps JS API v3 and the jQuery Google Maps plugin to the project

Adding a jQuery Plugin is usually as simple as including a javascript file in your html file. The reference to the plugin can point to a local copy or reference the file on a server.

To use the plugin javascript locally, import the plugin files:

Edit index.html to include google maps javascript before mapapp.js:

 <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>

Edit index.html to include the maps plugin files, before the mapapp.js and after google maps javascript:

 <script type="text/javascript" src="jquery.ui.map/jquery.ui.map.js"></script>
 <script type="text/javascript" src="jquery.ui.map/jquery.ui.map.services.js"></script>

Sanity test: The app can be deployed at this point, before any javascript is added, and should look like the following image. The Map button in the toolbar near the bottom can be used to navigate to the (empty) map and directions pages.

3. The Business Location (Destination)

The object mapdata defines the route destination. In the sample app, the location of the fictional business is in Stockholm, Sweden. Google maps uses a LatLng object to hold coordinates, created as shown below.

var mapdata = { destination: new google.maps.LatLng(59.3327881, 18.064488100000062) };

Note: Recommended method for implementing this app: use the default coordinates provided for a first run/sanity test. Once everything is running as desired, custom coordinates can be substituted. A convenient website for finding coordinates anywhere in the world is Get Lat Lon by Simon Willison.

Further Note: Want to use a street address instead? See forum post "How To: Geocoding, Google Maps..."

4. Create Small Map on Home Page

The API for the jQuery Google Maps plugin is defined by the wrapper method .gmap() used with a DOM element id (div). The home page, defined in index.html with jQuery data types: <div data-role="page" data-theme="c" id="page-home"> creates the element: <div "id="map_square"></div> on the page where the map will go.

Add the following code block to mapapp.js.

// Home page
$('#page-home').live("pageinit", function() {
    $('#map_square').gmap(
        { 'center' : mapdata.destination,
          'zoom' : 12,
          'mapTypeControl' : false,
          'navigationControl' : false,
          'streetViewControl' : false
        })
        .bind('init', function(evt, map) {
            $('#map_square').gmap('addMarker',
                { 'position': map.getCenter(),
                  'animation' : google.maps.Animation.DROP
 });                                                                                                                                                                                                               
        });
    $('#map_square').click( function() {
        $.mobile.changePage($('#page-map'), {});
    });
});


Alternative method: Modify index.html to include mapapp.complete.js instead of mapapp.js. The file mapapp.complete.js contains all the javascript for the app.

The code above uses map_square to create the small map on the home page, centered at the business location (mapdata.destination).  Documentation for all google map options can be found here.

The bound 'init' function of the plugin calls the method  'addMarker' to add a marker at the location after the map is created. More information on google markers here.

The area defined by map_square is then bound to the 'click' event handler, which will navigate to the page containing the full map when tapped.

For the desired layout and appearance, css styling and jQuery Mobile features are used in index.html and mapapp.css to control the size and location of the map.

5. Create the main map and directions page

Add the following code to the end mapapp.js. The function fadingMsg is used to briefly display the provided message to the user in a fading message box.

jQuery Mobile's pageinit event is used to create the map the first time the page is navigated to. The fullscreen map is created using the div id and plugin api: $('#map_canvas').gmap(... This call creates the new map centered at the destination, and binds an init function used by the maps plugin. The init function is called after the new google map is created, initialized and any option values applied.

The event handler bound to 'tap' on the refresh button (see the footer on page with id="page-map" in index.html) updates the map and directions panel (see the page id="page-dir" in index.html).