README

此插件为 WordPress 添加了 ajax_template_part() 函数。

它的工作方式类似于 get_template_part()，但 由 AJAX 驱动。

“由 AJAX 驱动”是什么意思？

当包含 ajax_template_part() 调用的文件由 WordPress 加载时，所需的模板不会立即加载，只有当整个页面加载完成时，才会向服务器发送 AJAX 请求以获取所有所需的模板，并将相关内容推送到正确位置。

第一个问题是

为什么在使用 get_template_part() 时我只需要运行一个 HTTP 请求，而显示我的模板时却需要运行 2 个 HTTP 请求（一个常规请求和一个 AJAX 请求）？

两个原因

1. 快速响应

模板可能需要 一些 时间才能渲染。让我们想象一个 loop.php 模板，它显示一系列帖子，每个帖子都包含一个渲染 动态内容 的短代码。以标准方式要求该模板将减慢页面加载速度。但是，有时可能希望向刚到达页面的用户提供快速响应，并 延迟 加载慢速内容（可能显示一个加载 UI）。

这可能更有用，用于渲染“次要”内容：例如，尽可能快地加载帖子内容，同时通过 AJAX 在同时加载相关帖子、广告或类似内容。

2. 缓存

ajax_template_part() 集成了一个强大的缓存系统：通过 AJAX 加载的所有内容都将被缓存。这意味着使用这个类似核心的单一函数可以实现一个 延迟 的片段缓存系统，而无需更改现有代码，无需使用额外的库或设置任何东西。有关插件缓存系统的更多信息，请参阅本页后面的缓存。

##要求

• PHP 5.4+
• WordPress 3.9+
• Composer 用于安装

##安装

此插件是 Composer 包，可以通过以下方式在插件目录中安装：

composer create-project gmazzap/ajax-template-part --no-dev

##如何使用

ajax_template_part() 的工作方式与 get_template_part() 相同。

接受 2 个参数

• $slug 通用模板的 slug 名称（必需）
• $name 特殊化模板的名称（可选）

例如，如果函数调用方式如下

ajax_template_part( 'content' );

它将首先在子主题文件夹（如果有）中查找 content.php，然后是主主题。

如果调用方式如下

ajax_template_part( 'content', 'page' );

它将通过 AJAX 加载第一个存在的文件，顺序如下：

• 子主题中的 content-page.php
• 主主题中的 content-page.php
• 子主题中的 content.php
• 主主题中的 content.php

在加载时显示内容

默认情况下，在包含模板内部调用函数的位置，不会显示任何内容，直到 AJAX 模板加载完成。但是，可以显示 一些 内容：一个旋转图像、加载消息、默认文本等。

可以通过两种方式实现

• 通过过滤器
• 使用 ajax_template_part_content() 函数。

通过过滤器

插件提供了过滤器 "ajax_template_loading_content"，并且通过钩子回调返回的内容用作临时内容，直到所需模板加载完毕。由于钩子回调接收4个参数，因此可以使用不同的内容来满足不同的调用。

• 当前内容，默认为空字符串。
• 所需模板的“名称”，即传递给函数的第一个参数。
• 所需模板的“缩写”，即传递给函数的第二个参数。
• 当前主查询对象。

通过 ajax_template_part_content()

此函数与 ajax_template_part() 的工作方式非常相似，但需要3个参数：作为第一个参数传递的内容将显示为临时内容，其他两个参数与 ajax_template_part() 相同。请注意，传递给此函数的内容不会使用 "ajax_template_loading_content" 钩子进行过滤。

临时容器类

当通过过滤器或使用 ajax_template_part_content() 设置临时内容时，它将被添加到一个 <div> 标签中。

可以使用 "ajax_template_loading_class" 过滤器钩子设置此容器的 HTML 类属性。

钩此过滤器的回调函数接收与 "ajax_template_loading_content" 相同的4个参数。

