README

带有ACF的Coretik页面构建器

Coretik页面构建器提供了一种现代方法，让开发者能够以带有 实时管理预览（并且对WP-CLI友好！）的方式构建页面构建块。它使用包含可重用组件和组合块的框架逻辑，并按需管理多个组件级别。

概述

此软件包与 StoutLogic/acf-builder 一起工作，用于创建字段，并提供一种构建 StoutLogic\AcfBuilder\FieldsBuilder 块的方式。您必须将它们包含在您想要的任何其他字段中。

块实例定义了所有功能

• 渲染方法；
• 管理字段和管理预览；

存在三种块类型

• 组件：较低的块级别，用于构建其他块；
• 块：一种自由构建完整块实例的方式；
• 组合：一种基于许多组件或其他块的快速构建块的方式；

组件不显示在用户库中。它们仅用于构建其他块。

要求

• PHP >= 8.0
• idetik/coretik： https://github.com/idetik/coretik
• 插件ACF： https://www.advancedcustomfields.com/
• 插件ACF Extended： https://acf-extended.com/

安装

composer require idetik/coretik-page-builder

使用

此构建器包含一些可立即使用的组件。您可以在 ./src/Library/Component/ 中找到它们。

配置

首先，您应该定义自己的环境变量以覆盖默认设置。默认配置列表

// The template directory in your theme to save the html views parts
'blocks.template.directory' => 'templates/blocks/',

// The blocks classes directory
'blocks.src.directory' => 'src/Services/PageBuilder/Blocks/',

// The template acf directory in your theme to save the additional admin styles and scripts
'blocks.acf.directory' => 'templates/acf/',

// Your blocks root namespace based on your app
'blocks.rootNamespace' => ($c['rootNamespace'] ?? 'App') . '\\Services\\PageBuilder\\Blocks',

// The blocks library containing all of your blocks
'blocks' => $c->get('pageBuilder.library')

// The fields directory to create and write complex fields groups
'fields.directory' => 'src/admin/fields/blocks/',

// The block thumbnail directory to save the blocks previews thumbnails
'fields.thumbnails.directory' => \get_stylesheet_directory() . '/assets/images/admin/acf/',

// The block thumbnail url to get the blocks previews thumbnails
'fields.thumbnails.baseUrl' => '<##ASSETS_URL##>/images/admin/acf/',

// Example to change the template directory
add_filter('coretik/page-builder/config', function ($config) {
    $config['blocks.template.directory'] = 'my-theme-templates/';
    return $config;
});

块类

组件

此较低块级别允许您在主题中重用一些基本字段。此包中提供的标题组件的简化示例即可作为可立即使用的组件。

<?php

namespace Coretik\PageBuilder\Library\Component;

use Coretik\PageBuilder\Core\Block\BlockComponent;
use StoutLogic\AcfBuilder\FieldsBuilder;

class TitleComponent extends BlockComponent
{
    const NAME = 'component.title';
    const LABEL = 'My title'; // Admin label

    /**
     * All fields to be retrieved must be declared as property class.
     * There are automatically populated with values from the database.
     */
    protected $title;
    protected $tag;

    public function fieldsBuilder(): FieldsBuilder
    {
        $field = $this->createFieldsBuilder();
        $field
            // First field : 'title'
            ->addText('title')
                ->setLabel('Title')
                ->setRequired()
            // Second field : 'tag'
            ->addRadio('tag', ['layout' => 'horizontal'])
                ->setLabel('Title level')
                ->addChoice('h2')
                ->addChoice('h3')
                ->addChoice('h4')
                ->addChoice('h5')
                ->setDefaultValue('h2')
                ->setRequired();

        $this->useSettingsOn($field);
        return $field;
    }

    /**
    * The block formatted data. You can apply your own format rules.
    */
    public function toArray()
    {
        return [
            'title' => $this->title,
            'tag' => $this->tag
        ];
    }

    /**
    * This is usefull to get html from light component without template file
    */
    protected function getPlainHtml(array $parameters): string
    {
        // Return <hN>A title from my acf field</hN>
        return sprintf(
            '<%1$s class="my_title_class">%2$s</%1$s>',
            $parameters['tag'],
            $parameters['title']
        );
    }
}

