Follow the installation steps to get started.

Purpose

Enhanced Categories basically allows for two new behaviors in the plugin: The ability to add images to the Directory Categories page, like so:

And the ability to have only parent categories show at the top:

With children showing underneath when clicked:

Administration

Enhanced Categories adds two sets of options to configure. They are both found under the Directory → Settings → Enhanced Categories tab:

Main Directory Behavior:

These options control what Enhanced Categories does to your directory.

Operation Mode:  Here you can determine the behavior of categories on the Main Directory page. Using “Parent + Child” means all categories will be displayed. If you select “Parent Only Categories”, then the main directory will start with ONLY parent categories in it. Selecting a parent category will display a secondary category screen with the children of ONLY that parent in it. This is a useful option if you have a very complicated set of parent/child categories and showing them all at once is too much for users to sort through.

Show listings from child categories in parent categories: This setting controls what listings are visible when you select a parent category.  You can have it so that ONLY listings that belong in a category appear, OR listings from that category or any CHILD category also appear.

Example:  Suppose you have the categories “Animals”, “Dog” and “Cat”.  Dog and Cat are child categories of Animal.  If you have this setting on, and click on the Animal category, you will see all Animal listings AND all Dog and Cat listings.  If you turn this setting OFF, then you would only see listings that are exactly an Animal, but not a Dog or Cat.

Force selection of parent category before child category: This setting controls whether users see ALL parent and child categories at once, or if they instead, only see parent categories and must pick one before selecting a child category.  This setting affects the MAIN directory page only.  It used to control the Submit Listing page, but now with the 5.0 workflow change, the selection control does not support this AND allow for multiple categories to be chosen at the same time.

Number of Category Columns to Use:  You can control the category column display using the “Number of Category Columns to Use”. This option may have trouble with certain themes that try to aggressively manage the layout, so know that this works most, but not all, of the time.

Category Images:

Display the Category List with Images:  Here you can turn on the ability to display images and how large they should be. The default is to leave this setting OFF, so if you’re not seeing images, be sure to check the “Display the Category List with Images” option.

Category image height/width:  Allows you to set the size of the images that are displayed.  If you change these settings, you may need to upload new copies of images to your categories if they are not displaying without pixelation or distortion.

The Claim Listing module allows admins to create listings for known companies or services and then charge users a fee to become the actual owners of those listings. This allows said users to edit listing information, answer messages from customers, etc.

The whole process is regulated and subject to admin approval.

Installation

Follow the installation steps to get started.

Basic Concepts

The module uses a simple way to distinguish between listings that can be claimed and those that can't: the module considers one special user, usually the admin, as the owner of “unclaimed” listings (see Module Settings). This means that listings from different authors can’t be claimed by anyone.

Users who want to claim their listing must be registered on your site.

Listings that can be claimed have a Claim listing link on top of them. If the user is registered and logged in, clicking the link reveals a form where users must enter some information before requesting ownership of the listing. Once this form is submitted a listing claim is created.

A listing claim refers to an ownership request from a particular user for a particular listing. Listing claims have statuses associated to them (see Claim status below): they begin as Pending (meaning the admin hasn’t seen the claim) and end up as either Rejected or Completed. A completed claim results in the user making the request being the author of the listing.

All of these concepts are more clearly illustrated in the Claim Workflow section below.

Claim status

Once a listing claim is submitted it can have one of several possible statuses:

• Pending – The claim has been submitted but it hasn’t been approved or rejected by the admin. Until this claim is resolved the listing is not available for other users to claim.
• Rejected – When the admin decides not to approve the claim. At this point the listing is released for other users to submit claims.
• Withdrawn – When the user gets to the payment page, they also have the option to withdraw the claim.
• Approved – When a particular claim is approved the user receives an email notification including instructions on how to proceed from there. At this point no other user can submit a claim for the same listing but it still doesn’t mean the user of the approved claim owns the listing. The user still needs to confirm the claim and pay the listing fees. Not doing so results in the claim being automatically rejected after some configurable number of days (see settings).
• Completed – User paid for the listing fees and is now the author of the listing, with permission to edit.

Claim Workflow

1. User submits a listing claim via the form available on unclaimed listings:
   
   
2. Admin is notified by email of the new listing claim (optional).
3. Admin goes to the Claims dashboard where the list of claims is displayed.
   
4. The admin approves or rejects the claim from this screen or goes to the details to see more information. On the detailed view admins can also contact the user making the claim to request further information.
5. Admin approves or rejects the claim:
   • If the claim is rejected, the user is informed via email. If there are no more pending claims for the listing, the listing is released again and can be claimed by other users.
   • If the claim is approved an email is sent to the user including a link to a page where the listing fee can be paid before becoming the owner of the listing.
6. (Only after an approved claim) The user follows the link from the approval email and pays for the listing in order to become its author and be able to edit and manage the listing.
7. If the user doesn't want to continue with the payment process this screen also offers the chance to withdraw the claim.
8. After the payment is confirmed the listing now belongs to the user and the listing is considered claimed.

Notes

• Even though users are offered the chance to withdraw their claims after approval (see above), this would’ve happened automatically after some days of inactivity (no payment). This threshold can be configured by admins.
• Claimed listings are regular listings. That means they are subject to the expiration or upgrade rules as other listings depending on how they were created.
• Transactions resulting from claims appear as regular transactions. Admins can manually approve or reject them as with other payments.
• Claims can also be deleted by admins. This is a silent operation and it doesn’t affect the current state of listings or other claims.

Settings

The Claim Listings settings can be found on Directory → Settings → Claim Listings. On this page, you’ll find that all settings include a description of what they do.

