Locations Map

$20.00Single-Site License

Shows a customizable Google map with location markers for all your Participants Database records.

Latest Release Available: Version 1.3.1

Description

Shows a customizable Google map with location markers for all records. This add-on will take all your records that have addresses and place them on a customizable map display that can be added to your Participants Database list display or shown separately on it’s own. The map location markers are updated when the list is searched, so that the locations of all the found records will be shown on a map that auto-resizes to fit the markers. Location markers can also have a configurable pop-up info window showing more information from the record.

Adds a Google Map with Markers to your List or Single Record Displays

The add-on is very simple to use: no need for custom templates or code at all, it just automatically places (according to your selected preference) the map in your list or single record displays.

You can also use one of the new shortcodes to just show a map with markers for each location.

And of course, it is possible to easily add a map to your custom templates if you want to go that way.

Automatically Geocodes Your Records

If your records have addresses, then this add-on can compute the longitude and latitude for the location so it’s marker can be placed. You can mass-geocode all your records in a single operation. If a new record is added or a record is updated and the address is changed, the location will be automatically computed.

You can disable automatic geocoding if your records have latitude and longitude information already.

Markers with Info Windows

Markers in dynamic maps can have click-to-show info windows that are completely configurable to show any information from the record.

Instructions

First install and activate the plugin. This will add the “Locations Map” menu item to the Participants Database admin menu. Click that item to open the Locations Map settings screen. The first step is to get your API key.

Getting Your API Key

To use Google maps services, you must have an API key. It’s no big deal: they are free, you just have to have a Google account, and then set up the API access through Google Developers.

  1. Visit https://cloud.google.com/maps-platform/
  2. Click on Get Started
  3. Select Maps, click continue
  4. Select or Create a Project: Just create a new project and give it the name of your website
  5. The project will be created, it can take several seconds
  6. Set up billing: Google requires that you have a billing account in case you start to run up charges (you probably won’t…see below)
  7. The Maps API will be enabled
  8. You will then be given your API key. Copy this and paste it into the “API Key” setting in the Locations Map settings
  9. You can get your API key any time on your Google Cloud Dashboard, make sure you have the right project selected.

Google Maps Dev Site: Getting your API Key

Google Maps Services is Free—To a Point

For each service used, Google provides a limited number of free loads (every time someone loads a page with a map on it, that’s one load). Unless your site has very high volume, it won’t cost you anything to show maps. This plugin uses three Google services: Dynamic Maps, Static Maps and Geocoding.

Every time a page with a dynamic map is opened on your site, it will generate a Dynamic Map load. You can have up to 28,000 of those per month for free. You’d probably have to be getting several thousand visits a month (with them all seeing your map) to hit that.

Static Maps has higher limits: you’ll get 100,000 free map loads per month with those. Static maps lack the user interactivity of dynamic maps, but they are cheap, fast and really all you need for most applications.

Geocoding also has limits, but it’s not used very often. We only need to geocode when a record is created or updated. You’ll get 40,000 of those for free.  If you have a lot of records, you might get over that number when you geocode the entire batch, but after that you’re unlikely to hit charges for geocoding.

Get all the details in the Google Maps Pricing Table…

Once you have the API key in place, you can show the map in your list and single record displays. A detailed explanation of the plugin’s settings is found under the “Settings” tabs here.

Dynamic Maps or Static Maps?

You should decide whether you need to use Dynamic Maps or Static Maps. They are used differently and result in a different display…here are the pros and cons:

Map Type Pros Cons
Dynamic
  • user interactivity like zoom, panning, street view, change map type
  • location markers
  • info popups on markers
  • more appearance control
  • fewer free loads
  • can take longer to load when viewed
  • more complex display could be confusing or distracting
Static
  • loads instantly, no javascript
  • simple display
  • location markers
  • lots of free loads
  • no user interactivity
  • less responsive: you must define dimensions
  • less control over appearance
  • no marker info popups

Placing Dynamic Maps

Dynamic maps can be placed automatically, without the need for custom templates, by selecting a location in the list or single record displays using the Automatic Map Placement settings. In the list display, the map will show in the selected location (top or bottom) with markers for all the records shown in the list results. A search result will show a repopulated map with markers for the result set.

The map for the single record shows a marker for the location of that record.

Dynamic Map Shortcodes

Dynamic maps can also be shown with a shortcode:

[pdb_listmap] shows a map with all your located records as markers. You can use the “filter” attribute in the shortcode to determine which records are included or excluded.

[pdb_singlemap] shows a map for a single record with a marker for it’s location. You will need to access it’s page using a ?pdb=id type of URL (typically, by using the “single record link” in the list display), so that the shortcode knows which record to show. Or, if you are a coder, you can use it in a custom template and set the record id in the shortcode, using the ‘record_id’ attribute.