块

块使用与组件相同的逻辑，但它们可以直接在块库中使用。块可以使用PHP trait Coretik\PageBuilder\Core\Block\Traits\Components 重用组件。

use Components;

$titleComponent = $this->component('component.title'); // Or with some defined values : $this->component(['acf_fc_layout' => 'component.title', 'tag' => 'h2'])
$titleFields = $titleComponent->fields();
[...]

组合

基于其他块或组件创建组合块。只需创建一个复杂的块。此示例显示了创建标题和WYSIWYG编辑器块的方法。

<?php

namespace Coretik\PageBuilder\Library\Block;

use Coretik\PageBuilder\Core\Block\BlockComposite;
use Coretik\PageBuilder\Library\{
    Component\TitleComponent,
    Component\WysiwygComponent,
};

use function Coretik\PageBuilder\Core\Block\Modifier\required;

class TitleAndTextComposite extends BlockComposite
{
    const NAME = 'block.title-editor';
    const LABEL = 'Title and editor';

    // By default, the rendering method is HTML. Other methods are RenderingType::Array or RenderingType::Object
    const RENDER_COMPONENTS = RenderingType::Html;

    /**
     * Define all sub blocks to build in this composite block.
     * The acf fields will be constructed and rendered from each component.
     */
    protected function prepareComponents(): array
    {
        return [
            'title' => TitleComponent::class,
            /**
             * Some modifiers functions are available to help you to build specifics composite blocks.
             * See `/src/Core/Block/Modifier/modifiers.php` 
             */
            'editor' => required(WysiwygComponent::class), // required(Block::class) set acf field as required
        ];
    }

    // Or use template in your template.directory/block/title-editor.php
    protected function getPlainHtml(array $parameters): string
    {
        /**
         * Following the RenderingType, the values will change. By default, values are the html rendered by each of sub blocks
         * RenderingType::Array allow you to get values from toArray method of each sub blocks
         * RenderingType::Object allow you to get sub blocks instances
         */
        return sprintf('%s%s', $parameters['title'], $parameters['editor']);
    }
}

模板示例 template.directory/block/title-editor.php

<div class="title-with-editor-block">
    <div class="title-with-editor-block__title">
        <?= $title ?>
    </div>
    <div class="title-with-editor-block__editor">
        <?= $editor ?>
    </div>
</div>

WP-CLI：创建块

以下命令将创建用于创建和渲染块或组件的PHP文件。

创建组件

wp page-builder create-component "我的超级组件"

创建组合

wp page-builder create-composite "我的超级块组合"

创建块

wp page-builder create-block "我的超级块"

每个命令可用的选项

[--name=<name>] : The block name to retrieve template (ex: component.title, template based in blocks/component/title.php), default is component.<labelToCamelCase>

[--class=<class>] : The block classname, default is (Component/<labelToCamelCase>Component)

[--without-acf-admin-files] : Avoid to create ACF admin files (script, style and template)

[--without-template-file] : Avoid to create template file

[--w] : Shortcut to create only class file

[--quiet] : Disable output

[--force]: Override existings files

将其包含在您的 FieldsBuilder 中

// Get the flexible content instance
$pageBuilder = app()->get('pageBuilder.field');

// You can filter ou use some specifics blocks as necessary
$pageBuilder->setBlocks(app()->get('pageBuilder.library')->filter());

// Generate the FieldsBuilder with your $fieldName, example "blocks"
$pageBuilder = $pageBuilder->field('blocks');

$page = new FieldsBuilder('page_builder', [
    'title' => 'Builder',
    'acfe_autosync' => ['php'],
    'hide_on_screen' => [
        'the_content',
        'custom_fields',
    ],
    'position' => 'normal',
    'style' => 'seamless',
    'label_placement' => 'top',
    'instruction_placement' => 'label'
]);

$page
    ->addFields($pageBuilder)
    ->setLocation('post_type', '==', 'page');