diff --git a/C4.puml b/C4.puml index 050db8b..74a3c2d 100644 --- a/C4.puml +++ b/C4.puml @@ -70,7 +70,7 @@ skinparam actor { style awesome } -' Some boundary skinparam have to be set a package skinparams too (PlantUML uses internal packages) +' Some boundary skinparams have to be set as package skinparams too (PlantUML uses internal packages) skinparam package { StereotypeFontSize 6 StereotypeFontColor $BOUNDARY_BG_COLOR @@ -516,9 +516,9 @@ $showActiveLegendEntries($tagDefaultLegend) $showActiveLegendEntries($tagCustomLegend) !endprocedure -!procedure $getLegendArea($hideStereotype) +!procedure $getLegendArea($areaAlias, $hideStereotype) $getHideStereotype($hideStereotype) -rectangle legendArea<> [ +rectangle $areaAlias<> [ $getLegendTable() ] !endprocedure @@ -555,25 +555,9 @@ endlegend SHOW_LEGEND($hideStereotype) !endprocedure -' enables that legend can be located in diagram, has to be last call in diagram -!unquoted procedure SHOW_LEGEND_LEFT($alias, $hideStereotype="true") -$getLegendArea($hideStereotype) -Lay_L($alias, legendArea) -!endprocedure - -!unquoted procedure SHOW_LEGEND_RIGHT($alias, $hideStereotype="true") -$getLegendArea($hideStereotype) -Lay_R($alias, legendArea) -!endprocedure - -!unquoted procedure SHOW_LEGEND_UP($alias, $hideStereotype="true") -$getLegendArea($hideStereotype) -Lay_U($alias, legendArea) -!endprocedure - -!unquoted procedure SHOW_LEGEND_DOWN($alias, $hideStereotype="true") -$getLegendArea($hideStereotype) -Lay_D($alias, legendArea) +' 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 @@ -711,6 +695,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 @@ -723,3 +711,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/LayoutOptions.md b/LayoutOptions.md index 3bc384f..7859a10 100644 --- a/LayoutOptions.md +++ b/LayoutOptions.md @@ -107,7 +107,7 @@ SHOW_LEGEND() ![SHOW_LEGEND Sample](https://www.plantuml.com/plantuml/png/JL5Dgzf05DtFhxYr2oDeWgMhhfgceWkreObr6IR9RHsOZs7cXY3b_VTtWpurcqlEn-4Svdia6MWm6ghThtEptsmtnvzGIUCrYa_ATdhe4Iv4FdxBiY37z9-Yoz0E4KFdBA6bj7CcyrhQAMOLgTUgpOglgtA2JeTzPcGa30mr1JkaiXXIpreXIWpHsKJsHjabpFBfgaX1aWkpXQYkR3JD3pVONePhqgsNCBzrco_Wlm3-7f79Y6qZlUUSCxQGUwzL9qavEsEe-Bo4l2hJuwPcIq3uagxXyAUOk5nhDqQO9aKW1xp7IvQOGPFo6g4U5H4686LGAukHkxtTsoLq8pddBcDI_4RziUfPwnJPoNTNrsN5gadqO9ynMwJ8lpYTly6PLujuUQLa8Tu1 "SHOW_LEGEND Sample") -## SHOW_LEGEND_UP(alias, ?hideStereotype), SHOW_LEGEND_DOWN(...), SHOW_LEGEND_LEFT(...) or SHOW_LEGEND_RIGHT(...) +## SHOW_FLOATING_LEGEND(?alias, ?hideStereotype) `LAYOUT_WITH_LEGEND()` and SHOW_LEGEND(?hideStereotype)` adds the legend at the bottom right of the picture like below and additional whitespace is created. @@ -115,55 +115,48 @@ SHOW_LEGEND() @startuml Layout With Whitespace Sample !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml -Container_Ext(A, "Ext. Container A", "techn") -Person(B, "Person B") -System(C, "System C") -Container(D, "Container D", "techn") -Container(E, "Container E", "techn") +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,"uses") -Rel_R(A,C,"uses") -Rel_D(B,C,"uses") -Rel_R(C,D,"uses") -Rel_D(B,D,"uses") -Rel_D(C,E,"uses") +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/NSwnReCm40RWtK_XCZbI0akdJWbWjGDj8r35Y1mu5IJR8FkiDc_VYw9QWOcxZz-_xkXHEGn6yqfTvu2ydN3axJWX-4Nrm1jb5WtiQRAz3WFm4N7nBrdcr4_wJTbm2HvSFri4Ysa_cspHojuQ3nu7FLsoulbmlj7NUvKPvH4SKLVG2pLPSEb2MSRYtibV5ASzJ-YRyiZyb90XzADDTkmCpizMv4JtaUUapPNQZIX8xoClI6E5AEb7t7WP2rSXkGh9nn2hGNSr7PVla-314_rBiP9Iv1kfwQfoczaAPMGKrhnzjbqbN-L7ANRi27O8Hly1 "Layout With Whitespace Sample") +![Layout With Whitespace Sample](http://www.plantuml.com/plantuml/png/LSwnReCm40RWtK_XCZbI0qkdJca1jGDjew2A4HdxL91iOzbdjNdx7eb4meJlk_y_SOWe0oPhU2FFSqBUJJZoRfmGefSAU2kjDy0U9gTCqi17H1-VYoB8t_o7icb84OAQ7OB3NCssy4QwvU8-eZRJK9HF--D2tnzDOML424HzIGqvEGYvfonZHmXnTa8-ykpwv2_PZgqfCT1YdVXhHYE26Xs5sZCTjK8HNP-yt5JrfbhTLrVkwpyKG1lwvloMhk_Jx0IcFot_E90gQKmaNR0I98emHRWPWTuObGbWCQybNfYrxrzTtzHlzMSbTkm0JYTh_W40 "Layout With Whitespace Sample") -Therefore calculated legends can be defined relative to an element too that existing whitespace can be reused like below. +Therefore a floating legends can be added via SHOW_FLOATING_LEGEND() and positioned with Lay_Distance() that existing whitespace can be reused like below. -- **SHOW_LEGEND_UP(alias, ?hideStereotype)**: shows the legend above the alias element -- **SHOW_LEGEND_DOWN(alias, ?hideStereotype)**: shows the legend below the alias element -- **SHOW_LEGEND_LEFT(alias, ?hideStereotype)**: shows the legend left of the alias element -- **SHOW_LEGEND_RIGHT(alias, ?hideStereotype)**: shows the legend right of the alias element +- `SHOW_FLOATING_LEGEND(?alias, ?hideStereotype): shows the legend in the drawing area ```csharp @startuml Compact Legend Layout Sample !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml -Container_Ext(A, "Ext. Container A", "techn") -Person(B, "Person B") -System(C, "System C") -Container(D, "Container D", "techn") -Container(E, "Container E", "techn") - -Rel_R(A,B,"uses") -Rel_R(A,C,"uses") -Rel_D(B,C,"uses") -Rel_R(C,D,"uses") -Rel_D(B,D,"uses") -Rel_D(C,E,"uses") - -' legend fills whitespace to the right of container E -SHOW_LEGEND_RIGHT(E) +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/NT51Ru8m50VmUp_56vTXed3PQIS56bt2DeDRTYGLdzAajAHznFdjzumPcvneV_pvvz4k0obFGsSWTrsl6e8IJsWFKAgB6mXsgkiDYWTj6pCS45gYFZodgLVdvAIf7VP3GDyuIsWfQLoNzaRPQ-4YqC7eVPe_BRPN-dmjqqu5GizKv_o5qXPzqdDMY75Vos-ALtE8-9d0oB2As0YRraOpiKKVd8qpfjiICjRTXTkxE6UzBI5d7IlYWb-CEoZ6mhkGl0l9_o5HeQah7YwRH_pNWUbNyZifucmY5KzLJ3DJuOmSHJo2kTt4KHiJuDngmi0tX40Eg4Nm-jGIk2CqV-EAtURzgoxbMhuLTVMotdp4SYQMNCEd_0C0 "Compact Legend Layout Sample") +![Compact Legend Layout Sample](http://www.plantuml.com/plantuml/png/LP51Q_im3CNl_XJ-z-J2lmc3dNPgbsJT86jBkx6ZSMtH1cp7s0fRl_ta5TBcPFcdzuHuMYPK4GTdUTMxe3Jo5axW3M_LfH-G7vGB5jY_pcix6E1dn92UoZAgx-BKuNau3WcYxZs2nqBthWnM-JnmaT3OxbXMZujTHf_lRUbKGeY4P4KErNc8HI0jOpk8gVT2_UUpQybNipaRLU98ZV77dsVqHT1dJwB3XOOweGbTIrvDh6PYhU-j8vRD3mgW3hq5lwcRUpNRWvNxl6FUHYjh4z4CQq544wGmReo0cJ0o4u3CWb7uXzdXTVibNzhjwkDjivPjisusjPWpob_M7Lt7Qn0st-HgVPYp9TKKsYy0 "Compact Legend Layout Sample") ## LAYOUT_AS_SKETCH() diff --git a/README.md b/README.md index 0fdd604..7134706 100644 --- a/README.md +++ b/README.md @@ -280,10 +280,10 @@ Rel_D(user, user1, "requests", "async message", "if sprite starts with &, it def In rare cases, you can force the layout of objects which have no relationships by using: -* `Lay_U` -* `Lay_D` -* `Lay_L` -* `Lay_R` +* `Lay_U(from, to)` +* `Lay_D(from, to)` +* `Lay_L(from, to)` +* `Lay_R(from, to)` In following sample a person uses different systems, and group of persons which have no relations @@ -318,6 +318,41 @@ Rel_L(x, s4, "uses") ![Relation versus Layout](https://www.plantuml.com/plantuml/png/LSt1QeD04CRnkq-HvgJGA55FFQLLeGLBHIEq9rbrQ8HrbTrPshnzPmn5Svl_3_RRaq6XqOxIUHXK9sqFkmlYR9w2G8iV_tl0Yssj0TrD2a6XtqrZC4kX-Ct1O2-7DaZYGy5Kl-V1A0o29ceIUY461TgVUV_rBSsQwfoLsSVvgyXSpt4Aq6PIhdZSxP_ttd-sb2zhTfJ9cZrbkYPGPfHEBgvDpLEjjzmbtztjJldkRtVEDwoV_zB09mrKLuCmkkP8NHqt43A46uWOeWt43361Ku9iQfvSPgm1GyfOBXZUOxfWT8_vWl6A9r2z7UKV "Relation versus Layout") +(In combination with [SHOW_FLOATING_LEGEND()](LayoutOptions.md#show_floating_legend)) a greater distance between an element and the +e.g. floating legend could be required that all e.g. corners of the drawing area can be reached. + +* `Lay_Distance(from, to, ?distance)`: Sets the distance between `from` and `to` with down alignment. (Lay_Distance(from,to,0) equals Lay_D(from, to)) + +In following sample the floating legend should be in the left bottom corner of the drawing are. +(The normal SHOW_LEGEND() call requires no extra Lay_Distance() call and the legend is automatically drawn below the diagram on the right side) + +``` +@startuml +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +!define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons +!define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5 +!include DEVICONS/angular.puml +!include DEVICONS/java.puml +!include DEVICONS/msql_server.puml +!include FONTAWESOME/users.puml + +Person(user, "Customer", "People that need products", $sprite="users") +Container(spa, "SPA", "angular", "The main interface that the customer interacts with", $sprite="angular") +Container(api, "API", "java", "Handles all business logic", $sprite="java") +ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information", $sprite="msql_server") + +Rel(user, spa, "Uses") +Rel(spa, api, "Uses") +Rel_R(api, db, "Reads/Writes") + +SHOW_FLOATING_LEGEND() +Lay_Distance(legend, db, 1) +@enduml +``` + +![db below legend, 1 unit distance](http://www.plantuml.com/plantuml/png/hL5DZzem4BtdLtXH3o0jH5NRIwLAYu3THUA30bkEqH0FuCgnKyy4r7_VCGcxKQjAFVHa-ytCUtvl7eWXS5NOvCwut5OQrOcvfCzf6k0oE1e-LVkACEJUCJeUvBv8ImikplI9jJNxTFInluhGotoM5a2CGQ1i91DW78P16VcJEuq7UQhnvDjqj5ni_a68gn9q-F0cQAJQFqX7dyfW6Eccf_4SQ_IgyhXSR8UxoMOvd_nNeIi65oHVOF_JBRKtLocuOsMXCVrd-JkSuM-rWdxOZ32SyVVnbfiq_fsQJ5TozQuReNlL6LN4li3GaViAVMbHyGbOEKIjok1rbJD9yLtjwKldIjNf9Q-hwb89ChnP3ID7OoLUjoTKXRGeunZ30VA6cWNF6zcw1gAXBf9oM-Z6r9Q2qWZnS3MD_36MU3w3qnP9WRLAjYIDHChweydRTB6xpJNUT_LUfiV0i0V2o3GtUV3a3wmsNsTNQcyrtMAuLpve34havDjdRtAKy-130MoyQukrjYAQoHfjatUTrGjXZ332Lo3QQgFPkdPw_U0QGLEwYyInd6oUbxliSROSRgUBfsmsUPeinjrUCeEVsTWGWyknQ_68JjS4xtl9Wpnazxy0 "db below legend, 1 unit distance") + ## Layout Options C4-PlantUML also comes with some layout options to make it easy and reusable to create nice and useful diagrams: diff --git a/percy/TestFloatingLegend.puml b/percy/TestFloatingLegend.puml new file mode 100644 index 0000000..24e5f5b --- /dev/null +++ b/percy/TestFloatingLegend.puml @@ -0,0 +1,22 @@ +@startuml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Container.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml +!endif + +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 diff --git a/percy/TestRelativeLegend.puml b/percy/TestRelativeLegend.puml deleted file mode 100644 index 3b32f82..0000000 --- a/percy/TestRelativeLegend.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml -' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally -!if %variable_exists("RELATIVE_INCLUDE") - !include ./../C4_Container.puml -!else - !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml -!endif - -Container_Ext(A, "Ext. Container A", "techn") -Person(B, "Person B") -System(C, "System C") -Container(D, "Container D", "techn") -Container(E, "Container E", "techn") - -Rel_R(A,B,"uses") -Rel_R(A,C,"uses") -Rel_D(B,C,"uses") -Rel_R(C,D,"uses") -Rel_D(B,D,"uses") -Rel_D(C,E,"uses") - -' legend fills whitespace to the right of container E -SHOW_LEGEND_RIGHT(E) -@enduml