!!! FEATURE: NodeTemplates Version 2.0

[mhsdesign]

!!! TASK Separate template configuration processing from node creation
In preparation for the 9.0 version. But to have a larger test user base we will introduce this new architecture also for the old CR

resolves #48
resolves #50
resolves #43
resolves #35 (todo add configuration to turn on this feature)

see also #35 (comment)

NodeTemplates Version 2.0

With this new major release, we strive to make the version 2.0 template syntax and behaviour as close to the upcoming version 3 for Neos 9.
So you can for example expect stricter validation for properties already right now.
This mentality will make it easier to have a more similar code-base and also be able to easily backport features to the Version 2.
For that reason the whole code-base was refactored. With the most prominent changes being a two-step procedure to process the template and then start the node creation. Also a graceful exception handing wraps now nearly every operation.
This release is breaking for lots of edge cases but the error logs will hopefully be a helping compensation :D

!!! Refactoring: Two-step procedure to process the template and then start the node creation

Previously the template configuration was processed and nodes were created in the same step - coupled together. This was suboptimal architecture for the reasons:

• It didn't allow us to properly test the template configuration processing separately
• We couldn't prevent the template from being applied if somewhere an exception was thrown. See issue
• The implementation of the content repository handler could not be switched out easily say for Neos 9

FEATURE: Spot on exception handling, resuming with the next possible operation.

In the first step the configuration is processed, exceptions like those caused by an EEL Expression are caught, and any malformed parts of the template are ignored (with their errors being logged).
This might lead to a partially processed template with some properties or childNodes missing.

You can decide via the exception handling configuration Flowpack.NodeTemplates.exceptionHandling, if you want to start the node creation of this partially processed template (stopOnException: false) or abort the process (stopOnException: true), which will only lead to creating the root node, ignoring the whole template.

Flowpack:
  NodeTemplates:
    exceptionHandling:
     templateConfigurationProcessing:
        stopOnException: false

In case exceptions are thrown in the node creation of the template, because a node constraint was not met or the type field was not set, the creation of the childNode is aborted, but we continue with the node creation of the other left over parts of the template.
It behaves similar with properties: In case a property value doesn't match its declared type the exception is logged, but we will try to continue with the next property.

Changes in sight of Neos 9 ESCR forward compatibility

