How to perfectly match your BD design to your Theme

Business Directory Plugin uses the WordPress core mechanism to handle template overrides. If you are unfamiliar with WordPress templates and how templates are organized, we suggest studying the provided links before proceeding further.

For further reading and even more advanced customization, please see the BD Customization Guide here:  http://businessdirectoryplugin.com/docs/customization-guide/

Template system overview

Business Directory Plugin uses a mechanism similar to WordPress template system to handle template overrides. The default templates can be found inside the templates plugin directory and are prefixed by businessdirectory. They are as follows:

BD template Description
businessdirectory-main-page.tpl.php This template is called inside the page with the [ businessdirectory ] shortcode.
businessdirectory-listings.tpl.php This template is used when displaying a list of listings (for instance inside a category/tag page or in search results)
businessdirectory-excerpt.tpl.php This template is used when displaying the excerpt view of a listing.
businessdirectory-listing.tpl.php This template is used when displaying a single listing.

 

IMPORTANT:

Do not call get_header(), get_footer() or get_sidebar() inside any of these templates. They are used within the context of a page so these functions have already been called by then by your theme.

 

The plugin vanilla templates are designed to work relatively well with most themes but if you do have the need to override these templates to match your theme please try to follow these conventions:

  1. Copy the default BD template inside of templates to your theme folder.
  2. Use the copied version of the template to have a grasp of how the Business Directory functionality works inside the template. The rest of this document is devoted to which functions are allowed inside each of the templates above, but it’s certainly a good idea to take a look at the default before trying anything.
  3. Use your theme’s file and the BD default’s to build your own definitive template.
  4. Test your changes. If you have a lot of trouble, remember you can just remove the file from your theme folder or copy the BD default template verbatim from templates and start over again.

For example, suppose you want to change how the “single listing view” looks like. As per the table above, you’ll need to base your template off the businessdirectory-listing.tpl.php template. You can name this new file businessdirectory-listing.tpl.php or just businessdirectory-listing.php (the .tpl extension is optional) and save it inside your theme’s folder.

Note on differences since 2.0.x

Version 2.1 of Business Directory plugin changed the way templates are used and should be overridden in order to simplify things and integrate better with themes by default. This document explains how the new system works but the old framework is still in place and templates of either style can be mixed at the moment.

Examples of old-style templates are: businessdirectory-category.tpl.php or businessdirectory-single.tpl.php. These were full-page templates and as such, required a more careful integration with themes.

It is not recommended to mix templates from both systems because templates from 2.0.x will be deprecated eventually, but documentation on them is still available. Check it for comparisons and legacy work.

General-purpose functions

Some functions can be used in all of the new templates (including WP standard ones). Even old Business Directory Plugin functions that are now deprecated are still available (see deprecated.php inside the plugin directory) but should not be relied upon because they might be removed in future releases.

The following functions are available everywhere to be used in any template:

wpbdp_the_directory_categories()

Displays the list of directory categories. Respects all of the configuration settings.

wpbdp_the_main_links()

Displays the list of links/buttons that are at the top of every Business Directory page. This list is controlled by settings inside of “Manage Options” and includes buttons such as “Directory”, “Submit Listing” and “View Listings”.

wpbdp_the_search_form()

Shows the short version of the search form, including a link to the advanced search page.

wpbdp_sticky_loop()

When within a category or tag page displays the corresponding list of featured listings.

wpbdp_render_listing($listing_id, $view, $echo)

This function can be used to render a single listing. This function takes into account all of the general, form field settings and calls the correct template depending on the type of view to be rendered.

It is recommended that you always use this function when there’s the need to display a listing.

If you need to customize the output, include either the listing template (see businessdirectory-listing.tpl.php) or the excerpt template (see businessdirectory-excerpt.tpl.php).

