State Map User Manual

Note

Please note that the following instructions assume a level of understanding with "Code View" in the CMS' Ephox editor, as well as a basic knowledge of HTML. If you have no experience with either of these subjects, please contact EWM for support.

The new State Map on GSA.gov is a scalable SVG file that turns each state in the Union into a button that your users can click. Unlike conventional images, SVGs can expand and contract without any loss of resolution, meaning that your customers will see the same map on mobile devices as they would on a desktop.

This manual is designed to explain how the map works, how CMS users can employ it on their own content, and hopefully lead to a deeper understanding of the system as a whole. If you just want a standard step-by-step instruction sheet, we've got you covered. If you just need a reference for what the parameters are (we'll explain those here, as well), check out our For Developers page.

Getting Started - Add Your SVG Container

The first step to adding a map on your page is creating an HTML element that will contain your map. Intuitively enough, we call this HTML element the container. For most purposes, you can simply copy and paste the below code for your container:

<div class="well search-option">
<svg id="map-canvas" preserveAspectRatio="xMidYMin slice" style="width: 100%; padding-bottom: 70%; height: 1px; overflow: visible; box-sizing: content-box; enable-background:new 0 0 381.1 381.1;" width="100%" height="100%" viewBox="0 0 870 900"></svg>
</div>

The most important part of the code above is the part that says id="map-canvas" in red. (It won't be red in code view in the CMS. Don't be alarmed about that.) You can change "map-canvas" to whatever you want, but don't do it unless you have a good reason for it. If you do decide that you need to change it, make sure you remember whatever you change it to for the next step.

Injecting The Map

Without Javascript, your container will remain empty and your users will never see the map that you want to show them. Which, obviously, is no good.

In order to correct this sad state of affairs, you'll need the code snippet that you see below. Copy it verbatim and paste it at the bottom of your page in Code View after the last closing tag (which will usually be </p> or </div>, but there are exceptions, and you should feel free to contact EWM if you're unsure about it).

<div>
<script src="/resources/js/asto_1.1/map-plugin.js" type="text/javascript"></script>
<script type="text/javascript">
$(‘#map-canvas’).usaMap({

 

});
</script>
</div>

Notice that we’re using "map-canvas" in that code (the hashtag is what Javascript and CSS use to identify an HTML element’s ID). If you changed the ID of the container that we gave as an example in the previous section, you’ll need to change "map-canvas" to whatever it was you decided to change it to above.

The next step is to customize your map so that it shows what you want it to show, and sends your users where you want them to go.

Configuration

If all you need your users to see are the 50 United States (and the District of Columbia), skip to the next section. If that's not going to cut it, though, you'll need to customize your layout. To do so, we add what are called parameters in between the curly braces (the red ones) in the Javascript code above.

There are three geographic locations you can "switch on" if you need them: Puerto Rico, Guam and the U.S. Virgin Islands. There is also an option to display three buttons above the map to represent American Samoa, Europe, and East Asia (check out the Customer Service Directors map for an example). Let's say you needed all of these "switches" to be flipped:

'topBoxes': true,
'puertoRico': true,
'virginIslands': true,
'guam': true

The box above contains four lines, each of which is a parameter. You would need all four of them to flip all four "switches," but all of them are optional - you can delete any of them and the map will still work. That means if you only need Puerto Rico on your map, you can delete all the parameters except for the one that says 'puertoRico'.

Please note that parameters need to be separated by a comma. Also, remember that the parameters go in between the curly braces.

Adding Links to Your Map

In almost every case, a state map's intended goal is to organize 50+ links to content that correspond to states, territories or geographic regions that GSA serves. In order to add those links to the map, you need to add in some parameters. To recap, parameters are basically "switches" that you can flip on to enable certain functionalities on the map. They go inbetween the curly braces in the Javascript (the red ones). Take a look at the section above for an example. (If you added parameters in the previous step, the ones we're talking about now are in addition to those).

Note

It's important to remember that a comma must separate parameters from each other. This will not work:

