Building a theme for Business Directory Plugin

Introduction

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.

File/Directory	Required?	Description
theme.json	Required	This is the manifest file. Theme folders (both packaged and unpackaged) are only considered a theme if they contain a valid manifest file. See theme.json manifest file for more details.
theme.php	Optional	This file is used to execute PHP code at certain points during theme initialization or after certain Business Directory actions take place. Details below.
thumbnail.png	Optional	A PNG image that is used on the backend to display your theme for selection
assets/	Optional	A folder containing CSS and Javascript assets for your theme. These files are included as part of the assets key of your theme’s theme.json manifest.
templates/	Optional	The actual PHP templates for your theme. Template files are described in detail below.

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": "[email protected]",
    "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.