Integration of diagrams.net (draw.io)

[ebivan]

Hey there, I just found Collectives and love it so far. First thing, I would like to use it for is documentation of my home IT projects. For most documentation purposes, visualization is an important factor. Thats why I suggest integration of draw.io, directly into Collectives. (like on Bookstack). Right now, its already possible to create, edit and save draw.io diagrams within NC using the draw.io app. But at the oment one has to Edit these files within the draw.io app, export them into some image file and then you can add them into Collectives. When changeing the diagram it has to be exportet again... But it would be even better, if that was also possible to directly integrate support for that from in Collectives.

[mejo-]

Now that reference providers are supported by Nextcloud, the Draw.io App could implement a custom reference provider for drawio files.

[juliushaertl]

Might be related to #414 as draw.io diagrams are also just files. I'm wondering if having an inline preview in the regular file widget would be feasible (at least as an option).

We may need to think more about how to reference and differentiate them and it would require general work on the widget API but as a quick mockup this could work also for PDFs and office documents

[mejo-]

I'm wondering if having an inline preview in the regular file widget would be feasible (at least as an option).

That's what I meant. But thinking more about it I see your point that this is not too easy to achieve, given that you would have to embed the application that renders the file into the widget. Still something that would be really nice to have, and I like your idea of making this configurable with a #embed anchor in the file link.

[max-nextcloud]

Frankly... I don't like the idea of embedding files in files. I can see the use for diagrams in collective pages - but even there i think a preview that opens the diagram in the viewer is sufficient for most of the cases.

Embedding other file types opens a whole new can of worms. Can i also embed markdown files in markdown files? What happens if i embed a file within itself? What if i create a cycle of embedded files?

From my point of view links are ideal. You can navigate from one file to the next. We should ensure that browser navigation works so you can get back to where you were before.

I see the point that you would want to temporarily display one thing on top of another - we have the viewer for that. I think that already adds quite a bit of complexity. For example ctrl-s currently downloads a md file when its opened in the viewer on top of files. I think we can fix such bugs and handle that level of complexity. But still in terms of mental models it's already a stretch to keep in mind you are not just viewing the thing you are seeing but actually it's just an overlay over the file system.

Embedding is even more complex in my opinion. Say you press ctrl-s in an embedded file or ctrl-+. What does that refer to? Did you mean to save or zoom into the embedded file or the entire md file?

If you open an md file with an embedded other file in the viewer in say... talk you have to handle 3 contexts. That is also 3 levels of navigation. And then try to render that on mobile...

Sorry for my rant. I guess you get the point.

[saierd]

I am also interested in an integration of diagrams into Collectives / the Markdown text editor.

I don't think linking files or using reference providers (as it was discussed above) is sufficient for use in a knowledge base. The main drawback from my point of view is that the diagrams are not versioned together with the text, which makes it very hard to view an earlier version of the file. You would have to find the correct version of each referenced file from a specific time.

I want to suggest two ways in which this functionality could be realized that allow versioning of the diagrams.

1. Editing Attachment Files

Collectives can already add images to a document. When an image is updated, the new version is added to the .attachments folder, which solves the versioning problem.

Diagrams could be added as a .drawio.png file into the attachments folder. The rendered image could show an edit button, which edits this file in draw.io and saves the result to a new file name, similar to replacing an image.

This concept could be very extensible to other types of editors, e.g. for annotating a normal image.

As far as I can see, this would require the following functionality to be implemented:

• A button to generate a new attachment and probably an API for plugins to register file types that are useful as an attachment (similar to the "New" button in the files app).
• An edit button which
  • Opens the attachment in the editor registered for the attachment's file type.
  • Intercepts the saving and redirects it to a new file name (or copies the file before editing).
  • Replaces the file name in the Markdown after saving.

2. Inline .drawio Files

There is a markdown-it plugin for rendering inlined .drawio files. This could be used to create an experience similar to the Mermaid integration where drawio code blocks are rendered as a preview and provide a button to edit the code block's content in draw.io.

The would be specific to draw.io diagrams, but allows the Markdown file to be self-contained and viewed in other editors that support the plugin.

---

What do you think about these ideas?

[rvjr]

I think both options have their respective advantages and disadvantages: 1) has completely baked PNG images that can be shown or previewed without any draw.io knowledge, which is helpful if you want to preview the content from a mounted/synced folder. 2) is likely easier to integrate in the UI and versioning of the file, but parallel editing of the draw.io diagram needs to be solved (e.g. locked) somehow...

[saierd]

@mejo- @juliushaertl @max-nextcloud We are open to implementing this feature ourselves and contributing it to the project, but need some feedback on the ideas first.

Are you interested in the ideas described above? If so, which variant would you prefer? Are there any other things we should keep in mind while implementing this?

[juliushaertl]

Since there is a draw.io Nextcloud app this might be something that can be done by implementing a viewer integration there, with Nextcloud 29 we support interactive renderings there that could directly be used in text/collectives then (https://github.com/nextcloud/server/pull/44012)

[saierd]

That looks nice.

But the viewers refer to a normal file, right? Do they allow to version the diagram together with the text? As mentioned above, I think that is absolutely necessary in a knowledge base to make sure that earlier versions of a document can be reproduced exactly.

[rvjr]

I also think the important part is to version the diagram together with the surrounding text. Otherwise the standalone draw.io app itself would solve the issue already. The main question is, how could an interface to the text plugin look like to apply versioning jointly to the markdown text and to included diagrams or attachments.

[rvjr]

@juliushaertl can you maybe give us some API hints what options there are and where APIs could be extended to allow editing attachments in general (not just for draw.io)? But the joint versioning with the text is crucial in my mind.

[BaerHub]

im also interrested in this. im about to switch from bookstack to nextcloud collectives and would love this addition