PlantUML — Draw Beautiful Diagrams

PlantUML is an open-source tool allowing users to create diagrams from a plain text language. I would say I havn’t see any more powerful and easy-to-use tool until now. Let’s see how powerful and easy-to-use PlantUML is.

PlantUML Introduction (Author: Bruce Wen)

Install

For me, ‘install’ is an luxurious word for PlantUML because you just need to download the jar file. What you actually need to install is JRE and GraphViz (only needed if you want to draw not only Sequence Diagram but more other kinds of Diagrams also).

You can follow the official guide to finish installation: https://plantuml.com/starting.

Syntax

PlantUML is more like one programming language, but it’s simple — too simple and too powerful. For sure, if you want, it could be very complex — when you working on big project and need to draw quite manage diagrams with much information. Don’t worry, PlantUML can do it. Let’s start from beginning.

Assuming we have one PlantUML file with below content:

@startuml
Client -> Server : Request
Client <-- Server : Response
@enduml

Obviously, it’s a sequence diagram to show communication sequence between Client and Server.

If we run below command, then we can generate a .png file for the PlantUML file. Let’s give it a name: client-server.pu

java -jar plantuml.jar client-server.pu
Sequence Diagram for Client-Server Communication
Client-Server Sequence Diagram — v1

Now, we can get closer to the 4 lines in the client-server.pu file:

  • @startuml and @enduml — these 2 annotations tell the start and end of the PlantUML file. So, if we add anything before @startuml or after @enduml , what will happen? Try yourself, the content before @startuml or after @enduml will be ignored by plantuml.jar . So, they will be treated as comments .
  • Client , Server — By default, they are participant. You can also add the keyword participant before Client and Server . But it will not make any change, just make it more readable.
  • Arrows -> , --> — they play very important roles in PlantUML and they make the PlantUML simple and powerful. There are many more different arrows, we will see later. One more thing, the arrow usage is quite flexible. For example, you can change Client <-- Server to Server --> Client and the final generated diagram will be the completely same.
  • File extension .pu — In fact, you can use any extension, there is no limitation. For example, you can even use .exe as the file extension — it will work in the same way with .pu . However, normally, people choose file extensions like .pu , .puml ,as such. Maybe, these file extensions are more formal, more readable, and more professional.

For now on, we can simply add more participants and more arrows between them to show their relationship.

Supported Diagrams

We have understood very basic concepts of PlantUML. Now, we can try to know more about diagrams PlantUML provided.

  • UML Diagrams: Sequence Diagram, Usecase Diagram, Class Diagram, Activity Diagram, Component Diagram, State Diagram, Object Diagram, Deployment Diagram, Timing Diagram.
  • Non-UML Diagrams: Wireframe graphical interface, Archimate diagram, Specification and Description Language (SDL), Ditaa diagram, Gantt diagram, MindMap diagram, Work Breakdown Structure diagram, Mathematic with AsciiMath or JLaTeXMath notation.

I guess few people will use each diagram in above list. Most of us just use some of them. So, choose those diagrams you need and learn how to use them. That’s enough and maybe it’s better to know other diagrams are also supported. And when needed, we can check how to implement them by PlantUML.

Color and Style Customization

I would say for all GUI applications, color customization is one of most important feature. Color makes GUI more fun. Different people like different color. Some people cannot distinguish some special colors.

Continue the example and let’s try to do some change for colors.

@startuml
participant Client #blue
participant Server #orange
Client -> Server : Request
Client <-- Server : Response
@enduml

We declared participants Client and Server by keyword participant and add color code at the end.

Note: if we don’t use the keyword participant in declaration statements, then Client and Server will be Actor by default.

The generated diagram will be:

Client-Server Sequence Diagram -v2

As you see, black text on blue background is hard to be seen. How can we change the text color then?

In addition, can we change color of arrows? And border of participants? And background? And connector line of participants from top to bottom? And border width, arrow width, connection line width?

Yes, we can do all above! Check below changed content:

@startuml
skinparam ParticipantFontColor #efefef
skinparam ParticipantBorderColor #c0c0c0
skinparam SequenceParticipantBorderThickness .5
skinparam ArrowThickness .3
skinparam SequenceLifeLineBorderColor #8a8a8a
participant Client #green
participant Server #880000
Client -[#green]> Server : Request
Client <-[#880000]- Server : Response
@enduml

This time, we changed quite a lot of things. Let’s look at the generated diagram before going through each change we made:

Client-Server Sequence Diagram -v3

As you see, we changed participants background color — client and server used different color, we changed arrows color for request and response, we changed lifeline color to gray (#8a8a8a) . If you watch closer, you might notice we also changed width of participants box border, and arrow border width.

Note: Lifelineis the dotted lines connected header and footer participants boxes.

You also noticed that we used skinparam command (yes, it’s command in PlantUML language). We wrote it line by line in above change. In fact, it has one more simple format — nested format:

skinparam {
ParticipantFontColor #efefef
ParticipantBorderColor #c0c0c0
SequenceParticipantBorderThickness .5
ArrowThickness .3
SequenceLifeLineBorderColor #8a8a8a
}

If we want to group those parameters with same prefix, like ParticipantFontColor and ParticipantBorderColor or SequenceParticipantBorderThickness and SequenceLifeLineBorderColor , then we can also use below format by moving prefix to the nest block:

skinparam Arrow{
Thickness .3
}
skinparam Participant{
FontColor #efefef
BorderColor #c0c0c0
}
skinparam Sequence{
ParticipantBorderThickness .5
LifeLineBorderColor #8a8a8a
}

Trust me, you will like this group format (I called it) when your PlantUML file becomes longer and longer.

To be honest, I would say skinparam command is very powerful. There are lots of other skin parameters can be used. You can use below command to get all of them:

java -jar plantuml.jar -language

Maybe you’d better use below one to filter what you want as the above command will print a super long list which is hard to find what you want:

java -jar plantuml.jar -language | grep -i color

skinparam is powerful but it’s used for global change. For example, you cannot use skinparam to set different color for different participants or each arrows. We have to use another syntax to do it — you noticed it, right?

participant Client #green
participant Server #880000
Client -[#green]> Server : Request
Client <-[#880000]- Server : Response

That’s it. We can provide color code after declaration of participants and in middle of the arrows. Very good design!

If you want to continuously refine the diagram — to have round corner, for example. You can do it, no problem. By using skinparam roundCorner 8 , you will get it.

Client-Server Sequence Diagram -v4

Finally, the diagram we generated is a bit small — maybe you noticed at the very beginning. How to enlarge it? By using scale 500 width we can bigger one:

Client-Server Sequence Diagram -v5

OK, you also observed that I forgot one thing — to change background color. OK, let’s do it now. With skinparam backgroundcolor #383838 we can get below one:

Client-Server Sequence Diagram -v6

Oh, it seems not good to have black font on dark gray background. Let’s change arrow font color by skinparam ArrowFontColor #acacac we can fix it:

Client-Server Sequence Diagram -v7

Now, I would stop to refine it as it’s enough to tell how to do it and you can explore more wonderful usage of skinparam and tune the diagram you created.

BTW, I like the v7 above. 😃

That’s all for this article to tell about great PlantUML. Hope it can help you start the journey of using PlantUML and enjoy.

To learn more about PlantUML, refer to official site about PlantUML Language Specification. And keep eyes on the forum. You must also like the page about All Skin Parameters.

Thanks for reading and happy coding. Take care!

If you like my articles, don’t hesitate to follow me and subscribe.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store