Support of "all" PlantUML elements can be enabled

[kirchsth]

Based on multiple requests #145, #104, #329 and #309 I think I found a relative good compromise for the support of "all PlantUML elements" as additional shapes.

If all PlantUML elements are required

• it can be enabled via "ENABLE_ALL_PLANT_ELEMENTS = 1"
• and the "PlantUML element" can be defined via an additional $plant=.... argument in combination of systems, containers and components.

The solution has following advantages

• it is optional, if it is not enabled the internal required skinparam overhead is very small
• no new function calls have to be defined

@Potherca, @jlesueur,@mdreano, @crgardner, @adrianvlupu, @dannief, ...: can you please give me your feedback before I start with a merge request?

Details see below and it can be tested via my extended branch

Thank you and best regards Helmut

Optional support of additional PlantUML elements

More often a full support of all PlantUML elements are requested.
They can be set via the new optional plant="...." argument of the calls

• System(..., ?plant),
• System_Ext(..., ?plant),
• Container(..., ?plant),
• Container_Ext(..., ?plant),
• Component(..., ?plant),
• Component_Ext(..., ?plant)

The already specified ...Db...() and ...Queue...() calls are not extended.

But based on the additional (internal) overhead it has to be explicit enabled
via ENABLE_ALL_PLANT_ELEMENTS. It can be set with following 2 options

• !ENABLE_ALL_PLANT_ELEMENTS = 1 directly in the scripts file
  BEFORE the first C4_* file is loaded, like e.g.

@startuml
!ENABLE_ALL_PLANT_ELEMENTS = 1
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Component.puml
...
@enduml

• or via additional command line parameter -DENABLE_ALL_PLANT_ELEMENTS=1

If ENABLE_ALL_PLANT_ELEMENTS is not set, the diagrams displays the requested "PlantUML element"
but the style is not correct displayed.

A simple sample with additional "PlantUML elements":

@startuml
!ENABLE_ALL_PLANT_ELEMENTS = 1
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Component.puml

Component(comp, "Copy component")

Component(config, "Config component", $plant="package")

ComponentDb(dbA, "DB A")
' alternative syntax for ComponentDb() with $plant="database"
Component(dbB, "DB B", $plant="database")

Rel_U(comp, config, "Configured by")
Rel_L(comp, dbA, "Reads from")
Rel_R(comp, dbB, "Writes to")

SHOW_LEGEND()
@enduml

List of supported PlantUML elements

PlantUML element	Support	Comment
rectangle	✅	already supported (works even without ENABLE_ALL_PLANT_ELEMENTS)
database	✅	already supported (works even without ENABLE_ALL_PLANT_ELEMENTS)
queue	✅	already supported (works even without ENABLE_ALL_PLANT_ELEMENTS)
node	❌	should not be used, already defined for Node() (works even without ENABLE_ALL_PLANT_ELEMENTS)
person	❌	should not be used, already defined for Person() (works even without ENABLE_ALL_PLANT_ELEMENTS)
actor	☑	requires ENABLE_ALL_PLANT_ELEMENTS
agent	☑	requires ENABLE_ALL_PLANT_ELEMENTS
artifact	☑	requires ENABLE_ALL_PLANT_ELEMENTS
boundary	☑	requires ENABLE_ALL_PLANT_ELEMENTS
card	☑	requires ENABLE_ALL_PLANT_ELEMENTS
circle	☑	requires ENABLE_ALL_PLANT_ELEMENTS
cloud	☑	requires ENABLE_ALL_PLANT_ELEMENTS
collections	☑	requires ENABLE_ALL_PLANT_ELEMENTS
control	☑	requires ENABLE_ALL_PLANT_ELEMENTS
entity	☑	requires ENABLE_ALL_PLANT_ELEMENTS
file	☑	requires ENABLE_ALL_PLANT_ELEMENTS
folder	☑	requires ENABLE_ALL_PLANT_ELEMENTS
frame	☑	requires ENABLE_ALL_PLANT_ELEMENTS
hexagon	☑	requires ENABLE_ALL_PLANT_ELEMENTS
interface	☑	requires ENABLE_ALL_PLANT_ELEMENTS
package	☑	requires ENABLE_ALL_PLANT_ELEMENTS
stack	☑	requires ENABLE_ALL_PLANT_ELEMENTS
storage	☑	requires ENABLE_ALL_PLANT_ELEMENTS
usecase	☑	requires ENABLE_ALL_PLANT_ELEMENTS
usecase/	☑	requires ENABLE_ALL_PLANT_ELEMENTS
actor/	❌	requires ENABLE_ALL_PLANT_ELEMENTS, not working (font color not changed to $bkColor) - and/or conflict with existing?
label	❌	requires ENABLE_ALL_PLANT_ELEMENTS, not working (font color not changed to $bkColor)

If ENABLE_ALL_PLANT_ELEMENTS is not set, the diagrams displays the requested "PlantUML element"
but the style is not correct.

(sometime the PlantUML server has no access to the referenced files, if this is the case please try it with your local system)

[Potherca]

I am in favor, with one point of concern: I would prefer a different term than plant. However, I do not have a suggestion yet.¹

Other than that, I think you are correct that we should provide the "customer" (user of the lib) with what they want. I think the ENABLE_* flag is a fair compromise.²

Footnotes

1. I would suggest shape but that is already used for a different purpose in the code. element might work but is also rather ambiguous (as are figure, form, format and model). And elementShape seems a bit too verbose... ↩

2. All of this is, obviously, under the constraint that things are sufficiently documented, but I have no concerns there based on the excellence of your previous work. ↩

[kirchsth]

I don't like plant too, but I didn't want to use 'planetUML....' we have basically no UML context.
I could call it baseShape?

I know, the better solution would be if we combine $shape, but
a) $shape is part of tags (atm we have ComponentDb() and this means "database" is part of the "Component()" definition without any tags)
b) and if would combine $shape with $plant and make it as part of the "Component(...,$shape)" then the internal logic==filesize/performance would be increased independent whether the feature is enabled or not

@Potherca: what do you think? (should I combine it and add it to the elements)

[jlesueur]

Flattered to be asked. For me, the plant=... is acceptable. to be more agnostic in naming, you could use renderAs or something like it?

[Potherca]

I wouldn't bother combining $shape, either renderAs or baseShape sound like good alternatives to me. 👍