README

使用简单、现代的界面扩展文章元字段/选项。

安装

通过composer

> composer require gebruederheitz/wp-easy-post-options

确保您有Composer自动加载或替代类加载器。

使用

此包提供了一组接口、抽象类和处理类，简化了在Wordpress中为文章或页面添加“文章元”的功能。

为了启用基本功能，您必须加载初始化类，在您的functions.php或控制器类或容器模块的任何地方

\Gebruederheitz\Wordpress\PageOrPostOption\PageOrPostOptions::init();

创建元框

每个自定义选项都需要添加到元框中（可以包含多个选项）。要轻松创建元框，请使用AbstractMetabox类

use Gebruederheitz\Wordpress\PageOrPostOption\AbstractMetabox;

class SocialLinksMetabox extends AbstractMetabox 
{
    
    public function getKey(): string 
    {
        // give this metabox a unique identifier
        return 'ghwp-social-links';
    }
    
    public function getTitle(): string 
    {
        // This title will be visible to the user
        return 'Social Links';
    }
}

限制元框显示的文章类型

默认情况下，元框显示类型为'文章'和'页面'的所有文章。您可以通过声明静态类属性$postTypes来自定义此行为

use Gebruederheitz\Wordpress\PageOrPostOption\AbstractMetabox;

class SocialLinksMetabox extends AbstractMetabox 
{
    
    // Not available on pages, but on all regular posts and all posts of the 
    // custom "my-custom-post-type" type.
    protected static $postTypes = ['post', 'my-custom-post-type'];
    
    public function getKey(): string 
    {
        return 'ghwp-social-links';
    }
    
    public function getTitle(): string 
    {
        return 'Social Links';
    }
}

更改元框显示的位置

同样，您可以通过提供静态类属性$context来自定义元框的位置，设置为side、normal或advanced（归咎于WordPress，而不是我！）

use Gebruederheitz\Wordpress\PageOrPostOption\AbstractMetabox;

class SocialLinksMetabox extends AbstractMetabox 
{
 
    protected static $context = 'advanced';
        
    public function getKey(): string 
    {
        return 'ghwp-social-links';
    }
    
    public function getTitle(): string 
    {
        return 'Social Links';
    }
}

添加文章选项

创建元框后，您可以为它添加设置。最快的方式是扩展AbstractPageOrPostOption

use Gebruederheitz\Wordpress\PageOrPostOption\AbstractPageOrPostOption;

class FacebookUrlPageOption extends AbstractPageOrPostOption 
{

    /** 
     * @var bool
     * @optional
     * You can set this to `true` to automatically have the "wp-link" script
     * enqueued – otherwise you can leave it out.  
     */
    protected static $hasLinks = false;

    /** 
     * @var string 
     * @required
     * A unique identifier for this setting, which will be used in the 
     * database amongst * others.
     */
    protected static $key = 'ghwp-social-facebook-url';

    /** 
     * @var string
     * A label to show the user next to the input field. When using MetaForms, 
     * this * will be automatically translated. It is strongly recommended you 
     * set this * attribute, especially if you dont' plan to override the 
     * default render method. 
     */
    protected static $inputLabel = 'Facebook URL';
}

然后，确保在某个地方实例化该类（通常是在您的functions.php中），以及元框应该包含输入的地方

use Gebruederheitz\Wordpress\PageOrPostOption\NonceField;

$socialBox = new SocialLinksMetaBox();
new FacebookUrlPageOption($socialBox, NonceField::getInstance());

对于基本的文本输入字段，就这样，您就完成了。然后您可以通过调用自定义类的静态getValue()方法来检索值

$facebookUrl = FacebookUrlPageOption::getValue($post->ID);

使用复选框字段显示布尔选项

库提供另一个小助手来显示简单的复选框字段

use Gebruederheitz\Wordpress\PageOrPostOption\AbstractBooleanPageOrPostOption;

class MyCheckboxField extends AbstractBooleanPageOrPostOption
{
    /** @var string */
    protected static $key = 'ghwp-my-checkbox';

    /** @var string */
    protected static $inputLabel = 'Checkbox';
}

修改输入和值解析

为了自定义渲染到元框中的表单控件，您可以覆盖基类的render()方法。

use Gebruederheitz\Wordpress\PageOrPostOption\AbstractPageOrPostOption;
use Gebruederheitz\Wordpress\MetaFields\MetaForms;

class BackgroundImagePageOption extends AbstractPageOrPostOption 
{
    protected static $key = 'ghwp-background-image';
    
    // We define a second key for convenience
    protected static $urlKey = 'ghwp-background-image-url';

    protected static $inputLabel = 'Background image';
    
    /**
     * Called when the meta box is being rendered in WP admin
     */
    public function render(WP_Post $post): void
    {
        // make sure you call the nonce field's render method at least once for
        // every page containing page options
        $this->nonceField->render();
        
        // we retrieve the original value
        $rawValue = $this->getValue($post->ID);
        $value = is_string($rawValue) 
            ? json_decode($rawValue) 
            : (object) ['id' => '', 'url' => ''];

        // ...and then render our input field. You could use the MetaForms library
        // from gebruederheitz/wp-meta-fields, output some raw HTML or include
        // a PHP or Twig template.
        MetaForms::makeMediaPicker()
            ->setIdFieldName(self::$key)
            ->setUrlFieldName(self::$urlKey);
            ->setLabel(self::$inputLabel)
            ->setIdFieldValue($value->id)
            ->setUrlFieldValue($value->url)
            ->render();
    }
    
     /**
     * @param ?array<string, mixed> $data The POST data submitted from wp admin
     */
    public function onChange(int $postId, ?array $data): void
    {
        $rawId = $data[static::$key] ?? null;
        $rawUrl = $data[static::$urlKey]
        // this is where you should do some validation and sanitization
        $value = json_encode([
            'id' => (int) $rawId,
            'url' => $rawUrl,
        ]);   

        update_post_meta($postId, static::getMetaKey(), $value);
    }
}

注意：wp-easy-post-options和adretto-extension-simple-post-options

此包与sillynet/adretto-extension-simple-post-options并行开发和维护，后者提供相同的基本功能，但编写为嵌入Adretto微框架（一个正在进行的项目）。未来，这两个包中的一个可能会大量重用另一个包的大部分代码，以避免大规模的代码重复。然而，这很可能不会影响任何项目的公共API。

开发

依赖关系

• PHP >= 7.3
• Composer 2.x
• NVM和nodeJS LTS（v16.x）
• 理想情况：GNU Make（或直接替代品）