PlantUML Pleasantness: Change Look-and-feel With Themes

When we convert our PlantUML diagrams we get a default look-and-feel for our diagrams that is mostly red and yellow based. We can alter the style and color of individual elements using the skinparam command. But we can also apply so-called themes to our diagram that will alter the look-and-feel of our diagram with a simple theme reference.

We can define the name of the theme in our diagram markup using the !theme directive. Or we can use the command-line option -theme when we generate a diagram from our markup. We can even combine both methods where the end result is also a combination of both themes.

Let's start with simple PlantUML markup to test some themes:

@startuml

' Elements
actor "Application User" as User
[Mail server] as Mail <<Mail>>

package "Sample Application" {
    [Controller] <<Spring REST controllers>>
    [Service] <<Spring service>>
}

' Connections
User --> Controller
Controller --> Service
Service --> Mail

@enduml

Without themes we get the following diagram with the default look-and-feel:

First we use the !theme directive and apply the cerulean theme. Later we will how we can check which themes are part of your PlantUML version.

@startuml

' Set theme
!theme cerulean

' Elements
actor "Application User" as User
[Mail server] as Mail <<Mail>>

package "Sample Application" {
    [Controller] <<Spring REST controllers>>
    [Service] <<Spring service>>
}

' Connections
User --> Controller
Controller --> Service
Service --> Mail

@enduml

The resulting diagram now has a different look-and-feel:

Instead of adding the !theme directive we can also the command-line tool for PlantUML and specify a theme with the option -theme. For our example we could run $ plantuml diagram.puml -theme crt-green and we get the following result:

If the PlantUML markup contains the !theme directive and we use the command-line -theme option the end result will be a combination. For example if we set the cerulean with the !theme directive and specify sketchy-outline with the -theme option we get:

If we want to know which themes are included with our PlantUML version we can use the command help themes in our PlantUML markup and the resulting diagram shows all themes available.

@startuml
help themes
@enduml

For an overview of themes we can check out the theme gallery.
More information is also available in the PlantUML documentation.

Written with PlantUML 1.2021.10.

PlantUML Pleasantness: Setting Arrow Directions

PlantUML mostly does a good job organizing elements and arrows in the resulting diagram. But we can help PlantUML by defining the arrow direction in our PlantUML definition. We can use the keywords up, down, left and right inside the arrow definition.

In the following example we have five rectangles connected with arrows. We define the arrow direction for each arrow.

@startuml
rectangle Export 
rectangle PDF
rectangle HTML
rectangle ePub
rectangle Word

Export -left-> PDF
Export -right-> HTML
Export -down-> ePub
Export -up-> Word
@enduml

We can even only use the first letters of the direction. The following definition will render the same diagram:

@startuml
rectangle Export 
rectangle PDF
rectangle HTML
rectangle ePub
rectangle Word

Export -l-> PDF
Export -r-> HTML
Export -d-> ePub
Export -u-> Word
@enduml

The resulting diagram looks like this:

Written with PlantUML 1.2018.6.

PlantUML Pleasantness: Using The Built-in Icons

PlantUML has a built-in icon set we can use in our diagram definitions. The icon set is open source icon set OpenIconic. We refer to an icon using the syntax <&iconName>.We can use an icon everywhere where we can use text in our diagrams.

In the following example we use different icons in different places:

@startuml

skinparam DefaultFontSize 24
skinparam DefaultTextAlignment center

title <&caret-right> Using icons in PlantUML <&caret-left>

package "Charts <&menu>" as charts {

    file bar [
        Bar

        <size:120><&bar-chart></size>
    ]

    file pie [
        Pie

        <size:42><&pie-chart></size>
    ]

}   

@enduml

When we generate a diagram we see the following output:

To get a list of available icons we can use the statement listopeniconic. This will create a diagram with all the icons and their names we can use:

@startuml
listopeniconic
@enduml

The following image shows all icons that we can use:

Written with PlantUML 1.2017.18.

PlantUML Pleasantness: Layout Elements With Hidden Lines

In a previous post we learned how to use a together block to keep elements together. We can also layout elements in a different way: using hidden lines. We define our elements and by using the keyword [hidden] in our line definition the elements are layout as if there was a line, but we don't see it. This gives us great flexibility on how we layout our elements.

In the following sample we first have a PlantUML definition where we rely on the default layout:

@startuml

package "Core Components" {
    [Backend Client] as BackendClient
    [File Reader] as FileReader
    [Content Transform] as ContentTransform
    [Logging]
}

BackendClient ~~> ContentTransform : uses
FileReader ~~> ContentTransform: uses

@enduml

This definition renders the following diagram:

