Chapter 11. jQuery and APIs: Objects, Objects Everywhere

As talented a developer as you are, you can’t do it all alone... We’ve seen how we can include jQuery plug-ins, like jQuery UI or the tabs navigation to help boost our jQuery app, without much effort. To take our applications to the next level, apply some of the really cool tools out there on the Internet, and use information provided by the big hitters—like Google, Twitter, or Yahoo!—we need something...more. Those companies, and many others, provide APIs (application programming interfaces) to their services so you can include them in your site. In this chapter, we’ll look at some API basics and use a very common one: the Google Maps API.

Where’s Waldo Sasquatch?

Dr. Pattersby and Dr. Gimli want to add some more cool features to their website—think you’re up to the task?

From: Dr. Gimli [gimli@cryptozoolologists.org]

Subject: Some more updates to our site

Hey guys,

Thank you so much for helping make our website more user-friendly and easier to collect data about sightings. We’ve had a substantial increase in traffic, so we’re really excited to look at all the data we’re collecting.

We’ve had several requests to make the information more accessible to the masses. Lots of people are interested in the sightings data, so we’d like to give them a way to see what we’ve collected.

Here’s what we need:

1. We’d like to be able to select a single sighting and view the information associated with it. Along with the information about the cryptid, we’d like to see the latitude/longitude information appear on a Google map.

2. When a point is displayed on the Google map, we’d like to be able to click it to see more information about the sighting.

3. We’d like to be able to select the creature type from a list and display all the creatures associated with that type from our database. We’d also like to see all the creatures with that type on a Google map, so we can find some sighting hotspots to examine more closely. Can all these points be clickable, as well as the list of creatures, so users can see more information about each one?

Not too much to ask, right, since we already have all the information stored?

Looking forward to hearing from you!

--

Dr. Gimli and Dr. Pattersby

cryptozoologists.org

Joe: Are you talking about the Google map we need to build?

Frank: Yep. Pretty straightforward...

Jim: Straightforward? They want a whole Google map!

Frank: Yep.

Jim: Multiple points on the map—one for each of their cryptids—each being clickable for more information...

Frank: Yeah, I think I know how to do that.

Jim: And custom click on the list to interact with the points and show the “more information” pop ups on the map.

Frank: Yeah, uh, I’m not too sure how to do that.

Joe: No worries on that part. The Google Maps folk provide an API we can use to get the job done.

Jim: AP what?

Frank: API. It’s short for application programming interface. It’s how companies like Google, Netflix, and Yahoo! enable us to use some of their cool tools on our own sites.

Jim: That does sound pretty cool, but will it give us all the pop ups and whatever else we need to put on the map?

Joe: Well, it should. Maybe we should look at the Google Maps API to see how it works.

The Google Maps API

For any API you want to use, you can look up documentation and get sample code online. We grabbed this sample from http://code.google.com/apis/maps.

var map;

function initialize() {
  var myLatlng = new google.maps.LatLng(40.720721,-74.005966);
  var myOptions = {
    zoom: 13,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);

  google.maps.event.addListener(map, 'zoom_changed', function() {
    setTimeout(moveToNewYork, 3000);
  });

  var marker = new google.maps.Marker({

      position: myLatlng,
      map: map,
      title:"Hello World!"
  });
  google.maps.event.addListener(marker, 'click', function() {
    map.setZoom(8);
  });
}

function moveToNewYork() {
  var NewYork = new google.maps.LatLng(45.526585, -122.642612);
  map.setCenter(NewYork);
}

That’s Google’s code.

It’s not as bad as it looks. Let’s see what’s going on in the code in a little more detail.

APIs use objects

Back in Chapter 6, we created our own JavaScript objects with properties and methods to store and use information as we saw fit. Many companies—like Google, Netflix, Microsoft, and Yahoo!—also create API objects to allow us to interact with their data. If you need a little reminder, feel free to hop back there to reacquaint yourself with objects and how they work.

