Introduction
NOTE: This is an OLDER guide for BD 3.x–some files have changed. For updated instructions, please visit: https://docs.businessdirectoryplugin.com/
This document describes the general layout of the Business Directory Plugin folder as well as the contents of most of the files and folders inside. The instructions provided here assume that you are an expert in PHP coding, understand HTML very well, and are comfortable with the WordPress PHP API. If you feel that your skills aren't up to par in these areas, you should consider hiring help for your project on a forum such as Upwork or Codeable.io.
CUSTOMIZATION WARNING: Beyond the help provided here, customizations to the plugin are something that you do on your own and without further support from the BD team. We can't provide support on any custom changes you make to the plugin–you must be comfortable in debugging techniques and tools to find and fix issues on your own. Any bugs you find in the plugin must be reproducible with the core, unmodified plugin in order to be considered issues we can address.
Before altering plugin files
- Consider alternative ways to achieve what you want: Business Directory supports CSS customization, template overrides and provides a lot of WordPress filters and actions you can hook into.
- Avoid modifying plugin files unless absolutely necessary. You could end up breaking your site or losing information.
- MAKE A FULL BACKUP BEFORE UPGRADING THE PLUGIN EACH TIME! Please keep in mind that WordPress will remove any modifications you make to the plugin files during plugin upgrades. This is standard WP behavior, so if you forget about it, you'll lose your changes!
Naming Conventions
Business Directory follows a simple naming convention used to make it easier to figure out what's in a file without opening it.
- The class- prefix is used when the file contains a PHP class and nothing else. For example, class-payment.php contains the
WPBDP_Paymentclass. - The view- prefix is used for files that contain views.
Business Directory follows the Model-View-Controller pattern but calls its controllers “views”, just like the Django framework does. Simple views also tend to take care of displaying content themselves, so the term makes sense. - Templates are suffixed with .tpl.php to differentiate themselves from regular PHP files.
Business Directory folder layout
The following is a general overview of the folder layout used in Business Directory. You'll find a more detailed description for most of the items below in the next section.
| File/Directory | Description |
|---|---|
| business-directory-plugin.php | Main plugin file. It takes care of setting everything up including instantiating core APIs such as Form Fields, Settings, etc. |
| admin/ | Backend code. |
| core/ | Basic classes and APIs. |
| core/compatibility/ | Deprecated and compatibility code for use with old templates (no longer supported). |
| core/css/ | Minified and non-minified CSS files for the frontend. |
| core/js/ | Minified and non-minified JS files for the frontend. |
| core/images/ | Some images used by BD. |
| templates/ | All frontend templates. Templates that can be overridden in themes are documented here. |
| vendors/ | External libraries used by BD such as reCAPTCHA, JWT, jQuery-File-Upload, etc. |
| languages/ | i18n files. Use “WPBDM.pot” as template to create your own translations. |
Folder layout in detail
business-directory-plugin.php
This is the file where it all starts. BD hooks into WordPress, initializes APIs, etc. in this file.
core/
| File/Directory | Description |
|---|---|
| debugging.php | BD debugging functionality: capture of PHP errors, queries and display of debugging output. Active only when WP_DEBUG is enabled. |
| utils.php | Various utility functions used by BD. |
| installer.php | Install/upgrade routines. |
| widgets.php | Code for Business Directory widgets. |
| api.php | General purpose functions used through out BD, mostly shortcut methods for API functionality available elsewhere. |
| class-ajax-response.php | Convenience class to handle AJAX responses. |
| class-db-model.php | CRUD class used to interact with database models. |
| class-email.php | The class used by BD for e-mailing. |
| class-form-field-type.php | Class definition for form field types (textfield, select, URL field, etc.). |
| class-form-field.php | Class definition for form fields. This class is in charge of storing and displaying values for listing fields. |
| class-gateway.php | Class definition for payment gateways. Inherit from this class to implement your own payment gateways. |
| class-listing.php | Convenience class for working with listings. |
| class-payment.php | Class definition for payments. |
| class-settings.php | Settings API. |
| class-view.php | Class definition for BD views. |
| form-fields-types.php | Form field types bundled with BD. |
| form-fields.php | Form fields API: registration of form fields and types, validation, etc. |
| listings.php | Listings API: upgrades to “Featured”, quick search, renewal notifications, permalink generation, etc. |
| payment.php | Payment API: fees, transactions, IPN handling, etc. |
| templates-generic.php | Functions commonly used in templates. |
| templates-listings.php | Functions affecting listing rendering. |
| templates-ui.php | UI functions available to all templates: search form, sort bar, links on top of Directory pages, etc. |
| view-checkout.php | Checkout procedure view. |
| view-listing-contact.php | Listing contact view. |
| view-renew-listing.php | Listing renewal view. |
| view-submit-listing.php | Listing submit view. |
| view-upgrade-listing.php | Listing upgrade view. |
| views.php | Misc. views: main page, category, tag, search, etc. |
core/compatibility/
Files inside this directory should not be used and are listed here just for completeness. These are legacy files that have been deprecated over time and remain here for reference to folks using older code for template overrides.
WARNING: Do not rely on functionality from these files since they could be removed in future releases.
| File/Directory | Description |
|---|---|
| deprecated.php | Functions that were available in BD 1.x and 2.x that could be still in use in some user templates. |
| templates/businessdirectory-category.tpl.php | Custom taxonomy archive template. Analog to WP's taxonomy-{taxonomy}.php. |
| templates/businessdirectory-single.tpl.php | Custom post type single template. Analog to WP's single-{post_type}.php. |
templates/
All frontend templates are available in this directory.
Some of the templates can be copied to theme directories for customization and will override the defaults.
| File/Directory | Description |
|---|---|
| businessdirectory-excerpt.tpl.php | Template for listing excerpt view. Can be overridden in themes. |
| businessdirectory-listing.tpl.php | Template for listing single view. Can be overridden in themes. |
| businessdirectory-listings.tpl.php | Template for lists of several listings. Can be overridden in themes. |
| businessdirectory-main-page.tpl.php | Main page template. Can be overridden in themes. |
| category.tpl.php | Category template. |
| email/ | E-mail templates. |
| listing-contactform.tpl.php | Listing contact form. |
| listing-upgradetosticky.tpl.php | Template for the “Upgrade to Featured” page. |
| manage-listings.tpl.php | Template for the “Manage Listings” shortcode. |
| parts/category-fee-selection.tpl.php | Category fee selection. |
| parts/listing-buttons.tpl.php | Buttons displayed under listings (View, Edit, etc.). |
| parts/login-required.tpl.php | Template used when login is required. |
| payment/payment_items.tpl.php | Invoice template. |
| payment-page.tpl.php | Payment page template. |
| renew-listing.tpl.php | Template for the “Renew Listing” page. |
| search.tpl.php | Search page template. |
| submit-listing/ | Templates for the listing submit procedure. |