• !!! The functionality to set internal node properties via _foo property syntax, which was introduced with was reverted.
  This was done in preparation for the Neos 9 ESCR to be forwards compatible. A new properties._hidden: true equivalent is in the work already see pr. In case you need support for another node option that will still be available in the new ESCR, please create an issue and let us know. In the other case you can stay on the previous v1.x Version of this package.
  (9.0 DOCS: Node hidden vs disabled neos/neos-development-collection#4312 (comment))
• !!! Like in Neos 9 we will validate that the property type declaration of the NodeType matches the given value. In case of a mismatch the property will not be set and an Error message will be displayed.
• !!! Also like in Neos 9 properties have now to be declared in the NodeType and will otherwise not be set.
• The option nodeCreationDepth was removed. It was previously more of a necessity as it was needed for the property mapper. Now the whole template will be evaluated and applied.
• !!! Previously EEL Expression could not only access the triggeringNode but also the current node and parentNode. Due to the two-step approach, first evaluating the template, you will only have access on to the triggeringNode.
  In version 3 the nature of the new Neos 9 API won't allow you to access the triggeringNode but presumably only the current subgraph.
• !!! Experimental extensibility via Signal and the options array introduced with will also be dropped as the use case was unclear and conflicts with the refactoring to the mentioned two-step approach.

Other changes

• Many tests have been written to make sure the package is working as previously and increase its stability
• EEL expression are now determined if the string starts with ${ instead of trying to check if there is a valid expression. This will help in cases where the malformed expression was saved as property value instead throwing an error. See issue
• Previously variables of withContext where not accessible in the root uriPathSegment.
• The strategy for the uriPathSegment generation of child pages was changed from Neos\ContentRepository\Utility::renderValidNodeName($properties['title'] ?? null) to Neos\Neos\Utility\NodeUriPathSegmentGenerator::generateUriPathSegment($node, $properties['title'] ?? null)
• The uriPathSegment on the template root node will be either based on the template property properties.uriPathSegment or defaults to the slug generated from the creation dialog's data.title (The original behaviour).
• Template Configuration Validation
  • Its is now ensured that only ['properties', 'hidden', 'childNodes', 'when', 'withContext'] is set on the root template. The other options were previously silently ignored.
  • The option type is not allowed to be set for auto-created child nodes. We don't allow to change the type right now. We never did.
  • The option type must be set to a valid existing NodeType for to be created nodes. Previously it would fall back to the configured fallback like: Neos.Neos:FallbackNode.
  • !!! Now template configuration properties are stricter validated and can only hold non array types like int|float|string|bool|null. (Using nested arrays might come in handy for new features later like for setting Neos 9 reference properties.) Previously it was also possible to set a property to a list like propertyName = ['foo', 'bar'] instead of using EEL: propertyName = "${['foo', 'bar']}".
• Bugfix: Only EEL expression were allowed in root level title and uriPathSegment now simple strings work too
• Bugfix: EEL expression was not parsed when uriPathSegment was build from title property in childNodes

[mhsdesign]

Todo:

discuss exceptionHandlingBehaviour setting

[mhsdesign]

New process + exception handling explained:

                                                                                                    ┌─────────────────────────────┐                                                                                                                 
                                                                                                    │                             │                                                                                                                 
                                                                                                    │  exceptionHandlingStrategy  │                                                                                                                 
                                                                                                    │                             │                                                                                                                 
                                                                                                    └─────────────────────────────┘                                                                                                                 
                                                                                                                   │                                                                                                                                
                                                                                                                   │                                                                                                                                
                                                                                                                   └───────────────────┐                                                                                                            
                                                                                                                                       │                                                                                                            
                                                                                                                                       │                                                                                                            
                                                                                                                 ┌──────────────────────────────────────────┐                                                                                       
                                                                                                                 │  templateConfigurationProcessing  │────────────────────────┐                                                              
                                                                                                                 └──────────────────────────────────────────┘                        │                                                              
                                                                                                                                       ▲                                             │                                                              
                                                                                                                                       │                                             │                                                              
                                                                                                                                       │            yes, there was an expected       │                                                              
                                                                                                                                       │              caught exception while         │                                                              
                                                                                                                                       │              evaluation the template        │                                                              
                                                                                                                                       │            configuration. The template      │                                                              
┌──────────────────────────────────────────────────────┐                                                                               └────────────was still build partially.       │                                                              
│'Flowpack.NodeTemplates:Content.Container':           │                                                                                            (Ignoring malformed parts)       │                                                              
│  superTypes:                                         │                                                                                                          │                  │                                                              
│    'Neos.Neos:Content': true                         │                                        ┌───────────────────────────────────────────────────┐             │                  │                                                              
│    'Neos.Neos:ContentCollection': true               │                                        │{                                                  │             │                  │                                                              
│  properties:                                         │                                        │  "properties": { "isBla": true },                 │             │                  │                                                              
│    isBla:                                            │                                        │  "childNodes": [{                                 │             │                  │                                                              
│      type: boolean                                   │          Step 1 (Evaluation)           │    "type": "Flowpack.NodeTemplates:Content.Text", │             │                  ▼            Step 2 (Apply)           ┌───────────────────────┐
│  options:                                            │                                        │    "properties": { "text": "item foo" }           │     ┌──────────────┐         ┌───┐                                   │                       │
│    template:                                         │──────The template configuration ──────▶│  }, {                                             │────▶│  Exception?  │───no───▶│   │────────The properties will───────▶│  Content Repository   │
│      properties:                                     │         will be evaluated and          │    "type": "Flowpack.NodeTemplates:Content.Text", │     └──────────────┘         └───┘         be set and child          │                       │
│        isBla: true                                   │               expanded:                │    "properties": { "text": "item bar" }           │                                              nodes created           └───────────────────────┘
│      childNodes:                                     │                                        │  }]                                               │                                                                                               
│        textNodes:                                    │                                        │}                                                  │                                                                                               
│          withItems: [ "foo", "bar" ]                 │                                        └───────────────────────────────────────────────────┘                                                                                               
│          type: 'Flowpack.NodeTemplates:Content.Text' │                                                                                                                                                                                            
│          properties:                                 │                                                                                                                                                                                            
│            text: "${'item ' + item}"                 │                                                                                                                                                                                            
└──────────────────────────────────────────────────────┘