SELECT t.name 'Category', p.post_title 'Company', GROUP_CONCAT(pm.meta_value) 'Contact', p.post_content 'Description'
FROM wp_terms t, wp_term_taxonomy tx, wp_posts p, wp_postmeta pm, wp_term_relationships tr
WHERE pm.post_id = p.ID AND
tr.object_id = p.id AND
p.post_type = 'wpbdp_listing' AND
pm.meta_key in ('_wpbdp[fields][6]','_wpbdp[fields][8]','_wpbdp[fields][10]','_wpbdp[fields][11]','_wpbdp[fields][12]') AND
tr.term_taxonomy_id = tx.term_taxonomy_id AND
tx.term_id = t.term_id
GROUP BY pm.post_id order by t.name, pm.meta_key

Explanation:
Line 1: pm.meta_value represents the fields that are in the form used for entering the directory date, e.g., address, city, state, etc.
the GROUP_CONCAT command strings together the data from individual rows into a string separated by a comma.
Line 2: These are the tables that hold the data to be extracted
Line 3-8: These are the columns used to link the tables together and also contain the data to be extracted. Note that the meta_key field contents may differ in your case; the above are the values that correspond to the address, city, state, zip, etc. in my database.
Line 9: This command groups the extracted data by post_id and sorts the output by category and meta_key (address, city, state, etc.)

Using general hooks custom processes can be included within Business Directory normal execution. Using template hooks extra HTML or output can be displayed on certain specific pages. When you make changes using hooks, they will not be overwritten with plugin updates.

How to use hooks?

Since our hooks are just regular WordPress actions, you can learn more in the WordPress Plugin API and with the add_action() function in particular.

To create a new plugin, follow these steps:

1. Install Pluginception from the WP.org repository. Go to Plugins → Add New. Enter Pluginception in the search field, hit Enter. A plugin written by Otto should appear.
2. Install and activate this plugin
3. From the WP Admin area, go to the Plugins menu and click on Create New Plugin. We're going to create a plugin with a PHP file that you can put in the custom code. This way, your changes will never be lost.
4. After that, you'll be on a screen with a lot of fields. You only need to fill out the FIRST one:

   Give the plugin a name like “Business Directory Plugin – Customizations”, like this:

   

   Then save your file at the bottom.

5. You should be redirected to the Plugin Editor where you can edit the code of the plugin.

   If you are not redirected, from the Plugins menu again, click Plugin Editor. Then, on the right hand side of the screen, find “Business Directory Plugin – Customizations”. This should open a BLANK PHP file.

   

6. On the editor, paste your code at the bottom of the file (before any ?> closing tags.)
   Save the PHP file by clicking Update File.

Examples

See Code Examples

General Actions

Template Actions

wpbdp_get_form_fields( $args )

This function can be used to obtain form fields from the database based on several criteria. The returned objects are instances of WPBDP_FormField.

Parameters

• $args: (optional) Array or querystring of arguments used to query fields from the database. The valid options here are:
  • association: Field association. Valid choices are “title”, “category”, “tags” and “meta”.
  • validators: Field validators. Prepending “-“ to the validator name excludes fields with that validator.
  • display_flags: Field display flags. Prepending “-“ to the display flag excludes fields with that display flag set.
  • unique: If TRUE only the first field will be returned.

Return

An array of WPBDP_FormField instances or just one object if the argument unique is set to TRUE.
Fields are ordered by their position (weight) inside the table. See WPBDP_FormField for more details.

Examples

Retrieve all fields (regardless of their nature) and print their label:

<?php
	$fields = wpbdp_get_form_fields();
	
	foreach ( $fields as $field ) {
		print $field->get_label();
	}
?>

Retrieve the one field with “title” association:

<?php
	$title_field = wpbdp_get_form_fields('association=title&unique=1');
?>

Retrieve all required fields that don’t appear in the search form:

<?php
	$args = array( 'validators' => 'required', 'display_flags' => '-search' );
	$fields = wpbdp_get_form_fields( $args );
?>

wpbdp_get_form_field( $id )

This function obtains a field by its ID. For more complex field-related queries, use wpbdp_get_form_fields.

Parameters

• $id: the field ID

Return

A WPBDP_FormField instance if the field is found or NULL if not.

Class Reference: WPBDP_FormField

Properties

Most of the WPBDP_FormField properties are private and should not be accessed directly. Use the getters & setters for this.

Business Directory themes are a way to easily change the look and feel of the whole directory.

Previously, only template overrides could be used to modify some (very limited) aspects of the directory. Overrides can still be used but they now depend on the templates provided by the Business Directory theme in use.

For more details about themes, please refer to our usage guide.

Why create your own theme?

There are several reasons you might want to create your own theme instead of using template overrides. Some of the benefits of creating a theme are:

