PlantUML Pleasantness: Include Partial Content From Files

With PlantUML we can include external files in our definition with the !include directive. We specify the file name and the content is included in our PlantUML definition. The included file can also have multiple @startuml ... @enduml sections and we can refer to individual sections with the !include directive. We must append to the include file name an exclamation mark (!) followed by either a number or identifier. If we use a number we specify which section we want to include, where section are numbered starting from 0. So to get the second section from a file commons.puml we would write !include commons.puml!1. Alternatively we can use identifiers in the include file. We append to @startuml an identifier as (id=idValue). Then from the definition that is including the file we refer to the identifier after an exclamation mark (!). If our included file commons.puml has a section with id user then we would include it as !include commons.puml!user.

In the following example PlantUML definition we define the file to be included. We have two sections with @startuml ... @enduml which both have an identifier:

' File: commons.puml

' section with id user to define user actor
@startuml(id=user)
actor "Application User" as User
@enduml

' section with id mail to define mail component
@startuml(id=mail)
[Mail server] as Mail <<Mail>> #ffcc66
@enduml

Next we write a definition where we include commons.puml using a section number and section identifier:

' File: sample.puml
@startuml

' Include first section (0-based index) of commons.puml
!include commons.puml!0

' Include section with id mail of commons.puml
!include commons.puml!mail


[Sample Application] <<Software System>> as SampleApp

User --> SampleApp
SampleApp --> Mail

@enduml

Let's generate a diagram and look at the result where we see our user and mail components from the included file:

Written with PlantUML 8086.

PlantUML Pleasantness: Customize Stereotype Styling

To change the styling of our generated diagrams with PlantUML we can use the skinparam command. We can set for example font size, style, color, background colors and much more. We can change the style for a specific element or for the whole diagram. We can even set specific styling options for stereotypes. The settings for the stereotype are then applied to all elements in our diagram with that stereotype. We must append <<stereotype name>> to the skin parameter name.

In the following example PlantUML description we apply custom background colors to each stereotype:

@startuml

/' Set custom background colors for the default
   component elements and the specific stereotypes. '/
skinparam component {
    BackgroundColor #ff6666
    BackgroundColor<<Database>> #ccff66
    BackgroundColor<<Spring service>> #66ccff
    BackgroundColor<<Spring REST controllers>> #66ffcc
    BackgroundColor<<Spring repository>> #66ffff
    BackgroundColor<<Mail server>> #ffcc66
}

actor User
[Third party application] as ThirdPartyApp

together {
    [PostgreSQL database] as PostgresDB <<Database>>
    [Mail server] as Mail <<Mail server>>
}

package "Spring Boot Application" {
    [APIController] <<Spring REST controllers>>
    [AdminController] <<Spring REST controllers>>

    [AdminService] <<Spring service>>
    [DataStoreService] <<Spring service>>

    [Repository] <<Spring repository>>
}

User --> AdminController
ThirdPartyApp --> APIController

APIController --> DataStoreService
AdminController --> DataStoreService
AdminController --> AdminService

DataStoreService --> Repository
AdminService --> Mail

Repository --> PostgresDB

@enduml

When we generate the diagram we see that each stereotype has it's own background color:

Written with PlantUML 8086.

PlantUML Pleasantness: Keeping Elements Together

When we write a PlantUML definition the generated graphical diagram is laid out by PlantUML. In a previous post we learned how to move elements using the length of the connection. But we can also use a together block with all elements that should be at the same level. PlantUML will try to keep the elements together when the diagram is drawn.

In the following sample PlantUML definition we want the PostgresDB and Mail elements to be at the same level, so we group them using a together block:

@startuml

actor User
[Third party application] as ThirdPartyApp

/' Try to keep PostgresDB and Mail together,
   so they are at the same level in the diagram. '/
together {
    [PostgreSQL database] as PostgresDB <<Database>>
    [Mail server] as Mail <<Mail server>>
}

package "Spring Boot Application" {
    [Controllers] <<Spring REST controllers>>
    [DataStoreService] <<Spring service>>
    [Repository] <<Spring repository>>
}

User --> Controllers
ThirdPartyApp --> Controllers

Controllers --> DataStoreService

DataStoreService --> Repository
DataStoreService --> Mail

Repository --> PostgresDB

@enduml

Let's create the diagram and we see the elements are aligned nicely:

Written with PlantUML 8086.

PlantUML Pleasantness: No Shadows In Diagrams

By default elements in a PlantUML generated diagram have shadows. To disable shadows we must set the skin parameter shadowing to the value false. PlantUML will then not create shadows on elements.

In the following sample PlantUML definition we use the value false for the skin parameter shadowing:

@startuml

' Remove shadows
skinparam shadowing false

actor User
[Third party application] as ThirdPartyApp

package "Spring Boot Application" {
    rectangle Controllers <<Spring REST controllers>>
    rectangle DataStoreService <<Spring service>>
    rectangle Repository <<Spring repository>>
}

User --> Controllers
ThirdPartyApp --> Controllers

Controllers --> DataStoreService
DataStoreService --> Repository

@enduml

The generated diagram has no shadows:

Written with PlantUML 8086.

PlantUML Pleasantness: Diagrams In Black And White

The default colors of PlantUML use red and yellow to draw the diagram elements. If we want our diagram to be in black, grey and white we can simply set skin parameter monochrome to true. The generated graphical diagram will now have black, grey and white colors.

In the following sample PlantUML definition we set the diagram skin parameter monochrone to true:

@startuml

' Generated diagram will be in black/grey/white.
skinparam monochrome true

actor User
[Third party application] as ThirdPartyApp

package "Spring Boot Application" {
    rectangle Controllers <<Spring REST controllers>>
    rectangle DataStoreService <<Spring service>>
    rectangle Repository <<Spring repository>>
}

User --> Controllers
ThirdPartyApp --> Controllers

Controllers --> DataStoreService
DataStoreService --> Repository

@enduml

The generated diagram looks like this:

Written with PlantUML 8048.