README

Poet提供了简单的基于配置的文章类型、分类法、编辑器颜色方案、块分类、块模式和块注册/修改。

特性

• 由Extended CPTs驱动的简单文章类型和分类法注册、修改和注销。
• 易于配置的编辑器颜色方案，包括对webpack-palette-plugin的内置支持。
• 注册的块在前端使用Laravel Blade进行渲染。
• 注册的块模式可以使用Laravel Blade定义其内容。
• 只需使用slug即可添加额外的块分类。
• 使用其页面slug将父管理员菜单项移动到工具子菜单。

要求

• Sage >= 10.0
• PHP >= 7.4
• Composer

安装

通过Composer安装

$ composer require log1x/poet

入门

使用Acorn发布Poet配置文件开始

$ wp acorn vendor:publish --provider="Log1x\Poet\PoetServiceProvider"

用法

注册文章类型

所有与Poet相关的配置都位于config/poet.php中。在这里，您将找到一个预配置的示例“图书”文章类型，其中包含一些常用设置

'post' => [
    'book' => [
        'enter_title_here' => 'Enter book title',
        'menu_icon' => 'dashicons-book-alt',
        'supports' => ['title', 'editor', 'author', 'revisions', 'thumbnail'],
        'show_in_rest' => true,
        'has_archive' => false,
        'labels' => [
            'singular' => 'Book',
            'plural' => 'Books',
        ],
    ],
],

在其最简单的形式中，可以通过传递一个字符串来创建文章类型

'post' => [
    'book',
],

要修改现有的文章类型，只需将其视为创建新文章类型，只需传递您希望更改的配置选项即可

'post' => [
    'post' => [
        'labels' => [
            'singular' => 'Article',
            'plural' => 'Articles',
        ],
    ],
],

还可以通过简单地传递false来注销现有的文章类型

'post' => [
    'book' => false,
],

请注意，某些内置文章类型（例如文章）不能传统地注销。

有关文章类型的更多配置选项，请参阅

• register_post_type()
• register_extended_post_type()

注意：不要像Extended CPTs文档中显示的那样在config键中嵌套配置。

注册分类法

注册分类法与文章类型类似。查看config/poet.php，您将看到与默认“图书”文章类型一起的“类型”分类法

'taxonomy' => [
    'genre' => [
        'links' => ['book'],
        'meta_box' => 'radio',
    ],
],

最相关的配置选项是links，它定义了分类法所连接的文章类型。如果没有指定链接，则默认为post。

要查看“类型”分类法的存档，将名为archive.blade.php的Blade模板复制到名为taxonomy-genre.blade.php的新文件中。

在其最简单的形式中，您可以直接传递一个字符串。以下示例会为“文章”文章类型创建一个“主题”分类法

'taxonomy' => [
    'topic',
],

与文章类型一样，要修改现有的分类法，只需传递您希望更改的配置选项即可

'taxonomy' => [
    'category' => [
        'labels' => [
            'singular' => 'Section',
            'plural' => 'Sections',
        ],
    ],
],

与文章类型一样，您也可以轻松注销现有的分类法，只需传递false即可

'taxonomy' => [
    'post_tag' => false,
    'category' => false,
],

有关分类法的更多配置选项，请参阅

• register_taxonomy()
• register_extended_taxonomy()

注意：不要像Extended CPTs文档中显示的那样在config键中嵌套配置。

注册块

Poet提供了一种简单的方法来使用随附的Blade视图注册Gutenberg块，以在编辑器中使用，并在前端渲染该块。

块是通过在将块与编辑器注册时定义的namespace/label进行注册的。

如果没有提供命名空间，将使用当前主题的文本域。

在大多数情况下，注册一个块就像

'block' => [
    'sage/accordion',
],

创建一个块视图

给定块 sage/accordion，您相应的 Blade 视图将位于 views/blocks/accordion.blade.php。

块视图有以下变量可用

• $data – 包含块数据的对象。
• $content – 包含 InnerBlocks 内容的字符串。当为空时返回 null。

默认情况下，在检查 $content 是否为空时，它将通过一个方法传递以移除所有标签和空白，然后再进行评估。这确保了像 nbsp 或空 <p></p> 标签这样的编辑器膨胀不会导致 $content 在条件使用时总是返回 true。

如果您不希望在特定的块上使用此行为，只需将其注册为数组即可

'block' => [
    'sage/accordion' => ['strip' => false],
],

如果您需要在特定块上使用 PHP 注册块属性，只需在注册时传递一个数组即可

