README

ACF Codifier

• 贡献者: devgeniem / Nomafin
• 标签: wordpress, acf
• 最低要求: 4.6.0
• 测试到: 5.6.3
• 许可: GPL-3.0 或更新版本
• 许可 URI: https://gnu.ac.cn/licenses/gpl-3.0.html

描述

一个辅助类，使在代码中定义 ACF 字段组和字段更容易。

类的完整文档可以在 此处 找到。

安装

推荐使用 Composer 安装 ACF Codifier

$ composer require devgeniem/acf-codifier

或者在您的 composer.json 中添加它

{
  "require": {
    "devgeniem/acf-codifier": "*"
  }
}

使用 Composer 安装插件需要 Bedrock 的自动加载器。它作为 mu-plugin 安装，不需要激活。

但是，您也可以将其作为普通插件安装。有两种方法可以实现

• 将此存储库克隆到您的 plugins 目录，然后在存储库文件夹中运行 composer install --no-dev。

• 在此处下载最新版本 此处 并将存档提取到您的 plugins 目录。

使用方法

Codifier 的所有类都位于命名空间 Geniem\ACF 下。为了方便，最好将您的声明放在单独的文件中，并在顶部声明 namespace Geniem\ACF;。本 ReadMe 的其余部分假定您已经这样做。

创建字段组。

字段组位于名为 Group 的类中。因此，可以使用以下方式创建新组：

$field_group = new Group( 'Field Group' );

这将创建一个具有“字段组”标题和“field-group”键的新字段组。

如果您想自己定义键，可以将它作为构造函数的第二个参数提供，或者使用

$field_group->set_key( 'new_key' );

您还可以稍后使用 set_title() 方法更改组的标题。

还有定义字段组其他属性的方法。所有字段组命令都可以链式调用。例如

$field_group->set_position( 'side' )         // Set the field group to be shown in the side bar of the edit screen.
            ->set_style( 'seamless' )        // Set the field group to show as seamless.
            ->hide_element( 'the_content' ); // Hide the native WP content field.

很少有人想在 WordPress 安装中的每个编辑屏幕中显示他们的字段组。可见性规则由它们自己的类 RuleGroup 处理。可以像这样创建和链接规则组：

$rule_group = new RuleGroup();
$rule_group->add_rule( 'post_type', '==', 'page' );

$field_group->add_rule_group( $rule_group );

您可以向规则组添加多个规则，并且组内的每个规则都被视为一个 'and'。如果您向字段组添加多个规则组，则被视为 'or'。

使用 register 方法注册字段组以使用

$field_group->register();

显然，您的新的字段组现在还没有任何字段，但不要担心，我们稍后会讨论它们。

类的全面文档可以在 此处 找到。

创建字段

像字段组一样，字段也是它们自己的对象。它们位于以它们的字段类型命名的类中。例如，可以使用以下方式创建文本字段：

$text = new Field\Text( 'Text field' );

现在，$text 变量已填充了一个标签为“文本字段”且键和名称均为“text-field”的文本字段。

键和名称也可以作为其第二个和第三个参数分别传递给构造函数。显然，像组一样，也提供了 set_key() 和 set_name() 方法。

插件会检查字段键在项目中的唯一性，并在发生冲突时触发通知。

每个字段类型都具有自己的方法来定义其属性。就像字段组一样，它们也可以与字段一起链式调用。

$text->set_placeholder( 'Placeholder text' ) // Set a placeholder text.
     ->set_append( 'Appendable' )            // Set an appending text.
     ->set_maxlength( 30 );                  // Set the maxlength.

ACF的条件逻辑组与组的定位规则非常相似。首先，您需要从 ConditionalLogicGroup 创建一个对象，并在其中添加规则。

$conditional_logic = new ConditionalLogicGroup();
$conditional_logic->add_rule( 'another_field', '==', true );

$text->add_conditional_logic( $conditional_logic );

'and' 和 'or' 之间的逻辑与组的定位规则相同。

可以使用 add_field 方法将字段添加到字段组中。

$field_group->add_field( $text );

通常 add_field 将字段添加到字段组的末尾。如果要将字段插入到最前面，请附加一个值为 first 的第二个参数。

$field_group->add_field( $text, 'first' );

