40q/acf-gutenberg

ACF Gutenberg

维护者

详细信息

github.com/40Q/acf-gutenberg

源代码

问题

安装次数: 3,563

依赖: 1

建议: 0

安全: 0

星标: 9

关注者: 7

分支: 3

开放问题: 0

类型:package

v3.0.2 2021-05-06 17:59 UTC

Requires

Requires (Dev)

Suggests

MIT 80a3b0242ed9df3cd73552130f87972fdda3def6

  • José Debuchy <jdebuchy.woop@40q.com.ar>
  • Pablo Capello <pcapello.woop@40q.com.ar>

This package is auto-updated.

Last update: 2024-09-07 01:18:05 UTC

README

⚠️ 注意‼️ 如果您曾使用这个存储库作为插件，请参考版本 1。该项目已停止开发，以支持此 Composer 包。

ACF Gutenberg 是一个基于 Log1x ACF-Composer 和 StoutLogic's ACF Builder 的优秀项目，并进行了一些适配以符合我们的工作流程的 Composer 包。

  • 使用部分组件作为块的主要包装器。
  • 块的 slug 使用不同的逻辑。
  • 我们在视图中包含变量，并且我们可以直接调用它而不使用块对象（使用 $variable 而不是 $block->variable）。
  • 默认创建全局选项。

特性

  • 🔥 鼓励使用 Sage 10 和 ACF 创建字段时的清晰结构。
  • 🔥 立即生成可工作的字段、块、小部件和选项页面。电池包含在内。
  • 🔥 立即生成可重用的字段组部分。
  • 🔥 使用 Blade 完全渲染块和小部件，以传递视图数据，具有原生 Sage 10 感觉。
  • 🔥 如果安装了 ACF v5.9.0+，则自动生成支持 <InnerBlocks /> 的块。
  • 🔥 自动将小部件与 WP_Widget 钩子连接，使其立即可用于使用。
  • 🔥 自动设置块、小部件和选项页面上的字段位置。
  • 🔥 全局设置默认字段类型和字段组设置。不再需要在每个选择字段上重复 ['ui' => 1]。

要求

安装

通过 Composer 安装

$ composer require 40q/acf-composer

用法

入门

首先使用 Acorn 发布 config/acf.php 配置文件

$ wp acorn vendor:publish --provider="AcfGutenberg\Providers\AcfComposerServiceProvider"

生成字段

要创建第一个字段，请从主题目录运行以下生成器命令

$ wp acorn acf:field Example

这将创建 src/Fields/Example.php，您将在其中创建和管理第一个字段组。

查看生成的 Example.php 模板，您会注意到它有一个简单的列表配置。

<?php

namespace App\Fields;

use AcfGutenberg\Field;
use StoutLogic\AcfBuilder\FieldsBuilder;

class Example extends Field
{
    /**
     * The field group.
     *
     * @return array
     */
    public function fields()
    {
        $example = new FieldsBuilder('example');

        $example
            ->setLocation('post_type', '==', 'post');

        $example
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $example->build();
    }
}

接下来检查字段的 添加帖子 以确保一切按预期工作 - 然后 开始工作。

生成字段部分

字段部分由可以重复使用和/或添加到现有字段组的字段组组成。

首先，让我们生成一个名为 ListItems 的部分，我们可以在上面生成的 Example 字段中使用它。

$ wp acorn acf:partial ListItems
<?php

namespace App\Fields\Partials;

use AcfGutenberg\Partial;
use StoutLogic\AcfBuilder\FieldsBuilder;

class ListItems extends Partial
{
    /**
     * The partial field group.
     *
     * @return array
     */
    public function fields()
    {
        $listItems = new FieldsBuilder('listItems');

        $listItems
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $listItems;
    }
}

查看 ListItems.php，您会发现它默认包含与生成的字段中相同的列表重复器。

与普通字段相比的一个关键区别是省略了 ->build() 而返回 FieldsBuilder 实例本身。

这可以通过将 ::class 常量传递给 ->addFields() 来在我们的 Example 字段中使用。

<?php

namespace App\Fields;

use AcfGutenberg\Field;
use StoutLogic\AcfBuilder\FieldsBuilder;
use App\Fields\Partials\ListItems;

class Example extends Field
{
    /**
     * The field group.
     *
     * @return array
     */
    public function fields()
    {
        $example = new FieldsBuilder('example');

        $example
            ->setLocation('post_type', '==', 'post');

        $example
            ->addFields($this->get(ListItems::class));

        return $example->build();
    }
}

生成块

生成块通常与上面的字段生成相同。

首先使用 Acorn 创建块字段

$ wp acorn acf:block Example
<?php

namespace App\Blocks;

use AcfGutenberg\Block;
use StoutLogic\AcfBuilder\FieldsBuilder;

class Example extends Block
{
    /**
     * The block name.
     *
     * @var string
     */
    public $name = 'Example';

    /**
     * The block description.
     *
     * @var string
     */
    public $description = 'Lorem ipsum...';

    /**
     * The block category.
     *
     * @var string
     */
    public $category = 'common';

    /**
     * The block icon.
     *
     * @var string|array
     */
    public $icon = 'star-half';

