gamajo / template-loader
A class for your WordPress plugin, to allow loading template parts with fallback through the child theme > parent theme > plugin
Installs: 37 106
Dependents: 8
Suggesters: 0
Security: 0
Stars: 292
Watchers: 17
Forks: 61
Open Issues: 6
Requires
- php: >=5.2.4
Requires (Dev)
- php: >=7.1
- dealerdirect/phpcodesniffer-composer-installer: ^0.4.4
- phpcompatibility/phpcompatibility-wp: ^1
- roave/security-advisories: dev-master
- squizlabs/php_codesniffer: ^3.3
- wp-coding-standards/wpcs: ^1
Suggests
- coenjacobs/mozart: Easily wrap this library with your own prefix, to prevent collisions when multiple plugins use this library
This package is auto-updated.
Last update: 2024-10-13 01:06:42 UTC
README
A class to copy into your WordPress plugin, to allow loading template parts with fallback through the child theme > parent theme > plugin.
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.
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.
Installation
This isn't a WordPress plugin on its own, so the usual instructions don't apply. Instead:
Manually install class
- Copy
class-gamajo-template-loader.php
into your plugin. It can be into a file in the plugin root, or better, anincludes
directory.
or:
Install class via Composer
- Tell Composer to install this class as a dependency:
composer require gamajo/template-loader
- Recommended: Install the Mozart package:
composer require coenjacobs/mozart --dev
and configure it. - The class is now renamed to use your own prefix, to prevent collisions with other plugins bundling this class.
Implement class
- Create a new file, such as
class-your-plugin-template-loader.php
, in the same directory. - Create a class in that file that extends
Gamajo_Template_Loader
(or the new prefixed name, if you installed via Composer/Mozart). You can see the Meal Planner Template Loader example class below as a starting point if it helps. - Override the class properties to suit your plugin. You could also override the
get_templates_dir()
method if it isn't right for you. - You can now instantiate your custom template loader class, and 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.
// Template loader instantiated elsewhere, such as the main plugin file. $meal_planner_template_loader = new Meal_Planner_Template_Loader();
-
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.$meal_planner_template_loader->get_template_part( 'recipe' );
-
If you want to pass data to the template, call the
set_template_data()
method with an array before callingget_template_part()
.set_template_data()
returns the loader object to allow for method chaining.$data = array( 'foo' => 'bar', 'baz' => 'boom' ); $meal_planner_template_loader ->set_template_data( $data ) ->get_template_part( 'recipe' );
The value of
bar
is now available inside the recipe template as$data->foo
.If you wish to use a different variable name, add a second parameter to
set_template_data()
:$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
.This will try to load up
wp-content/themes/my-theme/meal-planner/recipe-ingredients.php
, orwp-content/themes/my-theme/meal-planner/recipe.php
, then fallback towp-content/plugins/meal-planner/templates/recipe-ingredients.php
orwp-content/plugins/meal-planner/templates/recipe.php
. -
You can also pass the template loader object into the template as well:
$template_loader = new Your_Template_Loader(); $template_loader->set_template_data( array( 'template_loader' => $template_loader, // Optional other data as needed. ) );
Then in the template you can use:
$data->template_loader->get_template_part( 'recipe' );
Meal Planner Example Class
<?php /** * Meal Planner * * @package Meal_Planner * @author Gary Jones * @link http://example.com/meal-planner * @copyright 2013 Gary Jones * @license GPL-2.0+ */ if ( ! class_exists( 'Gamajo_Template_Loader' ) ) { require plugin_dir_path( __FILE__ ) . 'class-gamajo-template-loader.php'; } /** * Template loader for Meal Planner. * * Only need to specify class properties here. * * @package Meal_Planner * @author Gary Jones */ class Meal_Planner_Template_Loader extends Gamajo_Template_Loader { /** * Prefix for filter names. * * @since 1.0.0 * * @var string */ protected $filter_prefix = 'meal_planner'; /** * Directory name where custom templates for this plugin should be found in the theme. * * @since 1.0.0 * * @var string */ protected $theme_template_directory = 'meal-planner'; /** * Reference to the root directory path of this plugin. * * Can either be a defined constant, or a relative reference from where the subclass lives. * * In this case, `MEAL_PLANNER_PLUGIN_DIR` would be defined in the root plugin file as: * * ~~~ * define( 'MEAL_PLANNER_PLUGIN_DIR', plugin_dir_path( __FILE__ ) ); * ~~~ * * @since 1.0.0 * * @var string */ protected $plugin_directory = MEAL_PLANNER_PLUGIN_DIR; /** * Directory name where templates are found in this plugin. * * Can either be a defined constant, or a relative reference from where the subclass lives. * * e.g. 'templates' or 'includes/templates', etc. * * @since 1.1.0 * * @var string */ protected $plugin_template_directory = 'templates'; }
Usage Example
The Cue plugin from AudioTheme uses this class. Starting at https://github.com/AudioTheme/cue/tree/develop/includes, it has this class in the vendor directory, then the required subclass of my class in the class-cue-template-loader.php
file, which sets a few basic properties. It also has a template in https://github.com/AudioTheme/cue/tree/develop/templates.
If you wanted the playlist to have different markup for your theme, you'd copy templates/playlist.php
to wp-content/themes/{your-active-theme}/cue/playlist.php
and do whatever changes you wanted. WordPress will look for that file first, before then checking a parent theme location (if your active theme is a child theme), before falling back to the default template that comes with the Cue plugin.
Change Log
See the change log.
License
Contributions
Contributions are welcome - fork, fix and send pull requests against the develop
branch please.
Credits
Built by Gary Jones
Copyright 2013 Gary Jones