README

介绍

这是一个用于开发WordPress插件的简单框架。

WordPress中的实体（文章类型、分类法等）被视为对象，因此创建新的实体并设置其属性与PHP中的任何对象相同。每个对象在实例化时都会将其自身与适当的WordPress动作钩子关联起来。

入门指南

Composer

该包托管在Packagist上，并准备好与Composer一起使用。只需将包添加到您的composer.json文件中。

在您的插件中使用SPF

开始使用SPF的最简单方法是为您的插件创建一个类，并在类的构造函数中放置框架代码。

class myPlugin
{
    public function __construct()
    {
        // Place SPF code in there.
    }
}

new myPlugin();

创建WordPress对象

SPF包含用于创建文章类型、分类法、页面、设置和仪表板小部件的类。这些类都继承自WordPressObject类。

WordPressObject

WordPressObject类提供了一些其他类使用的一些常用方法，并为定义您的文本域提供了一个静态属性。这是一个抽象类，不能被实例化。

文本域

要为所有WordPressObject类指定自定义文本域，请设置WordPressObject父类的静态属性$textDomain。这是可选的，文本域的默认值为'default'。

WordPressObject::$textDomain = 'my-text-domain';

getSlug()

此公共方法返回对象的slug。slug是WordPress数据库中对象的唯一标识符。此方法在框架中用于将相关对象关联起来。

echo $someObject->getSlug();

getName()

使用此公共方法获取对象的用户可读显示名称。$name属性在返回之前通过文本域传递。

echo $someObject->getName();

display()

此方法从不直接调用，而是用作WordPress对象的显示回调函数。它调用视图类的render()方法，传入对象的$viewFile和$viewData属性。

PostType

PostType类的构造函数需要创建文章类型的名称和一个slug。名称必须是复数形式，以确保正确生成标签。

PostType类的构造函数生成文章类型的标签，然后将register_post_type()函数绑定到init钩子上。

$postType = new PostType('My Post Type');

PostType 的其余属性默认设置为创建一个基本、公开的帖子类型，但可以使用设置器进行覆盖。

setDescription()

setDescription() 方法接受一个字符串。

$postType->setDescription('This is my custom post type.');

hasArchive()

hasArchive() 方法接受一个布尔值。默认为 true。

$postType->hasArchive(false);

setPublic()

setPublic() 方法接受一个布尔值。这决定了帖子类型是否显示在仪表板和网站的前端。

$postType->setPublic(false);

setMenuPosition()

setMenuPosition() 方法接受一个整数或数字字符串。数字越高，帖子类型在仪表板中的菜单项位置越高。如果您指定了一个被另一个菜单项使用的值，可能会覆盖另一个。

$postType->setMenuPosition(85);

或者...

$postType->setMenuPosition('85');

setMenuIcon()

setMenuIcon() 方法接受一个图像 URL 或 dashicon 作为字符串。

$postType->setMenuIcon('http://placehold.it/15x15');

或者...

$postType->setMenuIcon('dashicons-admin-tools');

setCapabilities()

setCapabilities() 方法接受一个字符串数组，用于管理帖子类型的权限。

包含的 Capabilities 类可以用来确保使用有效的 WordPress 权限。

默认

array(
    'edit_post'          => Capability::edit_posts,
    'read_post'          => Capability::read_posts,
    'delete_post'        => Capability::delete_posts,
    'edit_posts'         => Capability::edit_posts,
    'edit_others_posts'  => Capability::edit_others_posts,
    'publish_posts'      => Capability::publish_posts,
    'read_private_posts' => Capability::read_private_posts,
)

用法

$postType->setCapabilities($myCapabilitiesArray);

setSupports()

setSupports() 方法接受一个字符串数组，表示帖子类型支持的 WordPress 功能。您也可以传入 false 来禁用所有功能。

$postType->setSupports(['title', 'editor', 'thumbnail']``);

分类法

分类法类在实例化时需要分类法的复数显示名称和 slug。可选地，要注册分类法的帖子类型（默认为帖子）和文本域。

构造函数设置属性，生成标签，并将 register_taxonomy() 函数绑定到 init 钩子。

SPF 在添加之前检查分类法是否存在。

$taxonomy = new Taxonomy('Custom Tags', $postType->getSlug);

