Business Directory Plugin for WordPress

Create any kind of directory on your site, easily

Quick Start Guide

You are here: Home / Quick Start Guide

Business Directory Quick Start Guide (version 3.0 and higher)

Maybe you were looking for the Full Documentation instead of this?

Or perhaps The BD Customization Guide (file details, directory layout)?

We also have Video Tutorials available for some aspects of the plugin.

Table of Contents:

I want to…
Get started with Business Directory Plugin

 Customize the Look of Business Directory Plugin
Administrate Listings

 Troubleshoot BD

Installing Business Directory

Full installation instructions for BD and the premium modules.

Return to Table of Contents

Performing Initial Setup

Initial setup instructions for BD.

Return to Table of Contents

Importing Data from an Outside Source

Business Directory plugin currently allows imports from CSV files, that are properly formatted.

Full import instructions.

Return to Table of Contents

How to Translate Business Directory Plugin to your Native Language OR Modify Some Labels in Business Directory Plugin

Business Directory uses the standard WordPress string externalization mechanism (PO files) to allow you to translate the plugin to any language you wish. We also support the use of WPML if you prefer. This article explains how to create a single-language translation file.

NOTE: These instructions have been updated for WP 4.0+, which has changed how translations are handled.

The Translation file can serve TWO purposes:

  • To change the language Business Directory Plugin is displayed in from English to something else
  • To change labels, strings and messages that you see in English to whatever you want (also in English)

Choose the proper steps based on which workflow you are following.

Please note–Business Directory Plugin does ship with SOME translations already completed for you! Please look under wp-content/plugins/business-directory-plugin/languages on your site server for the available files (as of Jan 2017, we have full Spanish, French, English, German, Arabic, Polish, and Swedish translations included).

To FULLY translate the plugin to another language, please follow THESE steps:

Business Directory Plugin can be translated into any language, per the WordPress text internationalization standards. For more general information about how WordPress supports externalized strings for plugins, please read this article first.

  1. Start with the POT file from Business Directory Plugin (in the wp-content/plugins/business-directory-plugin/languages directory of the plugin, named WPBDM.pot)
  2. Downloaded the POedit software (You can find it here)
  3. Translate all strings to your preferred language following the instructions in the POEdit documentation
  4. Save the file as WPBDM-<langcode_COUNTRY>.po, where <langcode_COUNTRY> represents your ISO language code/country combination, such as en_US (English, US), en_UK (English, UK), fr_FR (French, France), pt_BR (Portuguese, Brazil), etc. Country codes can be found on this GNU website.
  5. Upload this new language-coded file to the wp-content/languages/plugins/ on your website’s server (if it does not exist, please CREATE this directory first).
  6. The language of the website should be configured directly through General Settings section in the WordPress Dashboard: http://YOURSITE//wp-admin/options-general.php, where YOURSITE is replaced by the domain name of your WordPress site. Pick the correct language setting and be sure to Save Settings. For more information on doing this, see this WordPress Codex page on Installing WordPress in your Language.
  7. IMPORTANT: Be sure to flush any browser caching you have in addition to any WordPress/web hosting caching you have so that you can see your new strings.
  8. You should now see your site in the new language, with a few exceptions (see below!)

This will translate about 95% of the plugin. Further translation must happen in the following places, which are stored in the database:

  1. Your Business Directory Plugin page name must be translated to your native language (under Pages->All Pages)
  2. Strings that are inside the configuration (see under Directory Admin->Manage Options), such as the Terms and Conditions (General tab), the Submit Listing and Sticky Listing messages (Listings tab) must be translated
  3. Email templates (under Directory Admin->Manage Options, Email tab) must be translated
  4. Update all field labels, by going to Directory Admin->Manage Form Fields

After you do all of these, Business Directory Plugin is fully translated.

Where should I upload the translation file?

Translations files for other languages (WPBDM-<language_COUNTRY>.po and WPBDM-<language_COUNTRY>.mo) can be uploaded to one of the following locations:
1) wp-content/languages/plugins/ (RECOMMENDED)
2) <plugin-directory>/languages/ (DEFAULT)
3) <plugin-directory>

<plugin-directory> is usually /wp-content/plugins/business-directory-plugin.