General Settings

Default owner of unclaimed listings. Listings having this user as author are considered unclaimed (see above). Listings with a user other than this one are considered claimed.  They will not show the claim link when displayed on your site.  The admin is typically the default user for this purpose of unclaimed listings.

Days before releasing claimed listings pending payment? As explained above once a listing claim is approved, the user submitting the claim has to pay the listing fees to become its owner. This setting controls how many days to wait for this payment before considering the listing unclaimed again and rejecting the user’s claim.

Emails

Notify admin of new claims. Turn this on to receive emails from your directory when a user attempts to claim a listing. This is useful if you want to know when to check claims that are pending.

Approval email. The email sent to the user when their claim is approved and paid for.  Only sent if the user is required to pay for a listing and they are approved. This email is also sent 3 days after approval as a reminder to take action.

Approval email (no payment required). If your listings do not require payment, this is the email that is sent instead when a claim is approved.

Rejection email. Email sent to the user when you reject the claim and provide a reason.

Claim listing form

Put reCAPTCHA on the claim form? Because of possible spam, you may wish to enable Google's reCAPTCHA to show up on the form to avoid bots from submitting fake claims.  Requires that you have the reCAPTCHA API keys setup in Directory → Settings → General → SPAM tab to use this.

Show a “Claim Reason” field? When a user is submitting a listing claim you can use a “Claim Reason” field to capture additional information to support the claim.

Make “Claim Reason” required? If the user submits a claim, do they have to provide a reason?  If so, turn this option on.

“Claim Reason” field label. Specific label text you can use instead of “Claim Reason” for the reason why they are claiming this business.

Request Received Text. This is the message that is displayed to users once the listing claim form is submitted.

Installation

Follow the installation steps to get started.

Administration

File Uploads/Attachments allows you to set site-wide attachment settings for all listings OR you can specify them per plan or even use Restrictions. Site-wide settings will be used if no other settings are found or changed. This can be configured under Directory → Settings → Listings → Attachments at the very bottom:

The options work as follows:

• Enable Listing Attachments:  Turns on the option to allow attachments on listings when checked.  Listing attachments must be enabled for any listing to use attachments, so ensure this is checked when the module is installed.
• Attachment Header Text:  The Attachment Header text is the label used on a listing as a title above the attachment links.  Default is “Listing Attachments”. Change this as desired.
• Enable Icons for Attachments:  For the given file types, we have default icons that are available to indicate the type of file graphically.  Enabling this will display the icons.  If you prefer a tighter display, turn this off.
• Max Attachments Per Listing:  The number of attachments your users are allowed to upload by default.
• Max Attachment Size:  The largest file you allow to be uploaded as an attachment in kilobytes (KB).  Adjust as needed.  Helps prevent users from uploading obnoxiously large files and chewing up your disk space.
• Allowed File Types: Allows you to control the kinds of files you allow on your listings.  The types are hard coded for PDFs, various image types (PNG, JPG, GIF) as well as basic text files (RTF, TXT)

You can override these settings on Plans if you wish when the Restrictions module is installed. Click on Restrictions and this will take to you to this screen where you can decide which plans have access to Attachments:

Managing Attachments

From the admin-side, you can easily manage attachments on any listing. When you edit the listing, on the lower right side, under the Categories (and possibly Regions, if you have that installed), you will see Listing Attachments in a widget:

Hovering your mouse over the attachment shown, you can Delete it if you wish by clicking on the red Delete link shown. Clicking on the name of the attachment will display it for you in a window. You can also add new ones. Clicking Add Attachment opens this dialog:

Where you can upload the file as well as specify the text used to display on the link when the listing is shown to users.

Submitting a listing allows users to add the attachments at the same step as adding images in the listing:

The display on the right will indicate the settings from your admin tab so the user is aware of any restrictions for attachments–in this case, that only 5 attachments can be uploaded, the max size is 4.88 MB (5000KB) and the extension must be a PDF file.

The map can be displayed on any of the following views:

• The Directory (and List) Page (showing all visible listings)
• The Search Page (showing all listings in the results)
• The Detail Page (showing the current listing’s map only)

After the maps are set up, maps will show on your selected pages. Here's an example on a single listing view:

This example is using the Large Map and Roadmap options. The Address, City and State fields are used to map the location of Apple Computer here.

Installation

Follow the installation steps to get started.

Administration

Google Maps admin screen is broken into several sections.

General settings

Google Maps API Key (REQUIRED)
Enter your Geocoding API key here from Google. See below for more details about getting and using one.

Show listings map on: Activates or deactivates the map that shows on the category page, the Directory/List page, and the advanced search page. On by default.

Current page listings to show on map
This allows you to control whether the map shows ALL listings in your directory or just the listings on the active page.  If you have a LARGE directory, then changing this to “active page” will improve performance.  Some large directories require too much processing to pull all markers on the map at once so this allows you to control that.

Allow visitors to get directions to listings
Turning this on will show “Get directions” where the user can enter their current address and the map will display turn-by-turn directions and a route to get to that particular listing's location.  Please note–Google's API requires that secure HTTP connections (https) are used, so if your site is not using SSL, you may see warnings about https redirects.  This is not a bug with BD, but a problem where your site is not compatible with Google's API unless you make it fully secure (SSL). If you use this option, you also need to turn on the Directions API in Google.

Allow visitors to manually adjust the location of their listings
Turning this on will allow users on the FRONT END only to manually move a marker to a physical location on a map.  This is useful if you have clients with addresses in rural areas where Google Maps doesn't place the marker in the “proper” place.

Listing locations