Dynamic Map Templates

Dynamic maps can also be displayed using a custom template. The add-on comes with two example templates for showing a dynamic map: pdb-list-dynamicmap-default.php and pdb-single-dynamicmap-default.php You can use them as-is or use them as a starting point for your own custom templates.

If you are already using a custom template, take a look at these examples, you’ll see it’s very simple to add a map to a template.

Placing Static Maps

Static Maps are used in three ways: as a custom form element, the [pdb_list_static_map] shortcode or using a special template.

The Static Map Form Element

Setting up the map as a Participants Database field is convenient if you want to show a small map in a list display or you want the map to be part of the single record display.

Static maps must have their width and height set beforehand. If you don’t define the width and height in the field definition, it will use the global map height setting for the width and the height (resulting in a square map).

You can set several parameters in the field definition to set up your map:

  • ‘width’ sets the width, in pixels for your map display
  • ‘height’ sets the height in pixels
  • ‘located_only’ when set to true will only show a map if the record has been located (i.e., has latitude and longitude data)
  • ‘zoom’ sets the zoom level of the map; if omitted, the zoom level is determined by the global zoom setting
  • ‘maptype” can take one of 4 values: roadmap, satellite, terrain, hybrid and determines the type of map display to use
  • ‘center’ allows you to set a default center for the map: if there is a marker present, it will center on that marker. You must use the | (pipe) character instead of a comma to separate the latitude and longitude values. 


For example: this field is configured to show a map of width 650 pixels wide by 500 pixels in height, showing a hybrid map centered on San Francisco.

Note: map sizes are limited by your Google API plan type. Normally, this is 650 pixels, but if you upgrade your plan, you can get up to 2048 pixels. Details here…

You can manage the appearance like any other Participants Database field. If you want the map to show up in your list display, make sure the map field is configured to do so. For single displays, it will appear like any other field.

Map fields do not display in signup forms or record edit forms.

The [pdb_list_static_map] Shortcode

This works much the same as the [pdb_listmap] shortcode, only it shows a static map. The shortcode uses the ‘width’ and ‘height’ attributes to set up the dimensions of the map display. You can use these attributes in the shortcode:

  • width – in pixels
  • height – in pixels
  • zoom – sets the base zoom level of the map
  • center – longitude | latitude for the center of the map, defaults to auto-centering the map on the markers
  • maptype – can be roadmap, satellite, terrain, or hybrid

The Static Map Template

This add-on includes a special template for showing all your record markers in a static map. If you need to set up a custom list template using a static map, you can use the included pdb-list-static-map-default.php template as your starting point or as an example of how to include the map.

To use the static map template in your list shortcode, use a shortcode like this: [pdb_list template="static-map-default"].

Configuring the Appearance of the Dynamic Map

There are several preferences for determining how the dynamic map will look. First, you can select the Map Style, which is the color scheme of the map. There are several available, and it is possible to create your own color scheme if you want.

The Map Height setting sets the size of the map display. The map will always try to be as wide as possible, filling the available horizontal space. It is necessary to give the map a specific height to determine how much vertical space it will take. The usual size is around 300 pixels, this will look good on most handheld devices. You don’t want to try to show a map that is larger than the screen size of the device since the user can scroll within the map window.

Map Controls determine what the user can do with the map. You have several controls that you can enable or disable depending on your needs. It is probably a good idea to have as few of these enabled as possible to avoid unneeded clutter in the display.

Each location is marked on the map with a Marker Icon, you can select the type of icon and color.

Marker Info Pop-Ups show information from the record when the marker is clicked on or hovered over. You can configure the content of the info box: it’s possible to put pretty much anything you want to show in there, the template gives you a way to determine which fields are shown and how they are laid out in the box.

Geocoding

Most of the time, your records will have an address that defines it’s location. Geocoding takes this address information (from anywhere in the world!) and converts it to the latitude and longitude values needed to place the marker on the right spot on the map.

You’ll need to tell the plugin which fields are your Address Fields, it uses the data in those fields to determine the location. It’s possible to locate markers with partial information, such as a state or city, but it will be more accurate with a complete address.

If your records already have latitude and longitude data, you don’t need to use geocoding, just make sure the Latitude and Longitude Field settings tell the plugin where to find that info.

Mass Geocoding

If you already have a records when you set up the map plugin, you’ll want to geocode those so that their markers will be placed. The Geocode All Records button does this for all the records in the database. The operation takes place in the background, so once you start it, you can do other things. You’ll need to refresh the page after a few minutes to see the results of the operation.

 

Settings

Google Maps API Settings

Google Maps API Key

You must have an API key to use Google’s map service. Instructions for getting your API key are found under the “Instructions” tab.

Google Static Maps Secret Key