The best practice is to store custom translations in wp-content/languages/plugins/, because that way the translations won’t be deleted during an upgrade. Options 2 and 3 above will be overwritten on upgrade.

As of Business Directory Plugin 4.x, we now support loading translations from some other locations as well:
The file wp-content/languages/{plugin-slug}/{plugin-text-domain}-en_US.mo, if present, will always be loaded (for users in “English/US” domains), allowing users to overwrite the translation of specific strings. They can create translation files that include only the strings that they want to change. WordPress will use their translations for those strings and use the ones provided by plugin in other cases.

Then, the plugin will check for each of the following files, in the given order, until one of them can be loaded.

wp-content/plugins/{plugin-slug}/languages/{plugin-text-domain}-en_US.mo
Generated by us, included in the plugin.

wp-content/plugins/{plugin-slug}/{plugin-text-domain}-en_US.mo
Previous versions included the translations files in here, in the plugin’s root directory.

wp-content/languages/plugins/{plugin-text-domain}-en_US.mo
WordPress checks for files in this location automatically.

For reference–Business Directory Plugin’s {plugin-slug} is business-directory-plugin.
Business Directory Plugin’s {plugin-text-domain} is WPBDM.

Last, but not least: If you are upgrading from an older version of BD and have an old translation file, you can UPGRADE the translation file instead of starting from scratch! See this article on how to do that: How to Upgrade your BD Translation File for New Plugin Versions.

BD also supports the use of WPML to do translations as well. We cover how to configure that in this article.

Furthermore, here’s a guide for translating WP plugins in general (including language codes, naming conventions, and encodings):
http://urbangiraffe.com/articles/translating-wordpress-themes-and-plugins/

Return to Table of Contents

Changing the Labels of Business Directory Fields

Changing the labels for Business Directory is identical to Translating BD for an entire language, except that you only need to change the strings inside the translation file that you want to change, leaving the rest untouched. This allows you a simple way to customize the labels of Business Directory without modifying the code.

To update some of the plugin’s labels, strings and messages, please follow these steps:

 

  1. Start with the main POT file from Business Directory Plugin (in the wp-content/plugins/business-directory-plugin/languages directory of the plugin, named WPBDM.pot)
  2. Downloaded the POedit software (You can find it here)
  3. Open the file, and search for the string(s) you wish to change. Change those labels in the file.
  4. Save the file as WPBDM-en_US.po on your local machine. Make sure POEdit also generated a WPBDM-en_US.mo file; you’ll have to upload both of them to your server (SEE BELOW FOR THE RIGHT LOCATIONS!). Save a copy of those files on your local machine, just in case.
  5. Upload BOTH of these new language-coded files to the wp-content/languages/plugins/ on your website’s server (if it does not exist, please CREATE this directory first).
  6. WP 4.x users only: The language of the website should be configured directly through General Settings section in the WordPress Dashboard: http://YOURSITE//wp-admin/options-general.php, where YOURSITE is replaced by the domain name of your WordPress site. Pick the correct language setting and be sure to Save Settings. For more information on doing this, see this WordPress Codex page on Installing WordPress in your Language.
  7. IMPORTANT: Be sure to flush any browser caching you have in addition to any WordPress/web hosting caching you have so that you can see your new strings.
  8. View the page in your browser that you changed–you should see your custom message there. If not, double check the steps above and make sure the caches are flushed.

NOTE: Some labels are configured elsewhere For example, all form field labels are changed by going to Directory Admin->Manage Form Fields. Some strings are also in the General tab of Directory Admin->Manage Options as well. Please be aware of this.

Return to Table of Contents

How to Run BD in “Free Mode” (no payments for listings)

You can run Business Directory Plugin as a PAID directory or a FREE one. We do not require that you have a payment gateway to run BD. By default, we have the payment mode active because that’s the most popular option. However, you can easily turn this off and change to Free mode.

To change to free mode, do the following:

  1. Go under Directory Admin->Manage Options, Payment tab
  2. Uncheck the option “Turn On payments?”
  3. Scroll to the bottom and click “Save Settings”

That’s it! You’re in free mode after that. If you want to activate paid mode, reverse option #2 above and then follow the steps in the next section below.

