You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
361 lines
17 KiB
Markdown
361 lines
17 KiB
Markdown
# Layout Options
|
|
|
|
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.
|
|
|
|
...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.
|
|
|
|
```csharp
|
|
@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()`
|
|
|
|
```csharp
|
|
@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()`.
|
|
|
|
```csharp
|
|
@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**
|
|
|
|
```csharp
|
|
@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_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
|
|
```
|
|
|
|
|
|
|
|
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
|
|
```
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
```csharp
|
|
@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()`.
|
|
|
|
```csharp
|
|
@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() and SHOW_PERSON_OUTLINE()
|
|
|
|
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 instead of a rectangle
|
|
- **SHOW_PERSON_OUTLINE()**: activates person outline instead of a rectangle
|
|
|
|
"person" and "person2" are predefined sprites which can be used as default sprite too.
|
|
|
|
```csharp
|
|
@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()**
|
|
|
|
```csharp
|
|
@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()**
|
|
|
|
```csharp
|
|
@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)**
|
|
|
|
```csharp
|
|
@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()**
|
|
|
|
```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
|
|
```
|
|
|
|
|
|
|
|
**Using SHOW_PERSON_OUTLINE()**
|
|
|
|
> This call requires PlantUML version >= v1.2021.4!
|
|
|
|
```csharp
|
|
@startuml SHOW_PERSON_OUTLINE() Sample
|
|
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
|
|
|
|
SHOW_PERSON_OUTLINE()
|
|
|
|
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
|
|
```
|
|
|
|
|