    /**
     * Data to be passed to the block before rendering.
     *
     * @return array
     */
    public function with()
    {
        return [
            'items' => $this->items(),
        ];
    }

    /**
     * The block field group.
     *
     * @return array
     */
    public function fields()
    {
        $example = new FieldsBuilder('example');

        $example
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $example->build();
    }

    /**
     * Return the items field.
     *
     * @return array
     */
    public function items()
    {
        return get_field('items') ?: [];
    }
}

在运行区块生成器时，与普通字段的一个区别是会在resources/views/blocks目录中生成一个伴随的View。

@if ($items)
  <ul>
    @foreach ($items as $item)
      <li>{{ $item['item'] }}</li>
    @endforeach
  </ul>
@else
  <p>No items found!</p>
@endif

<div>
  <InnerBlocks />
</div>

类似于字段生成器，示例区块包含一个简单的列表重复器，并且可以直接使用。

生成小部件

使用ACF Composer创建侧边栏小部件非常简单。小部件会自动加载和渲染，并注册到WP_Widget，这通常很烦人。

首先使用Acorn创建一个小部件

$ wp acorn acf:widget Example
<?php

namespace App\Widgets;

use AcfGutenberg\Widget;
use StoutLogic\AcfBuilder\FieldsBuilder;

class Example extends Widget
{
    /**
     * The widget name.
     *
     * @var string
     */
    public $name = 'Example';

    /**
     * The widget description.
     *
     * @var string
     */
    public $description = 'Lorem ipsum...';

    /**
     * Data to be passed to the widget before rendering.
     *
     * @return array
     */
    public function with()
    {
        return [
            'items' => $this->items(),
        ];
    }

    /**
     * The widget title.
     *
     * @return string
     */
    public function title() {
        return get_field('title', $this->widget->id);
    }

    /**
     * The widget field group.
     *
     * @return array
     */
    public function fields()
    {
        $example = new FieldsBuilder('example');

        $example
            ->addText('title');

        $example
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $example->build();
    }

    /**
     * Return the items field.
     *
     * @return array
     */
    public function items()
    {
        return get_field('items', $this->widget->id) ?: [];
    }
}

与区块类似，小部件也会在resources/views/widgets中生成一个视图。

@if ($items)
  <ul>
    @foreach ($items as $item)
      <li>{{ $item['item'] }}</li>
    @endforeach
  </ul>
@else
  <p>No items found!</p>
@endif

默认情况下，示例小部件可以立即使用，并应该出现在后端。

生成选项页面

创建选项页面类似于创建常规字段组，此外还有一些可用于自定义页面（其中大多数是可选的）的配置选项。

首先使用Acorn创建一个选项页面

$ wp acorn acf:options Example
<?php

namespace App\Options;

use AcfGutenberg\Options as Field;
use StoutLogic\AcfBuilder\FieldsBuilder;

class Example extends Field
{
    /**
     * The option page menu name.
     *
     * @var string
     */
    public $name = 'Example';

    /**
     * The option page document title.
     *
     * @var string
     */
    public $title = 'Example | Options';

    /**
     * The option page field group.
     *
     * @return array
     */
    public function fields()
    {
        $example = new FieldsBuilder('example');

        $example
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $example->build();
    }
}

可选地，您可以将--full传递给上述命令以生成包含附加配置示例的占位符。

$ wp acorn acf:options Options --full

完成之后，您应该可以在后端看到一个选项页面。

注册的所有字段都将自动设置为其位置。

默认字段设置

ACF Composer我最喜欢的功能之一是能够设置字段类型以及字段组默认值。当然，任何全局设置的默认值都可以通过在单个字段上设置来覆盖。

全局

查看config/acf.php，您将看到一些预先配置的默认值。

'defaults' => [
    'trueFalse' => ['ui' => 1],
    'select' => ['ui' => 1],
],

当将trueFalse和select的ui设置为默认值1时，就不再需要在字段上重复设置'ui' => 1。这将在全局范围内生效，并且可以通过在字段上设置不同的值来覆盖。

字段组

还可以为单个字段组定义默认值。这是通过在字段类中简单地定义$defaults来完成的。

/**
 * Default field type settings.
 *
 * @return array
 */
protected $defaults = ['ui' => 0];

我的默认值

以下是我个人使用的一些默认值。任何以acfe_前缀开头都与ACF Extended相关。

'defaults' => [
    'fieldGroup' => ['instruction_placement' => 'acfe_instructions_tooltip'],
    'repeater' => ['layout' => 'block', 'acfe_repeater_stylised_button' => 1],
    'trueFalse' => ['ui' => 1],
    'select' => ['ui' => 1],
    'postObject' => ['ui' => 1, 'return_format' => 'object'],
    'accordion' => ['multi_expand' => 1],
    'group' => ['layout' => 'table', 'acfe_group_modal' => 1],
    'tab' => ['placement' => 'left'],
    'sidebar_selector' => ['default_value' => 'sidebar-primary', 'allow_null' => 1]
],

错误报告

如果您在ACF Composer中发现错误，请提交问题。

贡献

鼓励并感谢通过PR、报告问题或提出建议来做出贡献。

许可

ACF Composer在MIT许可下提供。