WordPress Plugin Template Files

Written by
Published
Updated
Typical Read
3 minutes

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.

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.

Join the conversation.

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.