README

已弃用

Twigfield 已弃用；请使用 nystudio107/craft-code-editor 代替，这是一个通用的代码编辑器，也支持 Twig & 自动完成。

Twigfield for Craft CMS 3.x & 4.x

提供具有 Twig & Craft API 自动完成的 twig 编辑器字段

要求

Twigfield 需要 Craft CMS 3.0 或 4.0。

安装

要安装 Twigfield，请按照以下步骤操作

1. 打开您的终端并转到您的 Craft 项目

    cd /path/to/project
   

2. 然后让 Composer 需求此包

    composer require nystudio107/craft-twigfield
   

关于 Twigfield

Twigfield 提供了一个功能齐全的 Twig 编辑器，通过强大的 Monaco Editor（这是 VS Code 的基础编辑器）进行语法高亮。

Twigfield 为 Twig 过滤器/函数/标签以及完整的 Craft CMS API 提供了完整的自动完成，包括已安装的插件

并且当您将鼠标悬停在表达式上时，它会添加悬停文档

您还可以添加您自己的自定义自动完成，并自定义编辑器的行为。

Twigfield 还为 Twig 模板和对象模板提供了一个 Yii2 验证器。

使用 Twigfield

一旦您将 nystudio107/craft-twigfield 包添加到您的插件、模块或项目中，就不需要进一步的设置。这是因为它作为自动引导的 Yii2 模块运行。

Twigfield 不是一个 Craft CMS 插件，而是一个由插件、模块或项目使用的包。

将其添加到现有项目非常容易，如从 Preparse field pull request 中看到，该请求将其添加到 Preparse 插件。

在 Craft CP 中

Twigfield 与 Craft CMS 的 forms 宏类似，这对插件和模块开发者来说应该是熟悉的。

导入宏

只需导入宏即可

{% import "twigfield/twigfield" as twigfield %}

多行编辑器

然后要创建一个 textarea 多行编辑器，请执行以下操作

{{ twigfield.textarea({
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: textAreaText,
}) }}

...其中 textAreaText 是一个包含编辑器字段中应包含的初始文本的变量。这将创建一个 Twig 编辑器。

要创建一个多行 textareaField 编辑器，请按照以下步骤操作

{{ twigfield.textareaField({
    label: "Twig Editor"|t,
    instructions: "Enter any Twig code below, with full API autocompletion."|t,
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: textAreaText,
}) }}

...其中 textAreaText 是一个变量，包含编辑器字段中应显示的初始文本。这将创建 label 和 instructions，以及 Twig 编辑器。

单行编辑器

然后，要创建一个 text 单行编辑器，请按照以下步骤操作

{{ twigfield.text({
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: text,
}) }}

...其中 text 是一个变量，包含编辑器字段中应显示的初始文本。这将创建一个限制为单行的 Twig 编辑器，用于简单的 Twig 表达式。

要创建一个 textField 单行编辑器，请按照以下步骤操作

{{ twigfield.textField({
    label: "Twig Editor"|t,
    instructions: "Enter any Twig code below, with full API autocompletion."|t,
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: text,
}) }}

...其中 text 是一个变量，包含编辑器字段中应显示的初始文本。这将创建 label 和 instructions，以及限制为单行的 Twig 编辑器，用于简单的 Twig 表达式。

无论使用哪个宏，都会包含一个包含编辑器所需 CSS 和 JavaScript 的 Asset Bundle，并初始化编辑器。

在前端模板中

默认情况下，Twigfield 不会在前端模板中工作，除非您明确启用它。

通过将 config.php 文件复制到 Craft CMS 的 config/ 目录，并在过程中将其重命名为 twigfield.php 来执行此操作，然后将 allowFrontendAccess 设置为 true

return [
    // Whether to allow anonymous access be allowed to the twigfield/autocomplete/index endpoint
    'allowFrontendAccess' => true,
    // The default autcompletes to use for the default `Twigfield` field type
    'defaultTwigfieldAutocompletes' => [
        CraftApiAutocomplete::class,
        TwigLanguageAutocomplete::class,
    ]
];

然后导入宏

{% import "twigfield/twigfield" as twigfield %}

创建自己的 <textarea> 元素，并包含必要的 JavaScript，传入您的 textarea 元素的 id

<textarea id="myTwigfield">
</textarea>
{{ twigfield.includeJs("myTwigfield") }}

启用 allowFrontendAccess 设置允许访问 twigfield/autocomplete/index 端点，并将 twigfield/templates 目录添加到模板根目录。

其他选项

textarea、textareaField、text、textField 和 includeJs 宏都接受四个可选参数

{{ textarea(config, fieldType, wrapperClass, editorOptions, twigfieldOptions) }}