Because it speeds everything up.

Like we saw back in Chapter 6, objects offer smarter storage. You use objects when you need to store multiple variables about a particular thing. An API is just a series of object constructors that allow you to create your own instances of other people’s objects. Then, once you have an instance, you can use all the properties and methods associated with those objects in your code!

The complexities of creating a mapping application for everyone to use are exactly why Google uses objects in its API. That way, it can create objects with many different methods and properties for all the different elements you’d need to build a map.

From the code on the previous page, you can see that the map object has properties of zoom, center, and mapTypeId—plus many more that we haven’t shown here. The map also has many methods, like setCenter.

Do this!

Create a new page called display_one.html and save it in your project folder for this chapter.

Include Google maps in your page

First, make a copy of all the files you have from the end of the previous chapter. We’ll use all the same files in this solution too, so we might as well pick up where we left off. All that code plus your new display_one.html file will give us two important new things:

	A div with the ID of map_canvas.
	The Google Maps API code, by adding <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>.

To include a Google map on that page, you’ll need to create a maps.js file and add a function to it that calls the API code to build a map on the page.

jQuery Code Magnets

Rearrange the magnets to complete the code to create a function called initialize. This function will then create a new instance of the Google Maps map object, using some parameters defined in the code. The new map object will then be applied to the map_canvas element on the page. Also, update your existing form.css file to include some style definition for the map container.

jQuery Code Magnets Solution

Rearrange the magnets to complete the code to create a function called initialize. This function will then create a new instance of the Google Maps map object, using some parameters defined in the code. The new map object will then be applied to the map_canvas element on the page. Also, update your existing form.css file to include some style definition for the map container.

There are no Dumb Questions

Q:	Q: What about that LatLng object and mapOpts property?
A:	A: You can find more information about the API’s objects, methods, and more at http://code.google.com/apis/maps/documentation/javascript/reference.html. This website offers some example code and more details about all the different objects and methods you’ll need to interact with.
Q:	Q: Is Google Maps my only option for creating a map?
A:	A: Definitely not! It is probably the most popular though, which is why we’re using it here. Other companies like Yahoo!, Microsoft, MapQuest, and OpenLayers also offer Mapping APIs.

Test Drive

Update your maps.js file with the initialize function you put together with the magnets. Also, ensure that the maps.js file is included in display_one.html. Then, open up display_one.html in your browser. You should run all your code through your web server, so the URL should say http://, not file://.

Exactly.

Back in Chapter 9, you learned how we can get information from a MySQL database, using jQuery, Ajax, JSON, PHP, and MySQL. Although that’s quite a list of technologies, it did exactly what we needed it to. Let’s see how we can apply that here again.

Getting JSON data with SQL and PHP

Chapter 9 showed how a SQL select statement could pull the information you wanted out of the database so that a PHP file could turn it into JSON and return it to our page, using Ajax.

You also learned how to use Ajax to get JSON-encoded information from a PHP file. For PHP to return JSON data, it was easy—the json_encode function, which accepted an array, gave back JSON-encoded data so that jQuery could interact with it.

For this chapter, we’ve written all of the PHP and SQL for you. As long as you’ve got the MySQL database from Chapter 10, you’re good to go! The rest of the SQL and PHP code are in the downloads for this chapter. Feel free to run them on your own server. You can download all the PHP and SQL in a single file from http://thinkjquery.com/chapter11/end/service.zip.

jQuery, HTML, and CSS Code Magnets

Rearrange the magnets to update your display_one.html, forms.css, and maps. js files to get your data via JSON and display it on the screen. Add a div and a ul element to hold the data, some CSS to style the list, and a function to get the data, via JSON, to add each cryptid to the list.

jQuery, HTML, and CSS Code Magnets Solution

Rearrange the magnets to update your display_one.html, forms.css, and maps.js files to get your data, via JSON, and display it on the screen. Add a div and a ul element to hold the data, some CSS to style the list, and a function to get the data, via JSON, and add each cryptid to the list.

