Flow Diagrams

Flow diagrams show the several steps that make a task or algorithm and can be used for anything from statistical analyses to cake recipes. Figure 6, which is taken from the PlantBuddy GitHub site [4], shows a PlantUML flow diagram. While the language in Figure 6's source code (Listing 6) is intuitive, you need to know how to write a while cycle (lines 5 and 13) and how to use markers to delimit each phase of the flow. You use a colon at the beginning of a phase and semicolon at the end.

01 @startuml
02
03 :read moisture level;
04 :read humidity + temperature;
05 while (sensor readings) is (invalid)
06   :wait 2s;
07   :read moisture level;
08   :read humidity + temperature;
09   :increase counter;
10   if (MAX_READING_RETRIES reached) then (yes)
11     :send controller to deep sleep;
12   endif
13 endwhile (valid)
14 :submit sensor data;
15
16 @enduml

Figure 6: Part of a complex flow diagram, created on the fly from PlantBuddy's GitHub site [4]. @PlantBuddy.

Diagram Formatting

UML and PlantUML offer many options for controlling text formatting, as well as style and appearance.

According to the manual [5], the scale command enlarges the generated image in several ways, including but not limited to these options:

scale 1.5
scale 200 width
scale 1400*700

However, this option did not work as documented on several of my diagrams.

To format text, PlantUML supports both basic HTML tags like bold and underline, and their equivalents in Creole format, such as:

@startuml
This is **bold**
This is //italics//
This is ""monospaced""
This is --stroked--
This is __underlined__
This is ~~waved~~

The most important formatting command in PlantUML, skinparam (see [5] for its many attributes), lets you set fonts, background and text color, title properties, and much more. As an example, you can customize UML diagrams with skinparam to create real templates as shown in Listing 7.

01 skinparam backgroundColor transparent
02 skinparam monochrome true
03
04 skinparam titleBorderRoundCorner 15
05 skinparam titleBorderThickness 2
06 skinparam titleBackgroundColor Aqua-CadetBlue
07
08 skinparam classFontColor red
09 skinparam classFontSize 10
10 skinparam classFontName Aapex

skinparam's only drawback is that the more you use it, the less portable your diagrams may become. This is especially true with fonts, which may not be available on all systems that will generate diagrams from your UML code.

Diagram Metadata

Besides the actual diagram, UML files can define several widgets that give context, structure, and generally make the diagrams themselves easier to understand. For brevity, Figure 7 shows all of these elements, plus it introduces a few other PlantUML features. The source code for Figure 7 is shown in Listing 8.

Figure 7: With PlantUML, you can add legends, headers, footers, and more.

01 @startuml
02 caption Figure 1 Caption
03 title
04 <size:30><&bullhorn>Use case UML diagram<&star></size>
05 endtitle
06
07 header
08 header (not title) goes here
09 endheader
10
11 center footer You can also have a footer
12
13 legend right
14 This example shows
15 how you can add
16 <u><b>"meta-information"</b></u>
17 to any diagram
18 endlegend
19
20 left to right direction
21 skinparam packageStyle rectangle
22 actor customer
23 actor clerk
24 rectangle checkout {
25 customer -- (checkout)
26 (checkout) .> (payment) : include
27 (help) .> (checkout) : extends
28 (checkout) -- clerk
29 }
30 @enduml

In Listing 8, the actual diagram is shown in lines 20 to 29; again, you can easily understand the source code by comparing it carefully with the drawing. Lines 2 to 18 demonstrate how to define all the widgets I mentioned, from header and footer to title, legend, and captions. Line 4 requires an explanation. While the size:30 statement is self-explanatory, the &bullhorn and &star keywords tell PlantUML to insert the corresponding icons from the Open Iconic graphic library [6] (integrated in PlantUML) in their place.