WordPress Plugin Template Files

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.