可以使用 addTerm() 方法向分类法中添加术语。它需要添加的术语，并可可选地接受术语描述。此方法检查术语是否已被添加，并且只有当它未被添加时才添加。它将 WordPress 函数 wp_insert_term 绑定到 init 钩子。此方法可以链式调用。

$taxonomy->addTerm('Tag One', 'This is the first tag.');

元框

可以使用此类将包含 1 个或多个自定义字段的元框添加到您的帖子类型中。对象在实例化时需要名称、附加到的帖子类型 slugs 以及一个视图文件。可选地，可以传入视图数据。

构造函数设置属性，然后将 addMetaBox() 方法绑定到 add_meta_boxes 钩子，并将 saveMetaBox() 方法绑定到 save_post 钩子。

$postTypes 参数可以是单个字符串，也可以是字符串数组，如果您想将元框绑定到多个帖子类型。

$metaBox = new MetaBox('My MetaBox', $postTypes, $viewFiles, $viewData);

类会自动处理在帖子更新时将自定义字段保存到WordPress数据库。

设置器

设置器可用于上下文和优先级属性。

setContext()

此方法设置元盒将在页面的哪个部分显示。接受的值有 'normal'、'advanced' 和 'side'。默认为 'advanced'。

$metaBox->setContext('side');

setPriority()

此方法设置在元盒将显示的上下文中的优先级。接受的值有 'high'、'core'、'default' 和 'low'。默认为 'default'。

$metaBox->setPriority('low');

自定义字段

要使用MetaBox类在元盒视图文件中的静态方法添加自定义字段。

MetaBox::CheckboxInput($name, $slug, $value, $default = '');
MetaBox::ColorInput($name, $slug);
MetaBox::DateInput($name, $slug);
MetaBox::DateTimeInput($name, $slug);
MetaBox::DateTimeLocalInput($name, $slug);
MetaBox::EmailInput($name, $slug);
MetaBox::FileInput($name, $slug);
MetaBox::HiddenInput($name, $slug);
MetaBox::MonthInput($name, $slug);
MetaBox::NumberInput($name, $slug, $step = '1');
MetaBox::PasswordInput($name, $slug);
MetaBox::RadioButtonInputs($name, $slug, $options, $displayBlock);
MetaBox::RangeInput($name, $slug, $min, $max);
MetaBox::SearchInput($name, $slug);
MetaBox::SelectInput($name, $slug, $options);
MetaBox::TelInput($name, $slug);
MetaBox::Textarea($name, $slug, $rows, $cols);
MetaBox::TextInput($name, $slug);
MetaBox::TimeInput($name, $slug);
MetaBox::UrlInput($name, $slug);
MetaBox::WeekInput($name, $slug);

页面

您可以使用MenuPage、ObjectPage、UtilityPage、SubMenuPage和OptionsPage类创建新的仪表板页面。所有页面类都继承自Page抽象类。

所有页面类在实例化时都需要一个名称、slug和视图文件，$viewData可以可选传入。slug和名称将自动添加到$viewData数组中。

基本构造函数设置参数，然后将抽象的addPage()方法绑定到admin_menu钩子。在子类中覆盖addPage()方法以使用正确的WordPress函数添加该类型的页面。

设置器

设置器可用于能力、菜单图标、位置。对于SubMenuPage，还有父slug的设置器。

setCapability()

setCapability()方法接受一个字符串，指定用户访问页面的权限级别。

包含的 Capabilities 类可以用来确保使用有效的 WordPress 权限。

$page->setCapability(Capability::manage_options);

setMenuIcon()

setMenuIcon()方法接受一个URL或dashicon的名称作为字符串。

$page->setMenuIcon('http://placehold.it/15x15');

或者...

$page->setMenuIcon('dashicons-admin-tools');

setPosition()

setPosition()方法接受一个整数或数字字符串。如果您指定了已被其他菜单图标占用的位置，它们可能会相互覆盖。

$page->setPosition(100);

或者...

$page->setPosition('100');

setParentSlug()

setParentSlug()方法仅适用于SubMenuPage类。设置父slug是必需的。它设置了SubMenuPage的父页面。它接受一个字符串值，最简单的方法是使用父页面对象的getSlug()方法。将$parentSlug设置为null以创建一个不在菜单中出现的页面。

$subMenuPage->setParentSlug($parentPage->getSlug());

页面类型

MenuPage

