README

在 Winter CMS 中提供 "基于块" 的内容管理体验

注意：此插件仍在开发中，可能会进行更改。请在您的 composer.json 文件中使用版本约束，并仔细监控破坏性更改的情况下不要在生产环境中使用。

注意：此插件需要 Winter CMS v1.2.2 或更高版本。

安装

此插件可通过 Composer 安装。

composer require winter/wn-blocks-plugin

为了使 actions 支持函数正确工作，您需要在 Snowboard 框架加载后加载 /plugins/winter/blocks/assets/dist/js/blocks.js。

核心概念

块

此插件管理 Winter CMS 中的 "块" 概念。块是自包含的、结构化的内容片段，可以以多种方式管理和渲染。

块可以由插件和主题提供，并且可以被主题覆盖。

动作

此插件还引入了 "动作" 的概念；一种定义和执行客户端动作的方式，这些动作可以由各种事件触发。目前，动作仅在 $/winter/blocks/meta/actions.yaml 文件中定义，并且必须作为函数存在于前端 window.actions 对象上，键为动作的标识符，该函数将 data 对象作为第一个参数接收，并可选地接收触发动作的事件对象作为第二个参数。

注意：这是一个非常多的 WIP API，可能会更改。非常欢迎在此处提供有关如何注册、管理、扩展和向前端提供动作的想法。

注册块

主题可以通过在 /blocks 文件夹和子文件夹中放置 .block 文件来自动注册其块。

插件可以通过在其 Plugin.php 文件中提供 registerBlocks() 方法来注册块。该方法应返回一个数组，其中包含以下格式的块定义

public function registerBlocks(): array
{
    return [
        'example' => '$/myauthor/myplugin/blocks/example.block',
    ];
}

块定义

块定义为 .block 文件，由 2 到 3 部分组成

A YAML 配置部分，用于定义块名称、描述和其他元数据，以及块属性和用于编辑这些属性的形式。
A PHP 代码部分，允许在块渲染时执行基本代码，类似于部分。
A Twig 模板部分，用于定义块的 HTML 标记模板。

当有两个部分时，它们是设置（YAML）& 标记（Twig）部分。

以下属性值（名称、描述等）可以在 .block 文件的设置（YAML）部分中定义

name: Example
description: Example Block Description
icon: icon-name
tags: [] # Defines the tags that this block is associated with
permissions: [] # List of permissions required to interact with the block
fields: # The form fields used to populate the block's content
config: # The block configuration options

区块可以使用组件，尽管它们可能会遇到与部分组件支持类似的复杂AJAX处理程序的生命周期限制。

字段和配置

区块可以在设置中定义fields以及config属性。这两个参数都接受表单模式，但用途不同。一般来说，fields应包含实际填写区块内容的字段，而config应包含定义区块本身外观或结构的字段。字段在blocks表单小部件中显示，配置在通过点击blocks表单小部件中区块的“齿轮”图标显示的检查器中显示。

例如，假设您有一个可以显示内容中标题标签的标题区块。您可能希望将其左对齐、居中对齐或右对齐，并定义要使用的标题标签。最佳实践是在fields定义中有一个content字段，因为它是实际显示的内容。而alignment和tag将成为config配置的一部分。

示例

name: Title
description: Adds a title
icon: icon-heading
tags: ["content"]
fields:
    content:
        label: false
        span: full
        type: text
config:
    size:
        label: Size
        span: auto
        type: dropdown
        default: h2
        options:
            h1: H1
            h2: H2
            h3: H3
            h4: H4
            h5: H5
    alignment_x:
        label: Alignment
        span: auto
        type: dropdown
        default: center
        options:
            left: Left
            center: Centre
            right: Right
==
{% if config.alignment_x == 'left' %}
    {% set alignment = 'text-left' %}
{% elseif config.alignment_x == 'center' or not config.alignment_x %}
    {% set alignment = 'text-center' %}
{% elseif config.alignment_x == 'right' %}
    {% set alignment = 'text-right' %}
{% endif %}

<{{ config.size }} class="{{ alignment }}">
    {{ content }}
</{{ config.size }}>

使用`blocks`表单小部件

为了提供一个管理基于区块内容的界面，此插件提供了blocks表单小部件。该小部件可以用作后端表单字段来管理区块。

blocks表单小部件支持以下附加属性

allow：允许添加到小部件的区块类型数组。如果指定，则只有列出的那些区块类型可供添加到当前字段的实例。您可以定义一个允许的单独区块的直数组，或者定义一个具有tags和/或blocks的对象，以允许整个标签或单个区块。
ignore：不允许添加到小部件的区块类型列表。如果没有指定，则所有区块类型都将可供添加到当前字段的实例。您可以定义一个要忽略的单独区块的直数组，或者定义一个具有tags和/或blocks的对象，以忽略整个标签或单个区块。
tags：允许添加到小部件的区块标签列表。如果指定，则只有具有列出的至少一个标签的区块类型可供添加到当前字段的实例。