• Create a custom look and feel for your directory that can be easily packaged and deployed.
• Template overrides are installed inside the WordPress theme directory and, as such, they could be removed by a theme update. Business Directory themes, on the other hand, live in a different location and are not tied to the WordPress theme in any way. Your customizations won’t be removed by an update.
• While template overrides are only PHP files, themes can also include Javascript and CSS assets.
• Themes, unlike template overrides, can modify the behavior of a Directory view in a more profound way, thanks to their ability to define template blocks and template variables.

Specification details

Themes folder

Business Directory themes (except those bundled with the plugin) are stored inside wp-content/businessdirectory-themes. The folder should be automatically created when you install a new theme, but if you’re developing your own theme you can manually create it and give it 0755 permissions.

Any subfolder of this special directory following the directory structure below is considered a Business Directory theme and will be displayed on the backend so it can be activated, etc.

Theme directory structure

A theme, when unpackaged, looks something like this:

mytheme/
mytheme/theme.json
mytheme/theme.php
mytheme/thumbnail.png
mytheme/assets/
mytheme/assets/styles.css
mytheme/templates/
mytheme/templates/single.tpl.php
mytheme/templates/excerpt.tpl.php
mytheme/templates/field_social-twitter.tpl.php

Most of the files and directories are optional, but a theme won’t be recognized by Business Directory as such if it doesn’t have a theme.json file.

The table below provides a general overview of the files and directories that can be included in a Business Directory themes, while the following sections go into each topic in greater depth.

Important: The top folder (in the example above mytheme) would be the internal ID used by Business Directory to differentiate your theme. Please try to use names that don’t involve strange characters. Limit yourself to alphanumeric characters and dashes (-, _).

theme.json manifest file

The theme.json file specifies the details about the theme as a JSON dictionary (key and value pairs).
An example theme.json file might look like this:

{
    "name": "My Directory Theme",
    "description": "This is my awesome theme!",
    "version": "1.0",
    "author": "John Doe",
    "author_email": "jdoe@email.com",
    "author_url": "http://jdoe.com",
    "requires": "4.0",
    "assets": {
        "css": [ "styles.css", "vendor/font-awesome.min.css" ],
        "js": [ "javascript.js" ]
    }    
}

Important: We parse the theme.json manifest file for themes using the JSON parser available in PHP. This parser is very picky about the JSON it receives, so your manifest file must be correct JSON for your theme to be considered as such.

Manifest file keys

name

Required. This is the name that is publicly displayed for your theme. It’s different from the theme ID (the top folder containing your theme files).

description

Optional. The description for your theme. It is displayed on the backend when users place the cursor over the theme.

version

Required. The current version of the theme. It is used internally by Business Directory Plugin to determine if a theme requires an update or not.

Use only numeric values (for example “1.0”, “3.5”, etc.). Do not use alphanumeric values such as “1.0beta3”.

author

Required. The theme author’s name.

author_email

Required. The theme author’s e-mail address.

author_url

Optional. The theme author’s website.

requires

Optional. Minimum version of Business Directory Plugin that is required for the theme to work correctly.

Since Business Directory Plugin templates can change over time or the theme API enriched you might want to require at least the version that includes the functionality you’re using on your theme to prevent users from older versions from installing your theme and possibly breaking their sites.

Example

This theme would work only in Business Directory Plugin > 4.0.5.

{
...
	"requires": "4.0.5" 
...
}

assets

Optional. The CSS and Javascript files included with your theme and that you want Business Directory Plugin to automatically add to every directory page, when your theme is loaded.

The resources should be available inside the assets/ subfolder of your theme and will be loaded in the order defined in this key and after the core resources are loaded. This means themes styles take precedence over Business Directory Plugin default styles.

The value for this key must be a dictionary of two (both optional) key – list pairs named css and js, in this format:

{
...
	"assets": {
		"css": [],
		"js": []
	}
...
}

Important: Themes resources are only loaded inside Business Directory Plugin pages. This is relevant if you intend themes to affect the general layout of a WordPress site because that wouldn’t be possible.

Example

This theme includes files assets/reset.css and assets/styles.css, as well as a javascript file assets/vendor/cooltabs.js:

{
...
	"assets": {
		"css": ["reset.css", "styles.css"],
		"js": ["vendor/cooltabs.js"]
	}
...
}

suggested_fields

Business Directory Plugin is capable of recognizing some fields as having a special meaning. This is called “theme tags”, and it is explained in the themes usage guide.

If your theme has a special location for one or several of these special fields, you can add their tag names as a list for the suggested_fields key. When your theme is activated, Business Directory Plugin will prompt users to create or tag their fields so those fields in the suggested_fields list are available.

The following is the list of the current theme tags permitted:

• phone
• fax
• email
• address
• city
• state
• zip
• twitter
• website

Example

If your theme displays the phone number and address of a listing prominently, you might want to suggest users to define a field for phone numbers and for addresses. You can tell Business Directory Plugin that your theme intends to use those fields using the suggested_fields option like this:

{
...
	"suggested_fields": ["phone", "address"]
...
}

template_variables

As explained in the customization guide, template variables are special variables that are defined by Business Directory Plugin or modules and made available to certain template files.