These settings match up fields to the addresses used in the maps. You can select up to 5 different fields to use. Google Maps requires at least one to be mapped.

• Address: Which field in your list of form fields maps to the base address
• City: Which field in your list of form fields maps to the city
• State: Which field in your list of form fields maps to the state
• ZIP/Postal Code: Which field in your list of form fields maps to the postal code
• Country: Which field in your list of form fields maps to the country

Tooltip content
If you would like to customize the information shown in the tooltip, this is the place to do it. Field shortcodes like [name] can be used here. Other shortcodes that can be used in this box include:

• [address]: Shows the value from the field selected in the Address field dropdown.
• [city]: Shows the value from the field selected in the City field dropdown.
• [state]: Shows the value from the field selected in the State field dropdown.
• [zip]: Shows the value from the field selected in the Zip Code Field dropdown.
• [country]: Shows the value from the field selected in the Country Field dropdown.
• [url]: The link to the listing in your directory.
• [name]: The title of the listing.
• In addition, and field id or field shortname shown in the Directory → Directory Content → Form Fields page can be used.

Appearance

Appearance settings control how your maps will appear in the directory.

Use marker cluster indicators
When a map includes a lot of listings, it may start looking very cluttered and difficult to read. Using clusters will group sets of listings under a clickable number on the map.

Display map position – Allows you to control where the map appears in the listing pages selected in the Show listings map on setting. Choices: Above All Listings or Below All Listings.

Zoom level
This setting will change how close or far the map is for a single listing. When the map included multiple pins, this will always be automatic so all pins are shown.

Map type
One of the following choices: Road Map, Satellite, Terrain or Hybrid. Road Map will display the labeled streets in a colored map. Satellite and Terrain will use the images from Google Earth. Hybrid overlays the two.

Animate markers
Turns on basic Google Map drop in animations for the markers where the business is located.

Size

Map Size
The dimensions of the Google Map to display, either Large (400×600), Small (200×300) or Custom Size. Default is Automatic  If your map does not fit in the width of the map, use “custom” and set the size you want.  Automatic allows mobile and desktop users to receive the proper sizing and is the recommended setting.

Custom map size width
The custom width of the Google Map to display. Only valid when Map Size “Custom” is selected.

Custom map size height
The custom height of the Google Map to display. Only valid when Map Size “Custom” is selected.

Auto resize map when container is stretched
Turn this on to make your maps fully responsive on mobile displays where tablets and phones have wildly different sizes.

Using an API Key for Google Maps

What is the API key?

API keys allow developers and site owners to track usage of Google’s services on their sites via Google’s APIs Console.

Most of Google’s free services are limited to a given number of views, page loads, etc. This means that when your site goes over those limits the services will stop working on your site.

By using an API key (coupled with “Automated Billing”) you can prevent any interruption due to usage: when you hit a given limit, Google will charge you for the extra usage while your site keeps working.

In the specific case of the Google Maps APIs, the limits are as follows:

• 25,000 map views per day.
• 2,500 geolocation requests per day.
• 5 requests (of any kind) per second.

Why do I need API keys for the Google Maps module?

Most sites shouldn’t need API keys at all since limits on Google Maps APIs are very reasonable. Because limits are enforced during 24-hour intervals, even if your site goes over the limit, it could be the case that the outage lasts at most until the next day.

The Business Directory – Google Maps module uses a special kind of cache to prevent unnecessary API usage but sometimes that’s not enough.

If, after enabling the module, some or all of your maps are not being displayed and you’ve been seeing a warning about failed requests on your WP backend for more than 24 hours, you definitely need an API key.

If your maps are not being displayed but you’re not seeing a warning on the backend, you probably don’t need an API key. Please double check your settings and, if the problem persists, contact us for assistance.

If you have shared hosting, READ THIS:

When your site is on shared hosting, as the name suggests, it is sharing the same physical server resources (such as memory, CPU, etc.) with several other sites. Because all of those sites are on the same server, most of the time they’re also sharing the same IP address, regardless of the domain names being different.

Google enforces limits by looking at the IP address of your server so your site could be denied access to Google APIs even if it is not the one abusing the APIs or hitting the limits on its traffic alone.

An API key is a way to solve this issue without having to move your site to a dedicated server or VPS.

How do I get an API key from Google for use with the Google Maps module?

First, you’ll need a Google login, such as the one from a gmail.com account, and a credit card for billing.

1. Visit Google Developers Console and enter your login information (if asked).
2. If there are no projects listed, create a new one or select your current project.
3. Go to APIs & Services → Dashboard and click + Enable APIs and Services. Make sure the following APIs are enabled:
   
   • Google Maps Geocoding API. (NOTE: Don’t confuse this with Geolocation–they aren’t the same!)
   • Google Maps JavaScript API v3
   • Maps Embed API (NOTE: If you require the directions feature, then Directions API should be enabled.)
   • If you will use the directions feature in the Business Directory Maps settings, you also need to select the Directions API option.
4. Go to APIs & Services → Credentials and click Create Credentials. Choose API Key as the key type. You can also add IP or referrer restrictions to your key (recommended)
5. Your new API key should be created (a long string of characters and numbers).
6. Google requires customers to add billing information. We recommend that you set up automated billing for your project to avoid any outage. To do that, visit Billing & settings under your project’s name and click Enable billing.
7. Log in to your site’s WP admin and visit Directory → Settings → Google Maps to enter your new API Key.

API Key References

• Google Developers Console Help
• Geocoding API usage limits
• Usage Limits for Google Maps API Web Services

Troubleshooting

API Key Activation in Google Maps

There are three key areas where people run into trouble with activating their API keys when implementing the Google Maps Module.

