README

为 Kirby 的添加对话框提供自定义字段。此插件允许在相应页面的蓝图上定义在 Kirby 页面添加对话框中显示的字段。

安装

使用以下任一方法。

下载

下载并复制此存储库到 /site/plugins/kirby-plugin-custom-add-fields。

Git 子模块

git submodule add https://github.com/steirico/kirby-plugin-custom-add-fields.git site/plugins/kirby-plugin-custom-add-fields

Composer

composer require steirico/kirby-plugin-custom-add-fields

兼容性

使用方法

定义自定义添加字段

此插件向页面蓝图添加了额外的属性 addFields。要定义自定义添加字段，请像定义常规字段一样操作，但将定义放在属性 addFields 中。

/blueprints/pages/remote.yml:

title: Blueprint with custom Add Fields

fields:
    # field definitions
    title:
        label: Title
        type: text
    content:
        label: Content
        type: textarea

# custom add fields definition
addFields:
    title:
        label: Title
        type: text
        required: true
        icon: title

    remoteUrl:
        label: URL to external Content
        type: select
        options:
            'https://jaspervdj.be/lorem-markdownum/markdown-html.html?no-wrapping=on': Lorem Markdownum
            'https://raw.githubusercontent.com/steirico/kirby-plugin-custom-add-fields/master/README.md': README
        icon: url

重用和扩展

插件支持用于重用和扩展字段的 extends 关键字

/blueprints/pages/event.yml:

....
addFields:
    extends: fields/event-common
    title:
        label: Title
        type: text
    host:
        extends: fields/contact
        label: Event Host

有关重用和扩展字段更多信息的文档，请参阅 Kirby 文档。

以这种方式，可以重用和扩展 kirby 的默认添加字段（title 和 slug）

/blueprints/pages/book.yml:

....
addFields:
    # Reuse title and slug
    # - kirby 3.6 and newer
    extends: fields/default-add-fields
    # - pre kirby v3.6
    # extends: fields/legacy-default-add-fields.yml

    # Add custom fields
    isbn:
        label: ISBN
        type: text

使用自定义添加字段

与页面蓝图字段对应的自定义添加字段的值将直接用于新页面。在上面的示例中，添加页面对话框中 title 的值将被设置为页面的 title。

处理 slug

为了使 Kirby 正确添加页面，必须设置 slug 属性。定义页面 slug 有三种方式：

1. 添加一个名为 slug 的自定义添加字段，以便手动定义 slug。
2. 如果缺少名为 slug 的字段，则插件将根据当前时间戳设置 slug。
3. 在页面钩子脚本中设置/覆盖 slug（见下文）。

在钩子脚本中使用自定义添加字段

可以在服务器端使用自定义添加字段的值来修改要添加的页面。

为此，可以注册一个 page.create:after 钩子 并修改 page 对象。

插件还注册了一个通用钩子，它将自动检测并调用名为 hookPageCreate($page) 的 页面模型的静态方法。定义页面模型和该方法如下

/site/models/remote.php:

<?php
class RemotePage extends Page {
    public static function hookPageCreate($page){
        // get value of add field remoteUrl
        $remoteUrl = $page->remoteUrl()->value();

        // fetch remote content
        $content = file_get_contents($remoteUrl);

        // update page field content
        $page->update(array(
            'content' => $content
        ));

        // set slug according to add field title
        $page->changeSlug(Str::slug($page->title()->value()));
    }
}

如果在 page.create:after 钩子或 hookPageCreate($page) 中抛出异常，则会将相应的错误发送回面板，但新创建的页面仍然保留。在这种情况下，建议捕获异常并删除新创建的页面

try {
    // set slug according to add field title
    $page->changeSlug(Str::slug($page->title()->value()));
} catch (Kirby\Exception\DuplicateException $e) {
    // A pages withe the same slug already exists.
    // Therefore, delete the newly created one.
    $page->delete(true);
}

配置重定向

Kirby 的添加对话框将重定向到新创建的页面。由于存在 相关 kirby 问题，如果在钩子中更改 slugs，则此行为无法可靠地重现。因此，插件默认行为是在添加页面后停留在实际的仪表板页面上。

如果需要，可以按蓝图设置属性 redirect 为 true 以实现重定向到新创建的页面

/blueprints/pages/parent.yml:

title: Parent Blueprint which skips the Add Dialog

# custom add fields definition
addFields:
    __dialog:
        redirect: true

如果需要在创建后重定向到现有页面，可以将 redirect 设置为该页面 ID。

/blueprints/pages/parent.yml:

title: Parent Blueprint which skips the Add Dialog

# custom add fields definition
addFields:
    __dialog:
        redirect: my/existing/page/id

强制使用特定模板

新页面的模板可以通过当前页面的一个字段来强制指定。默认情况下，如果当前页面存在名为 forcedTemplate 的字段，则其值将作为新页面的模板。

可以通过 kirby 选项 来更改此字段。

/site/config/config.php:

<?php

return [
    // exitsing configurations
    'steirico.kirby-plugin-custom-add-fields.forcedTemplate.fieldName' => 'myForcedTemplateField'
];

跳过添加对话框

该插件允许跳过添加对话框（查看论坛）。

/blueprints/pages/parent.yml:

title: Parent Blueprint which skips the Add Dialog

# custom add fields definition
addFields:
    __dialog:
        skip: true
        forcedTemplate: remote

除了设置属性 skip: true，还需要定义新页面的模板。这可以通过设置属性 forcedTemplate 或通过 强制使用特定模板 中描述的方法实现。

显示/隐藏模板选择

从 Kirby 3.5.0 版本开始，如果添加对话框中只有一个选项（除调试模式外），则模板选择将隐藏。默认情况下，该插件会根据 Kirby 版本模仿此行为。

不受使用的 Kirby 版本的影响，该插件允许通过 kirby 选项 forceTemplateSelectionField 控制或强制特定的行为。

/site/config/config.php:

<?php

return [
    // exitsing configurations
    'steirico.kirby-plugin-custom-add-fields.forceTemplateSelectionField' => true
];

将选项设置为 true 将始终使添加对话框显示模板选择。将其设置为 false 将在只有一个模板可用时隐藏模板选择。

已知问题

与该插件相关的一些已知问题

• 某些字段（例如，页面字段）会向后端执行额外的请求。尽管页面字段从 v1.1.1 版本开始工作，但此类字段可能无法与该插件一起使用。如果您遇到损坏的字段，请随时提交 问题。
• 当安装 kirby3-security-headers 时，它会在面板中添加 CSP 头部，破坏此插件。作为一个解决方案，您可以像这样禁用它：

  'bnomei.securityheaders.enabled' => function () {
    # Panel check, borrowed from @bnomei's `security-headers`
    # See https://github.com/bnomei/kirby3-security-headers/issues/18#issuecomment-709985170
    $isPanel = strpos(
        kirby()->request()->url()->toString(),
        kirby()->urls()->panel
    ) !== false;
  
    if ($isPanel) {
        return false;
    }
  
    return true; // or 'force'
  }

许可证

MIT

致谢和贡献者

• Rico Steiner
• Nils Hörrmann
• mvilskersts
• Martin Folkers