The template_variables manifest key allows themes to indicate which variables they want to “capture” to (maybe) display in a different place than the default.

For example, for the “single” template (displaying the single/full view of a listing), the “googlemaps” template variable is available and it contains the HTML code to display the Google map for the listing. By default, the Google Maps plugin adds this variable to the after block of the template (meaning it is displayed after the main listing details), but if your theme wants to display the map in a different location (say, a sidebar), it must indicate Business Directory Plugin that it wants to capture this variable (preventing the variable from appearing at the default location) and can just output the value at the correct place.

The list of template variables and the template to which they apply is available in the customization guide.

Example

In the single view of a listing, this theme wants to display the “googlemaps” variable in a sidebar instead of its default location (after the listing details).

The theme.json manifest file should include something like this:

{
...
	"template_variables": {
		"single": ["googlemaps"]
	}
...
}

While the templates/single.tpl.php file would look like this:

<div id="listing-details">
...
</div>
<div id="listing-sidebar">
<?php echo $googlemaps; ?>
</div>

theme.php PHP file

This file can be used to provide custom initialization routines and hook into WordPress or Business Directory Plugin filters or actions.

Inside this file, you can use the full power of the WordPress or Business Directory Plugin API.

At certain points during the execution of the page, Business Directory calls functions from this file (if the function is available). Currently, two hooks are available:

• init: Called after the Themes subsystem has been initialized.
• enqueue_scripts: Called when enqueueing resources for the current page.

Business Directory Plugin will look for functions in the theme.php using the following naming convention:

wpbdp_themes__<theme id>_<hook>

and

<theme id>_<hook>.

Example 1

To enqueue the jquery-ui-tabs Javascript script you can use the enqueue_scripts hook. If your theme folder is mytheme/ then mytheme/theme.php could include the following callback:

<?php
function wpbdp_themes__mytheme_enqueue_scripts() {
	wp_enqueue_script( 'jquery-ui-tabs' );
}

Example 2

You can use the init hook to register regular WordPress filters or actions. The following code disables comments on all posts (if the theme is active).

<?php
function wpbdp_themes__mytheme_init() {
	add_filter( 'comments_open', '_mytheme_close_comments' );
}

function _mytheme_close_comments( $open, $post_id ) {
	return false;
}

Theme templates

Templates are just regular PHP files ending in .tpl.php that are loaded by Business Directory Plugin at certain points to display things like a list of listings, the excerpt view of a listing or the search form. All templates must be stored inside the templates/ subfolder.

For better organization, themes can also define their own template files and include them from other templates. You’re not limited to just overriding templates from the core plugin.

Themes, unlike template overrides from previous Business Directory Plugin versions, have the ability to change the look and feel or behavior of almost any part of the plugin. The customization guide discusses template files in greater detail. There you’ll find information about template files and variables as well as the full template hierarchy.

Important: Themes don’t necessarily have to include templates to be considered themes. If you don’t want to change the behavior provided by core templates, but just want to add your CSS styles or own Javascript on top of that, you can create a theme with only asset files.

Template loading order

When Business Directory Plugin requests a template to be displayed, it looks for the template in several paths. If several valid files exist, the first one available is used.
The paths, by default, are:

1. <active WordPress theme>/business-directory/ (WP theme’s folder)
2. <parent of active WordPress theme>/business-directory/ (WP parent theme’s folder, if used)
3. <active theme>/templates/ (Business Directory theme’s folder)
4. business-directory-plugin/templates/ (Business Directory templates folder, to be deprecated soon)
5. business-directory-plugin/core/templates/ (Business Directory templates folder)

You’ll notice that Business Directory themes are not the first path searched. This allows final users to override only parts of a Business Directory theme if they provide the matching template in a special directory inside the current WordPress theme.

Important: When overriding a core template in your theme, please refer to the original file and notice any hooks or actions that might be fired, as well as special CSS classes added to elements. You’re free to design the template in any way but try to preserve hooks and CSS classes to avoid breaking integration with modules or special behavior added via Javascript to certain Business Directory Plugin screens.

Example

excerpt_content.tpl.php is the template name for the file that displays the actual content of the excerpt view of a listing. Assuming mytheme/ is you current Business Directory theme and twentyfifteen/ your WordPress theme, the final file used is the first one that exists from the following list:

wp-content/themes/twentyfifteen/business-directory/excerpt_content.tpl.php
wp-content/businessdirectory-themes/mytheme/templates/excerpt_content.tpl.php
wp-content/plugins/business-directory-plugin/templates/excerpt_content.tpl.php
wp-content/plugins/business-directory-plugin/core/templates/excerpt_content.tpl.php

Some examples

Example: Show the Facebook field as a link with an icon instead of a Like button

# mytheme/templates/field_social-facebook.tpl.php
<a href="<?php echo $raw; ?>" target="_blank"><img src="<?php echo $THEME_URL; ?>/assets/facebook-icon.png" /></a>