Make sure all 3 APIs are added. The Google Maps Module requires three API keys, which are outlined in this article. To recap, here are the three that you need:

• Google Maps Geocoding API. (NOTE: Don’t confuse this with Geolocation–they aren’t the same!)
• Google Maps JavaScript API v3
• Maps Embed API (NOTE: If you require the directions feature, then Directions API should be enabled.)

Make sure you have billing turned on. The other issue is that Google made changes to its Maps usage accounts, and they have started requiring a payment method to be put on file. There is more information about the changes and how they may affect you at this link: https://cloud.google.com/maps-platform/user-guide/pricing-changes/ There is also a pricing sheet here for your reference: https://cloud.google.com/maps-platform/pricing/sheet/

The billing issue is the most common error we see. Here is the typical warning that Google gives you: You must enable Billing on the Google Cloud Project at https://console.cloud.google.com/project/_/billing/enable Learn more at https://developers.google.com/maps/gmp-get-started

Simple steps you can take to find the reason for the error

1. Go to a page on your site where Google Maps is supposed to show.
2. Right-click on the page.
3. Choose Inspect from the dropdown.
4. View the Console tab.
5. You will see the error there if there is one.

I am getting blank maps

Blank maps can happen for a variety of reasons. Here are some possibilities:

1) You recently imported a large number of listings. If you did this, the Google Maps API has a daily limit of calls made to it and can be exceeded during the process. Waiting 24 hours usually takes care of the problem as you'll get a new allocation of calls the next day. Once BD's Maps module can get the geolocation data, we cache it. This is probably the most common cause.

2) You're using a theme or other plugin that is using the Google Maps API as well. The limit is imposed for all calls made from the server, so if your other software has used them up for the day, the map is blank until it can get the data. This is less common but can happen.

3) You're on a shared hosting plan and someone else is using the Google Maps API on your server besides you. The calls are allocated per IP address, so a shared host means shared calls. This is the least common, but we see it occasionally.

4) You haven't mapped the listing fields on the Maps tab OR your listing doesn't have any address/location data. Without anything to locate with, the Map won't actually appear.

In the first two cases, the first thing to do is wait 24 hours and see if the maps appear on their own. If not, then the next thing to check is to see if the Maps are having some kind of conflict, but it's best to know if they restore on their own first.

Regions Concepts

Regions are set up in a hierarchy, like:

Continent → Country → State

Continent is at the TOP of the hierarchy, City is at the bottom.  This hierarchy can be ANYTHING you want, but we create one for you by default (the one above) which you are free to modify.

Regions are used to filter listings using the Region Selector on the main directory page:

And they are also used to search for listings on the Advanced Search page

as well as the Quick Search bar:

Regions are also used to filter listings using the Sidelist:

Clicking on a region name in the sidelist will restrict the listings in the view to that region only.

Regions can be defined in a hierarchical fashion, for example, Continent → Country → State → County → City. You do not need to define all those levels if you don’t want to. By default, we pre-configure the Regions module with all Continents, the Countries of the world, and the States of the United States. Additional regions and levels can be added easily to customize for your locale.

NOTE: The module does not come with states outside of those provided for the United States, and it doesn't come with cities, counties, etc. These must be populated manually. Instructions for doing this are provided below in the Adding cities to Regions in Bulk section of this page.

Installation

Follow the installation steps to get started.

Regions Setup

To correctly configure Regions Module, you must do the following activities:

1. Create and associate your regions in a hierarchy
2. Change the field labels to match your hierarchy naming convention
3. Decide where your fields will show up (Search Page, ListView, Detail View)
4. Change the order of display of fields

That’s it. The first step is the longest. We start you out with the Countries and Continents of the world as well as all states for the USA. The rest you will need to add or associate yourself.

The hierarchy definition does not need to match Continent → County → State → City. You can have any association you like, such as Middle Earth → Hobbiton → The Shire → Bilbo’s House if you like. The important part is to understand which are parent regions and which are child regions. We give you the most common use of Regions module pre-configured, but you are free to change that (including the labels of the fields) however you like.

Regions Fields

Installing Regions module automatically adds 3 new fields to your configuration under Directory → Directory Content → Form Fields. They are as follows:

• State
• Country
• Continent

As you add additional levels to your Regions hierarchy, additional form fields will be added automatically by the plugin. For example, if you add the city Orlando to the state of Florida, the plugin will automatically create a new city field for you.

You can configure what Regions fields will show in your listings however you like in the Form Fields section of Business Directory, including their output order. For example, if you only want to show City and State for US listings, you might have something that looks like this:

Display field in region selector?

There is also a setting in each form field itself that controls whether a level in the hierarchy is shown in the Regions selector (the dropdown list on the main page). The checkbox controls if the field is included in both the region selector and listing form.

NOTE: If you accidentally delete a Regions field, don’t panic. You can get it back by visiting the Regions tab under Directory → Settings → Regions → Actions. At the top, click to expand the Regions pane and click on “Restore Regions Form Fields”. Shown below at the bottom of the Regions admin screen:

Administration

The regions settings screen looks like this from Directory → Settings → Regions:

General Settings:

Hide Region Selector?: Turning on this option disables the Region selector that is shown in various places, such as the main directory or the search page.  The Region selector looks like this (closed):

Or (open):

Show Region Selector Open by Default: Turning this option on leaves the selector open (image above) when the user first visits the page.  Default is closed/off.

Show Post Counts: Turning on this option will display a count of the listings in that region when it's shown on the sidelist or in a drop-down menu, like “Albany (3)”.  Default is off.

Add Regions to Quick Search Bar?:  Turning this on will add the Region field to the Quick Search bar available fields to use.  It behaves similarly to the ZIP search option we show here:

