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
- Google Maps API keys
- Settings page
- Adding User Location fields to the form
- Enabling Distance Field Sorting in Member Directory Settings
- Setting User Role Icons for Map Markers
- Adding Map to the Member Directory
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:
- Maps JavaScript API
- Places API
- Geocoding API
Here's how to enable these APIs:
- Go to the Google Cloud Console and select your project.
- Click on "APIs & Services" in the side menu, then click on "Library"
- On the Map section, click on "VIEW ALL" to see all Maps APIs.
- For each of the APIs mentioned above, click on them and then click the "ENABLE" button.
- 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 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 & Distance 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:
- User Location Field: This field allows users to specify their location using Google Maps autocomplete. 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. - Distance Field: 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 form Fields Manager.
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.
Enabling Distance Field Sorting in Member Directory Settings#
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 field sorting option, navigate to wp-admin > Ultimate Member > Member Directory > Edit a member directory > Sorting Options. Enable custom sorting and choose the Distance field from the drop-down menu from 'Choose field(s) to enable in sorting' option.
Once set up, user will have the option to sort the member results by distance.
Setting User Role Icons 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:
- Go to wp-admin > Ultimate Member > User Roles > Edit Role.
- In the "User Locations" section, Role icon option, click on the 'Select' button to upload or select a user role icon.
- Then update or save the user role settings
- You can then set this User role marker in the directory member settings in the "User Locations" section - "Marker type" setting..
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.
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 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 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".
- 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. 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.
- Avatar marker: Displays a marker on the map using the user's avatar image.
NOTE: The "Search by radius" algorithm requires the "Enable custom table for usermeta" setting on wp-admin > Ultimate Member > Settings > Advanced > Features 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 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.
