vaersaagod/matrixmate

焊接矩阵成型，伙伴们！

维护者

详细信息

github.com/vaersaagod/matrixmate

源代码

问题

文档

安装次数: 232,268

依赖项: 3

建议者: 0

安全: 0

星级: 44

关注者: 5

分支: 10

开放问题: 1

类型:craft-plugin

2.2.1 2024-06-10 17:51 UTC

Requires

Requires (Dev)

MIT cf90a60e2e1f81366493f83ac5995becbc380dc4

cmsCraftcraftcmscraft-pluginmatrixmate

This package is auto-updated.

Last update: 2024-09-10 22:18:37 UTC

README

焊接矩阵成型，伙伴们！

Screenshot

需求

此插件需要 Craft CMS 4.0.0 或更高版本。

‼️MatrixMate 已被弃用，不再适用于 Craft 5。有关更多信息，请参阅 此问题。

安装

要安装此插件，您可以从插件商店安装，或按照以下说明操作

  1. 通过在项目目录下使用 composer require vaersaagod/matrixmate 通过 composer 安装。
  2. 在 Craft 控制面板的设置 -> 插件下安装插件，或通过命令行使用 ./craft plugin/install matrixmate。
  3. 要配置 MatrixMate 才能使用它，但首先请继续阅读！

MatrixMate 概述

MatrixMate 允许您通过将块类型排序到 分组 中以及将块类型字段排序到 标签 中来改进 Matrix 编写体验。

此外，MatrixMate 还提供以下实用功能

  • 可以为每个块类型设置最大限制
  • 未分组的块类型可以隐藏，或显示为原生 Matrix 按钮
  • 单个块类型可以添加到多个分组中（有时这样做是有意义的！）
  • 即使不使用分组功能，也可以明确隐藏块类型
  • 可以为不同的上下文（例如，部分、条目类型、类别组等）配置单个 Matrix 字段

alt text

我简直不敢相信这不是 Pimp My Matrix！

MatrixMate 是著名 Craft 插件 Pimp My Matrix（也称为 Spoon for Craft 3）的一个分支，我们向其作者 Josh Angell 表示敬意，感谢他启发了 MatrixMate。

Spoon 和 MatrixMate 之间的功能集重叠非常明显，但一个很大的不同之处在于，与 Spoon 不同，MatrixMate 并没有在 Craft 的控制面板内提供字段配置 UI。相反，MatrixMate 完全使用 PHP 配置文件进行配置。

在此处了解更多有关配置 MatrixMate 的信息

嵌套 Matrix 字段

MatrixMate 不支持嵌套在其他字段类型（例如 SuperTable）中的 Matrix 字段。如果您需要 SuperTable 支持，您应考虑使用 Spoon。

配置 MatrixMate

通过在 Craft 配置文件夹中创建一个名为 matrixmate.php 的配置文件来配置 MatrixMate（即您的 general.php 和 db.php 文件所在的文件夹）。

该配置文件应如下所示

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            'groups' => [[
                'label' => 'Content',
                'types' => ['text', 'images', 'video'],
            ], [
                'label' => 'Listings',
                'types' => ['news', 'employees'],
            ]],
            'types' => [
                'text' => [
                    'tabs' => [[
                        'label' => 'Text',
                        'fields' => ['heading', 'text'],
                    ], [
                        'label' => 'Settings',
                        'fields' => ['columns'],
                    ]],
                    'hiddenFields' => ['backgroundColor', 'textColor'],
                ],
                'news' => [
                    'maxLimit' => 1,
                ],
            ],
        ],
        'anotherMatrixFieldHandle' => [
            ...
        ],
    ],
];

以下示例将解释上述示例将做什么

对于具有处理程序 matrixFieldHandle 的 Matrix 字段，上述配置将创建两个块类型分组，分别称为 "Content" 和 "Listings"。text 块类型中的字段将按两个标签排序，分别是 "Text" 和 "Settings"，而 news 块类型将使用 maxLimit 设置限制为单个块。

此外，text 块类型中的两个字段 backgroundColor 和 textColor 使用 hiddenFields 设置被隐藏（自 MatrixMate v. 1.2.0 起添加）。

有关配置 MatrixMate 时可用的不同设置的更详细概述，请参阅 配置设置 部分。

配置上下文

默认情况下，MatrixMate字段配置将在字段使用的任何地方生效。然而，您可以使用上下文键在不同的内容类型中对同一字段应用不同的配置。

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [ 
            '*' => [
                'groups' => [
                    ...
                ],
            ],
            'section:news,section:blog' => [
                'groups' => [
                    ...
                ],
            ],
        ],
    ],
];

上述示例将针对在属于news和blog等部分的条目中使用的具有“matrixFieldHandle”处理器的Matrix字段应用特定的配置（注意，使用逗号分隔的列表应用相同的配置到多个上下文中）。