Test Drive

Update your maps.js file with the getAllSightings function you just completed. Also, add a call to this new function at the end of the initialize function. Then open up display_one.html in your browser. This assumes you’ve added some creatures to your database, back in Chapter 10; if not, be sure to do so now. Remember, you should run all your code through your web server, so the URL should say http://, not file://.

Right. We need to be able to add our cryptid data to the map.

Google Maps provides a very easy method to do this. Let’s have a look at how that works.

Points on a map are markers

When it comes to putting points on a map, Google’s got it down. However, Google doesn’t call them points. It calls them markers. Markers are objects—just like everything else in the Google Maps API—and have their own methods and properties for interaction and manipulation.

Sharpen your pencil

Update your getAllSightings function to add a click event listener to the list item, before it gets added to the list. This click event should call a custom function, called getSingleSighting, which take a single parameter—the ID of the clicked sighting. This new function should then load information about the clicked item and add it as a marker on the map, using its latitude and longitude properties.

Sharpen your pencil Solution

After you’ve completed the code, your list items will be clickable, which will then load data about the clicked cryptid and put it on the map.

Test Drive

Update your maps.js file with the getAllSightings and getSingleSighting functions you just completed. Then open up display_one.html in your browser, using http:// like before.

You’ve already nailed the first two requirements, so let’s have a look at the final thing the doctors asked for.

3)

We’d like to be able to select the creature type from a list and display all the creatures associated with that type from our database. We’d also like to see all the creatures with that type on a Google map so we can find some sighting hotspots to examine more closely. Can all these points be clickable, as well as the list of creatures, so users can see more information about each one?

Multicreature checklist

Here’s what we need in order to nail this last request:

1. A drop-down list with the list of creature types (selected from the database).

2. When the drop-down list changes, get a list of creatures from the database that match the selected type.

3. Display all the creatures returned from the database in the list and on the map.

4. Both the list and the map pointers should be clickable so users can get more information on the map to pop up.

Ready Bake Code

Create a new page called display_type.html and save it in the same directory as the other HTML files for this project. This new file will display the list of creature types that can be selected. Then, once selected, all the creatures of that type will be displayed on the map. The structure and style of this new page is very similar to our old page, except for the addition of a select element with the ID of ddlTypes.

jQuery Code Magnets

Rearrange the magnets to complete the getAllTypes function. This function will call the service.php file (which should be included in your downloads for this chapter) to get a list of the different creature types in the database. These creature types should then be added to the drop-down list, with the ID of ddlTypes. Also, create an event listener on the drop-down list to listen for a change event and alert the selected value. Finally, since we’re using the same maps.js file for our two HTML files, add some logic to the initialize function to check if the drop-down list exists. If it does, call the getAllTypes function. Otherwise, call the getAllSightings function.

jQuery Code Magnets Solution

Now you’ve got a drop-down list associated with your Google map, a function to grab the data (in JSON) on the selected creature types from the database, and an alert showing which creature type was selected.

Test Drive

Update your maps.js file with the getAllTypes function and the event listener for the change event on the drop-down list. Also, update your initialize function with this new logic. Then open up display_type.html in your browser, again using http://.

You’re really cookin’ now. You’ll have this map finished up in no time!

Time to cross off a couple of those requirements.

1. A drop-down list with the list of creature types (selected from the database).

2. When the drop-down list changes, get a list of creatures from the database that match the selected type.

3. Display all the creatures returned from the database in the list and on the map.

4. Both the list and the map pointers should be clickable so users can get more information on the map to pop up.

You’ve got us there.

We need to update our code so we can get information from the database when the drop-down list is changed, instead of just showing the creature type in an alert box.

Then we can mark that one off the list. But while we’re at it, we should be able knock off the third item on the list too. Roll up your sleeves—we’re about to dive in and put this all together.

Long Exercise

