Node attachments

[jace]

Eventframe's current design encourages nodes and templates to be mutually aware. This is a poor situation because it breaks layering: mutual awareness becomes mutual dependence. Since nodes are maintained in an Eventframe instance while templates are in a git repository, maintenance and versioning are broken as well. Neither side is complete in itself.

The main culprit is the getnode template helper which lets templates (a lower layer) call up into nodespace (a higher layer).

Node properties were supposed to mitigate this, but properties are text-only and the resulting syntax is crummy: {% with othernode = getnode(path=node.properties.get('label-name-here')) %}

I propose deprecating properties with attachments, where other nodes are directly attached with text labels. This way, a template can ask for attachments named "col1", "col2", etc, without needing to know what node actually serves that data, removing its awareness of nodespace.

There needs to be a way to declare a template's dependence on named attachments. This can perhaps be encoded in a "template doc-comment", if Jinja supports reading comments out of a template file, or in a separate descriptor file that sits alongside the template. The editing UI can use this to remind the user that the node won't render with a given template unless all the named attachments are supplied. Another approach is to have a JSON or YAML descriptor file on disk alongside the template describing what the template does. Eventframe can search for these descriptors and provide documentation when a template is used.

Node attachments solve another problem: search. Previously, if a fragment matched search results, it could not be rendered directly and there was no way to know which node+template used it. Node attachments exist at the database level, so finding the appropriate node becomes straightforward (except in the case of additional attachments that are not required by the given template, and therefore not actually rendered).

[jace]

Point for consideration:

1. Fragments, like all nodes, have a buid which is used for identifying them across installations.
2. Fragments have unique names within their folders.
3. Fragments cannot be rendered with their names in the URL.
4. Fragments attached to a page node get another name there.

So why do fragments (and other non-rendering nodes) need names at all? Why pollute the namespace with strings that will not be used, causing confusion for users who do not understand what the names are for?

[jace]

Attachments can break during import/export if they are across folders, since impex is only one folder at a time. To fix:

1. In the export JSON for each node, supply {"attachments": {"name": "node-buid", ...}}
2. Also supply {"attached-to": {"name": "parent-buid"}

The second is a list of nodes to which this node is attached. By supplying both sides of the attachment, import can always reconnect attachments.

[jace]

This description of attachments sounds suspiciously like folder containment, except nodes can now be attached in more than one place. They can only be in one folder.

Is there a good reason for both folder containment and attachments to be allowed? Arguments for yes:

1. Folder containment provides canonical URLs for nodes
2. Fragments can be used in more than one place
3. Fragments can be edited/renamed/moved even when not attached to a node, allowing content to be built-up before being deployed

[jace]

Alternate proposal:

Keep folder containment, but make names optional for nodes that cannot be rendered. Let them be accessible by BUID instead (for editing). This will mean BUIDs and names share the same URL namespace (/folder/name), which is a slight concern.

OR: keep the current status quo with everything having names. make_name() is smart enough to avoid name conflicts. Remove name as a field that can be edited from the fragment edit form. Let it be auto-generated. Instead, allow renames from the folder view.

[jace]

In debug mode, a missing node attachment can default to a dummy node with a lorem ipsum generator, allowing a designer to continue work without having to produce dummy content themselves.