WordPress Plugin Template Files

If you've got a plugin that outputs markup for end users, the ability to override that markup is crucial. That's where WordPress plugin template files come in — overridable by the theme allowing complete flexibility for themers.
Published
Updated
Typical Read
3 minutes
Sponsored
Sponsor my site by donating to help support open-source projects, like WordPress Zero Spam, Referrer Analytics & others.
Find your next web developer job
jobs by Indeed

In this article, I’ll go over how to create WordPress plugin template files that can be easily overridden by the theme. This gives developers the ability to customize the markup & theme based on their site design & structure.

How to Create WordPress Plugin Template Files

The key to making plugin template files available and overridable by themes is telling WordPress when they can be found — the default plugin templates & the theme template overrides. Here’s how it’ll work:

  1. WordPress will first look in the theme directory for any template files that are meant to override the plugin ones (i.e. themes/your-theme/plugin-name/template-name.php)
  2. If a template isn’t found, WordPress will search the main theme file for any overrides (i.e. themes/your-theme/template-name.php)
  3. Finally, if no template overrides are found, WordPress will fallback to the default plugin template (i.e. plugins/your-plugin/templates/template-name.php)

Step 1. Create a locate template function.

To get started, in the plugin, we’ll need to create a plugin_name_locate_template function that will be used in place of the core locate_template function. This function will be used to retrieve the name of the highest priority template file that exists.

For simplicity, we’ll just throw the code in the main plugin file (i.e. plugins/plugin-name/plugin-name.php).

/**
 * Locate a template for the plugin.
 *
 * Locate the called template.
 * Search Order:
 * 1. /themes/your-theme/your-plugin/$template_name
 * 2. /themes/your-theme/$template_name
 * 3. /plugins/your-plugin/templates/$template_name.
 *
 * @since 1.0.0
 *
 * @param 	string 	$template_name			    Template to load.
 * @param 	string 	$string $template_path	Path to templates.
 * @param 	string	$default_path			      Default path to template files.
 */
if ( ! function_exists( 'plugin_name_locate_template' ) ) {
  function plugin_name_locate_template( $template_name, $template_path = '', $default_path = '' ) {
    // Set the plugin theme folder (e.g. themes/your-plugin/templates/)
    if ( ! $template_path ) :
      $template_path = 'your-plugin/';
    endif;

    // Set the default plugin templates location (e.g. plugins/your-plugin/templates/)
    if ( ! $default_path ) :
      $default_path = plugin_dir_path( __FILE__ ) . 'templates/';
    endif;

    // Search for the template in the theme directory
    $template = locate_template([
      $template_path . $template_name,
      $template_name
    ]);

    // If a template couldn't be found, fallback to using the plugin template directory
    if ( ! $template ) :
      $template = $default_path . $template_name;
    endif;

    return apply_filters( 'plugin_name_locate_template', $template, $template_name, $template_path, $default_path );
  }
}

Step 2. Create a get template function.

Now that we know where our plugin template is located, we’ll create a function, plugin_name_get_template, that’ll get the contents of the template, similar to the core get_template_part function.

/**
 * Get the template.
 *
 * Search for the template and include the file if found.
 *
 * @since 1.0.0
 *
 * @see plugin_name_locate_template()
 *
 * @param string 	$template_name			    Template to load.
 * @param array 	$args					          Args passed for the template file.
 * @param string 	$string $template_path	Path to templates.
 * @param string	$default_path			      Default path to template files.
 */
if ( ! function_exists( 'plugin_name_get_template' ) ) {
  function plugin_name_get_template( $template_name, $args = array(), $tempate_path = '', $default_path = '' ) {
    if ( is_array( $args ) && isset( $args ) ) :
      extract( $args );
    endif;

    $template_file = plugin_name_locate_template( $template_name, $tempate_path, $default_path );

    if ( ! file_exists( $template_file ) ) :
      _doing_it_wrong( __FUNCTION__, sprintf( '<code>%s</code> does not exist.', $template_file ), '1.0.0' );
      return;
    endif;

    include $template_file;
  }
}

Step 3. Use the custom template.

We know how to find & get the plugin template using plugin_name_get_template and plugin_name_get_template, it’s time to output it. You can do this anywhere in WordPress, for instance a shortcode.

Check out the basic shortcode example below:

// [your_plugin_shortcode]
function your_plugin_shortcode() {
  return plugin_name_get_template( 'template_name.php' );
}
add_shortcode( 'your_plugin_shortcode', 'your_plugin_shortcode' );

Just like that, you now have a way to create overridable WordPress plugin template files.

Did you find WordPress Plugin Template Files useful? Get articles in your inbox.

…and don’t worry, I hate spam as much as you. Expect to hear from me at most once a week.

Latest Job Postings
Posted on Aug 9, 2020 at 9:17pm
Full-time
Los Angeles
Posted on Aug 9, 2020 at 9:15pm
Full-time
Los Angeles
Posted on Aug 9, 2020 at 1:19am
Littleton, CO
jobs by Indeed
Sponsored
Sponsor my site by donating to help support open-source projects, like WordPress Zero Spam, Referrer Analytics & others.
Sponsored
Help support open-source projects & pro-bono non-profit services by donating today.
Sponsored
Do you run a development agency, freelance developer or offer website services. Contact me today for information about advertising.
Sponsored
Do you have a great article to share you want to contribute? Contact me about your idea.
Sponsored
Need help with website, a boost in ranking or online marketing? Contact me today for a free quote.

Leave a Reply

Your email address will not be published. Required fields are marked *

All comments posted on 'WordPress Plugin Template Files' are held for moderation and only published when on topic and not rude. Get a gold star if you actually read & follow these rules.

You may write comments in Markdown. This is the best way to post any code, inline like `<div>this</div>` or multiline blocks within triple backtick fences (```) with double new lines before and after.

Want to tell me something privately, like pointing out a typo or stuff like that? Contact Me.