README

SelectPlus 是 Craft CMS 5+ 的一个基于 JSON 配置的自定义字段类型插件。它呈现的方式类似于标准 Craft CMS 下拉字段，该字段本身使用了 Selectize JS 库。

SelectPlus 内部隐藏了许多旨在提高整体内容 作者体验 (AX) 和开发者 Twig 模板体验的功能。

**This is a Beta Release!**

概述

• 可配置的 内联工具提示 和 帮助/文档模态框，以改善作者体验。
• 可定义的 虚拟输入字段，仅在 Dropdown 字段旁边的“设置”按钮下显示。渐进式披露 FTW！
  • 支持的字段类型包括：纯文本、数字、单选组、轻触、下拉/选择、货币、颜色、图标、日期、时间
• 每个字段选项都可以有单独的或共享的虚拟输入字段。
• 每个选项还可以有共享的或唯一的 设置令牌，这些令牌可以在 Twig 模板中访问，除了所选的字段值外。
• 通过存储在 Craft CMS templates 文件夹中的 .json 文件配置字段。
• 由于配置文件仍然技术上被解析为 Twig 文件，你可以用高级配置进行创造性地设置。

安装

这个早期版本目前不在 Craft 插件商店中可用，只能通过 Composer 安装。

需要 Craft CMS 5+

运行 composer require simplicateca/selectplus:5.0.4-beta 然后在 "设置 > 插件" 中启用插件

配置

每个 SelectPlus 字段的选择项存储在 Craft CMS templates 文件夹中的一个 JSON 文件中，而不是需要通过 Craft CMS 控制面板输入。

这意味着，当您想要向下拉菜单中添加、更改或删除选项时，您可以通过编辑代码编辑器中的 JSON 文件来实现，而无需进入控制面板并编辑或重新保存单个字段。

这对于在许多 Matrix 块类型中使用的字段特别有用，减少了需要在多个地方更新相同选项的需求，并减少了人为错误的风险。

示例 .json 文件

示例 JSON 配置文件可以在插件 'src/templates/samples' 文件夹 中找到。

此外，该文件夹中的每个文件都可以在开发模式下使用，以演示字段的特性和功能。

• _selectplus/config/simple.json
• _selectplus/config/all-inputs.json
• _selectplus/config/button-only.json

Twig 模板

SelectPlus 字段中的每个选项都允许关联额外的数据，您可以在 Twig 中使用这些数据，而不是创建匹配下拉字段值的逻辑。

在字段的 JSON 配置中，您可以有名为 settings 的属性，允许传递任意数量的键值对（字符串、数组等）到 Twig。

例如，如果您有一个SelectPlus字段fieldName具有以下配置

{
    "label": "Option One",
    "value": "one",
    "settings": {
        "usefulText": "This is some useful text"
    }
}

您可以在Twig模板中引用settings.usefulText，例如：{{ entry.fieldName.usefulText }}

当然，这只有在fieldName字段中选择“选项一”时才会起作用。如果选择了不同的选项，设置变量及其内容可能不同（这取决于您！）。

这有什么用呢？有很多原因！

Explain With Examples...

即时更新

因为JSON文件中的更改会立即反映在字段的各个实例中，所以您可以轻松地调整多个模板或条目的设置，而无需进入控制面板并逐个编辑/重新保存记录。

内联文档

虽然Craft CMS允许我们将说明与每个字段相关联，但这些说明仅适用于字段本身，而不是下拉菜单中选择的单个选项。

SelectPlus字段允许为每个选项创建内联文档，可以通过工具提示、模态框或链接到外部资源来访问。

模态内容是从您选择的Twig文件加载的，并且Twig模板可以利用有关字段和所选选项的动态信息来决定要显示哪种文档。

TODO: Outline Different documentation settings in the JSON config

虚拟输入字段

与常规下拉字段一样，SelectPlus字段存储用户选择的<option>的值。但是，它还可以用于存储与每个选项关联的多个附加输入字段。

这在所选选项有需要细调的“后续问题”的情况下很有用，特别是如果额外输入是表现性的而不是内容模型，并且可能不需要自己的自定义字段。

没有人喜欢杂乱的内容模型，这可以帮助保持事物整洁。

字段配置

用于虚拟字段配置的结构与Craft核心_includes/forms.twig文件中使用的结构相同。事实上，大多数字段都是直接由该文件生成的。

可用字段类型

可用的输入字段包括

• 纯文本
• 数字
• 单选按钮组
• 开关
• 下拉/选择
• 货币
• 颜色
• 图标
• 日期
• 时间

有关如何配置这些字段的示例，请参阅all-inputs.json。

动态配置

