Guide: Add Links to Your State Map

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.

These instructions also follow up from the Create Your Map guide. Please refer to the steps laid out there before moving on to the steps laid out below.

Adding Links to Your Map

Step 1: Look At Your Links

The first thing you should do is take a look at your links for patterns, whether they are internal links (that begin with a slash) or external links. For example, the Customer Service Directors map has internal links that all begin "/portal/staffDirectory/topic/18".

You should determine if you have similar pattern in your own links, and to what extent. Do all of them follow your pattern? Only a few? None? This analysis will be important heading into the next steps.

Step 2: Set the Plugin to Use Links

In Code View, find the usaMap Javascript function. As a reminder, this is what it will look like:

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

 

});
</script>
</div>

In between the curly braces (the red ones, though they will not be red in Code View on the CMS), you will have to add the following code.

'mapTarget': 'link',

Note

If you added a any of the code blocks in Step 4 of the Create Your Map guide, the preceding code and any code examples that follow will be in addition to the block that you have already added.

Step 3: Assign a Link Template

(If you are using anchor links on your page, skip to Step 4b.)

This is where the "patterns" question from Step 1 comes into play. If your links follow a pattern like the one we described for the Customer Service Directors page, you can add the following code block between the curly braces in Step 2.

'linkTemplate': 'YOUR LINK PATTERN HERE',

Step 4: Decide Your Link Template Suffix

The map's default behavior is to tack a state's two-letter Postal Code to the end of the link template you specified in Step 3 This is the exactly the behavior that can be seen on the Customer Service Directors map, where clicking on California will give you the "/portal/staffDirectory/topic/18" link template we discussed in Step 1, plus "CA" for a link that reads "/portal/staffDirectory/topic/18CA".

If that is the behavior you are looking for, move on to the next step. If it's not, the default behavior can be changed by adding one of the two following lines of code inside the curly braces from Step 2.

'convertStates': 'nospaces',

OR

'convertStates': 'name',

The first option will tack the state's name with no spaces to the end of the link template you designated e.g NewHampshire rather than NH. The second option will tack the state's name with spaces (e.g. New Hampshire) to the end of the link template you designated. We strongly recommend you do not use the second option because it is bad practice to use spaces within links.

Regardless of what you decide, you can only use one of the options highlighted above. The map will not work properly if you use more than one option.

Step 4b: Linking to Elements On Your Own Page

If you are not using anchor tags on your page, you may skip this step.

If you are going to use the map to send users to anchor tags on your own page, however, this is the following code block to insert between the curly braces in Step 2.

'linkTemplate': '#',
'convertStates': 'nospaces',

You must then make sure that your anchor tags are state names without spaces, e.g. NewHampshire, so that if you click on New Hampshire the page will scroll down to the correct anchor tag. Do not name your anchor tags with the two-letter Postal Code for any state or the District of Columbia. This will break your page!.

Step 5: Setting Exceptions

Think back to Step 1: Were there any exceptions to your link pattern? Are there any links where simply tacking the name or abbreviation of a state to the end of a template will not work?

If there are not, skip to Step 6. However, if there are exceptions to the rules that you've set, you will need to insert the below snippet of code in between the curly braces.

'exceptions': [{'state': '', 'link': ''},],

Enter the first state with an exception to your pattern defined in Step 3 above by entering the state's two-letter Postal Code in the empty single quotes after 'state': and its corresponding link in the empty single quotes after 'link':. For each state that has an exception, copy the code in between the green brackets above and then paste it after the comma that comes just before the closing green bracket. It will look like this:

'exceptions': [{'state': 'ST', 'link': 'www.example.com'},{'state': 'ST', 'link': 'www.example.com'},],

Once you have created a state/link pair for every state that requires an exception, delete the last comma before the closing green bracket. The code block should end }], rather than },],

Step 6: Finishing Up

The space between the red curly braces should, at this point, contain several pieces of code. Before you can click save, you will have to delete the last comma that appears in the code block. There should be no comma separating the closing curly brace from the code that you've added. By way of example:

<div>
<script src="/resources/js/asto_1.1/map-plugin.js" type="text/javascript"></script>
<script type="text/javascript">
$(‘#map-canvas’).usaMap( {
'mapTarget': 'link',
'linkTemplate': '#',
'convertStates': 'nospaces'});
</script>
</div>

Notice that there is no comma after the last line of the code inside the curly braces - that is to say, the one that begins 'convertStates'. If you forget to remove that last comma, the map will not load correctly.

After this last step, click "Save" on your page in the CMS and then publish to Staging so it can be reviewed before getting sent live for your users.

Last Reviewed 2017-06-07