{{ textareaField(config, fieldType, wrapperClass, editorOptions, twigfieldOptions }}

{{ text(config, fieldType, wrapperClass, editorOptions, twigfieldOptions) }}

{{ textField(config, fieldType, wrapperClass, editorOptions, twigfieldOptions }}

{{ includeJs(fieldId, fieldType, wrapperClass, editorOptions, twigfieldOptions }}

fieldType

fieldType - 可选的第二个参数。默认情况下，此值设置为 Twigfield。如果您使用的是自定义自动完成（见下文），则可能需要更改此值。

例如：

{{ twigfield.textarea({
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: textAreaText,
}), "MyCustomFieldType" }}

wrapperClass

wrapperClass - 可选的第三个参数。这是添加到 Twigfield 编辑器包装器 div 的额外类。默认情况下，这是一个空字符串。

例如：

{{ twigfield.textareaField({
    label: "Twig Editor"|t,
    instructions: "Enter any Twig code below, with full API autocompletion."|t,
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: textAreaText,
}), "Twigfield", "monaco-editor-background-frame" }}

捆绑了 monaco-editor-background-frame 类，这将使字段看起来像 Craft CMS 编辑器字段，但您也可以使用自己的类。

还有一个捆绑的 monaco-editor-inline-frame 样式，用于表格单元格中的内联编辑器（或不需要边框的其他地方）。

这两个捆绑样式在编辑器处于活动状态时都使用可访问性焦点环，这与 Craft CP 风格相匹配。

editorOptions

editorOptions - 可选的第四个参数。这是一个传递给 Monaco 编辑器以配置编辑器的 EditorOption。默认情况下，这是一个空对象。

例如：

<textarea id="myTwigfield">
</textarea>
{{ twigfield.includeJs("myTwigfield", "Twigfield", "monaco-editor-background-frame", {
    lineNumbers: 'on',
}) }}

twigfieldOptions

twigfieldOptions - 可选的第5个参数。这个对象可以包含您想要从您的Twig模板传递到自动完成的任何数据。这可以在自定义自动完成中利用，以将特定字段的上下文传递给自动完成（见下文）

例如：

{{ twigfield.textareaField({
    label: "Twig Editor"|t,
    instructions: "Enter any Twig code below, with full API autocompletion."|t,
    id: 'myTwigfield',
    name: 'myTwigfield',
    value: textAreaText,
}), "Twigfield", "monaco-editor-background-frame", { lineNumbers: 'on' }, {
   'key': value,
   'key2': value2,
} }}

使用其他自动完成

默认情况下，Twigfield使用CraftApiAutocomplete和TwigLanguageAutocomplete，但它还包括一个可选的EnvironmentVariableAutocomplete，它提供了任何Craft CMS 环境变量和别名的自动完成。

如果您想使用EnvironmentVariableAutocomplete或您编写的自定义自动完成，您需要向您的插件、模块或项目中添加一些PHP代码

use nystudio107\twigfield\autocompletes\EnvironmentVariableAutocomplete;
use nystudio107\twigfield\events\RegisterTwigfieldAutocompletesEvent;
use nystudio107\twigfield\services\AutocompleteService;

Event::on(
    AutocompleteService::class,
    AutocompleteService::EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES,
    function (RegisterTwigfieldAutocompletesEvent $event) {
        $event->types[] = EnvironmentVariableAutocomplete::class;
    }
);

上述代码将添加环境变量和别名自动完成到所有您的Twigfield编辑器中。

但是，因为您可能在同一页上有一个以上的Twigfield实例，并且它们可能提供不同的自动完成，您可能只想在fieldType匹配特定值时选择性地添加自定义自动完成。

以下是一个来自Sprig插件的示例

use nystudio107\twigfield\events\RegisterTwigfieldAutocompletesEvent;
use nystudio107\twigfield\services\AutocompleteService;
use putyourlightson\sprig\plugin\autocompletes\SprigApiAutocomplete;

public const SPRIG_TWIG_FIELD_TYPE = 'SprigField';

Event::on(
    AutocompleteService::class,
    AutocompleteService::EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES,
    function (RegisterTwigfieldAutocompletesEvent $event) {
        if ($event->fieldType === self::SPRIG_TWIG_FIELD_TYPE) {
            $event->types[] = SprigApiAutocomplete::class;
        }
    }
);

这确保了当传递给Twigfield宏的fieldType设置为SprigField时，才会添加SprigApiAutocomplete自动完成。

此外，您可能有一个您想在实例化时传递配置信息的自动完成。您可以通过将其作为数组添加来自动完成来实现这一点

use nystudio107\twigfield\autocompletes\CraftApiAutocomplete;
use nystudio107\twigfield\events\RegisterTwigfieldAutocompletesEvent;
use nystudio107\twigfield\services\AutocompleteService;

Event::on(
    AutocompleteService::class,
    AutocompleteService::EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES,
    function (RegisterTwigfieldAutocompletesEvent $event) {
         $config = [
             'additionalGlobals' => $arrayOfVariables,
         ];
        $event->types[] = [CraftApiAutocomplete::class => $config];
    }
);

注意，上述所有示例都是通过添加自动完成到Twigfield默认提供的自动完成（CraftApiAutocomplete和TwigLanguageAutocomplete）来完成的。如果您想完全替换它们，只需先清空types[]数组即可

        $event->types[] = [];
        $event->types[] = [CraftApiAutocomplete::class => $config];

编写自定义自动完成

自动完成从基本自动完成类扩展，并实现了自动完成接口

简单的自动完成看起来像这样

<?php
namespace myvendor\myname\autocompletes;

use nystudio107\twigfield\base\Autocomplete;
use nystudio107\twigfield\models\CompleteItem;
use nystudio107\twigfield\types\AutocompleteTypes;
use nystudio107\twigfield\types\CompleteItemKind;

class MyCustomAutocomplete extends Autocomplete
{
    public $name = 'EnvironmentVariableAutocomplete';

    public $type = AutocompleteTypes::GeneralAutocomplete;
    
    public $hasSubProperties = false;

    public function generateCompleteItems(): void
    {
    CompleteItem::create()
        ->label('MyAutocomplete')
        ->insertText('MyAutocomplete')
        ->detail('This is my autocomplete')
        ->documentation('This detailed documentation of my autocomplete')
        ->kind(CompleteItemKind::ConstantKind)
        ->add($this);
    }
}

$name属性是您的自动完成的名称，它用于自动完成缓存。

$type属性是AutocompleteTypes::TwigExpressionAutocomplete（仅在Twig表达式中自动完成）或AutocompleteTypes::GeneralAutocomplete（在任何地方自动完成）。

$hasSubProperties属性表示您的自动完成是否返回嵌套子属性，例如foo.bar.baz。这个提示有助于Twigfield提供更好的自动完成体验。

CompleteItem::create()是一个工厂方法，用于创建一个CompleteItem对象。您可以使用上面显示的Fluent Model设置器，或者也可以直接在模型上设置属性。CompleteItem::add()方法将其添加到生成的自动完成列表中。

您的自动完成还有一个$twigfieldOptions属性，它将包含通过可选的第5个twigfieldOptions参数从您的Twig模板传递下来的任何数据。这允许您具有特定字段的上下文信息。

请参阅以下示例，这些示例可以作为您创建自己的自定义自动完成的指南

• TrackingVarsAutocomplete
• SprigApiAutocomplete
• CraftApiAutocomplete
• EnvironmentVariableAutocomplete
• TwigLanguageAutocomplete

Twig模板验证器

Twigfield 还包括两个可以用来验证作为模型一部分保存的 Twig 模板的 验证器。

• TwigTemplateValidator - 通过 renderString() 验证模板
• TwigObjectTemplateValidator - 通过 renderObjectTemplate() 验证模板

您只需将它们作为规则添加到您的模型中，它就会传播模型，并在渲染模板时遇到任何错误

use nystudio107\twigfield\validators\TwigTemplateValidator;

public function defineRules()
{
    return [
        ['myTwigCode', TwigTemplateValidator::class],
    ];
}

您还可以添加任何应在 Twig 环境中存在的 变量

use nystudio107\twigfield\validators\TwigTemplateValidator;

public function defineRules()
{
    return [
        [
            'myTwigCode', TwigTemplateValidator::class,
            'variables' => [
               'foo' => 'bar',
           ]
        ],
    ];
}

对于 TwigObjectTemplateValidator，您还可以传入在渲染对象模板时应使用的 对象

use nystudio107\twigfield\validators\TwigObjectTemplateValidator;

public function defineRules()
{
    return [
        [
            'myTwigCode', TwigObjectTemplateValidator::class, 
            'object' => $object,
            'variables' => [
               'foo' => 'bar',
           ]
        ],
    ];
}

Twigfield 路线图

一些要做的事情，以及潜在功能的想法

• 也许可以作为衍生品的一个通用代码编辑器？
• 添加解析方法返回参数的处理程序，以便我们可以获取类似 craft.app.getSecurity(). 的自动完成
• 找出为什么建议详细信息的子窗口似乎没有正确调整大小以适应 文档。它在那里，但您必须调整窗口大小才能看到它，并且似乎某种方式计算错误
• 更智能的 Twig 表达式检测
• 只有当它们在 Twig 表达式中时，才应添加 TwigExpressionAutocomplete 的悬停
• 如果 SectionShorthandFieldsAutocomplete 完成也提供子项完成，那就更好了

由 nystudio107 提供