Add an :url property

[tobias-hammerschmidt]

I propose to add an :url property to overarch elements. This could be used for instance in plantuml output rendered as svg to include links to further documentation. Right now it is possible to achieve the desired result by including a formatted :name property like this:

{ ...
  :name "[[https://www.google.com/ Google]]"
  ...
}

While this works it couples the data to the output format while a specific property could be used (maybe in combination with custom templates) to automatically generate the proper format in the plantuml target. The example above could look like this within the edn model:

{ ...
  :name "Google"
  :url "https://www.google.com/"
  ...
}

[lsolbach]

Sorry Tobias, I missed this question until now.
I thought about adding an :url property, too. But I'm not sure, if that is the best way to get to linked elements. Maybe more indirection is needed here, because there may be more then one relevant URL for an element and depending on the view, different URLs might be shown.

Currently, I'm modelling the different URLs with different properties namespaced with the company (e.g. :xyz/info-url, :xyz/repository-url) and use them in the documentation templates to generate markdown links. So I currently don't generate links with PlantUML but in the template-generated documentation.

A possible solution for the generation of URLs with PlantUML would be to have a :link property which takes a string with a URL or a keyword for the lookup of the URL in the element. This link property could be specified on a :ref in a view to handle the view specific rendering of the link.

[tobias-hammerschmidt]

Thanks for the update. According to the documentation there is also a :link property within the deployment model (see https://github.com/soulspace-org/overarch/blob/main/doc/usage.md#deployment-model-relations). Maybe the new property should be renamed to prevent potential conflicts? Also I wonder whether the current approach of specifing the relation within the view definitions might be to tedious. For instance I'm having a code model where classes are organized within packages and the view only references the packages (classes are contained so will be automatically imported). I can maintain the link right now on class level with my workaround while with the official support from 0.28.0 I would have to add an additional ref to each class to specify the link. I get your point that depending on the view one might would like to link to different targets (or none at all). Maybe I should make up my mind about that.

[lsolbach]

The :link keyword in the deployment model is a value for the :el key defining the element type of that relation, the newly introduced :link is an attribute key. So the don't actually clash, but it might be a source of confusion. I have to think about it.

[lsolbach]

Regarding the specification of the :link attribute, it is fine to specify it on the classes in the model as a default. You can still override it in a reference defined in a specific view, if you want to link a different URL specific for this view. And when specifing the :link on the model element, you could still put a URL or a keyword to an attribute containing a URL in it. But using a keyword would be only useful, if you have more than one attribute containing a URL.

[lsolbach]

Currently, most of my views are based on a selection in combination with an include directive (e.g. :include :related). That works quite well out of the box for me. And if I want to add a specific element or override some properties for an included element, I put a ref for that element only in the :ct vector. The refs in the :ct vector get merged with the selected/included elements, so that they can still override properties for the selected/included elements.

[tobias-hammerschmidt]

Thanks for the explanation Ludger. I also started to change my views to make use of :related/:relations which is a good best practice IMHO 👍 .