此外，使用星号（*）键添加了一个“全局”配置，该配置将适用于除已指定上下文外的所有地方。全局配置是完全可选的——只声明特定的上下文键也是完全可以的（在这种情况下，Matrix字段将原生渲染；即在没有任何修改的情况下，在其他任何地方渲染）。

支持上下文

section:{handle} - 在特定部分的全部条目类型中应用
entryType:{handle} - 在具有特定条目类型的条目中应用
categoryGroup:{handle} - 在特定分类组中的分类应用
globalSet:{handle} - 在特定全局集中应用
volume:{handle} - 在特定卷中的资源应用
users - 在用户账户编辑页面中应用
productType:{handle} - 在具有特定产品类型的 Commerce 产品中应用

配置上下文继承

‼️ MatrixMate配置上下文不会递归合并——例如，与Craft的多环境配置不同。这意味着如果您有一个全局配置上下文（即*）和一个针对特定部分（例如'section:news'）的上下文，全局配置的设置不会继承到那个'section:news'上下文中。实际上，您为每个上下文都从头开始。这不是一个错误，而是一个特性！

...如果您希望配置上下文合并，可以通过在配置文件中添加一些PHP逻辑来解决这个问题

<?php

$globalConfig = [
    'groups' => [
        ...
    ],
];

return [
    'fields' => [
        'matrixFieldHandle' => [ 
            '*' => $globalConfig,
            'section:news,section:blog' => array_merge_recursive($globalConfig, [
                'groups' => [
                    ...
                ],
            ]),
        ],
    ],
];

配置设置

以下设置适用于Matrix字段配置，例如。

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            // Field configuration here
        ],
    ],
];

defaultTabName [string|bool]

默认值：'Fields'

如果字段配置中的任何块类型设置了自定义选项卡，MatrixMate将把任何未添加到选项卡中的字段放入一个名为“Fields”的“默认”选项卡中。要更改默认选项卡的名称，请将名为'defaultTabName'的键添加到字段配置中。

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            'defaultTabName' => 'Misc',
        ],
    ],
];

要不渲染任何默认选项卡（实际上隐藏所有未放入选项卡中的字段），请将defaultTabName设置为false。

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            'defaultTabName' => false,
        ],
    ],
];

此设置仅适用于配置为使用选项卡的块类型，并且可以在每个类型的基础上覆盖（请参阅下面的'types'配置部分）。

defaultTabFirst [bool]

默认值：false

默认情况下，默认选项卡将在任何自定义选项卡之后渲染。要将默认选项卡放在首位，请将defaultTabFirst设置为true。

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            ...
            'defaultTabName' => 'Misc',
            'defaultTabFirst' => true,
        ],
    ],
];

groups [array]

通过在字段配置中添加一个键'groups'，可以将块类型分组。

通过将关联数组添加到'groups'中，声明一个组，包含键'label'（字符串，组的名称）和'types'（数组，包含组应包含的块类型的处理器）

...
'matrixFieldHandle' => [
    'groups' => [[
        'label' => 'Content',
        'types' => ['text', 'heading'],
    ], [
        'label' => 'Misc',
        'types' => ['newsletter', 'feed'],
    ]],
],

注意，空组（或包含没有实际/有效块类型处理器的types数组的组）以及缺少标签的组将不会渲染。

types [array]

使用字段配置中的'types'键，您可以按选项卡对块类型字段进行排序，并/或为特定块类型允许的实例数设置最大限制。

'types'数组应使用相关块类型的处理器作为键，每个块类型的配置作为值数组

...
'matrixFieldHandle' => [
    'types' => [
        'text' => [
            // Block type config here
        ],
        'news' => [
            // Block type config here
        ],
    ],
],
创建选项卡

要将某个块类型的字段按标签页排序，请向 'types' 数组中的块类型配置内添加一个名为 'tabs' 的键。每个标签页应是一个关联数组，包含键 'label'（字符串；标签页的标题）和 'fields'（一个包含属于此标签页的字段处理器的数组）

...
'types' => [
    'text' => [
        'tabs' => [[
            'label' => 'Content',
            'fields' => ['heading', 'text'],
        ], [
            'label' => 'Settings',
            'fields' => ['columns'],
        ]],
    ],
],

上述示例会将字段 heading、text 和 columns 排序到两个标签页中；"内容" 和 "设置"。

在 'fields' 数组内字段的顺序无关紧要，因为 MatrixMate 不会重新排序字段 - 它将根据当前活动的标签页简单隐藏或显示它们。

缺少标签或拥有空 'fields' 数组（或没有有效字段处理器的数组）的标签页将不会显示。如果配置中只找到单个有效标签页，则不会渲染任何标签页。

当添加自定义标签页时，不属于添加到标签页的特定字段的所有字段将被放入一个名为 "字段" 的 "默认" 标签页中。有关详细信息，请参阅下一节。

更改默认标签页名称（或完全隐藏默认标签页）

