plantuml-stdlib · Potherca · Jul 4, 2021 · Apr 8, 2021 · Apr 8, 2021 · Apr 11, 2021
diff --git a/C4.puml b/C4.puml
@@ -36,6 +36,13 @@ skinparam LegendBorderColor transparent
 skinparam LegendBackgroundColor transparent
 skinparam LegendFontColor $LEGEND_FONT_COLOR
 
+skinparam shadowing<<legendArea>> false
+' #00000000 is transparent
+skinparam rectangle<<legendArea>> {
+    backgroundcolor #00000000
+    bordercolor #00000000
+}
+
 skinparam rectangle {
     StereotypeFontSize 12
     shadowing false
@@ -51,13 +58,19 @@ skinparam queue {
     shadowing false
 }
 
-skinparam Arrow {
+skinparam arrow {
     Color $ARROW_COLOR
     FontColor $ARROW_COLOR
     FontSize 12
 }
 
-' Some boundary skinparam have to be set a package skinparams too (PlantUML uses internal packages)
+skinparam actor {
+    StereotypeFontSize 12
+    shadowing false
+    style awesome
+}
+
+' Some boundary skinparams have to be set as package skinparams too (PlantUML uses internal packages)
 skinparam package {
     StereotypeFontSize 6
     StereotypeFontColor $BOUNDARY_BG_COLOR
@@ -154,6 +167,8 @@ skinparam rectangle<<boundary>> {
   !$tagSkin = $elementTagSkinparams("rectangle", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing)
   !$tagSkin = $tagSkin + $elementTagSkinparams("database", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing)
   !$tagSkin = $tagSkin + $elementTagSkinparams("queue", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing)
+  ' actor has style awesome, therefore $fontColor is ignored and text uses $bgColor too
+  !$tagSkin = $tagSkin + $elementTagSkinparams("actor", $tagStereo, $bgColor, $bgColor, $borderColor, $shadowing)
   !if ($tagStereo == "boundary" && $bgColor!="")
     !$tagSkin = $tagSkin + "skinparam package<<boundary>>StereotypeFontColor " + $bgColor + %newline()
     !$tagSkin = $tagSkin + "skinparam rectangle<<boundary>>StereotypeFontColor " + $bgColor + %newline()
@@ -170,7 +185,7 @@ $tagSkin
 !endfunction
 
 !unquoted procedure $defineRelSkinparams($tagStereo, $textColor, $lineColor)
-  !$elementSkin = "skinparam Arrow<<" + $tagStereo + ">> {" + %newline()
+  !$elementSkin = "skinparam arrow<<" + $tagStereo + ">> {" + %newline()
   !$elementSkin = $elementSkin + "    Color "
   !if ($lineColor!="")
     !$elementSkin = $elementSkin + ColorNoHash($lineColor)
@@ -322,7 +337,7 @@ UpdateElementStyle($elementName, $bgColor, $fontColor, $borderColor, $shadowing)
 
 ' update the style of default relation, it has to set both properties (combined statement not working)
 !unquoted procedure UpdateRelStyle($textColor, $lineColor)
-  !$elementSkin = "skinparam Arrow {" + %newline()
+  !$elementSkin = "skinparam arrow {" + %newline()
   !$elementSkin = $elementSkin + "    Color " + $lineColor + %newline()
   !$elementSkin = $elementSkin + "    FontColor " + $textColor + %newline()
   !$elementSkin = $elementSkin + "}" + %newline()
@@ -489,6 +504,25 @@ SetPropertyHeader("Property","Value")
 ' Layout
 ' ##################################
 
+!procedure $getHideStereotype($hideStereotype) 
+!if ($hideStereotype=="true")
+hide stereotype
+!endif
+!endprocedure
+
+!procedure $getLegendTable() 
+<#00000000,#00000000>|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
+$showActiveLegendEntries($tagDefaultLegend)
+$showActiveLegendEntries($tagCustomLegend)
+!endprocedure
+
+!procedure $getLegendArea($areaAlias, $hideStereotype) 
+$getHideStereotype($hideStereotype)
+rectangle $areaAlias<<legendArea>> [
+$getLegendTable()
+]
+!endprocedure
+
 !procedure HIDE_STEREOTYPE()
 hide stereotype
 !endprocedure
@@ -510,13 +544,9 @@ left to right direction
 
 ' has to be last call in diagram
 !unquoted procedure SHOW_LEGEND($hideStereotype="true")
-!if ($hideStereotype=="true")
-hide stereotype
-!endif
+$getHideStereotype($hideStereotype)
 legend right
-|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
-$showActiveLegendEntries($tagDefaultLegend)
-$showActiveLegendEntries($tagCustomLegend)
+$getLegendTable()
 endlegend
 !endprocedure
 
@@ -525,6 +555,18 @@ endlegend
 SHOW_LEGEND($hideStereotype)
 !endprocedure
 
+' legend is reserved and cannot be uses as alias of SHOW_FLOATING_LEGEND() therefore
+' LEGEND() is introduced. It returns the default name of the floating alias "floating_legend_alias"
+' and can be used in the Lay_Distance() calls
+!function LEGEND()
+!return "floating_legend_alias"
+!endfunction
+
+' enables that legend can be located in drawing area of the diagram. It has to be last call in diagram followed by Lay_Distance()
+!unquoted procedure SHOW_FLOATING_LEGEND($alias=LEGEND(), $hideStereotype="true")
+$getLegendArea($alias, $hideStereotype)
+!endprocedure
+
 ' Boundaries
 ' ##################################
 
@@ -660,6 +702,10 @@ $getRel("<<-RIGHT->>", $from, $to, $label, $techn, $descr, $sprite, $tags, $link
 ' Layout Helpers
 ' ##################################
 
+!function $getHiddenLine($distance)
+  !return '-[hidden]' + %substr('------------', 0, %intval($distance) + 1)
+!endfunction
+
 !unquoted procedure Lay_D($from, $to)
 $from -[hidden]D- $to
 !endprocedure
@@ -672,3 +718,10 @@ $from -[hidden]R- $to
 !unquoted procedure Lay_L($from, $to)
 $from -[hidden]L- $to
 !endprocedure
+
+' PlantUML bug: lines which does "not match" with the orientation/direction of the diagram
+' uses the same length therefore the method offers no direction at all.
+' If a direction is required the Lay_...() methods can be used
+!unquoted procedure Lay_Distance($from, $to, $distance="0")
+$from $getHiddenLine($distance) $to
+!endprocedure
diff --git a/C4_Context.puml b/C4_Context.puml
@@ -153,9 +153,11 @@ endlegend
 !endprocedure
 
 !global $defaultPersonSprite = "person"
+!global $portraitPerson = "false"
 
 !procedure HIDE_PERSON_SPRITE()
   !$defaultPersonSprite = ""
+  !$portraitPerson = "false"
 !endprocedure
 
 !unquoted procedure SHOW_PERSON_SPRITE($sprite="")
@@ -164,6 +166,12 @@ endlegend
   !else
     !$defaultPersonSprite = $sprite
   !endif
+  !$portraitPerson = "false"
+!endprocedure
+
+!unquoted procedure SHOW_PERSON_PORTRAIT()
+  !$defaultPersonSprite = ""
+  !$portraitPerson = "true"
 !endprocedure
 
 ' Elements
@@ -203,11 +211,19 @@ endlegend
 !endfunction
 
 !unquoted procedure Person($alias, $label, $descr="", $sprite="", $tags="", $link="")
+!if ($portraitPerson == "true") && ($sprite == "")
+actor "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("person", $tags) as $alias $getLink($link)
+!else
 rectangle "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("person", $tags) as $alias $getLink($link)
+!endif
 !endprocedure
 
 !unquoted procedure Person_Ext($alias, $label, $descr="", $sprite="", $tags="", $link="")
+!if ($portraitPerson == "true") && ($sprite == "")
+actor "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("external_person", $tags) as $alias $getLink($link)
+!else
 rectangle "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("external_person", $tags) as $alias $getLink($link)
+!endif
 !endprocedure
 
 !unquoted procedure System($alias, $label, $descr="", $sprite="", $tags="", $link="")

diff --git a/LayoutOptions.md b/LayoutOptions.md
@@ -107,6 +107,58 @@ SHOW_LEGEND()
 
 ![SHOW_LEGEND Sample](https://www.plantuml.com/plantuml/png/JL5Dgzf05DtFhxYr2oDeWgMhhfgceWkreObr6IR9RHsOZs7cXY3b_VTtWpurcqlEn-4Svdia6MWm6ghThtEptsmtnvzGIUCrYa_ATdhe4Iv4FdxBiY37z9-Yoz0E4KFdBA6bj7CcyrhQAMOLgTUgpOglgtA2JeTzPcGa30mr1JkaiXXIpreXIWpHsKJsHjabpFBfgaX1aWkpXQYkR3JD3pVONePhqgsNCBzrco_Wlm3-7f79Y6qZlUUSCxQGUwzL9qavEsEe-Bo4l2hJuwPcIq3uagxXyAUOk5nhDqQO9aKW1xp7IvQOGPFo6g4U5H4686LGAukHkxtTsoLq8pddBcDI_4RziUfPwnJPoNTNrsN5gadqO9ynMwJ8lpYTly6PLujuUQLa8Tu1 "SHOW_LEGEND Sample")
 
+## SHOW_FLOATING_LEGEND(?alias, ?hideStereotype) and LEGEND()
+
+`LAYOUT_WITH_LEGEND()` and SHOW_LEGEND(?hideStereotype)` adds the legend at the bottom right of the picture like below and additional whitespace is created.
+
+```csharp
+@startuml Layout With Whitespace Sample
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+Person(a, "Person A")
+Container(b, "Container B", "techn")
+System(c, "System C")
+Container(d, "Container D", "techn")
+Container_Ext(e, "Ext. Container E", "techn")
+
+Rel_R(a, b, "calls")
+Rel_D(b, c, "uses")
+Rel_D(c, d, "uses")
+Rel_R(d, e, "updates")
+
+SHOW_LEGEND()
+@enduml
+```
+
+![Layout With Whitespace Sample](https://www.plantuml.com/plantuml/png/LSwnReCm40RWtK_XCZbI0qkdJca1jGDjew2A4HdxL91iOzbdjNdx7eb4meJlk_y_SOWe0oPhU2FFSqBUJJZoRfmGefSAU2kjDy0U9gTCqi17H1-VYoB8t_o7icb84OAQ7OB3NCssy4QwvU8-eZRJK9HF--D2tnzDOML424HzIGqvEGYvfonZHmXnTa8-ykpwv2_PZgqfCT1YdVXhHYE26Xs5sZCTjK8HNP-yt5JrfbhTLrVkwpyKG1lwvloMhk_Jx0IcFot_E90gQKmaNR0I98emHRWPWTuObGbWCQybNfYrxrzTtzHlzMSbTkm0JYTh_W40 "Layout With Whitespace Sample")
+
+Therefore a floating legend can be added via SHOW_FLOATING_LEGEND(), positioned with Lay_Distance() and existing whitespace is reused like below.
+
+- `SHOW_FLOATING_LEGEND(?alias, ?hideStereotype): shows the legend in the drawing area
+- `LEGEND()`: is the default alias of the created floating legend and can be used in Lay_Distance() call
+
+```csharp
+@startuml Compact Legend Layout Sample
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+Person(a, "Person A")
+Container(b, "Container B", "techn")
+System(c, "System C")
+Container(d, "Container D", "techn")
+Container_Ext(e, "Ext. Container E", "techn")
+
+Rel_R(a, b, "calls")
+Rel_D(b, c, "uses")
+Rel_D(c, d, "uses")
+Rel_R(d, e, "updates")
+
+SHOW_FLOATING_LEGEND()
+Lay_Distance(LEGEND(), e, 1)
+@enduml
+```
+
+![Compact Legend Layout Sample](https://www.plantuml.com/plantuml/png/RP7VQ-em5CVVyrUavS9juTwMmPu60vtjtA1JqOqzXfWURLXC9Jbb-j_lr6gri9Ss-Nn_d3OPUPGEcvrXWRRAD2Nm2d7l7zBKoUzagx5greq7fsgBO35HzIxzqavL7gjqSlz_OQJ5ZxSYXGFf9PG4nOJCKbjmoRwjPcm1pjSsalzus2tvE8nPRulM9FGx_XJI5a5LbaoheqVOHOfGj-IJGRGSHBFRQ8z5Vi08IA5tmg_k_DRDbc34ilt6DL4bZV54MvX5H1H1EeWh8r0EsJ8Y02tRbn9Fc0MRnYhKzCT5FirdMHIpm04spl9mOsg9scw5WItOCcG1FIz-jdgPVuhdOZv-VvrDnJbzAObP8OyYqtHzLa6FJ-FlQ2pxouC_7UMFFEm62Eb0XYJzMdssnwGFki_yKZsY8hhK7m00 "Compact Legend Layout Sample")
+
 ## LAYOUT_AS_SKETCH()
 
 C4-PlantUML can be especially helpful during up-front design sessions.
@@ -166,13 +218,14 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")
 ![HIDE_STEREOTYPE Sample](https://www.plantuml.com/plantuml/png/NL1DIyD05BplhrZheIdKX8edJuqrMC5gQ5B5KzWcJxkmN-o-DHJnl_j2gnNtCl1ctfkPdGSK7gDMV7b_MpHLNQoBf_grB7Wbj5F0pgHfLUo0xn1TkCuoB_hqNU8kRcC0trg3O31jhSv4vwKm7ogwc2skBaeb36vM3vaI205fr2n8BQG1dpgoPEoVPp9Xh0GVh4b4fwMPyb4-e0pe1Le_ch1g7n1qSsEZwOJV9-rioiU7gEC9_sIStgzBqiEs4SxHdHVOyjmv9Lk1qfeHZHRdKvvNPVfOrBJYWL-cCxvwNWnShfJj0nyQ1ewMKpqdIAAZGabUlEub8dYEKeCYhq3Plexf4ZoGTESe8vAjGVsqEiNQ1DeaNDPrMP5g4FsofpDtW1IZXm7UlDL_L-PWElhCRm00 "HIDE_STEREOTYPE Sample")
 
 
-## HIDE_PERSON_SPRITE() or SHOW_PERSON_SPRITE(?sprite)
+## HIDE_PERSON_SPRITE(), SHOW_PERSON_SPRITE(?sprite), SHOW_PERSON_PORTRAIT()
 
-With the macros `HIDE_PERSON_SPRITE()` and `SHOW_PERSON_SPRITE()` it is possible to change the person related default sprite. `SHOW_PERSON_SPRITE()` is the default.
+With the macros `HIDE_PERSON_SPRITE()`, `SHOW_PERSON_SPRITE()` and `SHOW_PERSON_PORTRAIT()` it is possible to change the person related default sprite or person layout itself. `SHOW_PERSON_SPRITE()` is the default.
 
 - **HIDE_PERSON_SPRITE()**: deactivates the default sprite
 - **SHOW_PERSON_SPRITE()**: activates the default sprite "person"
 - **SHOW_PERSON_SPRITE($sprite)**: activates a specific sprite as default sprite
+- **SHOW_PERSON_PORTRAIT()**: activates portrait outline instead of a rectangle
 
 "person" and "person2" are predefined sprites which can be used as default sprite too.
 
@@ -255,3 +308,27 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")
 
 ![SHOW_PERSON_SPRITE(sprite) Sample](https://www.plantuml.com/plantuml/png/ZL1DQzj04BthLspTGnIm9H9wwYckC4sXIOGbDqUnbYRnmduiCxCOK_hVEzieTkcfkYmpx-EzqHsnHaxE5X-C7ssQG1sO8tskQzJ7wjNm8UqJ0Ox1CtYknk3gQBNFcXNnPCs-RZwjshpQFNoldIO6bDNGY48R3rZ5F_uJlCYa0kbMvl-8QL3J0IPd_5I_-wz214ym9ZHyqZWU3CF82U5sPKHBS_xbcZckRe9pmSzL_WLtabnhQz_Wehj_UXxQpRPxUXowTlkjtvGBeGwvuF2A07uuHo-kYw85fE1BdQikrMATNqECcWCAtfs8mGrVGlAJnbCvtYpLLQTTj71rhNuMIhxppogFi1zqZEBp37krZj6QKRC9VY6hvkDIhRksUjpq8a5GjzMDUlZHP6njRJYIoYL9SL1ZS54BnINBHh9KVpJCW8gD0ojP9Dr-pUrAVWF5PwRbmxPWtw-wrDeHKCwxx_ks4rOcdT6BpLTWaX7oyuB1_Isv0pybPty3 "SHOW_PERSON_SPRITE(sprite)")
 
+**Using SHOW_PERSON_PORTRAIT()**
+
+```csharp
+@startuml SHOW_PERSON_PORTRAIT() Sample
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+SHOW_PERSON_PORTRAIT()
+
+Person(admin, "Administrator")
+System_Boundary(c1, 'Sample') {
+    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
+}
+System(twitter, "Twitter")
+
+' if a person is combined with a sprite then the rectangle layout is used again
+Person(person, "Person with sprite", $sprite="person2")
+
+Rel(admin, web_app, "Uses", "HTTPS")
+Rel(web_app, twitter, "Gets tweets from", "HTTPS")
+@enduml
+```
+
+![SHOW_PERSON_PORTRAIT() Sample](https://www.plantuml.com/plantuml/png/RL1BQzj04BxhLqpTGcHm919wAXIYcj0KcbXOIdCKAsbYB-nZsPd5cDB_tbcKHm_LGRixyptccnjY5JbP0ztTxcbeR_VTxc5eT_j-t_peopLqoWQ3nGVj9fDcX2Dpe2zr7TMfEcW-fZ4HniaxHiVLv6qTZ79PyP9uDdgijvylsrnwlFzPMqMCKKh3LXXAEunL46nH_D--A5gCv5sfPglT1bPDFZLnLEpZQbrqPsAqmpUVtApYkPokDd2np7onXjy5oFTcLPvm75G8elE48pGX63qfrjwjfBJzk86cQwk7srue4U6wkeBxNzlSQupn9u8SbO0zICwW16AJOIrUq9yqCqPWRT685ybiVrwcAtbfYiuBJ9h51UXdK10mvmDDMNCKvWo2EKg7GjICm4Tq-GSH9rRk86P6dNtYp4aaU7MGTA-BMlJ4QdalOekK1FcqtBwk5jXr7cIFvdMzx_jv9AGS_AxlsqvG6VJMVS_p7PdaYVbuZjx-Ixb1DoTh_W80 "SHOW_PERSON_PORTRAIT()")
+