当尝试在字段配置屏幕内自动完成文件路径时，SelectPlus仅建议.json文件。

但是，如果提供

1. 您手动输入文件路径，而不使用自动完成（多么可怕！）
2. 文件输出一个有效的JSON选项数组

SelectPlus提供了一个element变量，可以在任何SelectPlus配置文件中的任何Twig标签或命令中访问（无论文件扩展名如何）。

此element变量包含有关字段所附加的元素的信息，以及该元素的拥有者（如果适用，例如矩阵字段的情况）。

这些是在element变量上可用的字段

element.section - 与直接附加的字段相关联的部分的处理程序（如果适用）。

element.type - 与直接附加的字段相关联的条目类型的处理程序（如果适用）。

此外，对于SelectPlus字段附加到矩阵块的情况，element变量还将包含一个owner变量，该变量包含与element变量相同的字段，但为矩阵块的拥有者。

这意味着，您可以考虑以下一些技术来配置SelectPlus字段，而不是使用静态的.json文件。

使用.twig而不是.json进行配置

field-config.twig

{% set fieldOptions = [
    {
        "label": "Option One",
        "value": "one",
        "settings": {
            "template" : "_layouts/basic.twig",
            "fizz": true
        }
    },{
        "label": "Option Two",
        "value": "two",
        "settings": {
            "template" : "_layouts/complicated.twig",
            "fizz": false
        }
    }] %}

{{ fieldOptions | json_encode }}

在.json中使用Twig进行配置

例如：field-config.json

[
    {
        "label": "Option One",
        "value": "one",
        "settings": {
            "template" : "_layouts/basic.twig",
            "fizz": true
        }
    }
    {% if element.section != 'blog' %}
        ,{
            "label": "Option Two",
            "value": "two",
            "settings": {
                "template" : "_layouts/complicated.twig",
                "fizz": false
            }
        }
    {% endif %}
]

其他不那么理智的配置方法

使用.twig作为路由器，该路由器使用Twig的source函数指向常规静态.json文件

例如：layout-field-router.twig

{% set section = element.owner.section ?? element.section ?? 'default' %}
{{ source("_config/layout-#{section}.json") }}

或者，您可以使用包含从.twig文件中提取的公共元素的.json文件，使用Twig的block函数

例如：field-config.json

[
    {
        "label": "Option One",
        "value": "one",
        "virtuals": [
            {{ block( 'align', '_config/field-inputs.twig' ) }},
            {{ block( 'size',  '_config/field-inputs.twig' ) }},
        ]
    }
   ,{
        "label": "Option Two",
        "value": "two",
        "virtuals": [
            {{ block( 'align', '_config/field-inputs.twig' ) }},
            {{ block( 'size',  '_config/field-inputs.twig' ) }},
        ]
    }
]

..以及field-inputs.twig

{% block align %}
    {
        "label": "Alignment",
        "name" : "align",
        "type" : "select",
        "value": "text-left",
        "options": [
            "text-left"  : "Left",
            "text-center": "Center",
            "text-right" : "Right"
        ]
    }
{% endblock %}

{% block size %}
    {
        "label": "Font Size",
        "name" : "fontSize",
        "type" : "select",
        "value": "text-base",
        "options": [
            "text-xs"  : "Extra Small",
            "text-sm"  : "Small",
            "text-base": "Normal",
            "text-lg"  : "Large",
            "text-xl"  : "Extra Large"
        ]
    }
{% endblock %}

元素变量

    'name'    => $element->type->name    ?? null,
    'type'    => $element->type->handle  ?? null,
    'field'   => $element->field->handle ?? null,
    'element' => $element->elementType   ?? null,
    'owner'   => [
        'site'    => $owner->site->handle    ?? null,
        'type'    => $owner->type->handle    ?? null,
        'level'   => $owner->level           ?? null,
        'section' => $owner->section->handle ?? null,
        'element' => $owner->elementType     ?? null,
    ],

仅按钮模式

还可以告诉SelectPlus字段以仅按钮模式运行，在这种情况下，可以通过点击按钮配置一个带有多个虚拟输入字段的“选项”。

按钮使用单个<option>的label作为其文本。

此外，为了区分只有一个选项的常规Select字段和仅按钮字段，必须在字段的JSON配置中包含"type":"button"，如下所示

[{
    "label": "Button Only Field Name",
    "value": "anything-really",
    "type" : "button",
    "tooltips": {...},
    "settings": {...},
    "virtuals": [{...}, {...}, {...}],
}]

对于非仅按钮字段，不需要包含type键的值。

致谢

由simplicate.ca提供

感谢Trendy Minds的Design Tokens字段插件和Feral的Matrix Field Preview插件带来的灵感。

欢迎提交错误报告.