这些属性允许您限制可以添加到特定小部件实例的区块类型，这在构建需要避免包含自身或只支持特定一组区块作为“子代”的“容器”类型区块时非常有用。

示例

button_group区块类型只允许添加button区块

buttons:
    label: Buttons
    span: full
    type: blocks
    allow:
        - button

container区块类型允许添加任何名为title的区块或具有content标签的区块

container:
    label: Container
    span: full
    type: blocks
    allow:
        blocks:
            - title
        tags:
            - content

columns_two区块类型允许添加除了自身以外的任何区块

left:
    label: Left Column
    span: left
    type: blocks
    ignore:
        - columns_two
right:
    label: Right Column
    span: right
    type: blocks
    ignore:
        - columns_two

与Winter.Pages插件的集成

在布局文件中包含以下行，以在Winter.Pages页面上包含blocks表单小部件

{variable type="blocks" name="blocks" tags="pages" tab="winter.pages::lang.editor.content"}{/variable}

渲染区块

使用Twig

此插件提供了用于渲染区块的Twig函数。然后，您可以使用以下Twig片段在布局中渲染区块数据

{{ renderBlocks(blocks) }}

您可以在接受表达式的任何地方使用它

{{ ('<p>Some text</p>' ~ renderBlocks(blocks) ~ '<p>Some more text<p/>') | raw }}

{% set myContent = renderBlocks(blocks) %}

如果您需要渲染单个区块，可以使用renderBlock函数

{{ renderBlock({
    '_group':'title',
    'content':'Lorem ipsum dolor sit amet.',
    'alignment_x':'left',
    'size':'h1',
}) }}

{{ renderBlock('title', {
    'content':'Lorem ipsum dolor sit amet.',
    'alignment_x':'left',
    'size':'h1',
}) }}

使用部分

如果您需要根据它们的组自定义区块的渲染，可以在您的主题中使用特殊的blocks.htm部分

{% for blockIndex, block in blocks %}
    {# Adding blocks to the following array allows them to implement their own containers #}
    {% if block._group in ["hero", "section"] %}
        {{ renderBlock(block) }}
    {% else %}
        <section class="flex flex-wrap items-center mx-auto max-w-screen-xl">
            <div class="w-full p-4">
                {{ renderBlock(block) }}
            </div>
        </section>
    {% endif %}
{% endfor %}

然后，您可以使用以下Twig片段在布局中渲染区块数据

{% partial 'blocks' blocks=blocks %}

使用PHP

use Winter\Blocks\Classes\Block;

// Render a single block from stored data
Block::render($model->blocks[0]);

// Render an array of blocks from stored data
Block::renderAll($model->blocks);

// Render a single block manually
Block::render('title', [
    'content' => 'Lorem ipsum dolor sit amet.',
    'alignment_x' => 'left',
    'size' => 'h1',
]);

// Render a single block manually using only array data
Block::render([
    '_group' => 'title',
    'content' => 'Lorem ipsum dolor sit amet.',
    'alignment_x' => 'left',
    'size' => 'h1',
]);

与TailwindCSS / CSS Purging集成

如果你的主题使用CSS类清除功能（例如Tailwind），将以下路径添加到构建配置中可以包括主题或插件定义的任何块的样式，这可能会很有用。

// tailwind.config.js
module.exports = {
    content: [
        // Winter.Pages static page content
        './content/**/*.htm',
        './layouts/**/*.htm',
        './pages/**/*.htm',
        './partials/**/*.htm',
        './blocks/**/*.block',

        // Blocks provided by plugins
        '../../plugins/*/*/blocks/*.block',
    ],
};

反馈

Winter.Blocks非常适合我的基于块的主题。我已经寻找类似的东西很久了

冬季 / wn-blocks-plugin

维护者

详细信息

README

安装

核心概念

块

动作

标签

注册块

块定义

字段和配置

使用`blocks`表单小部件

示例

与Winter.Pages插件的集成

渲染区块

使用Twig

使用部分

使用PHP

与TailwindCSS / CSS Purging集成

反馈

冬季 / wn-blocks-plugin

维护者

详细信息

README

安装

核心概念

块

动作

标签

注册块

块定义

字段和配置

使用blocks表单小部件

示例

与Winter.Pages插件的集成

渲染区块

使用Twig

使用部分

使用PHP

与TailwindCSS / CSS Purging集成

反馈

使用`blocks`表单小部件