Example: One tab for listing details and other for the contact form (single view)

# mytheme/theme.json
{
...
	"template_variables": {
		"single": ["contact_form"]
	}
...
}

# mytheme/templates/single.tpl.php
<div id="tabs-navigation">
	<ul>
		<li><a href="#details">Listing Details</a></li>
		<li><a href="#contact_form">Contact Form</a></li>
	</ul>
</div>

<div id="tabs">
	<div id="details">
		<?php echo $fields->html; ?>
	</div>
	<div id="contact_form">
		<?php echo $contact_form; ?>
	</div>
</div>

Distributing themes

While developing a theme, you’re probably working directly inside wp-content/businessdirectory-themes/. Even though you can just copy the folder from site to site and it will be picked up by Business Directory Plugin as a valid theme, there’s a better way to package and distribute your new theme.

How to package a theme?

Business Directory themes are just packaged as regular ZIP files. You can create the ZIP file using any tool you have available to compress the folder where you have all your theme files.

Creating a theme package allows users to install your Business Directory theme using our admin interface instead of having to uncompress and then copy the resulting directory using SSH or FTP.

Example: Creating a package for “mytheme”

Let’s assume your theme is mytheme/ and you’re seating in the wp-content/businessdirectory-themes. On macOS and Linux systems you can create the theme package with the following command:

$ zip -r mytheme.zip mytheme/

To verify that the output is correct, you can use unzip -l. It should look something like the following:

$ unzip -l business-card.zip
Archive:  business-card.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
        0  07-16-16 09:45   business-card/
        0  07-16-16 09:23   business-card/assets/
     1075  06-25-16 15:15   business-card/assets/business-card.js
      814  10-07-15 16:53   business-card/assets/social-facebook.png
      904  10-07-15 16:53   business-card/assets/social-linked-in.png
      833  10-07-15 16:53   business-card/assets/social-twitter.png
     2363  06-25-16 15:15   business-card/assets/styles.css
        0  07-02-16 07:39   business-card/templates/
     2043  07-02-16 07:39   business-card/templates/excerpt_content.tpl.php
      160  10-07-15 18:14   business-card/templates/field_social-facebook.tpl.php
      183  10-07-15 17:56   business-card/templates/field_social-twitter.tpl.php
     1811  06-25-16 15:15   business-card/templates/single.tpl.php
      838  07-02-16 07:39   business-card/templates/single_content.tpl.php
      611  07-02-16 07:39   business-card/theme.json
   381857  07-02-16 07:39   business-card/thumbnail.png
...

Recommendations

• Only one theme.json file can be created per theme package.
• When uncompressing the theme package, the folder containing the theme.json file is considered the actual theme and it is the folder copied to its final location in wp-content/businessdirectory-themes/. If the theme.json file is located at the root of the ZIP file, then the ZIP filename is used as the folder name.

• Because of the above, we recommend you don’t compress the contents of your theme folder directly, but instead compress the folder itself.

  This is important: assuming your theme is mytheme/ and the package mytheme.zip, if you compress the contents of mytheme/ directly, then renaming mytheme.zip to notmytheme.zip would result in the theme being installed in wp-content/businessdirectory-themes/notmytheme/ instead of wp-content/businessdirectory-themes/mytheme/. Since the folder name is considered the theme ID, this might result in your callbacks in theme.php not working correctly.

  If you, on the other hand, compress mytheme/ itself to create the ZIP package, even if someone renames mytheme.zip to notmytheme.zip, once uncompressed, the theme.json file will be inside mytheme/, not at the root folder, so the theme will be installed as wp-content/businessdirectory-themes/mytheme/, as expected.

A complete example

Any theme bundled with Business Directory Plugin can serve as an example.

Once installed, Business Directory themes that are available for purchase are also useful to review because they have a lot more detail than the default themes.

CSS

If you only want to adjust some CSS styles for the directory, the best way to do it is with what we call a “custom CSS file”.

You just have to add a CSS file with your customizations to a special location in your WordPress setup and Business Directory Plugin will pick up this file and load it on Directory pages right after all of the core CSS files, so the styles in it take precedence over the default ones.

The file must be named wpbdp.css and you can store it in any of the following locations:

wp-content/plugins/
wp-content/themes/<your active WP theme>/
wp-content/themes/<your active WP theme>/css/

Adjusting the CSS files provided in the Business Directory Plugin is not recommended because the changes will be lost after a plugin update.

Directory Themes

Directory Themes are packaged templates that can be used to change the look and feel of your directory quickly and easily.

There are a number of themes available for purchase here, but you can also create your own themes. Consult the Directory Themes specification to get the details.

Template overrides

Template overrides are a way to modify the behavior of a particular template file. In essence, themes are just a package of templates that override some of the core templates, and what we call “template overrides” here are overrides for theme or core templates.

Core templates are usually located in business-directory-plugin/templates but template overrides should be stored inside your active WordPress theme directory, under the business-directory/ subfolder.
The nice thing about template overrides is that they work for templates provided by modules and Business Directory themes, allowing for maximum flexibility.

