Toolset Maps plugin makes it easy to display any sort of information on Google Maps. You can use special custom fields for addresses on Google Maps, display the maps and add pointers to them.

To use the Google Maps integration, first install the Toolset Maps plugin, which is included in the full Toolset and Views packages.

Before you can start using the Google Maps API, you need to enter your API key.

Once Toolset Maps is activated, you will have the following:

  • An Address field type, to use as a custom field or user field
  • A Map field, which displays a Google Map on the front-end
  • A Marker field, which adds a marker to a Google Map
  • Several additional fields that control the Google Map on the front-end

Displaying Google Maps on the site’s front-end

You can display Google Maps inside regular content, in Content Templates, in Views and in WordPress Archives.

The following table summarizes typical uses for a Google Map and how to implement:

What How
Display a page with “our address”
  1. Create a regular WordPress page.
  2. Click on Fields and Views and insert the Map field from under the Google Maps section.
  3. Add a Marker field, and in the Marker address comes from section, select An address option and enter the address.
Display a map with a marker for a single item
  1. Add an Address field to the content-type that needs to display an address on the map.
  2. Create a Content Template for that content-type
  3. When editing the Content Template, click on Fields and Views and insert the Map field from under the Google Maps section.
  4. Add a Marker field and select the data-source as the custom field that you’ve added in step (1).
Display a list of items on a map
  1. Add an Address field to the content-type that needs to display an address on the map.
  2. Create a View that will display that content-type
  3. When editing the Loop Output, position the cursor before the View Loop, click on Fields and Views and insert the Map field from under the Google Maps section.
  4. Position the cursor inside the View Loop, add a Marker field and select the data-source as the custom field that you’ve added in step (1).

Adding Google Map addresses as custom fields for posts, terms and users

Once the Toolset Maps plugin is active, you will see a new kind of field called Address. You can use it as a custom field for your custom post types and as a term or user field.

In the WordPress editor, the field will display like this:

Address field in the WordPress admin
Address field in the WordPress admin

You can enter the address by typing it, or by clicking on the map. The Address field is saved as an address string (auto-completed by Google Map service).

You can adjust the location of the address by dragging the marker on the map preview, or by setting latitude and longitude coordinates manually. In this case, the field value will be stored as a pair – {latitude,longitude}. After fine tuning this location, you can also pick the nearest street address if you want.

The Address field will display very similarly in CRED forms and in Field Tables.

Displaying a Google Map

Under Fields and Views, you will find a new section for Google Maps. In it, there are different fields for maps-related functionality.

You should always start by inserting the Map field.

Google Maps fields
Google Maps fields

The “map” field alone will display just the map, without any markers on it. Usually, you will include some markers on the map (see the next section). When you add markers to the map, the markers will center it.

Inserting a map
Inserting a map

After you insert the map, you will get a wpv-map-render shortcode, like this one:

[wpv-map-render map_id="map-5"]

Every map that you insert gets a “map ID” and in the insertion dialog, Toolset Maps plugin will automatically suggest the best Map ID option. This ID will appear in the resulting shortcode (which will display the map on the front-end). You need these map IDs, in order to display markers on maps. The marker knows which map to display on, according to the map ID.

If you don’t need any markers on the map, you should center it manually. In that case, click on the Map zoom and center tab, disable the Adjust automatically to show all markers option and enter the map coordinates. If you need help finding map coordinates, follow the Google Maps help on finding coordinates.

Positioning a map manually
Positioning a map manually

Displaying markers on Google Maps

Once you’ve inserted a map (using the Map field), you can display markers on it. You can display any number of markers on a map.

Displaying a map with a single marker for a Content Template

Let’s look at an example. A “property” item would typically have an “address” field. When you display a single property, you almost certainly want to include a Google Map with the property on it.

Follow the steps listed above to add an “address” field to your content.

When you edit the Content Template, you first need to add a map to it (see the previous section). Next, you add a marker to that map.

Screenshot What to do

Inserting a marker for a map
Inserting a marker for a map
Place the cursor below the wpv-map-render shortcode and click again on Fields and Views. Look for the Google Maps section and insert the Marker field.

Selecting the source of the marker from a custom field
Selecting the source of the marker from a custom field
When you insert the marker, indicate that the marker comes from a Google Maps field and select the custom field that you’ve used to save the address.

After you insert the marker, the page source should look like this:

[wpv-map-render map_id="map-6"]
[wpv-map-marker map_id="map-6" marker_id="marker-6" marker_field="wpcf-property-address"][/wpv-map-marker]

You can see first the Map field and then the Marker field. The map_id should be the same for both, so that the marker will display on the correct map.

Each marker has an ID (the marker_id attribute). If we want to reference that marker, use its ID. You will need it for operations that work on specific markers, such as to center the map on a marker.

Displaying a map with a list of markers, coming from a View

When you want to display a list of addresses (markers) on a map, you need to use a View.

First, make sure that the content includes an “address” custom field.

Next, create the View that will display that content (or edit an existing View).

We want the View to display one map and multiple markers on it (one marker per item in the View loop). So, we will insert the Map field outside of the View loop and the marker inside the View loop.

The View Loop needs to be created already, in order to add the map to it. If you haven’t yet created the View Loop, use the Loop Wizard. A View can display the results both on a map and as the normal View output. If you only want to display the View results on a map, still use the Loop Wizard, insert any field and delete it from the Loop Output area later.

Screenshot What to do

Loop Output section in View with map and marker fields
Loop Output section in View with map and marker fields
Go to the Loop Output section of the View. Find the <!– wpv-loop-start –> tag and insert the Map field before it. Alternatively, you can insert the Map field after the View loop. Just make sure to display it outside of the loop, so that it displays once for the View.

Find the <wpv-loop> tag and insert the Marker field after it. When you insert the marker, be sure to connect it with the right map and field to display.

The map displays together with the normal View output.

A View producing a Google Map with markers and the normal output
A View producing a Google Map with markers and the normal output

Specify marker source

A marker can be a custom post, user or term field. In case of using markers in a View, the source of these fields is the current post, user or term respectively in the loop. To define a custom source, you can also set a specific post, user or term ID using the id parameter of the wpv-map-marker shortcode.

In case of post fields, you can also use the following placeholders:

  • $parent for the native parent post
  • $post_type_slug for the Types parent post

When the marker from a term field is outside a View listing terms, term ID field is mandatory in order to display a valid marker.

Grouping close markers into clusters

With Toolset Maps you can group close markers on a map into clusters. Clusters are represented by a single, cluster icon on a map, and when you zoom the map closer, individual marker icons are shown on the map.

Following image shows a front-end example of a Google Map with some clusters on it.

Toolset Maps - Clusters Example

By default, clusters are displayed as coloured circles containing a number at their center. This number as well as their size, represent the number of markers they contain: a blue circle for less than 10 markers, a yellow circle for 10 to 99 markers, and so on.

You can enable clustering for any map, while you are inserting it into your contents.

Screenshot What to do

Toolset Maps - Clustering Options
Marker clustering options in the Map insertion dialog.
In the Map insertion dialog, go to the Marker clustering tab and turn the clustering On. Additional set of clustering options will appear and you can choose their respective values.

Toolset Maps plugins allows you to further customize the clustering options, for example changie the cluster icons, use different numbers of markers per clusters, etc. This involves a bit of custom JavaScript coding and you can learn how to do it in our separate user guide: Customizing Cluster Markers With Javascript Functions.

Marker Title and Popup

You can add a title and an information box (popup) to markers. The title displays when you hover over a marker and the information box displays when you click on a marker.

Screenshot What to do

Entering the title and popup content for a marker
Entering the title and popup content for a marker
When you insert the marker, go to the Marker data tab.

Inserting fields to the title and popup
Inserting fields to the title and popup
Enter text for the marker title and popup. You can also use field shortcodes for the title and popup. To include fields in the title and popup, return to the editor and add them from the Fields and Views button.

The title attribute can only include plain texts (fields are OK, as long as they don’t produce HTML output). The popup content displays between the [wpv-map-marker…] and [/wpv-map-marker] shortcodes. It can include HTML.

The marker popup on the front-end
The marker popup on the front-end

Customizing the marker icons

You can choose between a number of available marker icons or upload your own.

Screenshot What to do

Choosing the marker icon
Choosing the marker icon
When you insert a marker, go to the Marker icons tab.

By default, the same graphics is used for both ‘normal’ and ‘hover’ states of the marker. You can choose a different icon for the hover state.

Markers with custom icons
Markers with custom icons

Creating a Google Maps API Key

Google Maps require the usage of an API key, in order to work properly. This requirement was announced by Google, in June 2016.

This means you need to register your site for a Google Maps API key and involves the following steps:

  1. Visit the Google Developer console here: https://console.developers.google.com/projectselector/apis/credentials.
  2. Select a project (or create a new one).
  3. In API Manager -> Library -> Google Maps APIs, click and enable the following APIs one by one:
    • Google Maps Geocoding API
    • Google Maps JavaScript API
    • Google Places API Web Service
  4. In Credentials, click Create Credentials -> API Key -> Browser Key -> Create.
  5. Optionally, when you are creating the Browser Key (previous step), you can restrict the API key being used, by the referrer URLs that need it. This helps to secure the key and reduce the impact of a potential compromise. You can use asterisks for wildcards.
    For example, to use the API key in all sub-domains and sub-pages of the example.com domain, you can set *.example.com/* as the referrer URL. You should enter this into the Accept requests from these HTTP referrers (websites) field while creating the Browser Key.

Restricting access requests for a Google Map API Key
Restricting access requests for a Google Maps API Key

If you are experiencing problems with displaying markers on a map, try creating a Google map API without adding a domain name. Many users confirmed that this issue was resolved when using a non-restricted key.

To read more about setting up the Google Maps API key, please visit Google’s official documentation page.

Once you have the Google Maps API key for your site, you need to enter it on the Toolset Maps settings page. This is done on the Maps tab of the Toolset Settings page, as shown in the following image.

Google Maps API key settings for Toolset Maps plugins
Google Maps API key settings for Toolset Maps plugins

Toolset Maps Data Caching

When you use Toolset Maps plugin, Views will cache every address that needs to be displayed on a map. This makes the maps load quicker and helps to avoid reaching the data request limits of the Google Maps API. You can read more about this feature in a separate user guide Data Caching For Google Maps Addresses.