1. Home
  2. Docs
  3. Developer
  4. Where to Put Matador Modifications

Nearly every tutorial on WordPress recommends 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. If the code modifies how WordPress displays content, it should be put in a clearly named and labeled ‘include’ file that is included via a include_once in the theme functions.php.

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 is making a change to an existing behavior or routine in Matador or it affects the data it creates and manages, like by telling it to get an additional field from your ATS, adding a field to the application form, or forcing a certain setting to always return a same value, we recommend a ‘must-use’ plugin, especially when these changes would be specific to one use case.
  • If the code is adding a behavior or routine that isn’t yet in Matador, like adding a field that, when checked, signs the user up for a mailing list not currently supported by a Matador Jobs Pro Extension, we recommend creating a general 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.
  • If the code is using a template action or filter to affect how data is presented, like a filter that adds the file type icons to the resume field or prepends the search form with a description, we recommend you use a theme include file.

Adding a ‘Must Use’ 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 on 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!