当使用 'tabs' 设置添加自定义标签页时，MatrixMate 会将任何未添加到标签页的字段放入一个名为 "字段" 的 "默认" 标签页中。要更改默认标签页的名称，请向相关块类型的配置中添加一个名为 'defaultTabName' 的键

...
'types' => [
    'text' => [
        'tabs' => [[
            'label' => 'Content',
            'fields' => ['heading', 'text'],
        ], [
            'label' => 'Settings',
            'fields' => ['columns'],
        ]],
        'defaultTabName' => 'Misc',
    ],
],

要 不 渲染默认标签页 - 事实上，隐藏不属于自定义标签页的所有字段 - 请将 'defaultTabName' 设置为 false

...
'types' => [
    'text' => [
        'tabs' => [[
            'label' => 'Content',
            'fields' => ['heading', 'text'],
        ], [
            'label' => 'Settings',
            'fields' => ['columns'],
        ]],
        'defaultTabName' => false,
    ],
],

将 'defaultTabName' 设置添加到块类型配置中将覆盖在字段级别设置的相同设置。

最大限制

要为特定类型设置最大限制，请向该类型的配置中添加一个名为 'maxLimit' 的键

...
'types' => [
    ...
    'news' => [
        'maxLimit' => 1,
    ],
],
隐藏字段

要在块类型的配置中隐藏特定字段，请使用 hiddenFields 设置（应为字段处理器的数组）

...
'types' => [
    ...
    'text' => [
        'hiddenFields' => ['backgroundColor', 'textColor'],
    ],
],

请注意，hiddenFields 中的任何字段都将被隐藏，即使该字段也添加到了标签页中。

注意不要隐藏必填字段！ MatrixMate 不包括处理隐藏的必填字段的任何功能，因此隐藏必填字段将使内容编辑器无法实际保存块。

hideUngroupedTypes [布尔值]

默认值：false

默认情况下，MatrixMate 将为不属于任何组的任何块类型渲染原生 Matrix 按钮。要 隐藏 所有未分组块类型，请将 hideUngroupedTypes 设置为 true

...
'matrixFieldHandle' => [
    'groups' => [...],
    'hideUngroupedTypes' => true,
],

此设置仅适用于使用分组功能时。

hiddenTypes [数组]

要显式隐藏一个或多个块类型，请向 hiddenTypes 键添加一个包含块类型处理器的数组

...
'matrixFieldHandle' => [
    'hiddenTypes' => ['newsletter', 'feed'],
],

此设置将隐藏添加到其中的任何和所有块类型，无论这些类型是否已添加到任何组中，以及无论 hideUngroupedTypes 设置的值如何。

ungroupedTypesPosition [字符串]

默认：'before'

如果设置为 'after'，则未分组块类型的按钮将渲染在组按钮 之后。

...
'matrixFieldHandle' => [
    'groups' => [...],
    'ungroupedTypesPosition' => 'after',
],

此设置仅适用于使用分组功能时。

高级配置

危险区域

这是一个旁注，但由于 config/matrixmate.php 文件只是 PHP，您当然可以随意使用逻辑来构建所需的任何复杂配置。作为一个简单的例子，以下是如何仅当当前登录用户不是管理员用户时渲染特定配置的方法

<?php

$isUserAdmin = Craft::$app->getUser()->admin;

return [
    'fields' => [
        'matrixFieldHandle' => [ 
            ...
            'section:news,section:blog' => !$isUserAdmin ? [
                'groups' => [
                    ...
                ],
            ] : null,
        ],
    ],
];

显然，在上述配置文件中放置逻辑可能是一个非常糟糕的主意，并且很容易引入应用程序的性能问题或其他错误。

如果在配置文件中添加了可能负担较重的逻辑（例如导致大量数据库查询的代码），您应该考虑在适用的情况下使用Craft的缓存组件（即Craft::$app->getCache()）。您还可以考虑完全禁用MatrixMate以处理非CP请求，在config/general.php中使用Craft的disabledPlugins配置设置，例如通过以下操作

<?php

$isCpRequest = \explode('/', \parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH))[1] ?? null === 'admin';

return [
    '*' => [
        ...
        'disabledPlugins' => \array_filter([!$isCpRequest ? 'matrixmate' : null]),
    ],
    ...
];

注意：即使MatrixMate插件与前端请求无关，除非您的config/matrixmate.php配置文件中有一些重或定制的逻辑，否则上述操作完全是多余的微优化。

翻译MatrixMate

所有配置的用户界面文本字符串，如选项卡和组标签，将使用'site'静态翻译类别进行翻译。

价格、许可证和支持

此插件根据MIT许可证发布，这意味着只要您不责怪我们（并尊重原始许可证），您就可以随意使用它。它是免费的，这意味着绝对不包含支持，但您可能仍然会得到支持。只需在GitHub上发布一个问题，我们将看看我们能做什么。

变更日志

请参阅CHANGELOG.MD。

鸣谢

由Værsågod提供。

图标由Freepik from Flaticon设计。