Fill in the missing lines of code to create a getSightingsByType function. This function should accept one parameter: the creature type you are viewing. This function should get its data in JSON format, loop through all the returned creatures (if there are any), and add points for each one on the map. Also, create two more global variables: an array called markerArray and a new Google Maps LatLngBounds object called bounds. Also, create a function that clears the previous points, before adding any new ones, if the drop-down list is changed.

Long Exercise Solution

With the addition of the two new global variables and some other Google Maps functions, you can now add and remove markers from the map when the drop-down list is changed. As the markers are being added to the map, they are also added to the markerArray array and used to extend the map’s bounds. This way, the map can autozoom to fit all the points, using the fitBounds function. The getSightingsByType function, now called on any change of the drop-down list, adds the markers to the map and adds the creature to the list on the page.

Geek Bits

We’ve included a function called clearOverlays that will remove the previously added markers before adding the new ones. Google refers to anything added to a base map as an overlay, which can be a Marker, a Line, a Polyline, a Polygon, or many other types of objects.

Test Drive

Update your maps.js file with the new code you just created. Then, open up display_type.html in your browser and select some creatures from the list.

1. A drop-down list with the list of creature types (selected from the database).

2. When the drop-down list is changed, get a list of creatures from the database that match the selected type.

3. Display all the creatures returned from the database in the list and on the map.

4. Both the list and the map pointers should be clickable so users can get more information on the map to pop up.

So close...just one more item to go!

Brain Power

You already know how to make things clickable with jQuery. How will this help complete the final requirement on the list?

There are no Dumb Questions

Q:	Q: So, is the Google Maps API free for me to use on my website?
A:	A: Yes! Google makes the API freely available to everyone who wants to use it—personal or commercial—as long as they comply with the Terms of Service.
Q:	Q: I don’t know if I comply or not. Where can I see the Terms of Service?
A:	A: Simply browse to http://www.google.com/apis/maps/terms.html to view the full Terms of Service.
Q:	Q: Does the Google Maps API cover the whole world?
A:	A: Not quite, but it’s close. There are only a few countries that are not covered. Check out the Google Maps API site to find the list.
Q:	Q: Can I show maps on a mobile device, using the Google Maps API?
A:	A: Yes, you can. At the time of publishing, version 3 of the Google Maps API has been released. It has been developed to cater to mobile devices with browsers capable of running JavaScript.
Q:	Q: But I’d rather write an app for that. Is the Google Maps API for me?
A:	A: If you’re writing for the Android or iPhone platforms, then yes. Google provides specific frameworks for both of these platforms for you to include in your app. If you’re writing for another mobile platform, there is no specific framework yet, so you’ll have to use the same as on your website.
Q:	Q: The full version of Google Maps lets me get directions. Can this API do that?
A:	A: No, you cannot do that with this API. There is another API produced by Google, called the Google Directions API, that you can use to find the directions.
Q:	Q: What about finding places on a map by address?
A:	A: In the business, they call this geocoding. Google has yet another API to do that: the Geocoding API. These are all part of the Google Maps API family. Also, luckily for you, whenever you request data from Google, it will return JSON data to you, which you already know how to handle!
Q:	Q: What else is in the Google Maps API family?
A:	A: Both the Directions and Geocoding APIs belong to a subsection called the Maps API Web Service. Also in that sub-section are the Distance API, the Elevation API, and the Places API.
Q:	Q: There’s even more?
A:	A: Yup. There’s also the Static Maps API for browsers that don’t fully support JavaScript; Maps API for Flash; and even an Earth API, which lets you load a Google Earth viewer into your page to get 3D images of the globe, as well as take virtual tours and draw shapes over the terrain. This one requires the Google Earth plug-in to be installed too, though.
Q:	Q: So JavaScript aside, can I get APIs for any other languages?
A:	A: Yes! There are countless numbers of APIs available—some free, some that require licensing. Chances are, if you’re looking for a specific piece of functionality you don’t want to write, there’s probably an API for it somewhere.