Most of the core templates and the PHP variables they receive are documented in the Core templates and variables section below. This information also applies to template overrides, of course.

Read section How to implement a template override? below for more information about template overrides.

Templates in detail

What is a template?

Templates are just regular PHP files ending in .tpl.php that are loaded by Business Directory Plugin at certain points to display things like a list of listings, the excerpt view of a listing or the search form. Modules also make use of templates.

Since they are just PHP files, templates receive a set of PHP variables that can be used to generate the desired output. For example, the “listing excerpt” template receives a lot of information (a WPBDP_Listing object, the fields and values for the listing, whether the listing is featured or not, images, etc.) while the “search form” template just receives the fields to be printed.

Details about each template and the PHP variables available to them, can be found below in the Core templates and variables section.

Template path resolution

When Business Directory Plugin needs to display a template, it looks for the template in several paths. If multiple valid files exist, the last one is used.
The paths, by default, are:

1. business-directory-plugin/templates/ (inside WP plugins folder wp-content/plugins/)
2. <active theme>/templates/ (inside Business Directory themes folder wp-content/businessdirectory-themes/ or wp-content/plugins/business-directory-plugin/themes/ when using the default or “Pre-4.0” themes)
3. <active WordPress theme>/business-directory/ (inside WP themes folder wp-content/themes/)

You’ll notice that Business Directory themes are not actually the last path searched. This allows users to override templates.

Important: When overriding a core template in your theme, please refer to the original file and notice any hooks or actions that might be fired, as well as special CSS classes added to elements. You’re free to design the template in any way but try to preserve hooks and CSS classes to avoid breaking integration with modules or special behavior added via Javascript to certain Business Directory Plugin screens.

Business Directory templates are not WP templates

It is important to keep in mind that Business Directory templates are not WordPress templates. Even if some template names are similar to those used by WordPress, you can’t use these templates interchangeably.

For instance, there’s a single.tpl.php for listings, but it only affects Business Directory listings and doesn’t control the output for the whole page, but just the part that belongs to a listing. This is different than, say, the single.php template from WordPress.

Important: Do not call get_header() or get_footer() inside templates for Business Directory Plugin. This might break your layout. Our templates are designed to control just a small part of the whole page-rendering process, usually “the content”, so the rest of the HTML must be added by the WP theme, not our templates.

How to implement a template override?

1. Locate the template you want to override. It can be a template from the core plugin (business-directory-plugin/templates), from a module or a Business Directory theme (theme templates are under wp-content/businessdirectory-themes/[active theme]/templates/ except if you’re using the default or “Pre-4.0” themes, in which case the path is business-directoryplugin/themes/[active theme]/templates/).
2. Copy the template to your active WordPress theme directory under the business-directory subfolder. You might need to create this folder. The final file should be located at wp-content/themes/[active WP theme]/business-directory/[template name].tpl.php.
3. Use the copied version of the template to have a grasp of how the Business Directory functionality works inside the template.
4. Use your theme’s file and the BD default’s to build your own definitive template. Read the subsection in Core templates and variables that applies to the template you’re overriding. This gives you information about the PHP variables and methods that are available inside the template.
5. Test your changes. If you have a lot of trouble, remember that you can just remove the file from your theme folder or copy the Business Directory Plugin original template verbatim and start over again.

Example

Let’s assume that you want to change how the “single” listing view looks like. As per the documentation below, you’ll find that the template is called single.tpl.php and it is located in business-directory-plugin/templates/single.tpl.php.
Assuming your current WordPress theme is “Twenty Fifteen”, you should copy this file to wp-content/themes/twentyfifteen/business-directory/single.tpl.php and make your changes here.

Important: Some Business Directory themes might implement additional templates not available in core or modules themselves. These templates can also be overridden.

Override for a theme template

The Restaurant theme breaks up the single.tpl.php in several subtemplates, including restaurant_sidebar.tpl.php which implements a sidebar. If you just want to modify the sidebar instead of the whole single.tpl.php template, you can override just the sidebar (restaurant_sidebar.tpl.php). The override would only work when the “Restaurant” theme is enabled.

Template blocks

The new templates system introduced in Business Directory 4.0, adds the concept of template block to templates.

A block is a section of a template where the output from several sources (from the core plugin or Modules) is put together and then displayed.
The content for a template block comes from its associated block variables.

Two blocks are made available to all templates: the “before” and “after” block. As their names suggest, the “before” block contains output that is included before the template and the “after” block contains output that is to be included after the template has been rendered.

Example: Listing contact form

In a single listing view the listing contact form (when enabled) is always displayed after the listing details, but if you take a look at the actual template single.tpl.php you’ll see that there’s no code associated to the contact form.

This is not an error. This is because the contact form is registered by Business Directory Plugin as a block variable associated to the “after” block, so it gets automatically added without the templating even noticing it.

Unsurprisingly, when a template is rendered the final output looks like this:

