Add WordPress Plugin Template Files

If you’ve ever worked with WooCommerce theming, you’ve probably had to copy some of their templates files to your own theme in order to override the HTML. It’s a great system that allows front enders the ability to change the output to match designs. In this article, I’ll walk you through how to do just that — easily add WordPress plugin template files.

Let’s get started!

In this tutorial, we’ll create a templates folder within the plugin where we’ll add our… you guessed it, templates. Here we’ll place the templates that can be overridden in themes. These templates will be loaded via a custom plugin template function that will be called in place of WordPress’ get_template_part function.

Step 1: Locating the right template

In order for this to work, WordPress needs to be able to find the correct template file to load — the plugin or theme template. With the code below, WordPress will first look in the theme’s templates folder, if not found then will search in the main theme’s folder and then if still not found will fallback to the plugin’s templates folder.

<?php
/**
 * Locate template.
 *
 * Locate the called template.
 * Search Order:
 * 1. /themes/theme/templates/$template_name
 * 2. /themes/theme/$template_name
 * 3. /plugins/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.
 * @return  string                          Path to the template file.
 */
function PLUGIN_locate_template( $template_name, $template_path = '', $default_path = '' ) {
  // Set variable to search in the templates folder of theme.
  if ( ! $template_path ) :
    $template_path = 'templates/';
  endif;
  // Set default plugin templates path.
  if ( ! $default_path ) :
    $default_path = plugin_dir_path( __FILE__ ) . 'templates/'; // Path to the template folder
  endif;
  // Search template file in theme folder.
  $template = locate_template( array(
    $template_path . $template_name,
    $template_name
  ) );
  // Get plugins template file.
  if ( ! $template ) :
    $template = $default_path . $template_name;
  endif;
  return apply_filters( 'PLUGIN_locate_template', $template, $template_name, $template_path, $default_path );
}

Step 2: Loading the template file

Now that WordPress can find the right template, we need a function to load it. This is what will be used in place of get_template_part.

<?php
/**
 * Get template.
 *
 * Search for the template and include the file.
 *
 * @since 1.0.0
 *
 * @see PLUGIN_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.
 */
function PLUGIN_get_template( $template_name, $args = array(), $tempate_path = '', $default_path = '' ) {
  if ( is_array( $args ) && isset( $args ) ) :
    extract( $args );
  endif;
  $template_file = contests_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: Override the WordPress template file

Lastly, we’ll override the default WordPress template file with the code below.

<?php
/**
 * Template loader.
 *
 * The template loader will check if WP is loading a template
 * for a specific Post Type and will try to load the template
 * from out 'templates' directory.
 *
 * @since 1.0.0
 *
 * @param string  $template Template file that is being loaded.
 * @return  string          Template file that should be loaded.
 */
function PLUGIN_template_loader( $template ) {
  $find = array();
  $file = '';
  if( is_singular() ):
    $file = 'single-plugin.php';
  elseif( is_tax() ):
    $file = 'archive-plugin.php';
  endif;
  if ( file_exists( PLUGIN_locate_template( $file ) ) ) :
    $template = PLUGIN_locate_template( $file );
  endif;
  return $template;
}
add_filter( 'template_include', 'PLUGIN_template_loader' );

Putting It All Together

<?php
/**
 * Locate template.
 *
 * Locate the called template.
 * Search Order:
 * 1. /themes/theme/templates/$template_name
 * 2. /themes/theme/$template_name
 * 3. /plugins/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.
 * @return  string                          Path to the template file.
 */
function PLUGIN_locate_template( $template_name, $template_path = '', $default_path = '' ) {
  // Set variable to search in the templates folder of theme.
  if ( ! $template_path ) :
    $template_path = 'templates/';
  endif;
  // Set default plugin templates path.
  if ( ! $default_path ) :
    $default_path = plugin_dir_path( __FILE__ ) . 'templates/'; // Path to the template folder
  endif;
  // Search template file in theme folder.
  $template = locate_template( array(
    $template_path . $template_name,
    $template_name
  ) );
  // Get plugins template file.
  if ( ! $template ) :
    $template = $default_path . $template_name;
  endif;
  return apply_filters( 'PLUGIN_locate_template', $template, $template_name, $template_path, $default_path );
}
/**
 * Get template.
 *
 * Search for the template and include the file.
 *
 * @since 1.0.0
 *
 * @see PLUGIN_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.
 */
function PLUGIN_get_template( $template_name, $args = array(), $tempate_path = '', $default_path = '' ) {
  if ( is_array( $args ) && isset( $args ) ) :
    extract( $args );
  endif;
  $template_file = PLUGIN_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;
}
/**
 * Template loader.
 *
 * The template loader will check if WP is loading a template
 * for a specific Post Type and will try to load the template
 * from out 'templates' directory.
 *
 * @since 1.0.0
 *
 * @param string  $template Template file that is being loaded.
 * @return  string          Template file that should be loaded.
 */
function PLUGIN_template_loader( $template ) {
  $find = array();
  $file = '';
  if( is_singular() ):
    $file = 'single-plugin.php';
  elseif( is_tax() ):
    $file = 'archive-plugin.php';
  endif;
  if ( file_exists( PLUGIN_locate_template( $file ) ) ) :
    $template = PLUGIN_locate_template( $file );
  endif;
  return $template;
}
add_filter( 'template_include', 'PLUGIN_template_loader' );