$plugin->getTemplateContent( $name, $args )
Templates are used to keep your html conveniently separated from your business logic. They allow overrides to be placed in themes, and for other plugins to adapt their output using filters. They are re-usable and can be embedded within other templates.
As a rule of thumb, any html needed by your plugin business logic should be generated via a template and rarely ever be “hardcoded”.
Scaffolding new templates is easy when you use the WP CLI.
$ wp mwp add-template views/index
@Code Example
use VendorName\PackageName\Plugin as VendorPlugin;
$plugin = VendorPlugin::instance();
$html = $plugin->getTemplateContent( 'views/index', [ 'title' => 'Welcome!' ] );
echo $html;
@File Location
Template files for plugins are located inside the /templates
subdirectory of the plugin. When you load a template using getTemplateContent()
, the template name corresponds to the file path of the template file, without the ‘php’ extension. Therefore, $plugin->getTemplateContent('views/index')
would load a file named plugin-dir/templates/views/index.php
.
If a file could not be found in the associated plugin’s templates folder, then the location falls back to the core framework /templates
folder.
@Overrides
Plugin template files can be overridden by copying them to a subfolder in the theme, where the name of the subfolder is the same as the plugin slug.
Therefore, if a theme were to need to override a template from the core framework such as widget/layout/standard
, the template could be copied into theme-dir/mwp-framework/templates/widget/layout/standard.php
and be overridden.
@Variables
If you want to pass data into templates, you can provide them in an associative array as the second argument to getTemplateContent( $name, $vars )
. The following example will set the $title variable inside the template to the associated value.
$template_content = $plugin->getTemplateContent( 'views/index', array(
'title' => 'Welcome!'
));
@Filters
Specific plugin templates can be filtered by calling the addTemplateFilter()
method on the plugin instance which provides the template.
$plugin->addTemplateFilter( $template, $callback, $priority )
use VendorName\PackageName\Plugin;
/**
* Add a custom template filter
*
*
* @param string $template Plugin template to filter (without file extension)
* @param callable $callback The callback which will filter the template
* @param int $priority The priority to use when adding the filter
* @return void
*/
Plugin::instance()->addTemplateFilter( 'views/main', function( $templateContent, $vars ) {
return '<div>' . $templateContent . '</div>';
});
All templates are also passed through a common mwp_fw_tmpl
WordPress filter.
add_filter( 'mwp_fw_tmpl', $callback )
/**
* Filter the content of every fetched template
*
* @param string $templateContent The rendered template content
* @param string $pluginSlug The slug of the plugin the template was generated by
* @param string $template The name of the template rendered
* @param array $vars The variables provided to the template
* @return string
*/
add_filter( 'mwp_fw_tmpl', function( $templateContent, $pluginSlug, $template, $vars ) {
return $templateContent;
});