Return to Table of Contents

How to Fix the “Payments Turned Off” Error

If you see the following:
I keep getting this message on the main page on the public website, “You are offering featured listings (or paid listings) but have payments turned off. Go to Manage Options – Payment to change the payment settings. Until you change this, the (Paid Listings) Upgrade to Featured option will be disabled.”

How do I make this go away?

This message is telling you that you need to complete the Payment configuration to get Business Directory to accept payments for listings/charge for Featured listings OR to deactivate payments for BD.

You have two options here:

  1. You can EITHER turn OFF payments (make your directory free–which we talk about here)
  2. If you want to accept payments, do the steps below

To Activate a Payment Gateway Properly:

1) You need to have at least one payment gateway installed. You can use the default (Authorize.net) or you can purchase one of the others (2Checkout, Stripe, PayFast, PayPal) from here: http://businessdirectoryplugin.com/premium-modules/

2) You need to configure that payment gateway under Directory Admin->Manage Options, Payments tab. You should have the “Activate XXX” checked where XXX is the gateway you installed on step 1. You should enter all the required info for that gateway as well (e.g. For PayPal, you need the PayPal email).

3) You need to define at least one Fee plan under Directory Admin->Manage Fees. (Paid listings)

Once these are configured, you can enable Sticky/Featured Listings AND offer Paid Listings on your site. It’s best to test with a sandbox/test account to ensure everything is working smoothly first. Please note your testing will require a “buy side” account and a “sell side” account, as no payment gateway will let you buy and sell with the same account.

And finally, once you are finished testing, you’ll want to make sure your payment gateways are NOT in test mode. Go under Directory Admin->Manage Options, Payment tab and uncheck “Put payment gateways in test mode?” to go to production.

Return to Table of Contents

How to Fix Display Errors with Business Directory and my Theme

Business Directory is written in a way to seamlessly integrate into your theme to avoid major customization requirements. However, not all themes are written the same way and to the same standards.

Handling Minor Display Issues via CSS

Most themes may have a few minor things that don’t look quite right with BD. This can usually be fixed with a small CSS override that targets your specific BD page elements.

Starting with 2.1, Business Directory incorporated the ability to pull styles from a custom CSS file that isn’t overwritten on upgrade. For those with a quirky theme, or the desire to heavily customize BD’s look to match their site, this is great news…

How to use the BD Custom Style CSS file:

1) Create a file called wpbdp_custom_style.css under wp-content/plugins on your site. This location won’t be overwritten by any plugin or WordPress on upgrade. You may also place this file under your theme directory as well.

The plugin is forgiving in locating the file–any of the following names will work for the custom style file, in EITHER location:
– wpbdp_custom_style.css
– wpbdp.css
– wpbusdirman.css
– wpbdp_custom_styles.css
– wpbdm_custom_style.css
– wpbdm_custom_styles.css

That means you should be careful not to have TWO custom files laying around. Pick one place, stick with it! I recommend the wp-content/plugins area as it can’t be overwritten by a theme upgrade.

2) Place any style changes you need in this file. It will be loaded such that these changes will take precedence in the CSS hierarchy over other styles in BD.