Function arguments

  • $listing_id: The listing ID or null in order to use the current post ID (if inside “the loop”).
  • $view: The type of view to render: either “single” (the default) or “excerpt”.
  • $echo: If true the output will be echoed instead of returned. Default is false.

wpbdp_latest_listings($n, $before, $after, $before_item, $after_item)

This function can be used to display a list of the latest listings posted to the directory. Only the title is shown.

Function arguments

  • $n: The number of listings to display. Defaults to 10.
  • $before: Output this before the list. Defaults to <ul>.
  • $after: Output this after the list. Defaults to </ul>.
  • $before_item: Output this before each item. Defaults to <li>.
  • $after_item: Output this after each item. Defaults to </li>.

Template specifics

businessdirectory-main-page.tpl.php

This template is used when rendering the main directory page, i.e., the one with the [ businessdirectory ] shortcode.
In addition to the standard functions, the following functions and variables are available inside this template:

Method / variable Description
wpbdp_the_directory_categories() Displays the list of categories following all the settings configured for the directory (display subcategories or not, display post count, etc.)
$listings If the setting “”Show listings under categories on main page?” is checked, this variable will contain the listings to be displayed in this page (taking into account pagination, etc.). See businessdirectory-listings.tpl.php to find how the display of this list can be changed.

businessdirectory-listings.tpl.php

This template is used every time a bunch of listings is to be displayed (either in single or excerpt view). This happens, for instance, inside every category or tag page, inside “View Listings”, “Manage Listings” and for search results. By the time this template is called the list of directory listings has been prepared by the plugin, so you only need to worry about presentation.

Don’t forget to include the pagination methods called at the bottom of this template if you are overriding it. They are used to display the next/previous links shown when there are multiple listings.

In addition to the standard functions, the following functions and variables are available inside this template:

Method / variable Description
$excludebuttons If true this variable indicates that the main buttons shouldn’t be displayed this time. This happens, for instance, when the buttons have been included already by another template. See wpbdp_the_main_links().
$stickies Contains the formatted output corresponding to the sticky/featured listings that need to be included within this list.
wpbdp_render_listing() Use this function everytime you need to render a listing within the loop. See wpbdp_render_listing().

 

NOTE:

You can also use every WordPress function available inside “the loop” because this template is always called within a WordPress loop.

 

businessdirectory-excerpt.tpl.php

This template is used when displaying the ‘excerpt’ view of a listing. This is the default view used when there are multiple listings in the page (i.e. in search results, category/tag pages, etc.).

In addition to the standard functions, the following functions and variables are available inside this template:

Method / variable Description
$title The listing title correctly formatted for display.
$thumbnail If not empty, the HTML to display the listing thumbnail.
$is_sticky true if the listing is a sticky/featured one.
$listing_fields HTML output for this listing fields. Only fields with the option “Display this value in post excerpt view” checked are available here.

 

NOTE:

You can also use every WordPress function available inside “the loop” because this template is always called within a WordPress loop.

 

businessdirectory-listing.tpl.php

This template is used when displaying the ‘single’ view of a listing. This is the main view of a listing and it’s used when the listing is shown in a page of its own, along with the comment/contact form, etc.

In addition to the standard functions, the following functions and variables are available inside this template:

Method / variable Description
$title The listing title correctly formatted for display.
$is_sticky true if the listing is a sticky/featured one.
$sticky_tag If the listing is sticky, this contains the HTML of the default “Featured Listing” image.
$actions The HTML for the action buttons for this listing: “Edit”, “Delete”, “Upgrade to Featured” (depends on configuration settings and permissions).
$main_image HTML output for the main image for this listing (the one used as thumbnail).
$extra_images An array where each item is the HTML output for one of the listing images (if any) except for the main one.
$listing_fields HTML output for this listing fields. Only fields with the option “Display this value in the listing view” checked are available here.

 

NOTE:

You can also use every WordPress function available inside “the loop” because this template is always called within a WordPress loop.

Directory powered by Business Directory Plugin