Content reference block (Block Editor) #19215
Replies: 7 comments 14 replies
-
|
I think for this to work as expected, we should really implement the block editor to operate as a m2a. Without doing so, we'd lose relational constraints and the ability for the api to nest data responses 🤔 |
Beta Was this translation helpful? Give feedback.
-
|
Yes, that would be way better than just adding the item ID into the JSON - also a lot more complex to build, I imagine. |
Beta Was this translation helpful? Give feedback.
-
|
that would require each collection with an editor to have its own M2A junction collection. and what if there are multiple editors in one collection? |
Beta Was this translation helpful? Give feedback.
-
|
alternative approach: there is a "directus_block_editors" system-collection which keeps track of all block editors. |
Beta Was this translation helpful? Give feedback.
-
|
Please be aware, the day after I submitted this feature request, Formfcw released an extension called Flexible Editor which largely achieves effectively want we want, but with the added benefit of creating relationships between the current item and the referenced items. |
Beta Was this translation helpful? Give feedback.
-
|
I've tried the "Flexible-Editor" and it is a very good proof of concept. Setup is a little bit hard, but it is a good showcase how things should work. But in the long run I would really like to see this kind of feature in Directus Core to advertise Directus as viable CMS solution, because in the long run it would be easier to build trust with clients if they don't depend on 3rd party plugins. |
Beta Was this translation helpful? Give feedback.
-
|
Heya! Thanks for opening this feature request! This feature request has received over 15 votes from the community. This means we'll move this feature request to the Under Review state! The Core team will schedule a meeting to review this request as soon as possible. The discussion will then be approved or denied. You may or may not be invited to join this meeting with the core team. For more information, see our Feature Request Process. |
Beta Was this translation helpful? Give feedback.
-
|
Unresolved Questions:
|
Beta Was this translation helpful? Give feedback.
-
|
After giving this some more thought, I believe it makes the most sense for this core-interface to be implemented based on the many to any structure. That'll give you the flexibility for the pagination question, nested relational lookups, foreign key constraints, and helps with configuring allowed related collections, as that's already part of the regular many to any setup. I'd also think it'd be super nice if each related collection becomes it's own "Block" type inline there, so instead of having a single |
Beta Was this translation helpful? Give feedback.
-
|
I have created the Flexible Editor extension which was already mentioned earlier. While working on it, I always had the idea in mind that one day it could be integrated into the Directus core. This means everything is meant to be done the Directus way and the code should be easy to read. In short: Flexible Editor integrates the Tiptap editor as an extension into the Directus app and utilizes an optional many-to-any (M2A) field to place and link related nodes in the editor. With Flexible Editor Content the editors JSON content can be serialized with interactive components on the front-end. Here is a video demo: flexible-editor.mp4ThoughtsFrom this point I would like to share my thoughts and experiences in the following (expandable) sections: Editor choiceFlexible Editor uses the Tiptap editor for a good reason: Inline marks like bold, italic or links are stored as JSON, while Editor.js (used by Directus’ block editor) stores it as plain html (at the time of writing). The latter makes rendering these inline marks unnecessarily difficult in a component library like React or Vue. Read more about rendering below. Here is an example to demonstrate the difference while using the same input: Editor.js output: {
"time": 1696920696173,
"blocks": [
{
"id": "AgITQMm-Vg",
"type": "paragraph",
"data": {
"text": "How <a href=\"https://directus.io/\">inline marks</a> are stored.<br>"
}
}
],
"version": "2.22.1"
}Tiptap editor output: {
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{ "type": "text", "text": "How " },
{
"type": "text",
"marks": [
{
"type": "link",
"attrs": {
"href": "https://directus.io",
"target": "_blank",
"rel": "noopener noreferrer nofollow",
"class": null
}
}
],
"text": "inline marks"
},
{ "type": "text", "text": " are stored." }
]
}
]
}SetupThe setup process should be simple. Since the current version of Flexible Editor is a MVP, there is still room for improvement in this regard. However, there are limitations by Directus. Here’s what might make it feel more intuitive.
All in one fieldCurrently, it is not possible to combine a JSON structure and a M2A relation in one field in a meaningful way. Therefore, Flexible Editor requires two fields – a JSON field and a M2A field – which complicates the setup. Besides the setup process, there is another aspect where the combination of JSON and M2A in one field would be useful: no need to sync relation nodes. Flexible Editor is an interface for a JSON field, and uses a separate M2A-field to integrate relation nodes. This means that the relation nodes must always be kept in sync with the content of the editor. We could skip this part, if the JSON structure itself could hold all the information/values to create/update/delete the related M2A items. For example, when adding a video-url (for embedding) via a related collection called “videos”, we are getting the following value in the M2A field … {
"create": [
{
"collection": "videos",
"item": {
"video_url": "https://video-provider.com/2309487"
},
"id": "2f06f613-2348-47c9-8524-1d70831757c3"
}
],
"update": [],
"delete": []
}… and the following value in Flexible Editor (where the ID has to be the same): {
"type": "doc",
"content": [
{
"type": "relation-block",
"attrs": {
"id": "2f06f613-2348-47c9-8524-1d70831757c3",
"junction": "editor_nodes",
"collection": "videos"
}
}
]
}For an “all in one field” approach it would be ideal to integrate the create-update-delete-command from above in the editors JSON structure like this: {
"type": "doc",
"content": [
{
"type": "relation-block",
"attrs": {
"id": "2f06f613-2348-47c9-8524-1d70831757c3",
"collection": "videos",
"relation": {
"create": [
{
"collection": "videos",
"item": {
"video_url": "https://video-provider.com/2309487"
},
"id": "2f06f613-2348-47c9-8524-1d70831757c3"
}
],
"update": [],
"delete": []
}
}
}
]
}Then when saving the item (that holds the block editor), the create-update-delete-command(s) could be extracted and executed as before. To extract these commands of the JSON structure a callback function could be emitted inside Directus interfaces, that extracts the commands, depending on the editor implementation and its corresponding JSON structure. The latter allows extension developers to implement a different editor with a different JSON structure. Types of relation nodes (internal linking)At the time of writing, Flexible Editor supports the usage of Relation Blocks, which are references to other (collection) items. There are two more types of “relation nodes” that could be implemented:
While relation inline blocks don't have that many use cases, relation marks are very important because they provide a solution for internal linking. Create and/or select itemsAt the time of writing Flexible Editor supports creating new M2A items and inserting them into the editor. To insert existing items you need to use a wrapper collection. As others have mentioned, it would be ideal if we could insert multiple existing items directly and at once, as we are used to do it with the M2A Builder interface. This could be solved via the drawer by adding a create button to it. To wrap it up, here are the three use cases (already mentioned in the setup section above):
This way we avoid doubling every UI button in the editor interface, like „Create News“ and „Select News“. Duplication (Set Item Duplication Fields automatically)Duplication of related M2A items is a complex topic because there are so many use cases:
Apart from all these use cases, we would have a bad experience when we had to specify the “Item Duplication Fields” for each related collection and for each editor field we use. There is no question that we need these rules, but I think we could provide a default behaviour for this. Have a look at this feature request about “Set Item Duplication Fields automatically”. Fetching dataAt the time of writing, Flexible Editor needs to retrieve the editors JSON content and its relation nodes separately, like … () => [
// Fetch the editors JSON content
"description",
// Fetch the editors relation nodes
"relation_nodes.gallery.*",
"relation_nodes.video.*",
"relation_nodes.related_content.*",
];… and then merge it on the front-end like: import { injectDataIntoContent } from "directus-extension-flexible-editor/content";
const data = await fetchDirectusData();
injectDataIntoContent(data.editor_nodes, data.description);It would be nice to skip the last part and inject the data already on the backend like: () => [
"description.gallery.*",
"description.video.*",
"description.related_content.*",
];But I think if we don't use two separate fields (read more above at “All in one field”), this would happen anyway. Rendering in the front-end (SDK)When it comes to rendering the JSON Content generated by the editor, we need to provide a way to serialize it with interactive components, aside from just rendering plain HTML or plain text. Flexible Editor provides Flexible Editor Content, where you can pass the data to (Vue) components, so that you can fully customize the output for each individual node (block or mark). For example, you could take a link node and render its data using your own link component – or a router link component provided by your framework. But the main focus here is to serialize relation nodes. Read more about this in the Flexible Editor Content docs or check out this example on StackBlitz. Such a toolset could be provided through the SDK and offer components for the most common frameworks like Vue, React, and so on. As you can see, there are many aspects associated with an “editor with content references”. I've put a lot of work into this project and would be happy if it could be integrated into the Directus core, as I am still interested in pushing this “beast” forward. |
Beta Was this translation helpful? Give feedback.
-
|
Let me know how I can help ! |
Beta Was this translation helpful? Give feedback.
-
How do you mean import HTML data? migrating from a wysiwyg to structured json is very custom to your wishes/project as your frontend will need to render the JSON into the desired html instead of just getting a HTML string so there will not be a 1 to 1 translation there.
For the SDK the content of the flexible editor is just a JSON blob so the transformation will have to be done before handing the final JSON to the SDK to submit it. |
Beta Was this translation helpful? Give feedback.
-
|
It would be nice to document the shape of the JSON blob that the Flexible Editor accepts. I am working on the JSON APIs that represent the HTML content in our current wysiwyg. One of the things that took a bit to figure out was how to write an HTML parser that got the correct shape of the JSON and the types. For example, I learned that |
Beta Was this translation helpful? Give feedback.
-
|
Oh now I see that these managed by the TipTap editor https://tiptap.dev/docs/editor/api/nodes |
Beta Was this translation helpful? Give feedback.
-
|
@formfcw great work on the plugin! :-) |
Beta Was this translation helpful? Give feedback.
-
|
Something else to consider — Make the relationship happen at the record level first. Then make it possible to choose which of the related items appear in the content body. Example:Let's say I have a publication that produces a lot of articles, and also a lot of videos. In the article that I am writing, I am referencing in the text a number of the videos we produce, but I really only want to embed one on the page and plan on linking off to the rest. Here is how I produce that:
This reduces the responsibility that the content body field has to manage all of these relationships, both technically, and for editors. It also opens up options in that these content relationships are part final JSON output. |
Beta Was this translation helpful? Give feedback.
-
|
For your use case, I would suggest creating two separate relationships like Or even better: Create one relationship I won't recommend manually referencing cryptic video codes inside a text editor. |
Beta Was this translation helpful? Give feedback.
-
|
@formfcw Can u give more details about how do u use shortcodes ? do you process them on frontend? |
Beta Was this translation helpful? Give feedback.
-
|
@snimavat I don’t use shortcodes. |
Beta Was this translation helpful? Give feedback.
-
Summary
Add a custom block to the Block Editor that allows users to insert a reference to an existing content item. Effectively, we want to be able to use the M2A interface inside the Block Editor.
Basic Example
No response
Motivation
We need the ability to freely mix rich text content and references to other content items. When building content, you sometimes want to reference other content items. Currently, the only way to provide that ability is to use an M2A (page builder) field. This allows you to build your content by adding existing content items in a specific order. Unfortunately, this requires that all the “pieces” that you use to build your content must be content items of their own – it is not possible to compose some new content directly onto the current item, then reference another content item, then continue composing the content on the current item. Not only is this an uncomfortable editing experience, it means you need a content model for your “content fragments” and you’ll end up with lots of single-use content items many of which would contain just a single sentence.
Imagine you’re building the body content for a webpage. Using the current M2A page builder method, that would look something like this:
Using the proposed content reference tool within Block Editor, it would look something like this:
Detailed Design
When adding the Block Editor to a content model, you should first be able to choose ‘content reference’ as a tool from the list of tools to show in the toolbar. If you do enable ‘content reference’ as a tool, then you should be able to specify which collections users should be able to reference content from.
When using the Block Editor, the user should be able to select ‘content reference’ from the toolbar.
This will then present 2 options ‘create item’ or ‘add existing’, which when clicked will show a dropdown list of collections.
Selecting a collection to add existing item from will open the drawer showing all items in that collection allowing the user to select multiple items.
Confirming the selection will take you back to the block editor, with your referenced items inserted.
Allowing you to continue inserting blocks and building your content around the inserted references.
The references are stored in the JSON just like any other block editor content, that would look something like this:
In context that would look like this, for example:
Requirements List
Must Have:
Should Have:
Could Have:
Won't Have:
Drawbacks
I tried really hard – I couldn’t think of any 👀
Alternatives
We considered other solutions to the problem:
Some of the risks of not implementing this feature are:
Adoption Strategy
This will not be a breaking change. It will be a new tool that Directus developers can simply opt-in to by editing the content models and adding it to their block editor toolbar. Adoption will be entirely optional.
Unresolved Questions
• Do developers want to be able to choose whether to enable the ‘create new’ and ‘add existing’ buttons?
• Do developers want to be able to allow/disallow duplicates?
• Do developers want to be able to limit the number of items that can be referenced?
• Should referenced items paginate?
Beta Was this translation helpful? Give feedback.
All reactions