RFC: Document Markers

gerhard_boden · May 21, 2018, 6:59pm

Neos provides many different ways to provide dynamic links to certain nodes. Integrating a property with a reference selector, fixed child nodes, filtering by node type and probably many more.

But I would like to find a reliable way to dynamically link to a document node without any knowledge of the current site structure or node type configuration while at the same time being minimally invasive.

So my actual proposal would be configurable markers that can be easily placed on an existing site within the inspector (maybe even in its own tab to keep it separated from the node properties?)

The configuration itself could look something like this:

Neos:
  Neos:
   nodeMarker:
     ‘imprint’:
       label: ‘Imprint page’
       unique: true

There is an inspector editor where I then can choose from all available node markers and also receive an error when a unique marker is already in use.

A custom FlowQuery helper would help me find a specific marker. Could be looking something like this:

imprintNode = ${q(site).findByMarker(‘imprint’).get()}

Possible use cases for this would be a link within a plugin that needs the current “data protection policy” of a page, without having to know anything about the actual structure.
I would like to keep the necessary (and also possible) configuration down to an absolute minimum because for everything that goes beyond this a custom node type should be used.

As you can see I would not add the markers as properties. Should the markers (containing the node id) be kept in a separate model outside the NeosCR or should this be a property for Neos.Neos:Document with a select box editor combined with a check for uniqueness of the property? Wouldn’t that be rather slow on larger sites? (unless we use ES which should not be a necessary dependency for this to work properly)

Is there maybe even a better alternative altogether I’m not seeing here?

michael.gerdemann · May 22, 2018, 6:28am

Nice idea, I’d like a best practice solution to this problem.
But please note that it should be possible to give several markers to one page. This would speak in favor of storing the markers on e.g. the root page as properties.

mficzel · May 22, 2018, 6:54am

As i understand this approach it covers two aspects that should be adjusted but i am not sure we should cover them together:

1: Allow the definition of NodeConstraints that ensure a node like “impressum” exists maximal once. Currently we could only define this as autocreated childNode which does not cover optional nodes that may or may not exist.

Enforcing such constraints will be interesting since two editors could add new nodes in their personal workspace but only the first one should be allowed to publish. Btw. that would be the same with markers.

2: Avoid abusing nodeTypes for finding meaningful documents (“impressum”, “search”) again by adding another way to mark special nodes.

The first one is definitely a core topic, and not an easy one. Regarding the second i think this can be prototyped safely in an external package.

bwaidelich · May 22, 2018, 12:08pm

I don’t think that this extension is needed to be honest because it can be achieved with custom Node Types (and they make sense for some other reasons, too):

'Your.Site:Document.HomePage':
  superTypes:
    'Your.Site:Page': true
  constraints:
    nodeTypes:
      '*': false
  ui:
    label: 'Home Page'
    icon: 'icon-globe'
  childNodes:
    'search':
      type:  'Your.Site:Document.Search'
      position: 'start'
    'imprint':
      type:  'Your.Site:Document.Imprint'
      position: 'after search'

Those nodes can’t be inserted manually anywhere so a “maximal once” constraint is not required.

Besides: Because you just add the constraints to the homepage (or the parent page in question) once they are ready, there is no need to manually add them to each copy of the site.

Retrieving the instance is as easy as

${q(site).children('imprint').get(0)}

or

${q(node).find('[instanceof Your.Site.Imprint]').get(0)}

gerhard_boden · May 22, 2018, 7:41pm

Thanks for all the swift feedback guys

I wouldn’t care for a node to exist multiple times (could just be a general content node after all), but we would have to take care that the marker can only be assigned once in the inspector. Either with a custom model, or filtering for the property.

We also use this approach inside our site packages, but the idea with the document markers is aiming for a solution where you don’t need any knowledge of the node type structure at all. In your configuration for example I would have to know at least two nodes:

Your.Site:Document.HomePage and Your.Site:Document.Imprint .

Markers would be very useful in plugins to be assigned by the editor in the backend, without any YAML or Fusion configuration necessary to work on any site.

dfeyer · May 23, 2018, 10:28am

The PHPCR has this kind of feature, but I can’t find the documentation.

I will change the name to “Content Bookmarks”, and I see them they can serve in different case:

Use bookmark don’t need to be named nor unique, but can be useful
Some business require some legal notice at the end of an article, but with some variants, so the bookmarked content node can be marked “legal-basic”, “legal-product”, …
Samething when some document are a frequent target for link but with colision in the page title where bookmarks can be “product-search”, “knowledge-search”, …

Not sure if the bookmark need to be a node, I think a central bounded context, based on simple doctrine model, can works perfectly.

Bookmarks need to be created on the fly, so this feature is not really useful if a deployment is necessary to add new bookmarks. It’s really something that need to help Editor make their life easier, with requiring developer intervention.

I will continue to think about this and post maybe some more ideas later.

dfeyer · May 23, 2018, 10:34am

A bookmark MUST just be an alias of UUID, so one single Bookmark per UUID.

If we implement Bookmark with support for multiple bookmark per node, we implement Tagging, different use case, more complex. We really should take care that we dont create two concept that overlaps.

Bookmark is Editor conveniance

Tagging is way to organize content