README

Craft 3 的 Blockonomicon

此插件通过一系列功能增强了 Craft 自身的矩阵字段。

可以导入和导出单个矩阵块配置，允许在不手动编辑的情况下轻松复制，甚至可以在整个 Craft 安装中完成。
矩阵块配置可以与 HTML、CSS 和 JS 一起打包。这些包允许块在 Craft 网站的前端具有一致的布局、外观和行为。
模板的可选简易使用功能，允许通过单个命令通过关联的 HTML 渲染矩阵块。
单击即可按字母顺序对块进行排序。
数据仍然存储在 Craft 矩阵字段中。您可以在任何时候选择卸载 Blockonomicon 而不会丢失对数据访问。

要求

Craft CMS 3.0.0-RC6 或更高版本

安装

打开终端并导航到您的项目文件夹

cd /path/to/project

通过 Composer 下载包以获取它

composer require charliedev/blockonomicon

在 Craft 控制面板的 设置 -> 插件 页面上安装插件。

--- 或 ---

通过命令行安装插件

./craft install/plugin blockonomicon

什么是块？

如果您熟悉 Craft，您无疑已经看到了矩阵字段的实际应用。每个可重复的字段集都称为一个块。您可以将 Blockonomicon 的块视为同一块，但有一个主要扩展

在 Blockonomicon 中，可以从矩阵字段中导出矩阵块。这些导出的块，尽管可能包含其他配置和模板文件，与它们的矩阵对应物没有区别。

用法

块管理

Blockonomicon 最强大的功能是其导出和导入块配置的能力。为此，请转到 Blockonomicon 控制面板的块子菜单。从这里您可以查看 块概述 部分，其中列出了所有导出的块以供快速参考。在侧边栏中，列出了矩阵字段，选择一个将带您到其相应的编辑器。如果单个块需要名称或描述更新，则可以通过任何显示的块的编辑图标访问简单的块编辑器。如果安装的任何块存在配置问题（缺少配置、格式错误等），则在此面板中将会有通知说明哪些块存在问题。

矩阵编辑

选择一个矩阵将显示包含已附加到矩阵的块和可导入的块列表的矩阵编辑器。在矩阵编辑器中，可以自由重新排列块，可以将新块导入到矩阵中，也可以导出现有块。每个块都有指示器，显示它是否存在于矩阵中，是否有对应的导出配置文件，甚至块配置是否与当前配置文件匹配。

导出

导出块将块的配置保存到文件，并创建一个包含HTML、CSS和JS文件的捆绑包，与块一起使用。当导出已导出的块时，配置将被备份（作为单独的json.bak文件），然后覆盖配置。如果捆绑包文件不存在，则不会重新生成额外的捆绑包文件。

导入

导入块将在正在编辑的矩阵中创建一个新的块，使用配置文件中的字段及其相应的设置。如果覆盖现有块，Blockonomicon将使用每个字段的handle创建新字段，更新已更改的字段设置，并删除不再存在的任何字段。

块编辑

从块概览中，点击编辑图标将带您到块编辑器。这里提供了与块相关联的字段的简单参考，以及编辑块名称、handle和描述的手段。要完全编辑块的各个字段配置，最好使用Craft内置的矩阵编辑器，然后重新导出（新）块。如果您非常勇于尝试，可以手动编辑JSON块配置文件。

捆绑包和模板

默认情况下，块保存在Craft的自身storage文件夹中，尽管此设置可以更改（见下文高级设置）。这些捆绑包不仅提供块的字段配置（在json文件中），还提供一组可能与每个块一起重用的HTML、CSS和JS。当块首次导出时，会创建这些资源的占位符文件。

要使用这些资源在前端模板中，有几个便利方法可以使用。

例如，如果您当前条目中的矩阵字段称为myMatrixField，您可以使用以下Twig标签按顺序渲染每个矩阵块，使用它自己的捆绑HTML模板

{{ craft.blockonomicon.renderMatrix(entry.myMatrixField) }}

这将根据每个块的handle查找导出块的模板。当这些模板被渲染时，将设置block Twig变量为正在渲染的矩阵中的那个块。这意味着如果您的myMatrixField有一个header纯文本字段，您可以使用以下方法在块模板中显示它

{{ block.header }}

您的块不仅可能有特定的模板，还可能有您希望在整个网站或Craft安装中使用的特定样式和脚本。使用包含的CSS和JS文件，这些捆绑包可以隔离和携带。要生成CSS的<link>标签或JS的<script>标签，可以使用以下Twig

{{ craft.blockonomicon.renderCSS(options) }} {{ craft.blockonomicon.renderJS(options) }}

默认情况下，每个块都会生成单独的 <link> 和 <script> 标签，这在积极开发时可能很有用。要将所有块样式和脚本文件合并为单个 JS 或 CSS 文件，请将这些函数的 options 传递为 {condense: true}。

默认捆绑文件

如果您需要调整 Blockonomicon 生成的捆绑文件，使用的模板将存储在 Craft 的 storage/blockonomicon 文件夹中。用于在导出时生成每个块的 HTML、CSS 和 JS 的 Twig 模板分别称为 base.html、base.css 和 base.js。

捆绑安全

请注意，Blockonomicon 需要JSON和HTML块文件以下划线为前缀。这个前缀导致 Craft 防止这些文件从前端直接检索。

自定义字段

Blockonomicon 支持所有原生 Craft 字段。许多第三方字段也可能直接支持。不受支持的字段不会阻止块导出或导入。相反，如果所有设置都无法保存，则导入时可能不完全匹配导出的配置。相反，对于更复杂的字段，Blockonomicon 提供了一个扩展系统，允许适配器支持这些更复杂的字段。这个扩展系统用于 Craft 的元素字段（资产、分类、条目、标签、用户）。

一个允许更复杂字段导入/导出的扩展示例是 Blockonomicon Super Table Adapter

高级设置

Blockonomicon 通过编辑 Craft 的 config 文件夹下的 blockonomicon.php 文件提供了特殊的配置设置。可以使用 设置面板 来确认和审查这些设置。

`allowedUsers`

如果设置，则列出的用户（按 ID）是唯一允许在控制面板中访问 Blockonomicon 的用户。这是针对那些一些用户是管理员或有权限访问 Blockonomicon 面板，但应该受到限制的 Craft 安装。

`blockStorage`

这将更改 Blockonomicon 的块配置和模板导出位置到不同的本地文件夹。请注意，此路径已注册为模板根，其中的文件可以通过前端上的 /blockonomicon 路径访问。

插件内示例

对于开发人员参考，Blockonomicon 允许安装一组示例模板和数据。在示例部分列出了与示例内容一起安装的所有数据的分解。

由 Craft CMS 的 Charlie Development 构建

charliedev / blockonomicon

维护者

详细信息