README

当使用 Neos CMS 作为编辑器时，您通常需要手动创建嵌套的节点结构。此包旨在通过在 Neos UI 中自动创建有用的子节点并修改节点属性来简化编辑流程。

与在常规节点类型定义中定义的子节点（编辑器无法删除）不同，当应用模板时进行的所有修改都可以由编辑器更改或删除。

所需的节点结构以声明方式定义在 NodeTypes.yaml 文件下的 options.template 路径中。

TL;DR

1. composer require flowpack/nodetemplates
2. 如以下示例所述，将模板添加到 NodeTypes.yaml 中的 nodetypes 配置
3. 或使用以下命令根据工作区导出基于模板的配置

Hello world

以下示例将向通过 UI 创建的所有页面的主内容集合中添加一个包含“Hello World”内容的文本子节点

'Neos.NodeTypes:Page':
  options:
    template:
      childNodes:
        mainContentCollection:
          name: 'main'
          childNodes:
            helloWorldTextNode:
              type: 'Neos.NodeTypes:Text'
              properties:
                text: '<p>Hello world!</p>'

使用节点创建对话框

Neos UI 提供一个可配置的节点创建对话框。您可以使用 EEL 查询访问节点创建对话框中输入的数据。您可以允许编辑器在以下示例中选择不同的占位文本

'Neos.NodeTypes:Page':
  ui:
    creationDialog:
      elements:
        dummyText:
          type: string
          ui:
            label: 'Dummy text'
            editor: 'Neos.Neos/Inspector/Editors/SelectBoxEditor'
            editorOptions:
              values:
                'Hello world':
                  label: 'Hello world'
                'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.':
                  label: 'Lorem ipsum'
  options:
    template:
      childNodes:
        mainContentCollection:
          name: 'main'
          childNodes:
            helloWorldTextNode:
              type: 'Neos.NodeTypes:Text'
              properties:
                text: '${"<p>" + data.dummyText + "</p>"}'

如果您使用 showInCreationDialog 功能，也可以访问节点创建对话框中的数据

'Some.Package:SomeNodeType':
  # ...
  properties:
    'firstName':
      type: string
      label: 'First Name'
      ui:
        showInCreationDialog: true
    'lastName':
      type: string
      label: 'First Name'
      ui:
        showInCreationDialog: true
    'cardTitle':
      type: string
      label: 'Card Title'
  options:
    template:
      properties:
        cardTitle: '${"<h2>" + data.firstName + " " + data.lastName + "</h2>"}'

条件和循环

条件

如果您只想在满足某些条件下应用模板，可以使用 when 配置键。它可以在主节点模板或任何子节点模板中使用。

以下示例仅在创建对话框中选中选项时创建文本节点

'Your.NodeType:ContentCollection':
  ui:
    creationDialog:
      elements:
        createText:
          type: boolean
  options:
    template:
      childNodes:
        text:
          type: 'Your.NodeType:Text'
          properties:
            text: "bar"
          when: '${data.createText}'

由于 when 条件评估为 false 会阻止整个模板（以及所有子模板）的应用，因此其最常见用例是条件性子节点创建。

循环

循环可以用来创建多个子节点。您可以使用 withItems 定义循环的项。当使用 EEL 时，请确保返回一个数组。当前项在 EEL 表达式中的 item 上下文变量中可用。

以下示例在主内容集合中创建三个不同的文本子节点

'Neos.NodeTypes:Page':
  options:
    template:
      childNodes:
        mainContentCollection:
          name: 'main'
          childNodes:
            multipleTextNodes:
              type: 'Neos.NodeTypes:Text'
              properties:
                text: '${"<p>" + item + "</p>"}'
              withItems:
                - 'Hello world'
                - 'Different text'
                - 'Yet another text'

我们称条件为 when，循环为 withItems（而不是 if 和 forEach），因为它启发了一种更声明性的风格。命名灵感来自 Ansible。

EEL 上下文变量

在 EEL 上下文中有几个可用的变量。

注意 triggeringNode 将在版本 3.0 中删除

