RFC: New Prototypes `Neos.Fusion:Renderer.Path` and `Neos.Fusion:Renderer.Type`

Creating Neos & Flow
1

@sjsone and I looked into documenting the Neos.Fusion:Renderer but the prototypes functionality is quite hard to explain and to use due to overloaded properties.

Current state

The Neos.Fusion:Renderer accepts 3 paths as an entry point.
Either renderer, renderPath or type. In the last case the element path will also come into play, but it’s ignored otherwise.
If no option is given the renderer will assume the type is existing and an hard to parse error will be thrown.

The Fusion object “” cannot be rendered: Most likely you mistyped the prototype name or did not define the Fusion prototype […]

Suggestion

Neos.Fusion:Renderer.Path

to eventually replace Neos.Fusion:Renderer { renderPath }

Documentation of the prototype

Renders a given fusion path

return

mixed The rendered path

usage

A Fusion path must be provided as string of alpha numeric characters
seperated by slashes.
The path must be renderable. This can be ensured via Neos.Fusion:CanRender.Path.

absolute path

Absolute paths start with a slash and will be directly evaluated
by the runtime:

value = Neos.Fusion:Renderer.Path {
    path = "/root/foo/bar"
}
root.foo.bar = "to be rendered"

relative path

Relative paths start without slash and will be rendered
relative to the path where this object resides in:

value = Neos.Fusion:Renderer.Path {
    path = "foo/bar"
    foo.bar = "to be rendered"
}

dynamic path

Anything that will evaluate to a valid path might be used:

value = Neos.Fusion:Renderer.Path {
    path = ${'/' + String.replace(request.format, '.', '/')}
}
json = "to be rendered"

prototype(Neos.Fusion:Renderer.Path) {
    /// string The path in relative or absolute format.
    path = ""
}

Differences to Neos.Fusion:Renderer

  • renderPath was renamed to path
  • a relative path is not allowed to contain dots (which were transformed to slashes)
  • for fusion pro’s the syntax /element<My:Object> is an internal implementation detail of the php fusion runtime implementation and will no longer be leaked outside, and thus will not be accepted as path.
  • a more descriptive exception will be thrown if the path does not exist

Neos.Fusion:Renderer.Type

to eventually replace Neos.Fusion:Renderer { type }

Documentation of the prototype

Renders a Fusion prototype by its name

return

mixed The rendered Fusion prototype

usage

A valid and defined Fusion prototype name must be provided as argument.

rendering by type

value = Neos.Fusion:Renderer.Type {
    type = "Vendor.Package:My.Component"
}

rendering with dynamic type

Anything that will evaluate to a valid prototype might be used:

value = Neos.Fusion:Renderer.Type {
    type = ${prototypeName}
}

full dynamic rendering

Addtionally the structure can define properties that will
be available to the Fusion prototype:

value = Neos.Fusion:Renderer.Type {
    type = ${"Neos.Fusion:Value"}
    structure {
        value = "output"
    }
}

prototype(Neos.Fusion:Renderer.Type) {
    /// string The prototype name to be rendered.
    type = ""
    //// The fusion structure that is available to the prototype.
    structure {
    }
}

Differences to Neos.Fusion:Renderer

  • element was renamed to structure
  • a proper exception will be raised if the type is empty or could not be rendered.

The renderer option of Neos.Fusion:Renderer doesn’t need a replacement, as this is just an alias for Neos.Fusion:Value.

To align behaviour with the Neos.Fusion:CanRender prototype, it will as well be deprecated in favour of:

// replaces Neos.Fusion:CanRender { path }
prototype(Neos.Fusion:CanRender.Path) {
    path = ""
}

// replaces Neos.Fusion:CanRender { type }
prototype(Neos.Fusion:CanRender.Type) {
    type = ""
}
1 Like
2

Agree to that, we should try to find better names still. The current suggestions reflects where it comes from but i hope there may be better names describing what it actually does.

  • Neos.Fusion:Renderer.ByType
  • Neos.Fusion:Render.Type
  • Neos.Fusion:Render.Prototype
  • …
1 Like
3 
<Neos.Fusion:Render.Prototype
    prototype={props.teaserNodeType}
    structure.@apply.data={item}
/>
<Neos.Fusion:Render.Path
   path={props.headerPath}
/>
4

I don’t like the proposed naming scheme as it sounds more like an object or variable than something that does something.

So personally I would prefer something like Neos.Fusion:PathRenderer or Neos.Fusion:TypeRenderer as it better communicates what it does IMO.

2 Likes