'mapTarget': 'link'
'linkTemplate': 'http://www.gsa.gov/'

This will:

'mapTarget': 'link',
'linkTemplate': 'http://www.gsa.gov/'

To add links to the map, here's the first parameter you'll need:

‘mapTarget’: ‘link’

That parameter simply tells the map that, yeah, we're going to be using links. If all of your links have a general template, you can then add it in as a 'linkTemplate' parameter.

The Customer Service Directors page is a good example. All of the links on that map start out "/portal/staffDirectory/topic/18" and then have a different ending depending on what state you clicked on (e.g. clicking on California will give you "/portal/staffDirectory/topic/18CA"). In this case, we've set the 'linkTemplate' parameter like so.

‘linkTemplate’: ‘/portal/staffDirectory/topic/18’

The link that you use will change based on your needs. For example, if your links target anchor tags that exist on the same page that the map is on, the 'linkTemplate' parameter would simply be a hashtag symbol in single quotes ('#'). If you are doing that (the Fleet Management Centers map is a good example of what we're talking about), you will have to add in one more parameter.

‘convertStates’: ‘nospaces’

This parameter will add the state's name without spaces to your link template, which in this case is just the hashtag from before. For example, instead of adding a #NH to the end of your URL, it will add #NewHampshire. (This will work on other link templates, too, so you could add this same 'convertStates' parameter to the Customer Service Directors example from before and get "/portal/staffDirectory/topic/18California" if you needed a different ending for your link template.)

Frequently, though, maps will include exceptions to the general rule. For example, the Per Diem map will, for most clicks, send users to a table of rates for whatever state you clicked on. Clicking Alaska or Hawaii, though, will send you to an external page. Adding exceptions like these can be time consuming, depending on how many there are, but it's not difficult. All you need is one more (potentially very long) parameter. It will look like this.

'exceptions': ‘[{‘state’:’MT’,’link’:’nytimes.com’},{‘state’:’CA’,’link’:’sfgiants.com’},{'state':'NY','link':'nycfc.com'}]’

It looks like a mess, but it's pretty simple: For each state that is an exception, add in another set of curly braces and replace the state's abbreviation and target link. To add Oregon, you would just pop ,{'state':'OR','link':'goducks.com'} into the list above after the last curly brace. Why the comma at the beginning? Like parameters, these exceptions must all be separated by a comma. You can add as few or as many as you'd like - if necessary, you could make 51 exceptions for each of the United States, the District of Columbia, and then also specify exceptions for Puerto Rico, Guam, the Virgin Islands, American Samoa, Europe and East Asia. This would make for a very long list of exceptions, but the option is open to you if you need it.

Using Your Map to Query a Database

The Per Diem page, unlike most maps, does not send users to a link, but rather fills out a hidden form on the page and submits it to a database. If this doesn't sound familiar to you, you are probably not using a database, and you can stop reading right here. Go forth and make your map!

If you are using a database, you will not be using 'link' as your 'mapTarget' parameter in the previous step. You'll be replacing it with 'form'.

The next step will be finding out the ID attribute of the form you'll be using to submit to your database. If you can't see one, or if you're just nervous about breaking something, contact EWM for help. Once you have the ID, though, you'll use it as another parameter. For example:

Here's an (incomplete, so don't just copy vebatim) example of a form that might be on your page with an ID of "theform".

<form id="theform"></form>

Here are the parameters you would put in your Javascript instead of 'mapTarget': 'link' and 'linkTemplate':

'mapTarget': 'form',
'mapForm': 'theform'

Using the 'convertStates' parameter from before, you can also specify what kind of information gets fed into the form. Make sure that your form as an input with an ID attribute of "map_state", then set the 'convertStates' parameter to 'nospaces' to push the state name with no spaces to that input, or set it to 'name' to just push the state's name to that input. If you don't specify anything for the parameter, the input will receive just the state's postal code abbreviation e.g. CA, DC, MO.

If any of this confuses you, don't hesitate to contact EWM. We'll be glad to help.

Good luck, prospective mapmakers!

Last Reviewed 2017-06-07