(content of the "before" block)
(actual template output)
(content of the "after" block)

This is a great system that allows plugins to add output to templates without themes or overrides having to deal with the new variables. If we didn’t have this system in place, you would need to take into account all output from modules (such as the Claim Listings form, ratings and reviews, contact form, comments, attachments, etc.) and add them manually to your templates.

Block variables

Block variables are just special content (output) variables that are added by Business Directory Plugin or Modules and associated to a template block.

Example

The Listing Contact Form is, in reality, a block variable named contact_form that is associated to the after block of the single.tpl.php template.

Example

The Google Map that is added to listings is, in reality, a block variable named googlemaps that is associated to the after block of both the single.tpl.php and excerpt.tpl.php templates.

Block and block variable customization

Even though the template blocks system allows plugins to add output to Business Directory Plugin without theme developers or users having to worry about adding the new output or code to their templates, in some cases you want a little bit more control.

For instance, what if you want to display the “after” block in a sidebar instead of right after the template? What if you want to change where the contact form appears, or the ratings and reviews from the Ratings module are shown?

The key here is to add special Template Blocks or Template Variables File Headers at the beginning of your override or theme template.

<?php
/**
 * Template Blocks: before
 * Template Variables: contact_form
 */
?>
...

Those special headers are your way to tell Business Directory Plugin that you want to do some things “manually” inside your template.
The are both optional and they work like this:

• Template Blocks is a list of blocks separated by comma, that you want to handle yourself in your template, instead of getting the “before” or “after” blocks automatically inserted before/after the output from your template. When a block is marked as to be handled manually, a $blocks array is made available to your template, with before or after as keys and the block’s HTML as value.
• Template Variables is a list of the block variables that you want to handle in your template by yourself. That means their output won’t be automatically inserted into their associated block and, instead, a PHP variable will be made available to your template so you can put it wherever you want.

Example. Handling the “after” block

Let’s assume templatefile.tpl.php is a template in which you want to display the “after” block in a particular place.

Your template override may look like this:

<?php
/**
 * Template Blocks: after
 */
?>
rest of the template...
<div id="after-block">
	<?php echo $blocks['after']; ?>
</div>

Example. Display the contact form and the Google map

These variables appear to the single.tpl.php template (single listing view), as per the Core templates and variables section below.

So, your single.tpl.php might look something like this:

<?php
/**
 * Template Variables: contact_form, googlemaps
 */
?>
<div id="my-listing-single-view">
	<!-- Main single view content (fields, etc.) -->
	<?php wpbdp_x_part( 'single_content' ); ?>

	<div id="my-listing-google-map"><?php echo $googlemaps; ?></div>
	<div id="my-listing-contact-form"><?php echo $contact_form; ?></div>
</div>

In this particular example, the “before” and “after” blocks will still be inserted at their respective locations (before and after your template above), but thanks to the Template Variables file header, those blocks will be missing both the Google Maps and the contact form, and instead, they will appear on the locations specified in your template.

Supported template variables

API

Most of the theming (and template subsystem) operates in a way that is invisible to you. The functions below, however, might be of interest when working with template overrides.

• wpbdp_x_render( $template, $vars ). This function renders the template named $template and passes the $vars array as context.
  • The final template file name is resolved as explained in Template path resolution.
  • The $vars array is unpacked before rendering the template. This means that any keys and values defined in the array are converted to regular PHP variables inside the template. For instance, if the context is array( 'myvar' => 'myvalue', ...), you can use $myvar directly inside the template.
• wpbdp_x_part( $template ). Similar to wpbdp_x_render() but doesn’t define a particular context. When $template gets loaded the context from the current template is shared. That means if you call this function from a template, the variables already available to that template are made available to the one you’re loading.
• wpbdp_render_listing( $id, $display ). Renders the single or excerpt view of a listing.

Core templates and variables reference

page.tpl.php

This is a wrapper for most of the content rendered by Business Directory Plugin. The main view is always wrapped in this template, even if its content is rendered by other templates.

Variables

• $show_bar: boolean. True if the top bar (with the buttons) should be shown.
• $content: string. The content that is being wrapped.

Example

<<span>div<span> class="a-directory-page">
<<span>?php</span> echo $content; ?>
<<span>/div></span>

bar.tpl.php

Renders the bar that appears on top of some pages, showing the main directory buttons and the quick search form.
This templates doesn’t receive any PHP variables as context but makes use of the wpbdp_the_main_links() and wpbdp_the_search_form() functions.

category.tpl.php, tag.tpl.php

Renders a category or tag view.

Variables

• $title: string. Title for the page (usually the category/tag name).
• $category: object. Details for the category/tag that is being viewed, in a similar format as WP function get_term().
  • term_id: int.
  • name: string. Category/tag name.
  • slug: string. Slug.
  • description: string. Category/tag description.
  • parent: int. Parent category/tag ID
  • count: int. Number of posts inside the category.
  • is_tag: boolean. True for Directory Tags and False for Directory Categories.