You must still click the link at the top of this tab (“Change the configuration here”) and select it to activate it as a “searched field”.

Sidelist Settings:

The next section is for the Sidelist of Regions.  The Sidelist is the area next to the main directory that shows locations and listing counts.

The settings that control this are as follows:

Show Sidelist: Turning on this option makes the Sidelist visible.  Otherwise, no sidelist for regions will be displayed.

Sidelist should start display at: This setting will change where the Region sidelist will start to display items in the region hierarchy. For example, use this to start displaying states instead of countries on the list.

Show “Clear Filter” option: Turning on this option will display a “Clear Filter” link at the top of the sidelist when you have a region selected, shown below.  Default is off.  The link will only appear when your mouse is hovering over the region sidelist.

Keep Sidelist expanded on current Region: Turning on this option means that selecting a Region will collapse all other regions EXCEPT the current selected one in the hierarchy.  Useful to highlight the selected region.

Automatically expand sidelist on page load?: Turning on this option means that the sidelist will fully expand when the page is loaded (all sub-regions will expand in the tree).  Makes it “prettier” when the user loads the directory.

In addition to the settings above, at the bottom of the tab, there are some buttons to help you manage the regions settings and fields, in case something goes wrong.

You can use these buttons to restore the default regions, the region form fields (if you accidentally delete them), or restore the default settings of the Regions Module.

Regions SEO Settings

Go to the Directory → Settings → General → SEO page to find the URL-related settings.

Regions Slug

This is used in the URL when users are filtering for a particular region, like /wpbdm-region/new-york/albany, which happens in some searches or the Regions browser page. This must be a unique slug. A default slug is provided but you can change it as long as it doesn't conflict with others.

Legacy Regions URLs

If you created any regions before v5.3, you might see this option. If you don't see it, that means the site is not using legacy URLs.

Before v5.3, the links to each region included the directory page slug, and they were not hierarchal. This option will change the URLs for existing regions, so only uncheck this option if you are not concerned about the URLs changing.

Warning: This will change the URLs for any existing regions. Once off, this cannot be turned back on.

Managing the Region Hierarchy

The Directory → Directory Content → Regions screen is where all region configuration happens. Regions are configured as a hierarchy. You can make the hierarchy anything you like, we pre-configure it with the most common scenario, but you are free to use as much or as little as you like. The default is setup as follows:

Continent → Country → State

You can add counties, cities, villages, boroughs, whatever you like. The important thing to understand is which regions are parents and which are children, and to make the association accordingly. Each level of the hierarchy is displayed with a dash in front of it. So top level regions have no dash, first level (country) regions have a single dash, second level (state) regions have two dashes, and so on.

As you add or delete regions, the Regions Module will automatically change the Form Fields to add or remove the level of the hierarchy you create. These fields will have default names associated to them, but you can change them to whatever you like. The names of the fields are not important to Regions Module.