您还可以使用以下方法在字段组中在另一个字段之后或之前插入字段。

$field_group->add_field_before( $text, 'target_field_key' );
$field_group->add_field_after( $text, $target_field_object );

您可以使用字段键或字段对象使用这两种方法。

还有像 add_fields() 这样的方法可以一次性添加一个字段数组，以及 add_fields_from()，它接受另一个 groupable 对象（例如字段组、组字段、重复器或灵活布局）作为其第一个参数，并将其字段复制到调用对象。

$field_group->add_fields_from( $repeater );

所有字段类型及其方法列表可以在 这里 找到。

分组字段类型

有一些特殊的字段类型可以在其中包含子字段。

组和重复器

组和重复器字段是分组字段类型中最简单的。它们非常直接。

$group = new Field\Group( 'Field name' );

$group->set_layout( 'table' )
      ->add_field( $some_field )
      ->add_field( $another_field );

$field_group->add_field( $group );

灵活内容

灵活内容字段由包含字段的布局组成。

$flexible_content = new Field\FlexibleContent( 'Flexible field' );

$layout = new Field\Flexible\Layout( 'Layout label' );

$layout->set_display_mode( 'row' )
       ->add_field( $some_field )
       ->add_field( $another_field );

$flexible_content->add_layout( $layout );

像字段一样，布局也可以接受键和名称作为其第二个和第三个参数。

克隆

克隆字段是一个特殊情况，因为其类名与字段短横线不同。《Clone》是PHP中的一个保留词，因此字段的类名为 CloneField。

您可以克隆字段和字段组，因此字段的 add_clone() 方法可以接受两者作为参数。它还可以接受所需的字段或字段组的键作为字符串。

$clone = new Field\CloneField( 'Clone' );

$clone->set_label_prefix()        // Set label prefix setting as true
      ->add_clone( $some_field )  // Add a field object
      ->add_clone( $some_group )  // Add a field group object.
      ->add_clone( 'field-key' ); // Add a field by its key

$field_group->add_field( $clone );

标签页和手风琴

使用 ACF Codifier，标签页和手风琴字段类型被视为有子字段。否则，它们的工作方式与原生 ACF 字段一样。

$tab = new Field\Tab( 'My Very First Tab' );

$tab->set_placement( 'left' )
    ->set_endpoint()
    ->add_field( $some_field )
    ->add_field( $another_field );

$field_group->add_field( $tab );

伪组

伪组类似于组字段，但它不会影响数据树或管理视图。它只作为多个字段的容器，然后在查看编辑页面或查看数据树时作为独立的字段出现。

$pseudo = new Field\Pseudo( 'pseudo-group' );

$pseudo->add_field( $some_field )
       ->add_field( $another_field );

双向关系

Codifier支持ACF支持的字段类型的双向关系功能（目前为PostObject、Relationship、Taxonomy和User）。

$field->set_bidirectional()
      ->set_bidirectional_targets( [ 'field_name_or_key' ] );

Gutenberg

Codifier有一个功能可以注册使用ACF的注册块功能内部的Gutenberg块。它与Codifier中的基本字段创建方式非常相似。

块的构造函数接受两个强制参数：块的标题和名称（或键）。然后使用适当的方法设置块的属性。

$block = new \Geniem\ACF\Block( 'Some block', 'some_block' );
$block->set_category( 'common' );
$block->add_post_type( 'post' );
$block->set_mode( 'edit' );

块渲染是通过Renderer类来完成的。Codifier默认包含三个渲染器：CallableRenderer，它使用简单的渲染方法；PHP，它使用给定数据渲染常规PHP文件；以及Dust，它使用DustPHP模板进行渲染。

以下使用print_r()方法输出字段的数据列表。

$renderer = new \Geniem\ACF\Renderer\CallableRenderer( function( $data ) {
  return print_r( $data, true );
});

$block->set_renderer( $renderer );

ACF字段本身被添加到块中，就像添加到任何其他具有add_field()和set_fields()等方法的可分组类型对象一样。

要为Gutenberg注册块，只需使用register()方法。

$block->register();

如果需要，上述方法返回ACF的register_block()函数的输出。

附加功能

防止在特定文章类型或页面模板中显示灵活内容布局

如果您想防止某些灵活内容布局在特定文章类型或页面模板中显示，可以使用exclude_post_type或exclude_template方法。