'block' => [
    'sage/accordion' => [
        'attributes' => [
            'title' => [
                'default' => 'Lorem ipsum',
                'type' => 'string',
            ],
        ],
    ],
],

考虑一个注册了 title 和 className 属性的折叠块。您的视图可能看起来像这样

<div class="wp-block-accordion {{ $data->className ?? '' }}">
  @isset ($data->title)
    <h2>{!! $data->title !!}</h2>
  @endisset

  <div>
    {!! $content ?? 'Please feed me InnerBlocks.' !!}
  </div>
</div>

注册块类别

Poet 提供了一种简单的方法来注册、修改和注销 Gutenberg 块类别。查看配置，您将看到针对调用行动类别的一个注释示例

'block_category' => [
    'cta' => [
        'title' => 'Call to Action',
        'icon' => 'star-filled',
    ],
],

这将导致一个具有 cta slugs 的块类别。一旦您的块类别注册，您必须将一个块注册到其 slugs 中，然后类别才会出现在编辑器中。

在其最简单形式中，您可以简单地传递一个字符串

'block_category' => [
    'my-cool-blocks',
],

这将导致 my-cool-blocks 类别自动将 slugs 转换为大写字母。

您还可以通过传递一个值到您的 slugs 来指定标题

'block_category' => [
    'my-cool-blocks' => 'Best Blocks, World.',
],

与帖子类型和分类法一样，修改现有的块类别与注册一个是一样的

'block_category' => [
    'layouts' => 'Sections',
    'common' => ['icon' => 'star-filled'],
],

您可以通过简单地传递 false 来注销现有的块类别

'block_category' => [
    'common' => false,
],

注册块模式

Poet 还可以为您注册块模式，并可选地提供内容 Blade 视图。

模式使用在向编辑器注册模式时定义的 namespace/label 注册。

如果没有提供命名空间，将使用当前主题的文本域。

在大多数情况下，注册一个块就像

'block_pattern' => [
    'sage/hero' => [
        'title' => 'Page Hero',
        'description' => 'Draw attention to the main focus of the page, and highlight key CTAs',
        'categories' => ['all'],
    ],
],

您还可以在这里注册模式的实际内容，使用 content 键。或者留空以使用相应的 blade 视图。

'block_pattern' => [
    'sage/fake-paragraph' => [
        'title' => 'Fake Paragraph',
        'description' => 'Filler content used instead of actual content for testing purposes',
        'categories' => ['all'],
        'content' => '<!-- wp:paragraph --><p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ratione nulla culpa repudiandae nisi nostrum et, labore earum repellendus porro, mollitia voluptas quam? Modi sint tempore deleniti nesciunt ab, perferendis et.</p><!-- /wp:paragraph -->',
    ],
],

创建模式视图

给定块 sage/fake-paragraph，如果没有定义 content 键，那么您的相应 Blade 视图将位于 views/block-patterns/fake-paragraph.blade.php。

这个块模式视图可能看起来像这样

<!-- wp:paragraph -->
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ratione nulla culpa repudiandae nisi nostrum et, labore earum repellendus porro, mollitia voluptas quam? Modi sint tempore deleniti nesciunt ab, perferendis et.</p>
<!-- /wp:paragraph -->

注册块模式类别

您可以在诗人配置中添加以下代码来添加块模式类别

'block_pattern_category' => [
    'all' => [
        'label' => 'All Patterns',
    ],
],

您可以根据需要指定所有类别属性，如 label，请参阅块编辑器手册。

注意：目前，如果没有可用的块模式类别，当点击编辑器中的块模式选项卡时，编辑器会崩溃。

注册编辑器调色板

Poet 通过不要求这样严格、脆弱的数组标记来简化使用编辑器注册调色板。

虽然您当然可以直接传递数组，但您也可以通过传递一个包含颜色和颜色的 slug 来注册颜色，让 Poet 处理其余部分。

'palette' => [
    'red' => '#ff0000',
    'blue' => '#0000ff',
],

作为传递数组的替代，Poet 还接受一个包含您的颜色调色板的 JSON 文件。Poet 默认会在 dist/ 中查找此文件。

'palette' => 'colors.json',

如果您正在使用 Palette Webpack 插件，您也可以在构建过程中简单地传递 true 来自动使用生成的 palette.json。

'palette' => true,

错误报告

如果您在 Poet 中发现错误，请 打开一个问题。

贡献

鼓励并感谢通过提交 PR、报告问题或提出想法的方式进行贡献。

许可证

Poet 在 MIT 许可证 下提供。