16 KiB
Layout Options
PlantUML uses Graphviz for its graph visualization. Thus the rendering itself is done automatically for you - that it one of the biggest advantages of using PlantUML.
...and also sometimes one of the biggest disadvantages, if the rendering is not what the user intended.
For this reason, C4-PlantUML also comes with some layout options.
LAYOUT_TOP_DOWN() or LAYOUT_LEFT_RIGHT()
With the two macros LAYOUT_TOP_DOWN() and LAYOUT_LEFT_RIGHT() it is possible to easily change the flow visualization of the diagram. LAYOUT_TOP_DOWN() is the default.
@startuml LAYOUT_TOP_DOWN Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
/' Not needed because this is the default '/
LAYOUT_TOP_DOWN()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
Using LAYOUT_LEFT_RIGHT()
@startuml LAYOUT_LEFT_RIGHT Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_LEFT_RIGHT()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
LAYOUT_WITH_LEGEND() or SHOW_LEGEND(?hideStereotype)
Colors can help to add additional information or simply to make the diagram more aesthetically pleasing. It can also help to save some space.
All of that is the reason, C4-PlantUML uses colors and prefer also to enable a layout without <<stereotypes>> and with a legend.
This can be enabled with LAYOUT_WITH_LEGEND().
@startuml LAYOUT_WITH_LEGEND Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_WITH_LEGEND()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
Instead of a static legend (activated with LAYOUT_WITH_LEGEND()) a calculated legend can be activated with SHOW_LEGEND(?hideStereotype).
The calculated legend has following differences:
- only relevant elements are listed
- custom tags/styles are supported
- stereotypes can remain visible (with
SHOW_LEGEND(false)) SHOW_LEGEND()has to be last call in the diagram
@startuml SHOW_LEGEND Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
SHOW_LEGEND()
@enduml
SHOW_LEGEND_UP(alias, ?hideStereotype), SHOW_LEGEND_DOWN(...), SHOW_LEGEND_LEFT(...) or SHOW_LEGEND_RIGHT(...)
LAYOUT_WITH_LEGEND() and SHOW_LEGEND(?hideStereotype)` adds the legend at the bottom right of the picture like below and additional whitespace is created.
@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")
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")
SHOW_LEGEND()
@enduml
Therefore calculated legends can be defined relative to an element too 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
@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)
@enduml
LAYOUT_AS_SKETCH()
C4-PlantUML can be especially helpful during up-front design sessions. One thing which is often ignored is the fact, that these software architecture sketches are just sketches.
Without any proof
- if they are technically possible
- if they can fulfill all requirements
- if they keep what they promise
More often these sketches are used by many people as facts and are manifested into their documentations.
With LAYOUT_AS_SKETCH() you can make a difference.
@startuml LAYOUT_AS_SKETCH Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_AS_SKETCH()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
HIDE_STEREOTYPE()
To enable a layout without <<stereotypes>> and legend.
This can be enabled with HIDE_STEREOTYPE().
@startuml HIDE_STEREOTYPE Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
HIDE_STEREOTYPE()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
HIDE_PERSON_SPRITE(), SHOW_PERSON_SPRITE(?sprite), SHOW_PERSON_PORTRAIT()
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.
@startuml predefined sprites Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
Person(userA, "User A", "with predefined sprite person", "person")
Person(userB, "User B", "with predefined sprite person2", "person2")
@enduml
Using HIDE_PERSON_SPRITE()
@startuml HIDE_PERSON_SPRITE Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
HIDE_PERSON_SPRITE()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
Using SHOW_PERSON_SPRITE()
@startuml SHOW_PERSON_SPRITE Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
/' Not needed because this is the default with sprite "person" '/
SHOW_PERSON_SPRITE()
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
Using SHOW_PERSON_SPRITE(sprite)
@startuml SHOW_PERSON_SPRITE(sprite) Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!define osaPuml https://raw.githubusercontent.com/Crashedmind/PlantUML-opensecurityarchitecture2-icons/master
!include osaPuml/Common.puml
!include osaPuml/User/all.puml
SHOW_PERSON_SPRITE("osa_user_green_architect")
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")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
Using SHOW_PERSON_PORTRAIT()
@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