Embed modified SVG images generated with structurizr in the HTML for the site

[iteratec-hscaffino]

Hi,

thanks for the awesome tool. It has saved the team I'm working for a great deal of work!

We would like to embed modified SVG images generated within the structurizr docker image in the website instead of using the tool to generate them. The problem is that we would like to use the default structurizr theme for the diagrams AND also modify some line positions in the diagrams. This is a different situation than the issue concerning the theme presented in Theme behaviour needs attention

We noticed that the SVG are normally embedded in the HTML files and that the generated SVG files are kept in memory and not saved to disk. Instead of generating the SVG, we would like structurizr-site-generatr to use images from a specific folder. How would we go about implementing this? Would it be possible to add a different "backend" that simply loads the image files?

[dirkgroot]

Hi @iteratec-hscaffino, glad to hear that this tool helps you and your team save time!

I'm not entirely sure if I understand your questions correctly, so I have two questions:

1. I think the theming part of your question would be addressed by adding the possibility of choosing the theme using a command-line, like I described in https://github.com/avisi-cloud/structurizr-site-generatr/issues/40#issuecomment-1240391842. Am I correct in this?
2. Could you elaborate some more on what you mean exactly by "modify some line positions in the diagrams"?

[UBessle]

Hi @dirkgroot , in some cases with complex diagrams, we would like to be able to rather use such handcrafted diagram from structurizr (https://tdhostserv.eurodata.de/bhpwwpjn/public/rYgKLqIY?k=0-nqngzn435gYn6l202fRN9k2i5DHaNzH2zWygc0LUk), than the automatically generated plantuml diagram, the structurzir-site-generatr creates (https://tdhostserv.eurodata.de/bhpwwpjn/public/whC_Cd60?k=pVk-h2cnjNz98n4ZyW8h2Iu272Doz5v7CY-advaFEe4).

The graphics from structurizr have the advantage that they may contain all image optimizations from structurizr (styles and themes with different shapes and colors) AND using structurizr enterprise installation, we are able to manually optimize the placement of boxes and lines on the canvas. The result of this is, that we can produce better understandable diagrams.

Unfortunately the currently used diagram is generated and embedded from structurizr-site-generat during the generation of the html documentation page.

The simplest idea would be, that we export all the graphics from structurizr enterprise as png and svg files and place those files in the corresponding folders for structurizr site generatr. So when running the site generator, it omits the diagram generation step and instead uses the already existing diagrams instead.

[dirkgroot]

Hi @UBessle, okay, I understand. So for your idea to work, the diagrams should be loaded as images, instead of the SVG code being embedded in the HTML pages. Currently, the SVG code is embedded, to make it possible that diagram elements are links to their corresponding sections in the generated website.

After some searching and experimentation, I found out that this behaviour can also be achieved without embedding the SVG, by using an <object data="filename.svg" type="image/svg+xml" /> tag.

So to make this possible, we would need to change the following:

• Save diagrams with links as .svg files instead of embedding the SVG in the HTML
• Use the object tag to include the diagrams on the HTML pages, so diagram elements are clickable

Some things to be aware of, when replacing the generated SVG's:

• You'll lose the ability to navigate the site by clicking on diagram elements
• Links in diagrams are relative to the page they are part of, so if one diagram is included on multiple pages, mulitple .svg files will exist for that diagram

Would a change like this suit your needs?

[UBessle]

Hi @dirkgroot ,

this change would improve the situation.

But it still sounds a little bit sub-optimal, due to the fact, that we would loose to some extent the possibility to navigate in the site using the embedded links.

Our real problem is not the fact, that the svg is embedded, but rather the circumstance, that the svg file is generated using plantuml. Perhaps an even better result could be achieved, if there is the possibility to provide the svg files for the site generator and the site generator than uses the provided sgv files to enrich them with the linking and embed them in the html code. What about this idea? Sounds this feasible from your viewpoint?

Cheers, uwe

[dirkgroot]

I'm not really keen on having to manipulate SVG's to add URL's. Also, whether or not that is feasable depends on if there is enough information available in the SVG's generated by Structurizr to be able to reliably link shapes in the SVG to elements in the Structurizr model.

[UBessle]

i'm totally with you. I would not like to manipulate SVG files either. But the interesting thing is, that SVG files from structurizr already contain links. The svg element link targets are defined with the url property in structurizr DSL files. url child elements may be used for describing

• person
• softwareSystem
• container
• component
• deploymentNode
• infrastructureNode
• softwareSystemInstance
• containerInstance
• custom elements
• relationships

[simonbrowndotje]

The Structurizr SVGs (which are what you see in the web browser; e.g. https://structurizr.com/share/36141/diagrams#SystemContext) do include pre-defined double-click handlers, and you can read a little more about this at https://structurizr.com/help/exporting-diagrams#svg

Those double-click handlers are used for navigation between diagrams, both inside the Structurizr app itself and the HTML export (you'll see this if you "view source" on the HTML export for the diagram I linked above).

Some thoughts then...

• Short term: I think supporting the Structurizr SVGs inside Site Generatr is a large and complicated undertaking to be honest. A simpler alternative @UBessle would be to simplify your diagram (e.g. create multiple smaller diagrams showing a subset of the overall picture) so that you can rely on the PlantUML export that's a part of Site Generatr. I understand that might not be what you want to hear, so apologies in advance!
• Long term: I'm open sourcing the Structurizr UI during 2023 (the browser-based code that generates those SVGs), so once this is done, that code could be integrated into Site Generatr to render the diagrams inside the web browser, as an alternative to the PlantUML versions.

[dirkgroot]

I think I agree with Simon about the short term. We also had some larger diagrams in our models. Our solution was to provide the large diagram, as well as some smaller ones, which are focused on specific aspects of the large one. Granted, we don't use the the Structurizr tools to manually optimize diagram layouts, so for us, this is the only option we have. However, having smaller, more focused diagrams is definitely something I would recommend, regardless of whether or not you have the option of manually optimizing your diagrams.

@simonbrowndotje: The long term solution you describe sounds interesting. How are you planning to package/distribute this code? And will it include the renderer as well as the editing functionality?

[simonbrowndotje]

@simonbrowndotje: The long term solution you describe sounds interesting. How are you planning to package/distribute this code? And will it include the renderer as well as the editing functionality?

I've started adding it to this repo -> https://github.com/structurizr/ui

It's primarily there to allow people to build Structurizr Lite (which is also being open sourced) from source, so yes ... both diagram renderer and editor ... and my aim is to detach it sufficiently from Lite for use elsewhere.

[simonbrowndotje]

An initial version of the diagram renderer is now available, and can be used standalone within other apps. There are a bunch of examples at https://github.com/structurizr/ui/tree/main/examples, with https://github.com/structurizr/ui/blob/main/examples/diagram-basic.html being a good starting point. All of these examples load a JSON workspace via a HTTP request, but you can load the workspace however you like.

[dirkgroot]

I'm closing this issue. We're not planning on adding this feature to the generator any time soon. It doesn't really fit well with the vision of this project.