How do I know what I want to put in this file?
– Good question! Use Firebug (http://getfirebug.com/) with IE or Firefox to determine what styles are being applied to any given element. Once you know what style is causing an issue, you can override it via the custom style CSS file.

Handling Major Display Issues via Custom Templates

In some cases, the CSS either isn’t enough, or you may wish to have full, detailed control over how you display the elements of BD in your page.

You can accomplish these sorts of changes using Custom Templates. See these FAQs for more information:

WARNING: Custom template work is ONLY for programmers with advanced knowledge of HTML, PHP and the WordPress API. Making use of these instructions without knowing what you are doing can seriously break BD and your site. If you are not comfortable doing this yourself, consider hiring some help from a place like oDesk.
Business Directory is not responsible for any custom changes you make to the plugin nor can we support any custom changes you make.

Return to Table of Contents

How to Customize the Templates for Business Directory

See the section on Display Errors.

Return to Table of Contents

How to Export my Listings

BD supports a CSV exporter within the plugin under Directory Admin->CSV Export. This is the easiest way to get data out of the plugin (and is useful for bulk editing of listing data).

However, some cases may require you to pull the data in a different format, and we have this (older) FAQ about it:

Exporting BD Listings via SQL

We definitely recommend the CSV Export *first*.

Return to Table of Contents

How to Create Two Instances of Business Directory on the Same Site

How do I put 2 (business) directories on the same WP installation?

First, using WPMU isn’t a solution to this problem. Each logical site is a single WordPress instance, and Business Directory can only be installed on an instance of WordPress once. Business Directory is WPMU compatible, but you must install it as a “single site” plugin right now (network activation is not permitted)

So you can’t install Business Directory more than once per site. But you’d like more than one directory. What do you do?

The simplest solution is to use high level categories to create “two directories” within one master directory. Whether this works with your market or not depends very much on what you’re doing.

One solution you might try is a subdomain/regular domain, both with WP installed, both with distinct copies of the Business Directory plugin, and both sites configured with the same content, but the URLs make the user look like they are on the same site. For example:

http://site.com -> directs to “main WP install”
http://site.com/page1 -> directs to “main WP install”
http://site.com/directory -> directs to “main WP install”, “main Business Directory”
http://site.com/otherdirectory -> directs to “secondary WP install”, “secondary Business Directory”
OR http://subdomain.site.com/directory -> directs to “secondary WP install”, “secondary Business Directory”

This would require a bit of content duplication and some URL tweaks on both blogs so you make sure the users are on the correct site at any time (most of secondary WP site’s links would go back to main WP site, one link on main site would go to secondary site (otherdirectory))…but that’s probably the only way I know of, at this time…

Return to Table of Contents

How to Use Shortcodes to Display Business Directory Listings on Other Pages

As of BD 2.1, we have some new easier to type and remember shortcodes:

Previous Shortcode New Shortcode(s) Page Function
WPBUSDIRMANUI businessdirectory Main BD page
WPBUSDIRMANADDLISTING businessdirectory-submitlisting Add Listing
WPBUSDIRMANMANAGELISTING businessdirectory-managelistings Manage Listings
WPBUSDIRMANMVIEWLISTINGS businessdirectory-listings
OR
businessdirectory-viewlistings		 View Listings
As of 3.6.10, this now supports showing listings of a particular tag and allows you to set the title:
[ businessdirectory-listings tag=”mytag,othertag” title=”My list” ]
(removing the leading and trailing spaces of course!)
n/a (new to 3.4) businessdirectory-featuredlistings Show Only Featured Listings
n/a (new to 3.4.1) businessdirectory-search
businessdirectory_search		 Show the BD Advanced Search
wpbdp_regions_browser base_region=”USA” businessdirectory-regions-browser base_region=”USA” Show the Craigslist style Region browser, base_region is the parameter that indicates the region to show all sub-regions for. Use the name of the Region you want to show here.Requires Regions 3.4 or higher

New to shortcodes? Read this article here: https://www.smashingmagazine.com/2012/05/wordpress-shortcodes-complete-guide/

And here: https://codex.wordpress.org/Shortcode

As always, except for the main directory page, the rest of them are optional.

As of 2.1, WPBUSDIRMANMVIEWLISTINGS and businessdirectory-listing(s) can take an optional parameter, the category ID, as follows:

{WPBUSDIRMANMVIEWLISTINGS category=1}

Be sure to replace the {} with [] in your page.

As of 3.6.10, businessdirectory-listings now supports additional parameters to show listings of a particular tag with a title you want on the page. The code is of the form:
{businessdirectory-listings tag="mytag,othertag" title="My list"}

Be sure to replace the {} with [] in your page.

Return to Table of Contents

What Plugins and Themes are Compatible with Business Directory?

Business Directory tries very hard to work well with as many plugins and themes as possible. We adhere to all WordPress standards and API practices and keep up to date with any changes that come our way.

With that said, not all plugins and themes are quite as diligent or well-written and conflicts can occur.

Here is the updated list of known conflicts and incompatibilities with Business Directory.

It’s possible that others exist that are not yet documented. To determine if a problem exists, we recommend following the steps outlined in this article.

Please report any new conflicts you find in the support forum.

Recommended Themes

Any well-written, professional grade theme that is WP 3.0+ compatible should work well with Business Directory. In particular, we like WooThemes because of their support, choices and overall quality.

Return to Table of Contents

How can I make Business Directory SEO Friendly?

Business Directory is SEO friendly when you use it in combination with Yoast’s WordPress SEO Plugin. Yoast’s plugin is the only one that offers an API for us to integrate with and provide the correct hooks to add for our pages. No other plugin currently offers this documented API except Yoast, so that’s the one we recommend.

Here’s our article on recommended configuration tips with Yoast SEO.

Return to Table of Contents

How do I do recurring payments with Business Directory?

Business Directory now allows recurring payments as of 3.4. To enable recurring payments for listings (“Automatic Renewal”), go under Directory Admin->Manage Options in the WP Admin Dashboard. Under the Listings tab, select the following options:

  • “Allow recurring renewal payments?”: Turn this on if you want to allow your users to automatically renew their listings at the end of the payment term.
  • “Use recurring payments as the default payment method?”: Turn this on if you want users to automatically have this option instead of selecting recurring vs. one-time payments

Recurring payments are currently supported on the following gateways:

  • PayPay (as of 3.4)
  • Google Wallet (as of 3.4.1)
  • Stripe (coming soon)

Return to Table of Contents

How do I embed videos in my listings with Business Directory?

Business Directory has supported this since v. 2.0. You must follow the WordPress video embedding rules (these are not controlled by BD in any way):

In addition to this, you must turn on Allow Embedded Shortcode? in the field in which you want to place the video. You can find this option under Directory Admin->Manage Form Fields and clicking Edit on the field you want to have videos in.

Return to Table of Contents

How do I delete a large number of listings in Business Directory?

Business Directory has an admin interface to handle listing administration but sometimes, you need to delete everything (for re-import if you made a mistake) and start over. Here’s how you handle that with SQL queries.

NOTE: These instructions assume that you are familiar with SQL and database queries and a database admin tool such as phpMyAdmin. If you are not comfortable with this, you should consult someone who is or hire someone to help you if you don’t know of a SQL expert.

Removing BD-related content from the database

This guide is only for those who want to remove a big number of BD-created content from their databases without having to use the admin screens available on the backend.
Please backup your database before executing any of the SQL queries from this guide.

From this point forward we assume your WordPress tables are prefixed with wp_ which is the default setting. If not, adjust the queries accordingly.

Introduction

If you are trying to remove content (listings, categories, tags, fields, fees, etc.) created by BD from your database, the most secure way to do is to use the delete functionality that is available on the relevant admin screens.

BD takes care of removing all information from the database and also from the file system (images and file attachments).

In some cases you might want to remove data directly via a SQL query due to the volume of data to be deleted. The SQL queries below will help you with that.

Delete all listings and their associated metadata

DELETE a, b, c
FROM wp_posts a
LEFT JOIN wp_term_relationships b ON ( a.ID = b.object_id )
LEFT JOIN wp_postmeta c ON ( a.ID = c.post_id )
WHERE a.post_type = 'wpbdp_listing';

DELETE FROM wp_wpbdp_listing_fees;
DELETE FROM wp_wpbdp_payments;
DELETE FROM wp_wpbdp_payments_items;

Please keep in mind that these queries don’t remove images or attachments associated to listings, since those are not stored inside the database but in the file system.

Delete all listing categories and tags

DELETE a, b
FROM wp_term_taxonomy a
LEFT JOIN wp_terms b ON (a.term_id = b.term_id)
WHERE a.taxonomy IN ( 'wpbdp_tag', 'wpbdp_category' );

Delete all BD data (with the plugin installed)

If you intend to remove all BD data (listings, categories, tags, settings, etc.) and associated tables, you might want to run the uninstall procedure available via “Directory Admin – Uninstall”.

This makes sure your WP setup is as if BD was never installed.

Delete all BD data (after the plugin has been removed)

Uninstalling the plugin as explained above removes all BD tables from your database but if, for some reason, you removed the plugin without uninstalling it first, you might want to completely delete the content it created and its tables manually.

To do so, follow the steps below:

  1. Delete all content from the database. See Delete all listings and their associated metadata and Delete all listing categories and tags.
  2. Delete all BD settings by running this query:

    DELETE FROM wp_options WHERE option_name LIKE 'wpbdp%';
  3. Remove all tables prefixed wp_wpbdp from the database.

Return to Table of Contents

How do I configure WPML to work with Business Directory?

Business Directory Plugin supports WPML as of version 3.6.x. We fully integrate with WPML, but there are some guidelines to be aware of when using it.

Working with WPML in Business Directory

The Basics

Business Directory is prepared to work with WPML. You don’t need to enable or configure anything.
BD will try to honor your WPML settings and act accordingly. That being said, there are some things to consider when
using WPML to translate your directory:

  • Familiarize yourself with WPML. Read the Getting started guide available at WPML.org.
  • In order to translate your directory, the first thing you need to do is translate the page containing the main short
    code (i.e. the main directory page) to each one of the languages you intend to support. These translated pages
    should still contain the main short code ({businessdirectory}) but you can name them in the correct language.
  • Since listings are just custom posts and categories/regions/tags are custom taxonomies, you can use WPML to provide
    translations for all the content managed via Business Directory Plugin.

Translating form fields and fees

To translate form fields and fees you need to install the String Translation module from WPML.
Once the module has been installed and activated, you’ll find a menu item called String Translation under the WPML
menu, where it is possible to provide translations for field labels and descriptions as well as fee names and
descriptions.

You can filter by context “Business Directory Plugin” if you only want to see strings related to Business Directory.
For more information on how to use the String Translation Module please visit the Getting started guide at WPML.org.

Important: If, for some reason, you don’t see fields and/or fees strings on the String Translation screen, try
visiting the form fields screen (Directory Admin → Manage Form Fields) and/or the fees screen (Directory Admin → Manage Fees) and save any item after editing it. You don’t actually have to change anything. The save will trigger a string database update.

Translating taxonomies (regions, categories, tags)

  1. Read the Translating post categories and custom taxonomies guide from WPML.
  2. Navigate to the Custom taxonomies header inside the Translation Options screen. Check the “Translate” radio button besides each one of the taxonomies you want to be able to
    translate. They can be “Directory Categories”, “Directory Tags” or “Directory Regions” (if the Regions module is
    enabled).
  3. WPML offers several ways to translate taxonomy terms. You can do so while editing a term but we recommend the use of
    the Taxonomy Translation screen (WPML menu) since it enables you to translate terms in batches.

Important

  • Please keep in mind that once you decide to translate a taxonomy, untranslated terms will stop appearing
    on the front end when you browse a language-specific version of the directory. For instance, when you are browsing the
    Spanish version of the directory page, you’ll only see categories, tags and regions that have been translated to
    Spanish. Untranslated regions (and their listings) won’t be available.
  • (For Regions users) Since WPML translates terms by creating new entries in the database, translated Regions work
    independently from Regions in the original language. This results in the flags that control whether the region is
    enabled or displayed on the sidelist to now be language specific.
    Settings from the original regions won’t be automatically migrated.

    You can filter regions by language using a row of filters that appears on top of your regions on the Manage Regions
    screen:

  • (For Enhanced Categories users) Due to the way WPML works, category images are language-specific. When you translate a
    category, you can assign it a category image that is shown only for that language. If no image is assigned, the image
    from the default language won’t be used for the translated term.

Translating listings

To provide translations for your listings, follow the following steps:

  1. Read WPML documentation on Using the translation editor.
  2. Navigate to the Translation Options screen and enable “Directory” under Custom posts. Translation Options is
    accessible via the WPML menu on the backend.
  3. Use any of the mechanisms available via WPML to translate your listings. One way to do so is to click the Plus [+]
    icon besides any untranslated listing on the Directory screen:


    When you’ve enabled translation of listings, an additional row of filters will appear on top of your listings. You
    can use those filters to find untranslated content easily:

Important: If you chose to translate taxonomies (see above) you will only be able to
assign already translated categories or regions to your translated listings. If you translated taxonomies, you can’t mix
listings in a language with categories or regions in a different one, regardless of the original language.
This also applies to the front end. Untranslated listings won’t appear inside translated categories or regions.

Return to Table of Contents