$layout->exclude_post_type( 'post' );

$layout->exclude_template( 'page-frontpage.php' );

还有set_exclude_post_types和set_exclude_templates方法，您可以使用数组一次性设置多个排除。

隐藏字段标签

使用Codifier，您可以在管理侧隐藏字段的标签。例如，对于灵活内容字段或分组字段，这可能很有用。

您只需为您的字段调用hide_label()即可实现这一点。

$field->hide_label();

还有show_label()和get_label_visibility()方法。

附加字段类型

PHP字段

PHP字段是仅能与Codifier一起使用的ACF字段类型。它允许开发者在管理侧的字段区域内运行自己的代码，并在常规字段之间打印任何内容。

字段类型在ACF管理界面中也会出现，但那里没有可用的功能。

字段类型的用法非常简单。您可以像这样运行自己的代码

$php = new Field\PHP( __( 'My PHP field' ) );
$php->run( function() {
    global $post;

    echo '<pre>';
    print_r( $post );
    echo '</pre>';
});

多站点关系

多站点关系是仅能与Codifier一起使用的ACF字段类型。它是原始关系字段的克隆，但具有定义可以从中选择文章的博客的能力。

用法与关系字段完全相同，但有一个新的set_blog_id()方法。

$ms_relationship = new Field\MultisiteRelationship( __( 'My Multisite Relationship field', 'multisite_relationship', 'multisite_relationship' ) );
$ms_relationship->set_blog_id( 2 );

多分类

多分类是仅能与Codifier一起使用的ACF字段类型。它是原始分类字段的克隆，但具有定义可以从中选择术语的多个分类的能力。它支持为分类字段定义的所有功能，除了使用字段输入添加新术语的能力。它还有一个额外的功能，可以设置字段禁用，这在原始分类字段中是不可能的。

使用方法

定义字段并设置分类别名以启用从多个分类中选择术语。

$categories_and_tags = new Field\Multitaxonomy( __( 'Select a category or a tag', 'multitaxonomy_test', 'multitaxonomy_test' ) );
$categories_and_tags->set_taxonomies( [ 'category', 'post_tag' ] );

要启用选择多个术语，将字段类型更改为multi_select。

$categories_and_tags->set_field_type( 'multi_select' );

多站点分类

多站点分类是仅能与Codifier一起使用的ACF字段类型。它扩展了多分类字段的能力，允许开发者为选择术语的博客设置多站点博客ID。

使用方法

$multisite_taxonomy = new Field\MultisiteTaxonomy( __( 'Select a category or a tag from blog 2', 'multisite_tax', 'multisite_tax' ) );
$multisite_taxonomy->set_taxonomies( [ 'category', 'post_tag' ] );
$multisite_taxonomy->set_blog_id( 2 );

扩展Wysiwyg

扩展Wysiwyg是仅能与Codifier一起使用的ACF字段类型。它扩展了Wysiwyg字段的能力，允许开发者为TinyMCE编辑器设置高度。

$extended_wysiwyg = new Field\ExtendedWysiwyg( __( 'Extended Wysiwyg', 'extended_wysiwyg', 'extended_wysiwyg' ) );
$extended_wysiwyg->set_height( 150 );

多站点文章对象

多站点文章对象是ACF字段类型，只能与Codifier一起使用。它是原始文章对象字段的克隆，但具有定义可以从中选择文章对象的博客的能力。

使用方式与文章对象字段类似，但新增了set_blog_id()方法来选择博客。

$ms_object = new Field\MultisitePostObject( __( 'My Multisite Post Object field', 'multisite_object', 'multisite_object' ) );
$ms_object->set_blog_id( 2 );

外部字段类型支持

ACF Codifier中创建的一些字段类型在ACF本身中不是内置的。这些字段需要插件才能工作。插件应在字段类型类的docblock注释中链接。

如果您使用了一些ACF字段类型插件，您可以通过在GitHub上创建问题或将字段类型类自己创建并提交拉取请求来请求将其包含在Codifier中。

包含的附加字段类型列表

• MediumEditor
• Gravity Forms

技巧与窍门

翻译

如果将翻译字符串用作字段标签、说明等，Codifier声明应在适当的钩子内部运行 - 例如init是可行的。