wpsmith/templates

WordPress templates.

Template Loader

, _(*1)

A class to copy into your WordPress plugin, to allow loading template parts with fallback through the child theme > parent theme > plugin., _(*2)

This is largely based on Gary Jones's Gamajo_Template_Loader. The main difference between Gary's version and this one is twofold: 1. I didn't want to extend the class for each and every plugin I created...call me lazy. 1. I didn't want to load the template parts automatically., _(*3)

Description

Easy Digital Downloads, WooCommerce, and Events Calendar plugins, amongst others, allow you to add files to your theme to override the default templates that come with the plugin. As a developer, adding this convenience in to your own plugin can be a little tricky., _(*4)

The get_template_part() function in WordPress was never really designed with plugins in mind, since it relies on locate_template() which only checks child and parent themes. So we can add in a final fallback that uses the templates in the plugin, we have to use a custom locate_template() function, and a custom get_template_part() function. The solution here just wraps them up as a class for convenience., _(*5)

Installation

This isn't a WordPress plugin on its own, so the usual instructions don't apply. Instead:, _(*6)

Manually install class

1. Copy Templates/src/TemplateLoader.php for basic usage

or:, _(*7)

1. Copy Templates/src/TemplateLoaderData.php and Templates/src/TemplateLoader.php](TemplateLoader.php) into your plugin. It can be into a file in the plugin root, or better, an includes directory.

or:, _(*8)

Install class via Composer

1. Tell Composer to install this class as a dependency: composer require wpsmith/templates
2. Recommended: Install the Mozart package: composer require coenjacobs/mozart --dev and configure it.
3. The class is now renamed to use your own prefix, to prevent collisions with other plugins bundling this class.

Implementation & Usage

Unlike Gamajo's Gamajo_Template_Loader, you do not have to implement a new class., _(*9)

Assuming..., _(*10)

// Set at the root folder of your plugin (e.g., wp-content/plugins/yourplugin/yourplugin.php).
// Defines YOUR_PLUGIN_DIRNAME as yourplugin.
define( 'YOUR_PLUGIN_DIRNAME', dirname( __FILE__ ) );

Initialization

We can initialize TemplateLoader:, _(*11)

// Create the loader with my prefix and directory.
// This assumes:
//  - plugin templates are found in the plugin folder: wp-content/plugins/yourplugin/templates/...
//  - theme templates are found in the plugin folder: wp-content/themes/yourtheme/templates/...
$template_loader = new TemplateLoader( [
    'prefix'           => 'wps',
    'plugin_directory' => YOUR_PLUGIN_DIRNAME,
] );

Or,, _(*12)

// Create the loader with all the parts.
// This declares:
//  - plugin templates are found in the plugin folder: wp-content/plugins/yourplugin/templates/...
//  - theme templates are found in the plugin folder: wp-content/themes/yourtheme/templates/yourplugin/...
$template_loader = new TemplateLoader( [
    'prefix'                   => 'wps',
    'theme_template_directory' => 'templates/yourplugin',
    'templates_directory'      => 'templates',
    'plugin_directory'         => WPS_PLUGIN_DIRNAME,
] );

You could utilize a template loader helper which will always return the same template loader:, _(*13)

/**
 * Gets the plugin template loader.
 *
 * @return \WPS\WP\Templates\TemplateLoader
 */
function yourprefix_get_template_loader() {
    static $loader;
    if ( $loader === null ) {
        $loader = new \WPS\WP\Templates\TemplateLoader( [
            'prefix'                   => 'wps',
            'theme_template_directory' => 'templates/yourplugin',
            'templates_directory'      => 'templates',
            'plugin_directory'         => WPS_PLUGIN_DIRNAME,
        ) );
    }

    return $loader;
}

Finally, you can use it for configuration purposes too., _(*14)

/**
 * Gets a configuration file as a data array.
 *
 * @return array
 */
function yourprefix_get_config( $config ) {
    static $loader;

    if ( $loader === null ) {
        $loader = new TemplateLoader( [
            'filter_prefix'            => 'wps',
            'theme_template_directory' => 'config',
            'templates_directory'      => 'config',
            'plugin_directory'         => WPS_PLUGIN_DIRNAME,
        ] );
    }

    $template = $loader->get_template_part( 'config', $config );

    $data = array();
    if ( is_readable( $template ) ) {
        $data = require $template;
    }

    return (array) $data;
}

Usage

• Use it to call the load_template_part() method. This could be within a shortcode callback, or something you want theme developers to include in their files., _(*15)

  $template_loader->load_template_part( 'recipe' );
  

• Use it to call the get_template_part() method. This could be within a shortcode callback, or something you want theme developers to include in their files., _(*16)

  // This will return the path to the particular template part.
  $template_loader->get_template_part( 'recipe' );
  
  // This will load the particular template part.
  $template_loader->get_template_part( 'recipe', null, true );
  

• If you want to pass data to the template, call the set_template_data() method with an array before calling get_template_part(). set_template_data() returns the loader object to allow for method chaining., _(*17)

  $data = [ 'foo' => 'bar', 'baz' => 'boom' ];
  $template_loader
    ->set_template_data( $data );
    ->get_template_part( 'recipe' );
  

  The value of bar is now available inside the recipe template as $wps_data->foo., _(*18)

  If you wish to use a different variable name, add a second parameter to set_template_data():, _(*19)

  $data = array( 'foo' => 'bar', 'baz' => 'boom' );
  $meal_planner_template_loader
    ->set_template_data( $data, 'context' )
    ->get_template_part( 'recipe', 'ingredients' );
  

  The value of bar is now available inside the recipe template as $context->foo., _(*20)

  This will try to load up:, _(*21)

  • Theme Templates:
    • wp-content/themes/my-theme/meal-planner/recipe-ingredients.php
    • wp-content/themes/my-theme/meal-planner/ingredients.php
    • wp-content/themes/my-theme/meal-planner/recipe.php
  • Plugin Templates:
    • wp-content/plugins/meal-planner/templates/recipe-ingredients.php
    • wp-content/plugins/meal-planner/templates/ingredients.php.
    • wp-content/plugins/meal-planner/templates/recipe.php.

Change Log

See the change log., _(*22)

License

GPL 2.0 or later., _(*23)

Contributions

Contributions are welcome - fork, fix and send pull requests against the develop branch please., _(*24)

Credits

Based upon Gary Jones's Gamajo_Template_Loader Built by Travis Smith
Copyright 2013-2020 Travis Smith, _(*25)