PrintLet's examine this start-up page and discuss its various pieces. Now that you are familiar with HTML, you should recognize the <html>, <head> and <body> tags. You should also recognize that the <!DOCTYPE> directive declares that the document is written as HTML5.
After defining the page's title (Simple Map), the <head> of the document contains two <meta> elements. The first of these is concerned with rendering the document in a user-friendly way across a variety of devices (part of the larger CSS topic of responsive web design [http://www.w3schools.com/css/css_rwd_viewport.asp]. This is not critical for you to dive into now, but you may want to return to this topic if you are developing for mobile phones or tablets). The second meta element specifies that your document is encoded in the UTF-8 character set, one that supports all of the world's major languages. It's a good idea to include this line verbatim in all of your map pages. If you're an insomniac, you may want to read more about character encoding [http://www.w3schools.com/charsets/default.asp].
The next block of code within the head is a style element containing a few CSS settings. The basic idea behind these settings is to produce the best consistency in the rendering of the document by different browsers. The document as a whole (i.e., the html element) should take up 100% of the available space in the browser window. The body element, in turn, should take up 100% of its parent container, the html element. The body's margin and padding are also set to 0px, which in effect specifies that there should be no whitespace added to either the exterior or interior of the body element's boundary. Finally, the element with the ID of "map" has its height set to 100% of its parent container.
Next comes the body of the document, in which the first thing you'll find is a div element. div elements are used to create divisions, or sections, in a document. In a Google Maps API context, a div is typically used as the container for the page's map. Note that this div is assigned an id of map. This is consistent with the style setting mentioned a moment ago and, as we'll soon see, with the creation of the Map object in the JavaScript code.
After the map div, you'll find two <script> elements, which are used to define scripts written in JavaScript. The first of these elements specifies how to create the map to be inserted on the page (more on this later), while the second sets up a reference to the current version of the Google Maps API by setting the element's src attribute equal to a Google URL. Including this script element is critical to building a working application. Without it, the browser won't know what to make of the JavaScript code that's found in the first script element.
Learn More
At this point, you should familiarize yourself with the syntax of JavaScript (JS). The w3schools site offers a good hands-on JavaScript tutorial that should do the job. Take a couple of hours to work through the topics listed under the JS Tutorial heading and pay particular attention to the following points:
- Ending statements with a semicolon is optional. (The start-up script from Google uses semicolons.)
- Note the difference between placing scripts inside the page's head section and its body section.
- JavaScript is a dynamically typed language; you do not need to specify a data type when declaring a variable.
- JavaScript variables are case sensitive.
- Variables can be initialized on the same line that they are declared.
- Code associated with a conditional statement (if or else statements) or a loop (for or while) must be enclosed in braces.
- Alert boxes can be used to debug scripts that aren't working properly.
- JS functions are reusable blocks of code with an optional return value.
- The backslash (\) can be used to insert special characters in a string (e.g., if you want a string enclosed in double quotes to also contain a double quote).
- Comments are signaled in JS using two slashes (//).
Now that you've learned a bit about JavaScript, we can examine the part of the file that loads the map onto the page. The first <script> element declares a variable called map, then defines a function called initMap(). Because the map variable is declared outside of the function, it has a global scope. In other words, if there were a second function -- say, loadData() -- the map variable could be used in that second function, whereas if the variable had been declared within initMap(), it would not be usable in a different function.
Before discussing what's going on in initMap(), first scan through it, and note the occurrence of the string "google.maps." This is an example of a namespace. The usage of namespaces is deserving of a lesson in itself, but you can get by with the basic knowledge that namespaces are used to prevent confusion when multiple classes share the same name. For example, the Hello, World page that we're discussing here references (or sources) a JavaScript code library stored on a Google server. One of the classes defined in that library is called Map. If you wanted to, you could develop your own class named Map, but you'd need a way to distinguish between your class and Google's. That's where namespaces come in. To use Google's Map class with no chance of confusion, we add the prefix "google.maps." to the class name.
To understand what's going on in initMap(), open the API Reference in a new tab. The API Reference is a large page containing documentation on all of the entities built into the API. The Contents section at the top of the page (collapsed by default) provides links to the part of the page that deals with the associated entity (class, object specification or constant). For example, if you click on the Map class, you'll be redirected to the section that describes that class's constructor (i.e., information on the parameters that are specified when creating a Map object), its methods (actions that the Map class is programmed to perform), its properties (characteristics that uniquely define Map objects) and its events (interactions with the Map that are triggered by the user and can be programmed against by you the developer).
Method parameters (pieces of information the method uses in performing its action) are listed in parentheses after the name. If a parameter is optional, it will be listed with a question mark next to it. If a method returns a value when it is called, the type of return value will be listed next to the method name and parameters. Finally, there is a brief description listed for each method.
Note that some methods return a basic data type like a Number, String or Boolean, while others return an object (anything presented as a link). Following one of these object name links will jump you to that object's section of the documentation.
The API Reference is good for getting a sense of everything that you can do as a developer with the API. However, it is not always easy to translate the information found in the API Reference into a working custom map application. That is where the code Samples page can be quite helpful.
Getting back to initMap(), it creates an object of the Map class, so we'll want to look at the constructor for that class. The documentation tells us that when creating a new Map object, we need to specify a container that will hold the Map. As we saw earlier, a div was created for this purpose and assigned an id of map. Getting a reference to that div element within your JavaScript code is done using the HTML Document Object Model (DOM).
Learn More
Once again, the w3schools site offers a good JavaScript HTML DOM tutorial. This short tutorial should only take you 30-60 minutes to complete. Pay particular attention to the usage of the getElementById() and getElementsByTagName() methods.
Returning to the documentation of the Map class constructor, note that we can optionally specify a MapOptions object when creating a Map. Following the MapOptions link takes you to a section of the API Reference labeled "MapOptions object specification." The wording of this header indicates that we're dealing with a JavaScript object literal, a term that may seem intimidating, but is actually not too difficult to grasp. Object literals are basically a list of property/value pairs, in which the list is enclosed in curly braces and the property/value pairs are separated by commas. Unlike a class such as Map, an object literal has no class constructor, methods or events. In this case, the object literal is specified using two property/value pairs: a center property, which is itself set equal to an object literal defined as a lat/lng pair, and a zoom property, which is set to a value of 8. Note that it is possible to store an object literal in a variable. For example, an alternative to the syntax seen in the Hello, World script would look like this:
var myMapOptions = {
center: {lat: -34.397, lng: 150.644},
zoom: 8
}
map = new google.maps.Map(document.getElementById('map'), myMapOptions);
Finally, here are a couple of important points to note:
- The second script element uses two attributes to control the loading and execution of the Google Maps API code. The default behavior for browsers is to pause the rendering of other HTML elements when they encounter a script element. The async attribute (introduced in HTML5) tells the browser to continue rendering the HTML and to load and execute the JavaScript code at the same time. The defer attribute (which has been around longer than async) similarly tells the browser to continue rendering the HTML while it loads the JavaScript code. The difference with defer is that it instructs the browser to wait to execute the JavaScript until the HTML is fully rendered. The two attributes can be used together to still get the "don't-stop-rendering" behavior even in older browsers that don't support HTML5 (and async). You can find further discussion of these attributes in this blog post, if you're interested. I wouldn't be too concerned if you're a bit fuzzy on the topic though, as it's not critical for a novice developer to understand.
- What is critical to understand are the key and callback parameters appended to the API URL. If you're adapting this example to create a page of your own, you'll want to replace the "API_KEY" value with the one that you obtained earlier in the lesson. Likewise, the value assigned to the callback parameter (the name of the function to execute when the API is done loading) may need modification depending on how you name your initialization function. For example, if you name your function initialize rather than initMap, you'll need to change the callback parameter accordingly.
Now that you understand the workings of the Google Maps Hello, World page, you'll see how to add a marker to your map in the next section.