General Customization Guide

Advanced Customization of Business Directory Plugin

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>