Nearly every tutorial on WordPress on the internet that provides you a code-based solution will recommend you “add this to your functions.php file”.
This is largely poor advice.
It leads to large, unreadable functions.php files where it is hard for a developer, especially one who is making changes after an original developer has moved on, to find everything. This also places behaviors that modify how the website or a plugin like Matador works inside a theme, which is designed to be hot-swappable. Don’t do it.
So, then, where should this code go?
In general, if the code modifies how WordPress functions, it should be put in a plugin or a ‘must-use’ plugin and when the code modifies how WordPress displays content it should it should be put in a clearly named and labeled ‘include’ file in the theme folder.
What does this mean for code that modifies Matador?
Ask yourself, what is this code doing to Matador? Based on the answer, we recommend the following:
If the code changes to an existing behavior or routine in Matador that affects the data it creates and manages, we recommend a ‘must-use’ or ‘site-plugin’ plugin, especially when these changes would be specific to one use case. Examples for when this condition would apply include:
- Programming an additional field import from the ATS,
- Programming an additional field for the application form and the data validation and verification handling for it, or,
- Forcing a certain setting to always return a same value.
If the code adds a new behavior or routine to Matador, we recommend creating an extension plugin, especially when these changes could be useful for other users in the future. Let us know what you’re working on, and we’ll even help you get started. Examples for when this condition would apply include:
- Sending data to a 3rd party analytic tracking system on certain user actions,
- Sending certain application data to a secondary CRM, customer relationship tracking, or,
- Sending information on newly added jobs to a social media publishing tool (not supported already by a Matador Jobs Pro All Access Extension), ie: Hoot Suite.
If the code is using a template action or filter to affect how data is presented we recommend you use theme include file in a separate folder in your theme. Examples include:
- Replace the look and feel of the file upload field on the application form, or,
- Change the structure of the HTML of the job info bar for styling purposes.
Adding a ‘Must Use’ or Plugin
If your code is going to modify existing Matador behavior, especially in a way that would be specific to a single user’s needs, we recommend a ‘must-use’ plugin. A ‘must-use’ plugin is a PHP file or folder containing PHP added to the mu-plugins folder inside of wp-content. You can write both object-oriented and procedural code in this file (a functions.php is often procedural).
If the site you’re building is for “ACME Staffing”, you might name your file mu-plugins/acme_staffing_site_plugin.php. If you ever feel like this file gets very long, you can create a folder for it, like mu-plugins/acme_staffing_site_plugin/acme_staffing_site_plugin.php and use include_once() calls to include other files in that folder.
A benefit to a ‘must-use’ plugin is that the site operators cannot turn it off unless they remove it from the file structure via FTP. This is useful because you’ll never have a site operator turn off a plugin that would in turn break their sites’ data.
A number of code snippets used in the Matador help docs will suggest you add them to a ‘must-use’ plugin.
Using a theme include file
If your code is going to affect only the display of Matador, but not alter its function, we recommend you gather all your Matador related code into a single file and include it in your theme.
In your theme folder, create a new file matador-functions.php. You may optionally put that file inside another folder, like a folder named matador or includes. Then, include that file with the following line added to your theme functions.php file.
include_once 'includes/matador-functions.php';A number of code snippets used in the Matador help docs will suggest you add them to a theme include file.
Building a Matador Extension Plugin
If your code is going to extend Matador’s behavior, instead of just changing or removing something it already does, you may want to build an extension plugin, especially if this extended behavior might be useful to others.
An extension plugin, a lot like our many Matador Jobs Pro Extensions, grant additional usefulness to Matador beyond its core behavior. These are optional, so a site operator can turn it on or off via the Plugins menu.
For example, if you are writing an extension to Matador that signs a user up for a mailing list service not currently supported by Matador’s existing Extensions, a site operator should be able to easily turn it off in the future if they switch providers or decide to stop running a mailing list.
Chances are you’ve already made a WordPress plugin if you’re planning to go down this route, but if not, feel free to use one of our Matador Jobs Pro Extensions as a starting point. Also feel free to contact us, as we love to know what developers are doing with Matador and we may be able to offer you some help along the way!