警告 parentNode 的行为从版本 1.x 到版本 2.2 发生变化。之前它引用当前模板部分的父节点及其嵌套。从版本 2.0 开始删除，2.2 重新引入了识别第一个/最顶层节点父节点的变量。

附加上下文

您可以通过 withContext 设置向模板添加更多上下文变量。withContext 接收一个任意数组的项目，其值可能包含 EEL 表达式

template:
  withContext:
    someText: '<p>foo</p>'
    processedData: "${String.trim(data.bla)}"
    booleanType: true
    arrayType: ["value"]
  childNodes:
    column0Tethered:
      name: column0
      childNodes:
        content0:
          type: 'Flowpack.NodeTemplates:Content.Text'
          when: "${booleanType}"
          withItems: "${arrayType}"
          properties:
            text: ${someText + processedData + item}

在withContext内部，可以通过EEL表达式访问父级上下文，但不能访问兄弟上下文值。由于withContext在when和withItems之前被评估，因此您可以在同一级别的withItems中访问来自withContext的上下文变量——但反之则不行。

如果您想使用自定义的EEL辅助函数，请确保在包的设置中注册它。为Neos.Fusion配置的EEL辅助函数不是自动可用的。

Flowpack:
  NodeTemplates:
    defaultEelContext:
      My.Foo: 'My\Site\Eel\Helper\FooHelper'

精细的错误处理，使用下一个可能的操作恢复。

在第一步中，处理配置，捕获由EEL表达式引起的异常，并忽略模板中的任何格式错误的部分（它们的错误将被记录）。这可能会导致部分处理的模板，其中某些属性或childNodes缺失。

您可以通过错误处理配置Flowpack.NodeTemplates.errorHandling来决定是否要启动此部分处理模板的节点创建（stopOnException: false），或者中止进程（stopOnException: true），这将只创建根节点，忽略整个模板。

Flowpack:
  NodeTemplates:
    errorHandling:
     templateConfigurationProcessing:
        stopOnException: false

如果在模板的节点创建过程中抛出异常，因为未满足节点约束或未设置type字段，则中止创建子节点，但我们会继续创建模板的其他剩余部分的节点。这与属性的行为类似：如果属性值与其声明的类型不匹配，则记录异常，但我们将尝试继续处理下一个属性。

命令

验证简单的节点模板

在一个较大的项目中，验证所有模板是否正常工作可能很繁琐。为了验证不依赖于节点创建对话框中的数据（较简单的模板）的那些模板，您可以利用此命令。

flow nodetemplate:validate

如果一切正常，它将成功执行X NodeType templates validated.。

但如果您的模板中存在语法错误或模板不匹配节点结构（非法属性），您将收到警告。

76 of 78 NodeType template validated. 2 could not be build standalone.

My.NodeType:Bing
 Property "someLegacyProperty" in NodeType "My.NodeType:Bing" | PropertyIgnoredException(Because property is not declared in NodeType. Got value `"bg-gray-100"`., 1685869035209)

My.NodeType:Bar (depends on "data" context)
  Configuration ""${data.aListOfThings}"" in "childNodes.pages.withItems" | RuntimeException(Type NULL is not iterable., 1685802354186)

独立的验证应该检测错误，并防止编辑器在运行时处理这些错误。

对于更复杂的模板，它们依赖于节点创建数据，建议编写单独的测试。目前，依赖于数据上下文的模板中的错误将仅被视为警告，因为在运行时可能不是问题。

从节点子树创建模板

当创建更复杂的节点模板（用于创建多个页面和内容元素）时，参考您的工作区中的当前节点子树可能会有所帮助。为此，您可以使用以下命令：

flow nodeTemplate:createFromNodeSubtree <starting node id>

• --starting-node-id：指定节点树的根节点

选项

• --workspace-name：从自定义工作区转储。默认为'live'。

它将给出类似于上述YAML示例的输出。在YAML中，对节点和非原始属性值的引用被注释掉了。

更多示例

有关更多示例，请参阅节点模板演示包。

https://github.com/mindscreen/neos-nodetemplates-demo