• $query: WP_Query. The query object for the view. You can iterate over this WP_Query object but it is recommended that instead you render the listings.tpl.php template passing the object as argument:

    <?php
    echo wpbdp_x_render( 'listings', array( 'query' => $query ) );
  

Example

<div class="my-category-page">
    <h1><?php echo $category->name; ?></h1>
    <p><?php echo $category->description; ?></p>

    <div class="category-listings">
        <?php echo wpbdp_x_render( 'listings', array( 'query' => $query ) ); ?>
    </div>
</div>

listings.tpl.php

Renders a list of listings (used by category/tag views, “View Listings” and other views).

You can use regular WP functions available “in the loop” such as get_the_title() while looping over $query.

Variables

• $query: WP_Query object. This object contains the query for the set of listings that you need to display.
  Though you can use this object to iterate over the listings and render details about them, we recommend you actually
  render the listings using [wpbdp_render_listing()][?#wpbdp_render_listing]. You can customize the output from this
  function using the single.tpl.php or excerpt.tpl.php templates.

Example

<ol class="a-set-of-listings">
    <?php if ( $query->have_posts() ):
        while( $query->have_posts() ): $query->the_post();
            // We call wpbdp_render_listing() here...
            echo wpbdp_render_listing( null, 'excerpt' );

            // ... but we could've just started using the listing directly as in a regular WP loop.
            // echo get_the_title();
            
        endwhile;
    else: ?>
        <li class="nothing-found">No listings found.</li>
    <?php endif; ?>
</ol>

main_page.tpl.php

Renders the main page of the Directory.

search.tpl.php

Renders the search page.

Variables

• $searching: boolean. True if a search has been performed.
• $results: string. If results are available, this template has the HTML output for the list of results, built using listings.tpl.php.
• $search_form: string. HTML for the advanced search form.

excerpt.tpl.php, excerpt_content.tpl.php, single.tpl.php, single_content.tpl.php

These templates are used when rendering the excerpt or single view of a listing.

excerpt.tpl.php and single.tpl.php are usually just “wrappers” for excerpt_content.tpl.php and
single_content.tpl.php respectively.

The logic here is that the wrappers add some basic CSS IDs and classes that are to be always present for integration with Modules, etc. while the _content.tpl.php templates render the actual content for the views.
This is entirely optional, of course, and you can override excerpt.tpl.php or single.tpl.php directly if that’s what you want, but we recommend you override the _content.tpl.php variants.

Since these views (single and excerpt) are crucial to the directory, all of these templates have a lot of variables available to them as well as complex objects that provide everything that’s needed for displaying listing form fields, images, etc.

Variables

• $listing_id: int. The listing ID.
• $listing: object. An instance of WPBDP_Listing providing easy access to properties and functionality related to this listing.
• $is_sticky: boolean. True if the listing is featured.
• $title: title. Title for the page. Usually the listing’s title.
• $sticky_tag: string. HTML output for the “Featured” badge. See listing-sticky-tag.tpl.php.
• $fields: object. Instance of WPBDP_Field_Display_List providing easy access to the field values (among other things) for this particular listing. You can do a lot of things with this object, but most of the time you just want to call echo $fields->html; to output the list of fields applying to the listing.Additionally, the $fields object includes dynamic properties that can be used to get access to specific form fields:
  • Use $fields->id[number] to access the representation of the field whose id is equal to [number].
  • Use $fields->[shortname] to access the representation of the field whose shortname is equal to [shortname].
  • Use $fields->t_[tag] to access the representation of the field associated with the theme tag [tag].Notes:
    • Field ID and Shortname are listed along with Field name in Form Fields Table.
    • Field Tag can be assigned clicking “Manage Theme Tags” button in Form Fields Table or Directory Themes.

      The representation of a field is also an object, with the following properties:

  • id: int. The field’s ID.
  • label: string. The field’s label.
  • value: string. HTML representation of the value of this field.
  • raw: The value, as stored in the database.
  • html: string. HTML representation of the field.
• $images: object. An object providing easy access to the listing images.
  • The $images object itself has properties main and thumbnail for the main listing image (for single views) or the thumbnail (for excerpt views); and extra, an array providing access to additional images available for the listing.
  • Each image is itself an object with the following properties:
    • id: int. The image ID.
    • html: string. HTML (link and img tags) to render this image.
    • url: string. URL to the full version of the image.
    • width: int. Image width.
    • height: int. Image height.

Example 1

<div class="my-listing">
    <h1><?php echo $title; ?></h1>

    <div class="listing-thumbnail"><?php echo $images->thumbnail->html; ?></div>
    <div class="listing-fields">
        <?php foreach ( $fields as $field ):
            // This produces the same output as $fields->html;
            echo $field->html;
        endforeach; ?>
    </div>

Example 2

[...]
<div class="my-listing">
    <h1><?php echo $title; ?></h1>

    <div class="listing-thumbnail"><?php echo $images->thumbnail->html; ?></div>
    <div class="listing-field-2">
        <!-- This echoes the html value for the representation of the field whose id is equal to 2 -->
        <?php echo $fields->id2->html; ?>
    </div>
[...]

Example 3

[...]
<div class="my-listing">
    <h1><?php echo $title; ?></h1>

    <div class="listing-thumbnail"><?php echo $images->thumbnail->html; ?></div>
    <div class="listing-field-business_genre">
        <!-- This echoes the html value for the representation of the field whose shortname is business_genre (category) -->
        <?php echo $fields->business_genre->html; ?>
    </div>
[...]

One of the most common things you might want to do in a template is detect whether listings are paid or not. Here are some examples of how to do that:

Basic Detection

[...]
<?php
$listing = wpbdp_get_listing( $listing_id );
$plan    = null;

if ( $listing ) {
    $plan = $listing->get_fee_plan();
}

if ( $plan && 0 < $plan->fee_price ) {
    // Include logic for paid plans here.
}
?>
[...]

For a specific plan

[...]
$listing = wpbdp_get_listing( $listing_id );
$plan    = null;

if( $listing ) {
    $plan = $listing->get_fee_plan();
}

if( $plan && 9 === $plan->fee_id ) {
    // Include logic for plan whose id equals 9 here.
}
[...]

Search within a group of plans

[...]
$listing = wpbdp_get_listing( $listing_id );
$plan    = null;

if( $listing ) {
    $plan = $listing->get_fee_plan();
}

if( $plan && in_array( $plan->fee_id, array( 1, 4, 9 ) ) ) {
    // Include logic for plans with fee_id 1, 4 or 9 here.
}
[...]

listing-sticky-tag.tpl.php

Used for rendering the “featured” badge that appears on listings.

field-{field ID}.tpl.php, field-type-{field type}.tpl.php

Core doesn’t make use of this template, but some themes do. When available, these templates control the output for a
form field.

These templates add a lot of flexibility to the field rendering process. You can override the output for a particular
field or a whole field type.

For example, to change how the field with ID 4 is rendered, you can use field-4.tpl.php, but if you want to change how
all URL fields are rendered, you can use field-type-url.tpl.php.

Variables

• $field: WPBDP_Form_Field object. The field object as described in the Form Fields API document.
• $context: string. The display context. It can be either “listing” (for single view) or “excerpt”.
• $listing_id: int. The ID of the listing requesting the display of one of its form fields.
• $raw: mixed. The “raw” value for listing’s field value. Refer to the Form Fields API for details.
• $value: string. The HTML output for the field, not including labels or wrapping elements.

Example: Show the Facebook field as a link with an icon instead of a Like button

# mytheme/templates/field_social-facebook.tpl.php
<a href="<?php echo $raw; ?>" target="_blank"><img src="<?php echo $THEME_URL; ?>/assets/facebook-icon.png" /></a>

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! We 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 Firefox Developer Console, Chrome Developer Tools or something similar 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.

These documents represent various items in Business Directory Plugin that you can customize yourself and the recommended ways to do so. You are welcome to ask questions about customizations, but please understand that while we can provide general guidance on them, it's beyond the scope of our customer support to provide specific files, lines to add, etc. Customization is something you have to debug and work out on your own.

We assume that you have the skills to do so when you start–which include, but are not limited to, advanced PHP, WordPress API, HTML and CSS. If you're not comfortable with these development aspects yourself, you'll probably want to hire someone to help you make those changes.

If you need help, there are a few great resources to help you out here.

1)  Codeable has WordPress expert developers available for short-term projects
2)  Tilden Tasks does longer WordPress tasks, but they break it down to 1 task per day.
3)  Upwork (formerly known as oDesk) to help out if you think this is beyond your current skill set.    There are a lot of decent folks on there as well.

Business Directory Customization Topics

• General Customization Guide
• Form Fields API
• Shortcodes
• Template Hooks
• Directory Themes / Usage

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_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 → Settings → Miscellaneous → 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.

Delete Regions data

Here is the SQL script to delete all data associated to regions, the only thing to consider here is table prefix wp_ depending on hostings the prefix may change, for instance a shared hosting plan uses an specific prefix to prevent different sites point to same db.

— Delete regionmeta table

DROP TABLE IF EXISTS wp_wpbdp_regionmeta;

-- Delete Regions Fields
DELETE FROM `wp_wpbdp_form_fields` WHERE association = 'region';

-- Delete Region Terms
DELETE FROM `wp_terms` WHERE term_id IN (SELECT term_id FROM `wp_term_taxonomy` WHERE taxonomy = 'wpbdm-region');

-- Delete Regions term relationships
DELETE FROM `wp_term_relationships` WHERE term_taxonomy_id IN (SELECT term_taxonomy_id FROM `wp_term_taxonomy` WHERE taxonomy = 'wpbdm-region');

-- Delete Regions Term taxonomies
DELETE FROM `wp_term_taxonomy` WHERE taxonomy = 'wpbdm-region';