Listening for map events

We’re almost at the end here, and by now you’ve seen a whole variety of events that jQuery and JavaScript provide for making fun, interactive web apps. Since the Google Maps API is just JavaScript (albeit very well written and efficient JavaScript), it too can utilize the browser’s ability to listen for events and act accordingly.

And for the same reasons that jQuery added its own event listener creation functions, the folks on the Google Maps end of things have provided the capability to add event listeners through the API. This is because not all browsers deal with event listeners in the same way, so this ensures that the API can control how the listeners are added to the page. Let’s have a look at adding an event listener for the click event to create a Google Maps pop up (also called an InfoWindow):

Geek Bits

In the Google Maps API, almost all the different object types (Map, Marker, Line, InfoWindow, TrafficOverlay, Polygon, and more) have events associated with them. However, even if the events for the different objects have the same event name, they may take different parameters! Be sure to check the documentation for the object you want to use.

Sharpen your pencil

Fill in the missing pieces of code to complete the getSightingsByType function, which will add the click functionality to both the markers on the map and the items on the list. Also, create a global variable called info_window, which will be a new instance of the Google Maps InfoWindow object with the default content set to an empty string.

Sharpen your pencil Solution

You’ve now updated the getSightingsByType function to display in list format and on the map, along with making the map markers and the list clickable.

Test Drive

Update your maps.js file with the new code you created on the previous page. Then, open up display_type.html in your browser and select a creature from the list. Click on the markers or the list to view more information about the creature.

1. A drop-down list with the list of creature types (selected from the database, if possible).

2. When the drop-down list is changed, get a list of creatures from the database that match the selected type.

3. Display all the creatures returned from the database in the list and on the map.

4. Both the list and the map pointers should be clickable so users can get more information on the map to pop up.

You did it!

In just a few short pages, you managed to put together a fully functional website, using code from several different languages—PHP, SQL, JavaScript, and jQuery—as well as pairing up the the Google Maps API with Ajax and JSON to display some pretty complex data. No small feat!

APIcross

It’s time to sit back and give your left brain something to do. It’s your standard crossword; all of the solution words are from this chapter.

Across

Down

1. The code for a Google Maps API constructor that lets you put a point on a Google Map: google.maps: new google.maps.______(). 2. The Google Maps API we used in Chapter 11 is written in this language. 7. Once you have an instance of an API object, you can use all the properties and _______ associated with those objects in your code. 8. API = Application Programming _________. 9. We used this jQuery method to get data from the sightings database using JSON and PHP. 10. Google Maps API object that has the following properties: zoom,center, and mapTypeId.

1. To include the GoogleMaps API in your web page, use this script tag: <script src="http://____.______.___maps/ api/js?sensor=false"></script>. 3. Google Maps API method that listens for a click event on a marker: google.maps.event.___________. 4. The jQuery event listener you used in this chapter. When the value of data in a field changes, this listener is triggered. 5. An API is a series of object ____________, allowing you to create your own instances of the API provider’s objects. 6. The Google Maps API object constructor that lets you pass the latitude and longitude as a parameter.

APIcross Solution

Your jQuery API Toolbox

You’ve got Chapter 11 under your belt and now you’ve learned how to pull together jQuery with APIs (plus JavaScript, PHP, MySQL, Ajax, JSON, and more!).

APIs

Application programming interfaces are really just code provided by other people (or companies) that you can tap into for their data, objects, and other services.

They provide a series of object constructors, allowing you to create your own instances of other objects. Once you have an instance, you can use all the properties and methods associated with those objects in your code.

Leaving town...

It’s been great having you in jQueryville!

We’re sad to see you leave, but now that you have all the skills you need to build your own cool jQuery-powered websites, we’re sure you’d rather be doing that than hanging around here. It’s been great showing you around the world of jQuery. Feel free to drop us a line or tell us about your cool new site at the Head First Labs: http://headfirstlabs.com.