@ -22,10 +22,35 @@ C4-PlantUML comes with some layout options.
- [SHOW_ELEMENT_DESCRIPTIONS(?show) ](#show_element_descriptionsshow )
- [SHOW_FOOT_BOXES(?show) ](#show_foot_boxesshow )
- [SHOW_INDEX(?show) ](#show_indexshow )
- [Optional support of additional PlantUML elements ](#optional-support-of-additional-plantuml-elements )
- [List of supported PlantUML elements ](#list-of-supported-plantuml-elements )
- [📄 Themes ](Themes.md#themes )
- samples
- [📄 C4 Model Diagrams ](samples/C4CoreDiagrams.md#c4-model-diagrams )
<!-- TOC -->
- [Layout Guidance and Practices ](#layout-guidance-and-practices )
- [Overall Guidance ](#overall-guidance )
- [Layout Practices ](#layout-practices )
- [LAYOUT_TOP_DOWN() or LAYOUT_LEFT_RIGHT() or LAYOUT_LANDSCAPE() ](#layout_top_down-or-layout_left_right-or-layout_landscape )
- [LAYOUT_WITH_LEGEND() or SHOW_LEGEND(?hideStereotype, ?details) ](#layout_with_legend-or-show_legendhidestereotype-details )
- [SHOW_FLOATING_LEGEND(?alias, ?hideStereotype, ?details) and LEGEND() ](#show_floating_legendalias-hidestereotype-details-and-legend )
- [LAYOUT_AS_SKETCH() and SET_SKETCH_STYLE(?bgColor, ?fontColor, ?warningColor, ?fontName, ?footerWarning, ?footerText) ](#layout_as_sketch-and-set_sketch_stylebgcolor-fontcolor-warningcolor-fontname-footerwarning-footertext )
- [HIDE_STEREOTYPE() ](#hide_stereotype )
- [HIDE_PERSON_SPRITE(), SHOW_PERSON_SPRITE(?sprite), SHOW_PERSON_PORTRAIT() and SHOW_PERSON_OUTLINE() ](#hide_person_sprite-show_person_spritesprite-show_person_portrait-and-show_person_outline )
- [Using HIDE_PERSON_SPRITE() ](#using-hide_person_sprite )
- [Using SHOW_PERSON_SPRITE() ](#using-show_person_sprite )
- [Using SHOW_PERSON_SPRITE(sprite) ](#using-show_person_spritesprite )
- [Using SHOW_PERSON_PORTRAIT() ](#using-show_person_portrait )
- [Using SHOW_PERSON_OUTLINE() ](#using-show_person_outline )
- [(C4 styled) Sequence diagram specific layout options ](#c4-styled-sequence-diagram-specific-layout-options )
- [SHOW_ELEMENT_DESCRIPTIONS(?show) ](#show_element_descriptionsshow )
- [SHOW_FOOT_BOXES(?show) ](#show_foot_boxesshow )
- [SHOW_INDEX(?show) ](#show_indexshow )
- [Optional support of additional PlantUML elements ](#optional-support-of-additional-plantuml-elements )
- [List of supported PlantUML elements ](#list-of-supported-plantuml-elements )
<!-- /TOC -->
## Layout Guidance and Practices
PlantUML uses [Graphviz ](https://www.graphviz.org/ ) for its graph visualization. Thus the rendering itself is done automatically for you - that it one of the biggest advantages of using PlantUML.
@ -83,7 +108,7 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")

`LAYOUT_LEFT_RIGHT()` rotates the flow visualization to *from Left to Right* and directed relations like `Rel_Left()` , `Rel_Right()` , `Rel_Up()` and `Rel_Down()` are rotated too.
`LAYOUT_LEFT_RIGHT()` rotates the flow visualization to _from Left to Right_ and directed relations like `Rel_Left()` , `Rel_Right()` , `Rel_Up()` and `Rel_Down()` are rotated too.
```plantuml
@startuml LAYOUT_LEFT_RIGHT Sample
@ -104,7 +129,7 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")

`LAYOUT_LANDSCAPE()` rotates the default flow visualization to *from Left to Right* like `LAYOUT_LEFT_RIGHT()` additional **directed relations** like Rel_Left(), Rel_Right(), Rel_Up() and Rel_Down() **are not rotated** anymore.
`LAYOUT_LANDSCAPE()` rotates the default flow visualization to _from Left to Right_ like `LAYOUT_LEFT_RIGHT()` additional **directed relations** like Rel_Left(), Rel_Right(), Rel_Up() and Rel_Down() **are not rotated** anymore.
```plantuml
@startuml LAYOUT_LANDSCAPE Sample
@ -209,9 +234,9 @@ Legend labels and details can be defined via `\n` in `$legendTest` arguments too
!else
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!endif
' $legendText with \n defines the label and details of the legend entry ("backend container" is label, "eight sided shape" is details)
' $legendText with \n defines the label and details of the legend entry ("backend container" is label, "eight sided shape" is details)
AddElementTag("backendContainer", $fontColor=$ELEMENT_FONT_COLOR, $bgColor="#335DA5", $shape=EightSidedShape(), $legendText="backend container\neight sided shape")
' $legendText without \n defines only a label
' $legendText without \n defines only a label
AddRelTag("async", $textColor=$ARROW_FONT_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DashedLine(), $legendText="async call")
' if no $legendText defined, $tag is automatically the label and all additional displayed properties are the details
AddRelTag("sync/async", $textColor=$ARROW_FONT_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DottedLine())
@ -241,9 +266,9 @@ Legend details can be deactivated via `SHOW_LEGEND($details=None())`
!else
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!endif
' $legendText with \n defines the label and details of the legend entry ("backend container" is label, "eight sided shape" is details)
' $legendText with \n defines the label and details of the legend entry ("backend container" is label, "eight sided shape" is details)
AddElementTag("backendContainer", $fontColor=$ELEMENT_FONT_COLOR, $bgColor="#335DA5", $shape=EightSidedShape(), $legendText="backend container\neight sided shape")
' $legendText without \n defines only a label
' $legendText without \n defines only a label
AddRelTag("async", $textColor=$ARROW_FONT_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DashedLine(), $legendText="async call")
' if no $legendText defined, $tag is automatically the label and all additional displayed properties are the details
AddRelTag("sync/async", $textColor=$ARROW_FONT_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DottedLine())
@ -636,3 +661,97 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")
 Sample")
## 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.
```plantuml
@startuml
!ENABLE_ALL_PLANT_ELEMENTS = 1
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/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":**
```plantuml
@startuml
!ENABLE_ALL_PLANT_ELEMENTS = 1
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/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.