请注意，即使没有使用临时内容，<div> 容器也始终会添加到页面中，但默认情况下，它使用内联 CSS 隐藏。但通过使用 "ajax_template_loading_class" 过滤器，可以添加类到 <div>，从而能够通过 CSS 进行样式化：例如，可以通过将加载图像设置为通过此过滤器添加的类的 CSS 背景图像属性来使用 加载图像。

嵌套调用

如果在通过 ajax_template_part() 加载的模板中存在对同一函数的附加调用，则按预期加载嵌套模板，并且在同一 AJAX 请求中：不要期望在父级 AJAX 所需模板加载完成后触发 另一个 AJAX 请求。

这同样适用于任何在 AJAX 加载模板内的 get_template_part() 调用。

注意安全

将 ajax_template_part() 调用放入您的模板会使您的网站 需要 安装并激活此插件，否则由于函数未声明而导致致命错误。

为了避免此类问题，例如，如果您意外地停用了插件，可以在您的 functions.php 中这样做：

if ( ! function_exists( 'ajax_template_part' ) ) {
  function ajax_template_part( $name = '', $slug = '' ) {
    return get_template_part( $name, $slug );
  }
}
if ( ! function_exists( 'ajax_template_part_content' ) ) {
  function ajax_template_part_content( $content = '', $name = '', $slug = '' ) {
    return get_template_part( $name, $slug );
  }
}

这样，如果由于任何原因插件未激活，则您的主题将优雅地降级到 get_template_part。

缓存

AJAX 模板加载和内容生成可能非常耗时，因此插件 需要 一种缓存它们的方法。

当常量 WP_DEBUG 设置为 FALSE 时，默认情况下启用缓存，这在生产环境中开启和在本地区域/开发环境中关闭应该是一个相当常见的方式。

但是，通过使用 "ajax_template_cache" 过滤器，可以自定义何时启用或禁用缓存。此钩子传递给钩子回调的唯一参数是当前缓存状态，必须返回一个布尔值：TRUE 表示缓存激活。

此插件可以与不同类型的缓存一起工作。

• 如果系统中已安装外部对象缓存，则此插件将使用它，无需执行其他操作。
• 如果没有使用外部对象缓存，此插件使用 Stash 来缓存数据。此库可以利用不同的 "驱动程序"：文件系统、APC、Memcached、Redis... 默认情况下，插件使用文件系统驱动程序，无需进行任何配置即可使用它。但是，如果系统满足要求，可以使用任何受支持的驱动程序。

使用替代缓存驱动程序

要使用不同的驱动程序，有2个过滤器可用

• "ajax_template_cache_driver"：挂钩回调必须返回要使用的类的完全限定名，以下之一
  • Stash\Driver\Sqlite
  • Stash\Driver\Memcache
  • Stash\Driver\APC
  • Stash\Driver\Redis
  • Stash\Driver\Composite

请参阅Stash 文档以获取详细信息。

• "ajax_template_{$driver}_driver_conf" 是用于配置所选驱动程序的过滤器。挂钩回调必须返回配置数组，有关详细信息，请参阅 Stash 文档。

例如，使用 Memcache 驱动程序的配置可能如下所示

add_filter( 'ajax_template_cache_driver', function() {
  return '\Stash\Driver\Memcache';
});

add_filter( "ajax_template_memcache_driver_conf", function() {
  return [ 'servers' => ['127.0.0.1', '11211'] ];
});

缓存过期时间

默认情况下，内容将被缓存1小时。请注意，如果内容（例如帖子）被更新且旧内容被缓存，则更新的内容将不会显示，直到缓存过期。

可以使用 "ajax_template_cache_ttl" 过滤器挂钩来更改默认的过期时间。挂钩回调接收并必须以秒为单位返回缓存“存活时间”值。请注意，设置低于30秒的值将被忽略并使用默认值。

如果您需要禁用缓存，请不要使用此过滤器，而是使用 "ajax_template_cache" 或将 WP_DEBUG 设置为 true（不建议在生产环境中使用，强烈建议在开发环境中使用）。

#许可证

此插件是根据 MIT 许可证发布的。