If you’re adding a map to your website, why settle for the vanilla design when you can customize it and leave your own personal mark?
This tutorial will show you how to create a custom map from scratch, then add a little unique flavor to it by replacing the standard “map pin” icon with a custom icon of your own design.
To do this, we’ll be using Mapstraction, a library that creates map code that can be reused across all the big mapping providers (Yahoo, Google, et al). Mapstraction also allows for multiple types of customization such as custom info bubbles and graphics like the one we’ll be dropping onto the map.
Note: This tutorial is adapted from the book Map Scripting 101 by Adam DuVander. Adam is a former Webmonkey contributor and executive editor of Programmable Web. In his book, he shows how to use all of the features of the most popular mapping APIs, and how to mash them up with data from other sources like events calendars, weather services and restaurant review sites to make a variety of custom maps.
This exercise comes from chapters 1 and 2 of Adam’s book, and it is reprinted here with his permission and that of the book’s publisher, No Starch Press. It isn’t a word-for-word excerpt. It has been slightly adapted to work as a web tutorial. You’ll find dozens of in-depth exercises — including the full version of this one — in the book itself.
Mapstraction is a little different from Google Maps and Yahoo Maps. Mapstraction is an open source JavaScript library that ties into other mapping APIs. If you use Mapstraction, you can switch from one type of map to another with very little work, as opposed to rewriting your code completely.
Using Mapstraction limits your risk to changes being made to an API. For example, if your site’s traffic takes you beyond the limit for your chosen provider, or the provider begins placing ads on the map, Mapstraction lets you switch providers quickly and inexpensively.
To use Mapstraction, you must first choose a provider. In this example, I’m using Mapstraction to create a Google Map.
Open a new HTML file and type the following:
Just like you would for a normal Google Map, we include Google’s JavaScript (line 4).
For this code to work, you also need to download the Mapstraction files. Go to mapstraction.com or the project’s github page, and follow the instructions to save the files in the same directory as your HTML file. Best practices would dictate that you keep JavaScript files in their own directory, separate from your HTML, but I’m simplifying things for this example.
The Mapstraction files you should have, at minimum, are mxn.js, mxn.core.js and googlev3.core.js. You may also have files for other providers, such as yahoo.core.js. The only one we need to reference in our HTML code is mxn.js, which loads the other files that it needs, including those we pass it in the file name. Then, in the create_map function, we let it know which type of map we are creating.
Once you have your Mapstraction map, save your HTML file and load it in a browser. The result should look exactly like this.
This Google map, created via Mapstraction, should be centered on No Starch Press’s neighborhood in San Francisco.
As you can see, the HTML hooks are minimal. Some styling to determine the size of the map and an empty div tag with an id attribute are all that’s required. The JavaScript function create_map() takes over and makes calls to the API. This function can have any name you want.
The minimum amount of information needed within the create_map() function is a map type (googlev3), a center point (using a latitude/longitude pair) and a zoom level (Mapstraction’s tightest zoom level is 16, so I backed off one notch to 15, about six blocks across). Then, we pass those options and reference the div tag’s id to create a map.
To add a simple marker to your map, you just need to use two Mapstraction functions. First, create the marker. Next, add it to the map. The reason for these two distinct steps will become clear in further projects when we start to use advanced options, such as custom marker icons.
Let’s see what creating the marker looks like in code. Start with the basic Mapstraction map you created and add these lines to the create_map() function:
marker = new mxn.Marker(new mxn.LatLonPoint(37.7740486,-122.4101883)); // marker options will go here mapstraction.addMarker(marker);
The first line creates a marker object, passing latitude/longitude coordinates for the No Starch Press offices in San Francisco. By drawing attention to the graphical marker, we are essentially marking that spot as important.
The second line is a placeholder for any marker options we want to add later. (Any JavaScript line that begins with two slashes is a comment, and the browser ignores them.) The marker options are where we tell Mapstraction which icon to use or add a message to be displayed when the marker is clicked.
Finally, the third line adds the marker to the map. Once this happens, no additional options can be added. The reason is that the marker object is used only by Mapstraction. Once the marker is added to the map, however, Mapstraction makes the appropriate calls to the mapping provider. Mapstraction plots the marker based on all options set beforehand. In this case, we don’t have options to add, but we’ll add to this map in future projects.
If you’re using Google as your mapping provider, your new map will look like the picture below. The default Google icon sits in the center of the map. Although the marker is clickable, this marker is very simple and nothing actually happens if you click it.
The quickest way to make a map feel like your own is to change the default icon used for markers. Mapstraction has simple marker options that make the technical process of using custom icons a cinch. The more laborious part may be creating the icon file itself. To avoid this, you can find icons others have made online for free. I list several resources on my website.
Still want to create your own? Read on.
To create your own marker icon, you just need to have a graphics program that can save a transparent .png file. The icon can be whatever size you want, but keeping each dimension between 20 and 50 pixels is probably best. If the icon is too small, clicking it becomes difficult; too big, and the icon obscures the location you’re attempting to call out. If you’re using Google as your mapping provider, you also want to create an image to use as your marker’s shadow. This step isn’t necessary if your marker is a similar shape to the Google default or if you’re using another provider.
Not much of an image magician? Use the free online Shadowmaker service to create a shadow.
Now that you have an icon, the easy part is adding it to the marker options. All it takes is setting a few values to tell Mapstraction where the icon image files resides. Your best bet is to keep custom marker icons in a special directory on your server. If you’re testing locally, you can use local copies, accessed by their location relative to the page containing the map. For simplicity, I have the HTML file and the icon files in the same directory in this example. In reality, you might prefer to be more organized.
I decided to use a teensy No Starch Press logo for my custom icon. It’s 27 pixels wide by 31 pixels high. Like I said, the icon is teensy. Then, I used the Shadowmaker service to create a file that is 43×31 including the marker’s shadow.
Finally, it’s time to code. Add these lines as marker options. These lines are inserted after a marker has been created but before the marker has been added to the map:
marker.setIcon('nostarch-logo.png', [27,31]); marker.setShadowIcon('nostarch-shadow.png', [43,31]);
The only parameter you need to include is the path to the image for both the icon and the shadow. Notice that the dimensions of each graphic get passed as an inline array. This parameter is optional but recommended. If you leave it out, some providers will assume the dimensions of the default marker, which could mean a poorly scaled graphic.
The results of the custom marker code are shown below.
The No Starch Press office is marked by the company’s logo, a little iron icon. Notice the shadow, as well, which makes the graphic pop out from the map.
Omit the shadow icon at your own risk. Some mapping providers will assume the default shadow, which might look silly with your icon. Not every mapping provider uses shadows, but planning for one is good. If you really don’t want a shadow, consider using a completely transparent graphic. I show an example of shadowless icons in the weather map example in chapter 10 of my book.
See also:
