User Locations Setup

Overview

This document provides instructions on how to configure the display of location fields in the user profile and map in the member directories using the extension User Location.

Contents

Installing #

You can download the extension via your account on our website. If you have made an individual extension purchase, you can download the extension via the download tab on your account page, or if you have purchased the pass, you can download the extensions via the downloads page. Once the extension is downloaded, you should install and activate it using the WordPress plugin installer on wp-admin > Plugins. You can read the article Installing an Extension for details.

Google Maps API keys #

After you have activated the plugin, you will be redirected to the installed plugins page, where you should see the following notice.

For the User Location extension to work on your site, you need to generate a Google Maps API key. If you already have the key, you can skip the next section. If you do not already have your Google Maps API key, click the Generate your API key button, and you will be taken to the official Google Maps API website.

Google Maps JavaScript API is a part of Google Maps Platform in Google Cloud Platform, so you need to be registered at Google Cloud Platform.

Follow instructions below to create a project and get your API Keys or read the article How to create a Google Maps API key for details.

Generating your Google Maps API key #

If you are a new user, click the Get Started button and go through the registration process. For the extension to work correctly, you need to enable these APIs: Maps, Places, Geocoding. You can enable needed APIs and get your API key, as shown in the screenshots below.

Getting your existent Google Maps API key #

If you have already created a project and enabled the Maps JavaScript API, you can copy the key by clicking the SHOW KEY link in the API keys table on the Credentials page.

Required APIs #

For the extension to work correctly, you need to enable these APIs:

  1. Maps Javascript API
  2. Places API
  3. Geocoding API

Go to the Google cloud console, select a project, click the APIs & Services item in the side menu then click the Enabled APIs & services link.

It will take you to the APIs & services page. Click the ENABLE APIS AND SERVICES link or the Library item in the side menu.

Click the VIEW ALL link in the Maps section to see all Maps API.

Click on each of the following APIs below. In each API, click the ENABLE button. You'll know that the API is enabled when a green circle with a check appears with the message "API Enabled," and the blue button is now MANAGE.

Image - How to enable the Maps Javascript API

Image - How to enable the Places API

Image - How to enable the Geocoding API

Settings page #

Once you have your API key go to the wp-admin > Ultimate Member > Setting > Extensions > User Location section, enter your API key to the setting Google Maps Javascript API Key, and click the Save Changes button.

Once you have successfully entered the correct key, the Google Map can be added to forms (Registration/Profile) and member directories. Please note that Google Maps will only show once you enter the API key. If you enter the wrong key, you will see an error appear on the forms or member directories where Google Maps should be.

Settings below are the key used to customize the map view. These settings will be applied for User Location fields in forms:

  • Map height - Set map height in px. Default 400.
  • Starting map zoom level - Pick a starting zoom level for the map. From 0 to 12.
  • Starting address latitude - Pick a starting position for the map. From -90 to 90.
  • Starting address longitude - Pick a starting position for the map. From -180 to 180.

Adding User Location fields to the form #

You can add the User Location field to the registration and/or profile form to allow members to fill their location data on registration or in their profiles. You could add one or multiple custom fields with the User Location type. Each field must have an unique meta key.

Note: The field meta key you specify is the base prefix. The User Location is a complex field type that stores data in four usermeta: {metakey}, {metakey}_lat, {metakey}_lng, {metakey}_url.

Image - The User Location button in the form Fields Manager.

There is a User Location field's layout. You can use Google's autocomplete to find the necessary location or just put a marker on the map.

Image - An example of the User Location field view in the form.

Adding Map to the Member Directory #

You can add a map to the member directory. The map uses members location data from the "User Location" field to display their location and can filter members in the member directory by their location.

Once you have successfully entered your Google Maps Javascript API Key you'll see the User Location box in the member directory settings. Turn on the Show Map setting and select a field used to display markers and filter members in the Show this user location field at the map setting. Use additional settings to configure a starting map view and filtering algorithm.

The member directory location and map settings:

  • Show nearest users when search results are empty - (optional, appears if the Search feature is enabled) The feature that focuses a map if nobody is found.
  • Show Map - Turn it on to display a map.
  • Show this user location field at the map - This option is used to select user location markers that will be displayed on the map.
  • Map height - This option is used to customize a map height on a screen. The size is set in pixels.
  • Starting map zoom level - This option is used to select the default map zoom.
  • Starting address latitude - This option is used to select the default latitude of the map center.
  • Starting address longitude - This option is used to select the default longitude of the map center.
  • Enable user location search field - This option is used to enable searching and filtering features. Additional search field is shown below the map if the location search is enabled.
    • Choose a type of searching - (optional, appears if user location search is enabled) This option is used to select a searching and filtering algorithm. Options: "Search by visible bounds", "Search by radius".
      • Nearby members searching radius - (optional, appears if the "Search by radius" algorithm is selected) Set a distance from the target location for getting nearby members.
      • Distance unit of measurement - (optional, appears if the "Search by radius" algorithm is selected) Set a unit to measure a distance.
  • Choose field(s) to display in marker's infowindow - This option is used to select what information to show in the marker's info window.
  • Marker type - This option is used to select a type of marker that displays members location on the map.

NOTE: The "Search by radius" algorithm requires the "Enable custom table for usermeta" setting on wp-admin > Ultimate Member > Settings > Misc to be enabled. Follow instructions here.

Image - The User Location settings box on wp-admin > Ultimate Member > Member Directories > Edit Member Directory.

Examples

This is a map on a member directory for showing users locations.

This is a map on a member directory for showing users locations and filtering users by the visible map's bounds.

Pagination

The member directory map displays markers for found members on the current page. Found members are divided into pages. The map displays markers for members who are in the current page only. You can switch a directory page using links in the pagination area under the profile cards area.