We want the Logging component at the bottom right corner of the Core Components. Using a visible line we would connect the BackendClient to the Logging component. This would place the Logging component beneath the BackendClient, just like we want. So we add a connecting line and we add the [hidden] attribute on our line definition. The Logging component is placed where we want and we don't see the line supporting this:

@startuml

package "Core Components" {
    [Backend Client] as BackendClient
    [File Reader] as FileReader
    [Content Transform] as ContentTransform
    [Logging]
}

BackendClient ~~> ContentTransform : uses
FileReader ~~> ContentTransform: uses

' Layout Logging under BackendClient
BackendClient -[hidden]- Logging

@enduml

When we regenerate the diagram we get the result we want:

Written with PlantUML 1.2017.16.

PlantUML Pleasantness: Align Multi-line Label Text

PlantUML has some features that come from the underlying software to create diagrams. Graphviz is used by PlantUML and we can use Graphviz features in our PlantUML diagrams. For example we can align multi-line text of labels to be either center (default), left or right aligned using a Graphviz feature. When we want to text to be center aligned we simply use the new-line character \n. If we want to have our text left aligned we use \l instead of \n. And to right align the text we use \r.

In the following example we have three labels that are center, left and right aligned:

@startuml

actor "Application User" as User

[Mail server] as Mail <<Mail>> #ffcc66

package "Sample Application" {
    [Controller] <<Spring REST controllers>>
    [Service] <<Spring service>>
}

' Label text is centered
User --> Controller : Types in\ndata to\nsend a message.

' Label text is left aligned
Controller --> Service : User data to\lcreate a\lnew message.

' Label text is right aligned
Service --> Mail : Mail message\robject containing\rall user information.

@enduml

When we run PlantUML with this diagram syntax we get the following diagram:

Written with PlantUML 1.2017.16.

PlantUML Pleasantness: Change Line Style And Color

We can change the line style and color when we "draw" the line in our PlantUML definition. We must set the line style and color between square brackets ([]). We can choose the following line styles: bold, plain, dotted and dashed. The color is either a color name or a hexadecimal RGB code prefixed with a hash (#).

In the following example activity diagram we apply different styles and colors to the lines:

@startuml

' Make a dashed line, alternative syntax for ..>
(*) -[dashed]-> "Write outline"

' Make line bold and use color name
"Write outline" -[bold,#green]-> "Find example"

' Only change the color with hexadecimal RGB code
"Find example" -[#ff00ff]-> "Write blog"

' Order of line style and color can be reversed
"Write blog" -[#6666ff,dashed]-> "Publish"

' Use dotted line style
"Publish" -[dotted]-> (*)

@enduml

When we generate the activity diagram we see the different line styles and colors:

Written with PlantUML 8051.

PlantUML Pleasantness: Using Current Date

In PlantUML we can use the special variable %date% to get the current date and time. The default format shows day of the week, date, time and timezone. We can change the date format by specifying our format with the Java SimpleDateFromat symbols. For example to only get the hours and minutes we would write %date[HH:mm]%.

In the following example we use the %date% variable as is and with a custom format:

@startuml
' Use %date% to get date diagram is generated.
title Sample with date - %date%

' We can use Java SimpleDateFormat options
' to format the date. In this example we
' only want the day-month-year of the date.
footer Generated on %date[dd-MM-yyyy]%
@enduml

When we generate a graphical representation we get the following result:

Written with PlantUML 8051.

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.

PlantUML Pleasantness: Align Elements With Line Length

Drawing diagrams with PlantUML is fun and easy. We use text to describe the diagram and the we get a graphical representation. Especially in combination with Asciidoctor with PlantUML integration we have a winning combination to write technical documentation. Because our text is transformed into a graphical format like PNG we don't have much influence on the layout. There are options to indicate positions of elements, but we can also use the length of lines to influence the position of elements.

In the following sample we have a PlantUML diagram description with standard lines. We use two hyphens (--) to define a line:

@startuml
actor User
[Third party application] as ThirdPartyApp

[PostgreSQL database] <<Database>> as PostgresDB
[Mail server] <<Mail server>> as Mail

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

We create a diagram and we get the following graphical diagram:

The diagram looks fine, but we want to have our mail server at the same level as the PostgreSQL database element. We simply add an extra hyphen (-) to the connection line between DataStoreService and Mail:

@startuml
actor User
[Third party application] as ThirdPartyApp

[PostgreSQL database] <<Database>> as PostgresDB
[Mail server] <<Mail server>> as Mail

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

User --> Controllers
ThirdPartyApp --> Controllers

Controllers --> DataStoreService
DataStoreService --> Repository

/'Add extra hyphen (-) to put Mail
  add the same level as PostgresDB '/
DataStoreService ---> Mail

Repository --> PostgresDB
@enduml

We regenerate our diagram and we get the following result:

Written with PlantUML 8048.