README

此插件是为希望向其主题添加简单功能标志的WordPress主题开发者设计的。这些标志可以通过管理员界面启用，按用户或组进行预览，甚至可以通过查询字符串为无账户的人启用。有关计划中的开发工作，请参阅路线图或带有增强标签的问题。

内容

1. 安装
2. 向主题添加标志
3. 启用标志
4. 标志组
5. 简码
6. 贡献

安装

将此项目的源代码添加到您的wp-content/plugins目录中，并像启用任何其他插件一样启用它。它也可以通过Packagist使用composer。

composer require jamesrwilliams/flagpole

目前，此插件不可通过WordPress插件目录获得，但我们正在努力在v1.0.0中实现这一点。

必需的主题更改

由于此插件与您的主题代码紧密耦合，因此建议您在主题中添加以下块以捕获Flagpole插件因任何原因被禁用时可能出现的错误。

if ( ! function_exists( 'flagpole_flag_enabled' ) ) {
	function flagpole_flag_enabled() {
		return false;
	}
}

注册标志

要注册标志，只需将以下内容添加到主题的functions.php文件中，使用flagpole_register_flag函数。

if ( function_exists( 'flagpole_register_flag' ) ) {
	flagpole_register_flag([
		'title'       => 'My awesome new feature',
		'key'         => 'correct-horse-battery-staple',
		'enforced'    => false,
		'label'       => 'All',
		'description' => 'An example feature definition',
		'stable'      => false,
	]);
}

将注册函数调用包裹在function_exists中可以帮助避免插件因任何原因被禁用时出现错误。您还可以传递一个标志数组到flagpole_register_flag以一次性轻松实例化多个标志。

检查标志状态

在您的模板中，您可以使用PHP主题代码中的flagpole_flag_enabled函数来检查功能状态，并根据标志的状态切换功能。

if ( flagpole_flag_enabled( 'flag_key' ) ) {
	/* flag_key is enabled! */
}

将flag_key替换为在flagpole_register_flag函数中使用的键，以检查它是否已启用。

标志选项/参数

启用标志

使用 Flagpole，有三种方法可以启用标志。这些是

• 预览 - 仅对当前登录用户启用标志。
• 发布 - 对网站上的每个访问者启用标志。
• 强制 - 默认在主题中启用的标志。

预览

可以通过在 Flagpole 管理屏幕中启用预览来为当前登录用户预览标志。

导航到位于工具 > Flagpole 下的 WP 管理仪表板中的 Flagpole 屏幕。找到您希望启用的标志，并单击“启用预览”按钮。

此标志现在将为此用户启用，直到再次切换。用户可以同时预览任意数量的标志。要同时预览多个标志，请查看 标志组。

发布

发布标志将使其对访问您网站的每个用户启用，包括注销用户。只要将标志注册块中的 stable 属性设置为 true 以标记为稳定，任何用户都可以发布功能。这充当了一个安全网，允许主题开发者标记功能已准备好发布。

例如：

flagpole_register_flag([
	'title'       => 'Feature ready for publication',
	'key'         => 'super-awesome-navigation-change',
	'stable'      => true,
]);

强制

强制标志是开发者可以强制标志处于发布状态的地方。他们可以通过将标志选项中的 'enforced' 选项设置为 true 来通过源代码启用标志。强制标志背后的理念是在从主题中删除标志逻辑之前的一个步骤。强制标志在管理员区域中显示在单独的列表中，并且对管理员区域中的用户不具交互性。

flagpole_register_flag([
	'title'       => 'An enforced flag',
	'key'         => 'enforced-flag',
	'enforced'    => true,
]);

标志组

标志组是一次管理多个标志的方法。您可以像单个标志一样预览标志组，并使用 group URL 参数以及您希望启用的组密钥。一个 private 组将要求用户在激活标志之前登录到网站。

您可以通过在 WP 管理中启用它来预览标志组，就像您为单个标志所做的那样，或者您可以使用查询字符串方法来启用一组标志，以下查询字符串格式： ?group={groupKey}

示例

https://www.example.com?group=battery-horse-staple

短代码

此插件添加了多个实用短代码，以帮助调试 Flagpole 标志的使用。

• debugFlagpole_flags
• debugFlagpole_groups
• debugFlagpole_db

debugFlagpole_flags

默认情况下，简码会显示在您的主题中找到的所有未强制执行的标志。您还可以使用标志参数指定您希望调试的特定标志，如下所示，可以使用单个键或逗号分隔的列表

基本用法

// Single Key
echo do_shortcode('[debugFlagpole_flags]');

这将显示当前在活动主题中找到的所有非强制执行标志的表格，包括状态以及如果它们被启用，原因。

如果您不想显示所有内容，可以指定单个或多个标志。

// Multiple keys
echo do_shortcode('[debugFlagpole_flags flag="key-1,key-2,key-3"]');

传递enforced值将显示所有enforced标志而不是其他标志。例如

echo do_shortcode('[debugFlagpole_flags enforced="true"]');

debugFlagpole_groups

使用以下简码以获取标志组的调试输出。

echo do_shortcode('[debugFlagpole_groups]');

debugFlagpole_db

使用以下简码以获取所有内容的调试输出！

echo do_shortcode('[debugFlagpole_db]');

贡献

非常欢迎所有PR和提议，包括对问题的想法和讨论。