Guide: Use Your Map for a Form

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.

Use Your Map for a Form

Step 1: Figure Out If You Need a Form

The map on the Per Diem page does not directly send users to a link when clicked. Instead, it submits information to a form embedded on the page and sends it as a query to the Per Diem API, which will take the query and return Per Diem rates.

If this is not what your page is designed to be doing, please don't go any further on this Guide! You should instead refer to the Add Links tutorial.

If you are using a form on your content to query a database, please continue.

Step 2: Add Your Form

Contact your database administrator for the HTML code for the form. Make sure the form includes a <input> tag with an ID of map_state (it would look like this: <input id="map_state">, and may include additional code).

Once you have the HTML code, paste it into your page in Code View.

Step 3: Configure Your Map Settings

One you have added the map to your page (refer to the Create Your Map guide for instructions how to do this), you will have to add parameters into your Javascript snippet. To recap, that snippet looks like this:

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

 

});
</script>
</div>

Your map settings will be added in between the curly braces (in red) above.

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.

You must start by inserting the following two parameters in between the curly braces:

'mapTarget': 'form',
'mapForm': 'YOUR FORM ID HERE',

You should substitute in the ID found inside the <form> tag of your form. For example, if your <form> tag looked like this - <form id="formID"> - then you would substitute formID for YOUR FORM ID HERE inside the single quotes above. The entries are case sensitive and must match each other exactly in order to function correctly.

Step 4: Pick What to Submit

The default behavior of a click on the map, if you are using a form is to set the value attribute of the map_state input from Step 2 to the two-letter Postal Code of the state you clicked. For example, clicking on California would change <input id="map_state"> to <input id="map_state" value="CA">

.

If this is the type of information your database or API can digest, you may skip to the next step. However, if you need the value attribute to be different, you may change the map's settings to return a different piece of information.

Below are your two options for information types:

'convertStates': 'nospaces',

OR

'convertStates': 'name',

The first option will change the value attribute of your input to the name of the state you clicked on with the spaces removed (e.g. New Hampshire will become NewHampshire in the code, Washington, D.C. will become DistrictofColumbia, etc.), while the second option will return the state's name verbatim.

You can only pick one; if you try to use both, the map will break and inaccurate information may be submitted to your form.

Step 5: Designate Exceptions

If there are any states or territories where a click should NOT submit information to your form, you will have to designate exceptions.

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

The above is an example of the code you will need to add to configure your exceptions.

Enter 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': 'form',
'mapForm': 'formID',
'convertStates': 'name'});
</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