This key, also known as a “signing secret” is optional, and you’ll only need it if you’re using Static Maps and want to increase the number of free loads you can have. More information on digital signatures here…

General Map Settings

Default Zoom Level

Normally, the map will auto-zoom to include all the markers. If the map has no markers, this is the zoom level to use. This also works as a minimum zoom level so that your maps won’t be zoomed in too close if there is only one marker or they are all clustered in a single location.

Details that would be seen at several example zoom levels:

  • 1: World
  • 5: Landmass/continent
  • 10: City
  • 15: Streets
  • 20: Buildings

Default Location

The center of the map is normally determined by the markers. If there are no markers, this location will be used as the center of the map.

Map Height

All maps require a height setting. Choose a value in pixels that looks good in the normal display you are using. This value can be overridden by individual maps. The maximum size available here is 650 pixels, unless you have a premium Google API plan.

For dynamic maps, the width of the map will be determined by the display, so it will be responsive to the viewing device screen. Static maps require a fixed width value, which is set in the configuration of the static map. Static maps can be made responsive with appropriate CSS, your responsive theme may take care of that for you.

Marker Icon

Choose the style of marker icon from a preset list of icons.

Custom Marker Icon

If you want to use a custom icon, put the URL to it here. This means it needs to be hosted on a server. The easiest way to do this is to upload the image to your site’s media library. To get the URL, open the image in the media library editor, then copy the URL for the image (seen in the upper right of the edit screen).

An icon should be a 32×32 pixel PNG with a transparent background.

Dynamic Map Features

List Display Automatic Map Placement
Single Record Automatic Map Placement

This selection inserts the dynamic map in your List or Single Record displays in the location specified.

This will be active in all single or list displays. If you need to selectively display a dynamic map, you must use a custom template. The plugin includes some default custom templates which you can use as-is or as a guide to creating your own.

Map Style

This chooses a color scheme for your map. There are several built-in ones to choose from, or you can build you own. See the “Custom Map Style” setting for details.

Map Controls

Dynamic Map Controls

There are several different controls available to users on a dynamic map. This setting lets you decide which ones will be available. Note that this can’t prevent users from zooming and panning using their keyboard and mouse, all this does is hide or show the specific on-screen control.

Enable Marker Info Pop-Up

Checkbox to enable/disable informational pop-ups for markers. These pop-ups show information from a record when its marker is clicked or hovered over.

Marker Info Show Action

Determines the action that will show the informational pop-up: click, the marker must be clicked on or hover, the info box for each marker is shown as the pointer hovers over it.

Marker Info Template

This mini-template determines which pieces of information will be included in the informational pop-up and how it will be formatted. It uses the same “value tags” as available in Participants Database email templates. Each tag will be replaced by the record data in the named field.

You can use simple HTML in the template, but it may break if you try to put too much in there.

Custom Map Style

Here is where you can add your own custom map color scheme. You’re expected to paste a valid JSON object, an error will result if there are syntax issues with the JSON object.

There are several online services that make developing your own map style fairly easy.

These services will all generate the JSON for you: just copy and paste into the custom map style to use it.

Geocoding

In order to place markers on a map, it is necessary to know the coordinates for each one. In most cases, your records will have an address of some kind. Geocoding is the process of taking a descriptive address of a place and converting it to the geometric coordinates of the place on the globe: the latitude and longitude.

Enable Auto-Geocoding

When enabled, a record is automatically geocoded when it is created or edited. You can disable this if your records already contain latitude and longitude information.

Address Fields

To geocode a place, we need the address information. This setting tells the geocoder which fields to use to find the coordinates. The address can be a mailing address or any other kind of descriptive address that is normally used. The address can be incomplete (for instance, just a city or even a country), the geocoder will place the coordinates as accurately as it can using whatever information it is given.

For example, if you give the geocoder the only name of a city, it will place the marker in the center of that city. If given a locality (such as “Hell’s Kitchen”) it will place it in the center of that locality, so even if your records don’t contain complete addresses, markers can be meaningfully placed.

Latitude Field
Longitude Field

Select the two fields where this information is held in your records. Normally, the plugin will add these fields and you won’t have to change this setting. If your records already have coordinate fields, you can set those here so the plugin knows where to get the information to place the marker.

Geocode All Records

When you first set up the plugin, you will probably need to get the coordinates for all the records that are already in the database. This button will start the process of geocoding all of your records.

It does this in the background, so you won’t see much happening until it is done. Refresh the page after a minute or two to see the results of the bulk geocoding operation.

Remember, there is a limit to the number of free geocoding requests you can make, and if you have a large database you could easily reach that limit if you perform this operation multiple times. You should only have to do this once.

Reviews

There are no reviews yet.

Be the first to review “Locations Map”
You have to agree to the comment policy.

Product-specific technical support can be found here:

Locations Map