The Regions screen primarily uses a list of regions to work with (notice the top level region, North America (a continent) has a country (with single dashes) below it, and state (with two dashes) and a city (with three dashes):

At the top of this list, you have various filters you can use to hide/show regions that you are interested in. Clicking Enabled will display all active regions (those that can be shown in the Region Selector, Search screen or Submit Listing screen), Disabled will show all inactive ones. Clicking All will return you to the master list of regions at any time.

To add a new region, simply type the name of the Region in the Name field, specify the parent region of it (type slowly and the plugin will suggest a list of matching options), and then click Add New Regions. If you do not specify a parent, that region will become a top-level region. By default, top-level regions are Continents.  You can configure your regions any way you like, continents do NOT have to be the top level–this is just how the default data set comes.

When you are working with regions, the operations you can perform on them are found when you hover the mouse over a particular region, like so:

The commands are as follows:

Edit: This will allow you to change the region name, slug and description on a separate screen.

Quick Edit: Similar to edit, but allows for in-line editing of the region info above.

Delete: Removes the region from the hierarchy. WARNING: Any child regions will ALSO be deleted as well, so be careful of this operation.

Enable/Disable: This will make a region active or inactive. Only active regions will show up in the Region Selector, the Advanced Search screen, and the Submit a Listing screen. A region must also be active to show on the side list.

How to Filter Listings By Regions

When you visit the Directory or View Listings pages, at the top, you will see the Region Selector (which by default will say “Displaying listings from All Regions” until you select something).

To the right of the region indicator is a drop-down arrow:

Clicking on it will open up the region selector:

When you start out, the first drop down will be the only one displayed. Clicking a region in it will create the control to select the next level (in this case, selecting “USA” caused the “State” drop-down to appear. Selecting “Washington” caused the City drop-down to appear.

When you have fully selected the desired region you wish to filter on, click Set Filter to set the region for filtering. Now, only listings from that region will be shown in View Listings and Directory, until you change it. In the above example, clicking Set Filter will cause only listings from Seattle, WA, USA to show up in the directory.

If you make a mistake or simply wish to see all listings, click Clear Filter and the drop downs will reset, allowing for a new selection.

How to Change the Regions Hierarchy

Modifying the regions hierarchy is done by defining the regions FIRST here in Directory → Directory Content → Regions.  We found that it was easier to take your data and associate it to a series of fields, than the other way around.  If you want to completely rework the default regions into your own setup, we recommend doing it this way:

1. Delete all of the regions on this page that you don't plan to use, starting with the PARENT regions you don't want.  (in the hierarchy Continent → Country → State → City, Continent is the PARENT of Country, Country is the PARENT of State, but the CHILD of Continent, and so on…).  This will help get rid of LOTS of regions you don't want to use
2. If you don't want Continent at the top of your hierarchy, you will need to delete ALL REGIONS and start from scratch.  This sounds scary, but it's not.  You can always reset the data BACK at any time.
3. Create the Regions you do want, starting at the TOP.  Instructions for that below.
4. When you are done, go to Directory → Directory Content → Form Fields
5. Delete ALL of the fields that are of type “Region” (again, this sounds scary but it's NOT!)
6. Tell Regions to “restore the fields” by returning to Directory → Directory Content → Regions, and clicking the Restore Region Form Fields button.  This will create NEW Region fields based on the NEW hierarchy you created.
7. Now return to Directory → Directory Content → Form Fields. Your new fields will have names like “Continent”, “Country”, etc., which you can edit  The hierarchy, though, is from PARENT → CHILD.

The Sidelist and Quick Filters

The sidelist allows you to have “quick filters” setup for regions you know will be of interest to your users. The side list appears like this in your directory on the View Listings and the Directory page, to the right of your listings and just below the button panel/region selector area:

When you click on a region in the sidelist, this will quickly set the region to match the one in the sidelist. Sidelist regions can also have sub-regions showing as well, such as this for USA (before and after pics):

By clicking on the button, that will open the sub-region list (States) for USA, allowing for further location filter refinement.

If you want a region on the sidelist, you must add it under the Directory → Directory Content → Regions area.

Adding cities to Regions in Bulk

The cities or other smaller regions will need to be added manually in the plugin, but you can do them several at a time.

To do this, go to Directory → Directory Content → Regions, then click on the Add New Region button.

Once you are there, you can easily write in the list of cities you want to add. You can also copy/paste lists of cities for each state in the box if you have them available, then associate those cities to the state you want. Then click the Add Regions button and those cities will be added:

You can do a Google search for the phrase “text list of cities in Florida” (for example) to get a good list you can copy/paste. We recommend putting the list in a text editor like Notepad to remove any formatting that may be on the page where you have copied the information from.

Note: We have also identified this potential source of information on cities/locales that you might wish to use instead: https://developers.google.com/adwords/api/docs/appendix/geotargeting?csw=1

Enabling newly added cities

Once you have added the list of cities, they will need to be enabled. To do this, from Directory → Directory Content → Regions, search for the state you added cities for

On the results page, click on the region name (in this example, please note there is both a State and a Country called Georgia — be sure to select the right one!):

Once those are displayed, you can see the newly added cities:

Here is what the ZIP Search Module looks like when it is enabled on the Quick Search Menu:

Here is what the Regions Module looks like when it is enabled on the Quick Search Menu, if you have the regions filter enabled as well:

If you have enabled both modules in the Quick Search bar,  then the Regions Module will take precedence. Only one of those options can be added to the Quick Search bar, so you must make a choice between the two modules here.

Shortcodes

Show Listings in a Region

[businessdirectory-region]
Displays a set of listings from a given region.

Learn more about [businessdirectory-region].

Example result:

Show List of Regions

[businessdirectory-regions-browser]
Shows the “Regions browser”, similar to what Craigslist shows on the home page when first visiting the site to pick your preferred location.

Learn more about [businessdirectory-regions-browser].

Example result:

Show Subregions

[businessdirectory-region-subregions]
Shows subregions of a region (parent). This shortcode displays a list of child regions from a specific region, defined by `parent_region` parameter.

Learn more about [businessdirectory-region-subregions].

Example result:

Filtered Directory Listings

[businessdirectory-region-home]
Shows the main directory page but filters automatically with the given region.

Learn more about [businessdirectory-region-home].

Example result:

Regions Module Troubleshooting

I'm getting a 404 error when I click on a Region.

This issue quite common with the Regions module and usually the problem is that permalinks need to be updated. To do that, go to Settings → Permalinks and click on Save Changes. This should bring back that page.

I see two city and state fields in my listings.

Usually, when this happens, it is because a Country and State field was created before you installed Regions, which adds another Country and State field. You will need to go to Directory → Directory Content → Form Fields and delete the field that looks like this:

And keep the field that looks like this:

This may be true of any other Regions fields, like state, so please be sure to check for that.

It's important that you keep the field with (as region) because that's the field that the Regions Module uses.

If you find that you accidentally remove that field, you can re-create it, no problem. Just go to Directory → Settings → Regions and scroll to the bottom where you will click on the “Restore Region Form Fields” button:

My listings have city and state data in them, but they are not showing up when I filter for the city and state.

This is likely because of the field issue outlined above — the data you have listed for city and state, for example, aren't in the right fields.

On the front-end of your listings, that might look something like this:

The listing looks great, but the Address field is not used by the Regions module for regional classification.

The data that the Regions Module uses for assigning a region to a listing is shown on the backend of the listing itself in the admin panel. It looks like this:

Your listings can certainly have data in both places to make the listing look nice, but the only place that the Regions Module will recognize the data is in the designated Regions field shown above. You can even keep both fields if you'd like, and choose one not to show up on the front end in the form field settings, but it is not recommended because it can get confusing.

I am getting a “no regions available” error.

This likely means that you need to add data to the Regions Module. Here is where we might see this message on the backend:

And here is what it looks like on the front-end of your site:

This occurs because you have added a level to your hierarchy (most likely city) for one particular region and not for another. For example, you have added cities in the region's hierarchy for Florida, but you have not added cities for Arkansas.

To fix this, you will need to add the city-level data for all states. If you don't want to do that, you can delete the data you have for cities in Florida and delete the City (as Region) form field under Directory → Directory Content → Form Fields and this will resolve the issue.

Follow the installation steps to get started.

Required Database Upload

ZIP search relies on a database to calculate the distance around a particular ZIP or postal code when doing radius searches (Like “Find all listings within 10mi of 90210”).  After installing the plugin, you will need to download and install the correct databases for all of the countries you need to support. Database installation requires these instructions.

Administration Options

ZIP search supports a number of options under Directory → Settings → Listings → Searching tab.  They are listed here.  First, we'll discuss the top of the admin screen:

Use this field for postal code/ZIP code information:  This drop-down contains a list of all fields in your directory.  Pick the ONE that maps to your notion of a Postal or ZIP code.  This is super important–without this field properly mapped, the ZIP search will not work correctly at all.

Units:  This drop-down allows you to pick between “Miles” and “Kilometers” depending on what unit your country uses for calculation of distance.  ZIP search will use this to change the display of units appropriately.

Use these custom distance options for searches with postal codes:  Turning on this option allows you to specify a dropdown with precise distances that you can use for search, instead of allowing users to type in any info they want.

Radius Options:  This field uses a comma-separated list of numbers (ONLY) to determine the search options you show the user for radius search.  Only valid when “Use these custom distance options for searches with postal codes” is checked.

Sort listings from closest to farthest in results:  Turning this option on means that for ZIP radius searches, your listings will be shown from the closest to the farthest in the results.  This only affects distance searches.

Default radius to use for Quick Search:  The number of miles or kilometers to use in Quick Search by default if they don't pick anything.  Only valid if you have ZIP search active in the Quick Search bar.

Add ZIP search to Quick Search Box?:  Turning this on will add the ZIP search field to the Quick Search bar.

Below the ZIP admin options, you will find the list of databases available:

You must manually install them following these instructions.

When you install a database, the option will become checked.  In the example above, the US database is installed.  The Cache Status at the bottom of the screen indicates the state of the cache used by ZIP search to improve performance.  Sometimes after upgrading the database you may need to rebuild it.  If you see a notice to do so, please follow it.

Note for users of both the Regions Module and the ZIP Search Module:

You can choose to enable the Regions Module on the Quick Search menu, which adds the Located at <City, State> search field OR you can choose to enable the ZIP Search Module on the Quick Search menu, which adds a ZIP code field to the Quick Search.

Here is what the ZIP Search Module looks like when it is enabled on the Quick Search Menu:

Here is what the Regions Module looks like when it is enabled on the Quick Search Menu:

If you have enabled both modules in the Quick Search bar,  then the Regions Module will take precedence. Only one of those options can be added to the Quick Search Bar, so you must make a choice between the two modules here.

You get the ability to require comments with ratings (or not), and to define a threshold to display ratings information on list views and single views.

Installation

Follow the installation steps to get started.

General Settings

The Ratings Module administration screen is broken into 2 separate parts.  The settings are as follows:

Ratings threshold
This is the minimum number of ratings that must be recorded before the “Ratings (average)” will display a star value. Default value is 0 (which displays all ratings immediately).

Allow unregistered users to post reviews?
This allows users who haven’t logged in to post a rating. The default is that a user must be registered and logged in to rate a listing. The user’s IP address is recorded to prevent multiple ratings from a single user.

Allow some HTML in the Rating comments?
This allows users to post reviews with some basic formatting HTML tags (bold, italic, pre, etc) without risking full HTML exposure to unsafe tags like iframe or scripting.

Rating Comments
Three options to choose from:  Required, Optional, or Disabled.  Required means that a user must enter a comment with their rating.  Optional is the opposite.  Disabled means the comment form is hidden from the user altogether.

Admin must approve reviews?
Turning this option on requires that the admin must see and approve all ratings before they are displayed on the listing. Useful when you have spammers attacking your site.

Email Settings

The second part relates to email settings with Ratings:

These settings are as follows:

Notify Listing owner of new ratings?
If active, the owner of the listing will be emailed after a rating is posted and approved by admin (if rating approvals are on).  Otherwise, the listing owner will not be notified of any ratings made.  The email template used for this notification is set under New Rating Posted email message below.

Notify site admin of approved/submitted ratings?
If active, sends email to the admin when ratings have been submitted or awaiting approval for any listing.

New Rating Posted email message
This is the email template that is sent to the listing owner when the Notify Listing owner of new ratings is active.  You can customize the text by clicking on the black button “Click to edit”.

Rating pending approval email message
This is the email template that is sent to the admin when the Notify site admin of approved/submitted ratings is active.  You can customize the text by clicking on the black button “Click to edit”.

Screenshots of Ratings Module

Here are some screenshots of the ratings module in action. First, the list-based (excerpt) view, with the average displayed:

And here is the rating near the top on the single listing display:

And after ratings have been submitted:

We also support emojis in reviews! Here is what that looks like when you're writing the review:

And here is the result on the page after the review is submitted:

Admin Reviews

Sometimes, users may contact you telling you that they have received mail reviews and would like for them to be added to their listing. As an admin, you can do this, no problem. Admins can submit reviews as needed in the listing itself. The ability to add reviews from the front end are disabled for admins.

To add a review, go to Directory > Directory Listings and find the listing you wish to add a review to. Choose edit, then scroll down to the Listing Ratings section and click “Add Review”:

Once you click “Add Review” you can then add the reviewer's name and their comments, as well as their star rating.

If needed, admins can edit or remove reviews also. Simply hover your mouse over the listing and you will have the option to edit or delete the review.

1. Authorize.net (included in the Core Plugin)
2. PayPal
3. Stripe
4. PayFast (South Africa only)

Installing Payment Gateways

Authorize.net AIM comes with the core Business Directory plugin. No installation is required.

Sign up for Authorize.net

Sandbox or Merchant account

Sandbox information

You will need to go to Authorize.net sandbox and sign up for a sandbox account in order to use test mode with the Authorize.net gateway. It's recommended to use test mode if you just started your directory to make sure payments work as should before you accept real payments, then find out there's an issue.

Merchant information

Sign up for an Authorize.net merchant account or login if you already have a merchant account. Make sure test mode is turned off when using merchant credentials.

Configuring Authorize.net Gateway

1. Go to Directory → Settings → Payment
2. Click on the Authorize.net sub-tab
3. Click the toggle button to activate the Authorize.net gateway
4. Log into your Authorize.net sandbox account for test mode or your merchant account for live payments.
5. Click the Account tab from your account home page.
   
6. Click API Credentials & Keys (under Security Settings).
   
7. Copy your API Login ID and paste it into your Login ID setting.
8. Navigate back to your Authorize.net account API Credentials & Keys page.
9. Select New Transaction Key and Submit to get a Transaction Key.
   
10. Copy the new Transaction Key and paste it to your Transaction Key setting.
    
11. (Optional, but recommended) Put the payment gateways in test mode. Uncheck this when done testing!
12. Change your currency, if applicable
13. Change currency display options, if you want
14. Turn on the abandoned cart emails, if desired
15. Save settings
16. Create one or more Plans
17. You’re ready to test payments. Logout as Administrator and attempt to place a listing–verify that it goes through. Payments will not be taken if you are logged in as the administrator!

Once correctly configured, your payment options and Authorize.net configuration will look like this (production mode):

Your Login ID and Transaction Key should be different, of course. The remaining settings including currency code and currency code placement are left up to you, depending on your preferences and needs. You can configure these under Directory → Settings → Payment → General Settings here:

You can also configure payment reminders for those who attempted to place a listing, but never complete the process (“Abandoned Cart Emails”):

And lastly, if you have the Discount Codes module installed, you can activate whether to allow discounts for listing purchases here as well.

Now you should be ready to receive payments via Authorize.net!

Follow the installation steps to get started.

Configuring PayFast Gateway

1. Install PayFast Gateway module
2. Go to Directory → Settings → Payment
3. At the top, check Enable Payments.
4. Click on the PayFast sub-tab
5. Check the box to activate PayFast gateway option
6. Enter your Merchant Email and ID from the PayFast account information
7. Enter your Merchant Key and Salted Passphrase from the PayFast account dashboard
8. (Optional, but recommended) Put the payment gateways in test mode. Uncheck this when done testing!
9. Change your currency, if applicable
10. Change currency display options, if you want
11. Turn on the abandoned cart emails, if desired
12. Save settings
13. Create one or more Plans
14. You’re ready to test payments. Logout as Administrator and attempt to place a listing–verify that it goes through.
    1. Payments will not be taken if you are logged in as the administrator!

Once correctly configured, your payment options and PayFast configuration will look like this (production mode):

Your settings for the Merchant Info will be different, of course.  In addition to the PayFast-specific settings, you should also have settings like this under the Payment → General settings sub tab:

The remaining settings including currency code and currency code placement are left up to you, depending on your preferences and needs.

You can also configure payment reminders for those who attempted to place a listing, but never complete the process (“Abandoned Cart Emails”):

And lastly, if you have the Discount Codes module installed, you can activate whether to allow discounts for listing purchases here as well.

Now you should be ready to receive payments via PayFast!

• Discounts can be a fixed value or a percentage of the order’s total.
• Discount codes can be applied to any purchase during the checkout process (listing submit, upgrade, etc.).
• Discount codes can be restricted to a maximum number of redemptions or a limited date.
• Discount codes can be limit to certain users only.

Installation

Follow the installation steps to get started.

• Make sure you have the discounts system enabled. The setting is located inside Directory → Settings → Payment, scroll towards the bottom and you'll find:

Managing Discount codes

When Discount Codes is enabled, a new menu item appears under Directory → Directory Content → Discount Codes.

On this screen, you can see a list of all discount codes and information about them (# of redemptions, expiration date, etc.) and some filtering options on top.

You can also edit or add new discount codes. Each of the options and fields available to discount codes are discussed in the following section.

Adding or editing discount codes

When adding a new discount (via the Add Discount button on the previous screen) or editing an existent discount, the following options/fields are available to you:

• Discount Code — An alphanumeric string that identifies the discount code.
• Discount Type — Whether the discount is a fixed value or a percentage of the order’s total.
• Discount Amount — The value of the discount (either as a fixed value or a percentage, according to the previous
  setting).
• Description — A description of the discount code. This field is never shown to users. You can use it for admin
  purposes or to add notes relevant to the discount code.
• Enabled? — Whether the discount is currently enabled to users or not.
• Expiration Date — (Optional) On this date, the discount code will stop working.
• Total redemptions allowed — (Optional) Once the discount has been redeemed this number of times, it will stop
  working.
• Redemption limit per user — (Optional) Limit for same-user use of the discount.
• Limit discount to certain users… — (Optional) A list of usernames that are allowed to use the discount code.

Payment workflow

When the discount system is enabled, a discount code field appears to users during the checkout process (listing submit, listing upgrade, listing claim, etc.). This allows users to apply a discount code to their purchase up to one discount code per purchase and always subject to the specific restrictions of the code (see above).

When a discount code is successfully applied, the user still needs to pay for the remaining amount (if any), to complete the checkout process.

NOTE: Discount codes can be used for recurring payment types but only for the first payment. Users will still put billing information on file and subscribe to the recurring information when they sign up.