User Locations Setup

Overview

User Locations is an extension of Ultimate Member that allows users to add location data to their profiles, which can then be displayed on a map in the member directories. Admins can customize the map settings and add icons for different user roles to enhance the map's visual representation. The extension integrates with Google Maps API to provide accurate and interactive maps for users. With User Locations, you can create a dynamic and engaging user experience by visualizing the geographic distribution of your members. This document provides instructions on how to configure the display of location fields in the user profile and map in the member directories using this extension.

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 activating the plugin, you'll be redirected to the installed plugins page, where you'll encounter an important notice. To enable the User Location extension on your site, you'll need to generate a Google Maps API key. If you don't already have one, simply click the " Generate your API key" button, which will take you to the official Google Maps API website.

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 restrict and protect your API key. Choose 'API restriction' as the restriction type, then select the following APIs: Maps, Places, and Geocoding, click the "Restrict key" button as illustrated 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 #

To ensure the extension functions properly, you must enable the following APIs:

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

Here's how to enable these APIs:

  1. Go to the Google Cloud Console and select your project.
  2. Click on "APIs & Services" in the side menu, then click on "Library"
  3. On the Map section, click on "VIEW ALL" to see all Maps APIs.
  4. For each of the APIs mentioned above, click on them and then click the "ENABLE" button.
  5. You'll know the API is enabled when you see a green circle with a check and the message API Enabled.

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:

  • Google Maps Javascript API Key - This setting is used to authenticate requests to Google Maps JavaScript API. It allows the plugin to use Google Maps services, such as displaying maps and geocoding addresses. You need to obtain an API key from the Google Cloud Platform and enter it here for the plugin to access these services.
  • Use site's locale as language for Google Maps - When enabled, this setting will use the current language/locale set for your WordPress site to display Google Maps. This means that if your site is in a language other than English, Google Maps will be displayed in that language as well, if supported by Google Maps. If disabled, Google Maps will use the default language settings.
  • Map height - Set the height of the map on the screen in pixels. It must be an integer. Default 400.
  • Starting map zoom level - Pick a starting zoom level for the map. It must be an integer from 0 to 12.
  • Starting address latitude - Pick a starting position for the map. It must be a decimal number between -90 and 90.
  • Starting address longitude - Pick a starting position for the map. It must be a decimal number between -180 and 180.

Adding User Location fields to the form #

To enable members to provide their location data during registration or in their profiles, you can add the User Location and Distance fields to the registration and/or profile form. Each field type serves a specific purpose:

  1. User Location: This field allows users to specify their location. You could add one or multiple custom fields with the "User Location" type. You must add at least one "User Location" field to use location searching in the member directory.

    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.

  2. Distance: This field allows users to specify the maximum distance they are willing to travel from their location. This field complements the User Location field and can help in scenarios where location-based searches or filters are used.

The image below shows the "User Location" and "Distance" fields in the Fields Manager.

Enabling the User Location searching in Member Directory #

The User Location field layout enables users to either use Google's autocomplete feature to find their location or manually place a marker on the map.The image below is an example of the User Location field view in the form.

To enable the location searching feature, navigate to wp-admin > Ultimate Member > Member Directory > Edit and scroll down to the User Locations section. Turn on the Show Map setting and choose the User Location field from the drop-down menu in the Show this user location field at the map setting to display a map. Turn on the Enable user location search field setting to enable the location searching. 

Once set up, user will see a map and location search line above the member directory.

Enabling the Distance sorting in Member Directory #

After adding the 'Distance' field to your forms, you can configure the member directory settings to sort and display the location information based on the distance, enhancing user profiles with geographical data. After integrating the 'Distance' field into your forms, you can configure the member directory settings to enable custom sorting based on location information. This allows you to choose the 'Distance' field to include in the sorting options, providing users with a tailored experience when browsing the directory. 

To enable the distance sorting feature, navigate to wp-admin > Ultimate Member > Member Directory > Edit and scroll down to the Sorting Options section. Enable custom sorting and choose the Distance field from the drop-down menu in the Choose field(s) to enable in sorting setting.

Once set up, user will have the option to sort the member results by distance.

User Role settings for Map Markers #

Admins can assign an icon to a user role, which will appear on the map for members with that role. Here's how to do it:

  1. Go to wp-admin > Ultimate Member > User Roles > Edit Role.
  2. In the User Locations section, Role icon option, click on the Select button to upload or select a user role icon.
  3. Then update or save the user role settings
  4. You can then set this User role marker in the directory member settings in the "User Locations" section - "Marker type" setting.

Member Directory settings #

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.

Note: For more information and a detailed guide on adding the map to the member directory, please refer to this article: Member Directory with User Locations map

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 directory will show members nearest to the device's location if there are no members whose location matches the current map. Note that this feature does not work on devices that cannot provide location data.
  • 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 parameter specifies the height of the map on the screen in pixels. It must be an integer.
  • Starting map zoom level - This parameter specifies the default map zoom. It must be an integer from 0 to 12.
  • Starting address latitude - This parameter specifies the default latitude of the map center. It must be a decimal number between -90 and 90.
  • Starting address longitude - This parameter specifies the default longitude of the map center. It must be a decimal number between -180 and 180.
  • 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".

      Note: The "Search by radius" algorithm requires the "Enable custom table for usermeta" setting to be enabled. Follow instructions here.

      • 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.
The User Location settings box on wp-admin > Ultimate Member > Member Directories > Edit Member Directory.

Marker types

You can select from the following options:

  • Avatar marker - Displays a marker on the map using the user's avatar image.
  • User Roles marker - Displays a marker on the map using a custom icon associated with the user's role.
  • Classic Google marker - Displays a standard Google Maps marker on the map.

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.

Related Articles