README

Vendi 使用此库以及 Advanced Custom Fields (ACF) 弹性内容布局系统来管理单个组件。从技术上来说，这个库实际上对 ACF 完全不了解，实际上它也用于管理 WordPress 部分。

全局函数

组件加载器导出几个函数到全局命名空间，以便于主题化时的使用。可以通过查看此文件来找到全局函数的列表，但它们的格式都是 vendi_load_XYZ_component 或 vendi_load_XYZ_component_with_state，其中 XYZ 可以是 loop、page、site、component 或 sub-component。 (是的，这意味着有一个名为 vendi_load_component_component 的函数，其中一致性胜过尴尬的命名。);

文件夹位置

所有组件必须位于名为 page-parts 的文件夹内的特别命名的文件夹中，而该文件夹本身必须位于主题的根文件夹中。特别命名的文件夹与 全局函数 部分中列出的相同：loop、page、site、component 和 sub-component。

文件夹/组件类型

这五个特别命名的文件夹没有明确的用途，并且如果选择不遵循此处概述的图案，系统也不会出错。有时主题开发者会根据其构建方式和演变方式偏离此模式。

一般来说，这些是五种文件夹类型及其用途。请参阅 附加文件夹类型 以获取更多自定义信息。

site
- site 文件夹旨在存放“外壳”内容，例如在大多数页面上都可以找到的页眉、页脚、面包屑和英雄横幅。
page
- page 文件夹旨在存放单个特定页面，例如 404、搜索和首页。
loop
- loop 文件夹与 page 文件夹非常相似，但旨在存放带有 WordPress 循环代码的特定页面。
component
- component 文件夹通常用于存放 ACF 弹性内容布局，但有时也包含其他由 ACF 无法控制的类似组件的东西。
sub-component
- 与其他文件夹不同，这个文件夹只能与 state 参数一起使用。该文件夹旨在存放由多个组件使用的模板，例如页眉或正文副本。

函数参数

上面的 sub-component 文件夹是在版本 1.5 中引入的，并且只支持以下提到的 state 版本。

模板名称

每个函数都接受一个参数，作为要加载的模板的名称。传递给此参数的参数不得包含文件扩展名。例如，vendi_load_page_component('404') 将加载文件 /page-parts/page/404.php。此参数是必需的。

子文件夹

每个函数接受一个可选参数，允许您指定一个子文件夹，相对于类型文件夹，从中加载模板。如果您使用基于状态的函数（请参阅 具有状态的组件），这是第三个参数，否则是第二个。例如，vendi_load_site_component('404', 'heros') 将加载文件 /page-parts/site/herps/404.php。

状态

名称中包含_with_state的函数允许将数组作为第三个参数传递，该数组将被用于填充一个仅在该模板包含时存在的全局变量。例如，vendi_load_site_component_with_state('404', ['abc' => 'xyz'], 'heros')将加载文件/page-parts/site/herps/404.php并将一个名为$vendi_component_object_state的全局数组变量填充为一个键名为abc，其值为xyz。更多详情请参阅带有状态的组件。

带有状态的组件

每个全局函数都有一个包含可选全局状态参数的版本，这允许您有效地将参数传递到包含的文件中。您提供给状态参数的值必须是一个数组，它将被设置在名为$vendi_component_object_state的全局变量上。模板文件本身负责对此全局变量进行操作，否则不会进行隐式使用。

注意：全局变量$vendi_component_object_state应始终被视为只读，并且不应写入。每次模板加载都会备份当前的全局变量，包含模板，然后将全局变量重置，以允许嵌套调用。正因为如此，直接写入此变量几乎永远不会按预期工作。

在版本1.5中，引入了一个新的子组件文件夹，它旨在仅用于基于状态的组件。并非所有具有状态的组件都必须居住在那里，这也不是最佳实践。请根据文件放置位置对未来的网站开发者最明显，自行决定。

缺失的文件

如果找不到模板或无法读取模板，将发送带有必要调试信息的HTML注释。注释的形式为：。

没有阶段/实时/生产/dev等概念，并且如果无法读取模板，则始终会发出此消息。

调试和操作

最简单的调试方法是在缺失的文件部分中提到的HTML注释中查找。

操作：加载模板

在模板加载之前，将触发自定义WordPress操作vendi/component-loaded/loading-template。由于这是一个操作，您无法停止模板加载，但至少可以记录或检查即将加载的内容。

此操作接收三个参数，正在加载的模板文件名、模板的相对文件夹路径和模板文件的绝对路径。它可以使用以下方法钩入：

add_action(
    'vendi/component-loaded/loading-template',
    static function($name, $folders, $path) {
        // Do something here
    },
    10,
    3
);

使用此操作的例子是如果您想审计组件被加载在每一个页面上。如果您想获取这个代码的示例，请联系Vendi。

操作：缺失模板

如果找不到模板，在发出HTML注释之前，将触发自定义WordPress操作vendi/component-loaded/missing-template。由于这是一个操作，您无法停止HTML注释的发出，但可以执行自己的附加逻辑。

此操作接收三个参数，正在加载的模板文件名、模板的相对文件夹路径和模板文件的绝对路径。它可以使用以下方法钩入：

add_action(
    'vendi/component-loaded/missing-template',
    static function($name, $folders, $path) {
        // Do something here
    },
    10,
    3
);

使用此操作的例子是如果您想自动为新创建的ACF布局创建模板文件，并预先填充内容，使其明显需要进一步的工作。我们特别建议在开发早期阶段这样做。如果您想获取这个代码的示例，请联系Vendi。

其他文件夹类型

为了简化，这个库只公开了五个主要组件类型，这些类型被大多数网站广泛使用。如果您想使用其他特定类型，您可以轻松实现它，只需创建一个自己的函数，该函数调用通用函数 Vendi\Shared\WordPress\VendiComponentLoader::load_component_by_folder()。此函数接受三个参数，模板名称（必需），一个相对于主题根目录的文件夹数组（必需），以及任何附加的对象状态（可选）。

注意：第二个参数是一个相对于主题根目录的子文件夹数组，默认情况下不包括 page-parts 文件夹。要使用它，请将 VendiComponentLoader::SHARED_PARENT_FOLDER 作为数组中的第一个参数。您还可以传递路径遍历参数，如 ..，以跳出主题文件夹，但请确保对您提供的内容进行 过滤和清理，以免引入漏洞或泄露私有数据！

注意：组件加载器旨在以简单的方式组织代码。虽然它还允许进一步的文件夹自定义，但我们鼓励开发者在没有提供具体好处的情况下不要过度思考组织。仅仅为了创建文件夹而创建文件夹可能会导致开发体验不佳，尤其是在团队新成员加入时。

示例

如果您想将“视频”视为一等类型，您可以创建以下函数

use Vendi\Shared\WordPress\VendiComponentLoader;

function YOUR_PREFIX_load_video_component(string $name)
{
    VendiComponentLoader::load_component_by_folder($name, [VendiComponentLoader::SHARED_PARENT_FOLDER, 'video']);
}

这将从 /page-parts/video/ 加载模板。

vensi-advertising / vensi-component-loader

维护者

详情