CM Map Locations (CMML) + Custom Fields - Use Case - Building a Location and Store Locator Tool
Building a Store Locator Tool
- Pro version of CM Map Locations - This document uses version 2.5.7
- Custom Fields add-on
CM Map Locations allows you and your users to create and showcase locations in Google Maps, including images and notes for each.
The Custom Fields add-on deepens the content by supporting fields such as "Cost-benefit", "Service" and such - you can create as many as necessary.
A great deal of the footage in this tutorial comes the demo Knowledge Trail.
Access it to see live what you can achieve with the plugin.
Use Case Front-End
Use Case Assumptions
In this example use case guide, we'll cover how to create a directory of locations with custom fields. We consider that you have already bought the plugin and add-on, but not installed them.
- Installing the plugin
- Initial Setup
- Adding first location
- Visual options
- The index page
- User interaction
- Modifying the form
- Who can access and collaborate
- Moderation, notification, and Terms of Service
- User dashboard
- Custom fields
- Main shortcodes
- Translating the plugin interface
Installing The Plugin and Add-on
The process is the same for all CM plugins and add-ons.
- Download the plugin from your customer dashboard
- Log in to WordPress and navigate to the WordPress Admin → Plugins settings
- Click on Add New
- Activate it and add the license
TIP: Automatic Index and Dashboard
Upon installation, the plugin automatically creates a page for the location index and another for the dashboard. Head to Settings → General tab to:
- Find shortcuts to these pages
- Enable or disable them (useful if you want to create your own)
Initial Setup - API Keys
To show Google Maps on your site, you require to create and then add a Google Maps API key into the plugin.
- Starting from July 2018, Google Maps requires billing information, such as an associated credit card.
- The pricing system also changed, but in practice, the services are still free for limited use.
Google API Keys - Obtaining the Google API Key
To obtain the Google API key, follow these steps:
- Head to the Google Developers webpage
- Log in to your Google account
- Go to your project or create a new one
- Head to APIs & Services and then Library
- Select one of the API from the list. You may have to search for it by using the search bar.
- This page is important. In it, you can enable the API and find resources about it. Click "Enable"
- Repeat steps 6 and 7 for all the API keys you need to enable:
- Geolocation API (For some features; requires HTTPS)
- Geocoding API
- Places API
- After you have enabled all the API Keys, activate the sidebar menu and click on Credentials. You will find the API key there, ready to be copied and pasted into the plugin's settings.
Also, if you have still not enabled billing, you can do so by activating the sidebar menu and then selecting Billing. Then click Link a billing account and follow the steps.
Adding Key to Plugin
Once you have the key, adding it to the plugin is easy. Head to the Setup tab and copy it to the Google Maps App key field.
In the same setting, you can click Test Configuration to ensure the connection is working.
OpenWeatherMap API key
If you want to add weather details to your maps, you will need to enter an OpenWeatherMap.org API Key the same way you did the Google Maps one.
To obtain the API key create an account and login to http://home.openweathermap.org/.
This guide will walk you through the process while creating a new account.
- Click Create an Account
- Enter your information
- Choose a purpose for which you will use the maps
- Click API keys and you will have access to the key. According to OpenWeatherMap, it can take a couple of hours for the key to be active.
Once you have the keys, add them to the plugin's settings.
Adding Your First Location
With the initial setup ready, head to WP Admin → CM Maps Locations Pro → Locations.
Both you and your users can use a fully-fledged Front-end form to create and edit locations.
By using a Front-end form, users don't need to access the WordPress Admin dashboard.
The plugin comes with a user-friendly location editor. The admin can use both editors.
TIP: Editing the Form
- You can change which fields appear and which are required from the Settings → Location Form tab. The changes will affect everyone who uses the form, not only the admin.
- Some other settings, namely default location behavior, are in the Dashboard tab.
- Labels can be translated from the Labels tab
- Custom Fields are located in the Custom Fields tab.
The form is feature-packed.
- Basic details - Name, description, status of the location.
- Taxonomy and custom taxonomy link - Categories, tags, and any created custom taxonomy. Learn more below
- Icon - Choose a default icon or upload a custom one. Set the size (small, normal, large)
- Multimedia - Images and video.
- Map - You can pinpoint the location directly on the map
- Coordinates - Fetched from the map. You can add them manually
- Shape colors - Visual settings
- Extra information - Data such as address and website to be shown on the location page
Learn more about each section: CM Map Locations (CMML) - Getting Started - Adding/Editing Locations - From Map
Extra - Polygons
You can enable polygons to let users draw geometrical areas related to their location.
To enable the polygon draw tool, enable Location Form tab → Form Settings section → Shape Tool.
TIP: Three Other Ways of Adding Locations
It's also possible to add locations:
1) From the User's Current Location (Geolocation)
2) Importing from KML files
3) From External Services (REST API)
You can build an app with the button "Create Location". When clicked, it generates a location based on the user's GPS information.
Configuring the Location Page
Every time a user adds a location, that location receives a page automatically. We'll review some ways to edit this page - the settings are located in both General and Location page tabs.
There are six themes to choose from.
Night Theme Example
You can change the map theme from the General tab → Map theme option.
Learn more: CM Map Locations (CMML) - How To - Change Map Theme.
What is This Feature
It's possible to offer additional tiles layers on your maps. These present additional information on top of the map.
By default, the plugin connects with the free OSM ( Open Street Map) service. Examples of what it can achieve:
The settings are in the General tab → Map section.
- Default map view - Choose what is the default view. Users can change this at any time.
- Insert URL for tile - Add the URL of the tile service of your choice. Check Tiles - OpenStreetMap Wiki for more examples.
- Change files feature - Lets the visitor turn tiles on or off while browsing the map
3) Custom Icon
It is possible to add custom icons to the pool of icons available when creating a location. Simply click Upload icon.
Adding Custom Icon
The Index Page
The index page is perhaps the most important page of the plugin, and it can be extensively edited.
What Is The Index Page?
In the Index view, visitors can view all locations that are published. They users can:
- See location list with overall map showing them
- Sort location by categories, difficulties, and location types
- Search for specific locations
- View locations in Satellite or Map view
- Click on specific locations on the map to learn more, or see snippets of all locations or locations in a certain category below the map.
Modifying Index Page
All edits are made from Settings → Index page tab.
Since there are a multitude of settings, we'll sum them up here.
For a more extensive view, check CM Map Locations (CMML) - Settings - Appearance (Index Page, Location Page, Dashboard).
You can change:
- Where to show locations list - Choose where to display the locations list on the index page.
- Bottom condensed
- Enable menu - If enabled, it will be shown above the map. Includes the buttons All locations, Add Locations and My Locations.
Pagination, order, search
- Locations per page - Limit the locations visible on the index page below the map. If more locations are available than pagination will be displayed
- Order locations by - This has no effect on the map itself. You can order the locations list by:
- Title (alphabetical order).
- Created date.
- Amount of views.
- User location proximity - This option requires HTTPS to work. It uses the browser's geolocation API and will ask him/her to share the current location. After checking the location successfully, the plugin will ask to reload the page to reorder by proximity.
- Sorting order - Choose sorting order for the list of locations ascending|descending showing beside the map. This has no effect on the map itself.
- Enable map - Display or hide the map on the index page.
- Enable marker clustering - If enabled, multiple markers will be combined as a single when overlapping due to the zoom.
- Enable info window on marker - Shows a tooltip when clicking on a clustered marker, listing each location
- Marker label type - Choose between
- show below the marker
- show tooltip on mouse hover
- not show at all
- Clicking on the map marker will - Select between
- Open the location's page - Directs to the location page
- Redirect to custom URL - Directs to the address in the "URL" field of the location entry.
- Show tooltip with information about location - Displays part of the description without directing the user to another page. This feature has extra settings.
- Number of characters from the location's description to display on the tooltip - Set number of characters from the location's description to display on the tooltip.
- Default location's icon URL - Used when no icon is set.
- Text on top - You can enter text which will be displayed on the top of the index page, below the page title.
- Information visible on the index page - Check which location parameters will be displayed on the index page on the location's snippet which appears below the map on the index page. Choose whether the address and postal code of the location are displayed.
- Location featured image - Choose what kind of featured image to display on the index page. If no icon was set to the location category a default icon will be used. The featured image is selected from 3 available options:
- predefined icon taken from the location category
- the first image in the location image gallery
- Location default image - Enter the URL of the default featured image of the location map index list. In case no featured image is defined, the location shows a default icon
- Show label below marker - Show text labels with location name below the location marker on the index page map.
- Click on the location marker will - Choose between
- open the location's page
- show tooltip with information about location.
- Show rating on the index page - Enable or disable the feature
Zip code neighborhood filter
- Enable ZIP code radius filter - Adds the ZIP code radius filter to the index page next to the search box.
- Country code for the ZIP code searching - The ZIP filter will work only within the single country. Leave it blank to not limit the search to one country only
- Enable geolocation - Recognizes the user's ZIP code using browser's geolocation API. Notice that the geolocation API works only if you're using https.
- Radius values
- Minimum/Maximum radius value - set minimum and maximum radius value.
- Radius value step - Set radius values step.
- Radius default value - Set default radius value.
You can configure:
- Template for the location's info window content - You can use HTML and placeholders
- Max width / height for the info window content
- Max width for images inside the info window
- Number of characters from the location's description to display on
Reminder: Index Page Shortcut
The plugin settings has a handy shortcut for the index page.
User Interaction - Who Can Edit
The plugin allows your users to collaborate, adding and editing their forms. In this section we'll discuss a series of features that affect this collaboration.
Reminder: Modifying the Form
You can edit what appears on the form and which fields are obligatory from the Location Form tab.
Who Can Access And Collaborate?
Head to the Settings → Access Control tab.
From here, you can edit who can:
- Access the index
- Access the location pages
- Create locations
- Edit their own locations
Options Have Choices
- Everyone including guests - Non-logged-in users (note that to let guests create maps, you need the Anonymous add-on).
- Only logged-in users - No matter the user role.
- Specific role - admin, editor etc. Note that only that role will have access - i.e. choosing admin will not grant the permission to other roles.
- Custom capability - You should add a new capability in this field and then include it in one or more user roles. Learn more about roles and capabilities from WordPress.
What Happens When User Posts? Moderation, Notifications and Terms of Service
You define what happens once a user has posted.
Let's start with moderation - you can automatically approve locations or draft it until they are approved by you. Head to the Moderation tab.
Here, enable or disable moderation and choose the email(s) address to receive the notice.
Learn more: CM Map Locations (CMML) - Settings - Moderation
In the same tab, you can configure notifications. These will be sent to the moderator once a suggestion is received, and to the user once the status of their location changes (for instance, it has been approved).
Naturally, these settings only apply if moderation is enabled.
Both messages accept placeholders, such as [accepturl] [trashurl] [blogname] [siteurl] [ip] [name] [description] [author] [permalink].
Learn more: CM Map Locations (CMML) - Settings - Moderation
Terms of Service
Last but not least, you can show TOS to first-time users that try to add a location.
This is configured from the GDPR Settings tab.
Learn more: CM Map Locations (CMML) - Terms of Service
Reminder: User Dashboard Link
You can easily access this page via the shortcut on the plugin's settings
Alternative: Adding Dashboard Via Shortcode
You can add the user dashboard to other parts of the site by applying the shortcode
Reminder 2: Who Can Access It?
You can change which users can view/edit their locations.
What Are Custom Fields?
Custom Fields are smart and flexible ways to categorize your locations. They can be of three types: single-line text, multiple line text, and 5-grade scale.
- Restaurant Review - Add the 5-grade scale fields "Cost-benefit", "Quality", "Service" and a multiple-line field "Review" to inform your readers about the venues you've visited.
- Traveling Blog - Add the text field "Tourist Tips" to help fellow travelers. Then, add the fields "Accessibility" and "Best Time to Visit" for the complete service.
- Journal - Add the text field "Best Memories" to locations that made a good impression on you.
If the Custom Fields Addon is enabled, you will also see the Custom Fields tab in the plugin's settings.
Click on the " Add new field" button below any previously created Custom Fields. A new blank row will appear.
Give the Custom Field a label, a meta key and choose its field type. The meta key is used as a unique identifier so that two fields can have the same name, but still be different.
When the Text label, meta key, and field type have been set, scroll down and click on the "Save" button.
Everyone Can Now Use Custom Fields
Note that custom fields apply to all locations - the fields you add on this page will be available when any user is editing any location.
Deleting Custom Fields
To delete a custom field, simply click on the x icon near it.
Interface - Label
The add-on has a single configurable label. Learn more about translating the plugin.
It can be found on Admin Panel → CM Map Locations Pro → Settings → Labels.
Learn more: CM Map Locations - Add-on - Custom Fields
Map for a Specific Location
- Use - Displays a single map with the specified location.
- Shortcode -
- Check additional parameters.
Map With All Locations or Group of Locations
- Use - Displays all locations or filter them by category, type or difficulty.
- Shortcode -
- Check additional parameters.
- Use - Shows a search form to find locations.
- Shortcode -
Translating the Plugin Interface
If your site is not in English, or if your users don't speak English, that is ok. You can translate virtually all labels from the Labels tab.
There are over 80 labels you can adjust. Some examples
Location (affects the location page and the form)
- Location name
- Phone number
- Edit location
- Access denied
Learn more: CM Map Locations (CMML) - Settings - Labels
To easily move locations between sites and devices, you can perform three main operations.
To check them, head to CM Maps Locations Pro → Export/Import.This screen gives you three options:
1) Import Locations From KML or KMZ Files
TIP: What is a KML/KMZ File
KML and KMZ are the file formats used to display geographic data in an Earth browser such as Google Earth, Google Maps, and Google Maps for mobile. They are tag-based.
Understand the file structure via a sample file. Download KML example files
After importing the file, the location will show on the map and you can edit it, if you'd like.
2) Import Locations From CSV File
Each row is a location. Download and edit the CSV example file.
- location name
- status - publish or draft
- postal code
- tags - separated by comma
- categories -separated by comma
- marker alt
3) Export All Locations
Will generate a ZIP archive with a KML file for each location.
CM Maps Location allows users to rate each location. You can show stars in both Index and location pages.
Navigate to the Index page tab. Head down to the Appearance section and set Yes to "Show rating on the index page".
Navigate to the Location page tab.Head down to the Appearance section and choose "Yes" to the option "Show rating on the location's page".
The plugin provides five widgets out of the box so you can show locations content on your sidebar. Widget list:
- Related Locations
- Locations Menu
- Tag cloud
- Search Bar
- Category Description Bar
Example (Search Widget)
TIP: Adding a Widget
Widgets can be accessed through Appearance → Widgets. Once a Location widget is added, it will only show up on pages related to the plugin.
Learn more: CM Map Locations (CMML) - Widgets
Here are some common issues. If you experience any of them, check the article CM Map Locations (CMML) - Troubleshooting.
- Map canvas is blank
- I cannot search for places on the edit map page
- Geolocation error shows up on the map page
- "404 Page Not Found" error
- Some icons are not being displayed or there's a rectangle in some text labels
- Imported KML file seems to be incorrect
Following instructions found in the plugin and guides, you and your users should be able to add multiple locations to your site.
Use Case Front-End