要添加顶级菜单页面，请使用MenuPage类。调用add_menu_page()函数。

$menuPage = new MenuPage('My Page', $myView);

ObjectPage

ObjectPage在对象级别（帖子、媒体、链接、页面、评论等）添加顶级页面。调用add_object_page()函数。

$objectPage = new ObjectPage('My Page', $myView);

UtilityPage

UtilityPage 在实用程序级别（外观、插件、用户、工具、设置等）添加顶级页面。调用 add_utility_page() 函数。

$utilityPage = new UtilityPage('My Page', $myView);

OptionsPage

OptionsPage 在设置下添加子菜单页面。调用 add_options_page 函数。

$optionsPage = new OptionsPage('My Page', $myView);

SubMenuPage

SubMenuPage 为其他页面添加一个页面作为子菜单项。调用 add_submenu_page() 函数。

$subPage = new SubMenuPage('My Sub Page', $myView);
$subPage->setParentSlug($myPage->getSlug());

Settings

SPF 的 Settings API 部分由三个类组成。Settings、SettingsSection 和 SettingsField。

SettingsField 对象代表单个设置字段，而 SettingsSection 对象代表 SettingsField 对象的集合。

Settings 对象管理 WordPress 交互以及设置将在哪一页上显示。

Settings 构造函数需要指定设置将在哪一页上显示的 slug。

$settings = new Settings($myPage->getSlug());

SettingsFields

SettingsField 构造函数需要传入一个名称、slug 和一个视图文件。也可以传入视图数据。

您必须指定字段的 slugs 的前缀，以使用 $prefix 参数帮助防止数据库中的命名冲突。

视图文件应仅包含渲染输入字段的 HTML 和逻辑。名称和 slug 会自动添加到 $viewData 属性。

$field = new SettingsField('My Field', $prefix, $viewView, $viewData);

SettingsSection

SettingsSection 类需要实例化时提供名称和 slug。可以可选地传入视图文件和视图数据。

除非您需要显示特定内容，如向用户显示说明，否则您不需要包含视图文件，因为 WordPress 会自动在页面上显示该部分的名称。

如果使用视图文件，名称会自动添加到 $viewData 属性。

$section = new SettingsSection('Section One', $viewFile, $viewData);

Adding SettingsField to SettingsSection

可以使用 addFields() 方法将单个 SettingsField 或 SettingsField 对象数组分配给 SettingsSection。

$section->addFields($field1)->addFields($field2);

或者...

$section->addFields(array($field1, $field2));

Adding SettingsSection to Settings

使用 Settings 的 addSections() 方法将 SettingsSection 对象添加到 Settings 对象。与 addFields() 类似，此方法接受单个 SettingsSection 或 SettingsSection 数组。

$settings->addSections($section1)->addSection($section2);

或者...

$settings->addSections(array($section1, $section2));

DashboardWidget

您可以使用 DashboardWidget 类向 WordPress 仪表板添加新小工具。

在实例化时，该类需要一个名称、slug 和视图文件路径。您可以在可选的 $viewData 参数中提供需要传递给视图的数据。DashboardWidget 的名称和 slug 会自动添加到 $viewData。

构造函数分配属性并将 addWidget() 方法绑定到 wp_dashboard_setup 钩子。

addWidget() 方法调用 WordPress 函数 wp_add_dashboard_widget。

$myWidget = new DashboardWidget('My Widget', $widgetView);

WelcomePanel

您可以使用这个类替换默认的WordPress欢迎面板，以自定义欢迎面板。这是通过使用welcome_panel钩子来实现的。

这个类只需要传入一个视图文件，但可以选择传入视图数据。视图文件将包含您希望欢迎面板显示的HTML。

$welcomePanel = new WelcomePanel($welcomePanelView);

视图

WordPressObject类使用包含的静态View类来显示它们的输出。每个对象都有一个display()方法，用作WordPress函数中的回调。

这个display()方法调用View::render()，传入$viewFile和$viewData属性。$viewFile属性是一个表示要使用的视图文件的完整路径和文件名的字符串。$viewData属性是一个关联数组，包含视图文件中可能需要的额外信息。

render()方法提取$viewData属性以在视图中创建变量。例如$viewData['foo']变成$foo。

视图文件至少是一个包含对象HTML输出的PHP文件。您可以在视图文件中包含尽可能少或尽可能多的逻辑。