Up till now, we are able to search our geographic information and display the results on the screen, but not actually view the geography.
To do this we are going to use a free, open source, mapping client called Community MapBuilder. It is a series of Javascript libraries that handle all the panning, zooming, and map setup for us.
Horray! We don't have to write our own.
MapBuilder (I might call it MB from here on) uses AJAX techniques to send requests to the WMS (Web Map Service) server and display the returned image, without having to reload the page. This makes for a nice user experience.
MapBuilder is really easy to set up.
First, download the zip file with all the MapBuilder files. Extract the folder to the directory where your page lives:
That is what our directory structure looks like: the root web folder with our index.html page, some images, and the mapbuilder folder.
Next we need to make two configuration files to display our map:
map.xml
map_config.xml
map.xml contains the layers that will make up our map
map_config.xml contains all the widgets we want to have on our map, the size of the map, and what map file we want to use (map.xml).
map.xml
This contains a list of all the layers we are going to use, and where the layers live. The XML structure looks something like this:
Origionally I had a separate <Layer> tag for each layer. This works fine, but it slow. Having a separate tag for each layer makes mapbuilder perform a separate request for each layer, and that really slows the site down.
So what I did was combine all the layers into the layer name andseparated them with a comma:
Also note that the image I want returned is a PNG. Using GIF results in horrible transparency (you get white edges around your features). Using JPEG results in no transparency.
I also added in some free background layers provided by NASA's OnEarth program: NavSat Globabl Mosaic of the Earth.
Here is the layer:
The order of the layers in the map.xml file determines the order in which the layers are drawn on the map. Layers listed first are drawn first, etc...
I put the global mosaic first as a background layer.
To set the map dimentions and starting AOI (Area Of Interest: current bounding box view of the map), change the file to look something like this:
map_config.xml
This file only needs to be changed a little bit to get it working for your map. Mainly the relative URLs to the mapbuilder files and the pointer to your map.xml file.
First, point the file to your map.xml file:
Next change the stylesheet tag to point to your relative mapbuilder path:
Finally, change the <skinDir> tag to point to the relative mapbuilder directory:
Put it on the page
Once you have the two files ready, you need to add a little HTML to your web page.
So somewhere in your page (where you want the map to appear) add this html:
How does MapBuilder know to put the map there? Because the <div> tag has its id="mainMapPane". If you look back at the map_config.xml file, the <MapPane> tag has an <htmlTagId> tag that has the name of the element that will hold the map on your page:
If you change the value in between <htmlTagId></htmlTagId>, you will need to change the value of the div in your html page to reflect the new id.
Next, we need to set a variable in the javascript portion of our page:
Then we need to initialize MapBuilder when the page initially loads. To do this, create a javascript function called setup() and in it call mbDoLoad(). It should look like this:
The web page needs to know to call setup() when it loads, so in the <BODY> tag of your page, add the onload value:
Try it out
Upload the three files (index.html, map.xml, map_config.xml) to the server, and also upload the mapbuilder folder. On the server, the directory structure should look like this:
Once all the files are up, load the page and you should have a map appear.
TROUBLESHOOTING
My image links are broken!
- You need to set the <skinDir> tag in map_config.xml to point to the image directory in map builder (mapbuilder/lib/skin/default)
Nothing shows up at all, not even widgets.
- Make sure your HTML page has a variable called mbConfigUrl that has a value of "map_config.xml"
- Make sure you have the setup() function being called on load, and make sure it calls mbDoLoad().
There is no map showing up, but there are some widgets.
- First, check to see that your map_config.xml file is pointing to your map.xml file with the <defaultModelUrl> tag.
- Next, check to make sure that the URLs to the layers actually work. Try the URLs we are using.
SUMMARY
First we downloaded the MapBuilder zip file and extracted the mapbuilder/ folder to the root of our site (where our page lives).
Then we created a map.xml file that contains all our layers.
Next, we made our map_config.xml file that configures the size of the map and what map file to use (map.xml).
Next, we put a div tag in our page with an ID matching the ID specified in the map_config.xml file, saying that "this is where the main map goes".
Finally, we told the page to set up MapBuilder when it loads and pointed it to our map_config.xml file through the javascript variable 'mbConfigUrl'.
>>Proceed onto the next step, Step 5: Link Search Results with the Map >>