README

辅助注册模板到主题的加载器。

注意：如果你正在构建一个 WordPress 插件，你可能不需要这个，你可能只需要 Underpin 中直接构建的模板特性。

此加载器使您能够创建用于主题中的任意位置的定制模板。它替换了 get_template_part，并增加了一些有用的功能。

它提供了一个清晰的逻辑、数据获取和其他类似事物的放置位置。
模板可以嵌套。
模板可以选择性覆盖，并由子主题扩展

安装

使用 Composer

composer require underpin/template-loader

手动

此插件使用内置的自动加载器，因此只要在 Underpin 之前要求它，它应该会按预期工作。

require_once(__DIR__ . '/underpin-templates/templates.php');

设置

安装 Underpin。请参阅 Underpin 文档
根据需要注册新模板。

注册模板

像任何加载项一样，模板必须注册。这可以通过几种不同的方式完成。

underpin()->templates()->add( 'index', [
	'description' => "Renders the home page.", // Human-readable description
	'name'        => "Index Template.",        // Human-readable name
	'group'       => 'index',                  // Template group.
	'root_path'   => underpin()->template_dir()// Template path
	'templates'   => [                         // Templates to include.
		'loop'     => 'public',
		'post'     => 'public',
		'no-posts' => 'public',
	],
] );

上面的示例将期望在 templates/index 目录内有三个模板。

循环
文章
无文章

这是一个设置模板的好方法，但对于更复杂的模板，使用模板内的自定义类方法将更有益。在这些情况下，扩展 Theme\Abstracts\Template 更有意义，这样您可以添加自己的逻辑并保持您的标记清洁。

您可以直接将模板注册为一个类，如下所示

// lib/templates/Index.php

class Index extends \Theme\Abstracts\Template{

  protected $name = 'Index Template';
  
  protected $description = 'Human Read-able description';

  protected $group = 'index';

  protected $templates = [                         // Templates to include.
		'loop'     => 'public',
		'post'     => 'public',
		'no-posts' => 'public',
	];

  // Optionally place any helper methods specific to this template here. These methods would be use-able inside of the
  // template, and can really help keep your templates clean.
}

然后像这样在 functions.php 中注册您的模板

underpin()->templates()->add('index','Theme\Templates\Index');

渲染模板输出

模板的目的是渲染输出 HTML。理想情况下，您的所有逻辑都应该是预先确定的，并直接传递给模板，以便通过 get_param() 直接访问。

让我们看看使用模板系统的基本 WordPress 循环

<?php
/**
 * Index Loop Template
 *
 * @author: Alex Standiford
 * @date  : 12/21/19
 * @var Theme\Abstracts\Template $template
 */

// This confirms that nobody is trying to be cute, and load this template in a potentially dangerous way.
if ( ! underpin()->templates()->is_valid_template( $template ) ) {
	return;
}

?>
<main>
	<?php if ( have_posts() ): ?>
		<?php while ( have_posts() ): the_post(); ?>
			<?= $template->get_template( 'post' ); ?>
		<?php endwhile; ?>
	<?php else: ?>
		<?= $template->get_template( 'no-posts' ); ?>
	<?php endif; ?>
	<?php get_sidebar(); ?>
</main>

请注意我们如何将 $template 作为类来引用？这是因为它确实是 Template 类的实例。您可以直接将其作为 $template 引用。这意味着您可以使用模板类中的任何方法。

这包括通过运行 get_template 来渲染子模板。在这种情况下，您不需要指定组，因为 $template 已经知道组 - 您只需要告诉它组中要使用哪个模板。

相反，get_template 的第二个参数是一个可选的关联数组，它将传递给下一个模板。这些参数可以使用 $template->get_param('argument-key', 'fallback_value') 来访问

调用模板

要调用模板，您可以这样做

<?= underpin()->templates()->get_template( 'index', 'loop', [/* Arguments to pass to template */] ); ?>

其中 index 是您的模板组，而 loop 是您希望加载的模板。第三个参数是传递给模板的关联数组。

就像上面的 $template 上下文中一样，传递给模板的任意数据都可以使用 $template->get_param('key', 'fallback value') 来访问，其中第一个参数是要获取的数组键，第二个值是如果键未设置时显示的默认值。

您可以在 Underpin 的文档中了解更多关于模板系统的信息。

在子主题中扩展模板

在子主题中扩展这个模板与在Underpin中扩展任何其他内容的方式完全相同 - 通过在正确的时间挂钩，并根据需要注册自定义项目。

覆盖主题模板

父主题中注册的任何模板都可以通过在子主题中匹配模板放置的目录来覆盖。例如，如果您想覆盖整个头部，您可以在子主题的根目录中创建一个文件：templates/header/header.php。模板系统将使用此模板而不是父主题中指定的模板。

扩展主题

您可以通过挂钩到underpn/after_setup从子主题中修改父主题中注册的任何内容。这是一个注册自定义样式表、脚本或模板的绝佳位置。

这应该放在子主题的functions.php文件中。

// Hook into Underpin's after_setup hook
add_action( 'underpin/after_setup', function ( $file, $class ) {
    
    // If the file is the parent theme, register the things. Ensures these only register one-time
	if ( trailingslashit( dirname( $file ) ) === trailingslashit( get_template_directory() ) ) {
	  // Do things
	}

}

扩展模板

如果您正在使用子主题，您可以通过在主题设置完成后挂钩来注册自定义模板到现有组中，如下所示

// Hook into Underpin's after_setup hook
add_action( 'underpin/after_setup', function ( $file, $class ) {
    
    // If the file is the parent theme, register the things. Ensures these only register one-time
	if ( trailingslashit( dirname( $file ) ) === trailingslashit( get_template_directory() ) ) {
	  // Add a new template group, with custom templates
	  theme()->templates()->add('custom-template-group', [/** Arguments to register child theme-specific template **/]);
	  
	  // Add a new template inside an existing group. This example extends the footer to include a slogan
	  theme()->templates()->get( 'footer' )->add_template( 'slogan',['override_visibility' => 'public'] );
	}

}

underpin / template-loader

维护者

详细信息