Search

Dark theme | Light theme
Showing posts with label PlantUML:Pleasantness. Show all posts
Showing posts with label PlantUML:Pleasantness. Show all posts

June 6, 2018

PlantUML Pleasantness: Using AWS, Font Awesome, Devicons and Google Material Icons

In a previous post we learned how to use the built-in icons from the OpenIconic set. In the newer PlantUML versions several icon sets have been added as standard library. These sets include AWS icons, Font Awesome icons, Devicons and Google Material icons.

To use an icon from the icon set we must include the icon using the !include statement. In our PlantUML definition we reference the icon with the syntax <$iconName>. In the following example PlantUML definition we include 2 icons from the Font Awesome and Devicons icon sets:

@startuml
' We only include the icon files.
!include <devicons/github>
!include <font-awesome/gitlab>

rectangle github [
    ' Reference github icon with <$icon>.
    <$github>
]

rectangle gitlab [
    ' Reference gitlab icon with <$icon>.
    <$gitlab>
]

github -> gitlab : ~#movingtogitlab
@enduml

When we render this definition to a diagram we get the following result:

Each icon set also comes with a common file that defines macros for creating elements with an icon. Instead of referencing an icon with the syntax <$iconName> we can use a macro. For each icon there is a corresponding macro and the macro is overloaded to accept different arguments. The icon sets for AWS, Font Awesome and Devicons use the same macro arguments. The arguments for using the Google Material icons is different. So we need to keep this in mind when we use the macros in our PlantUML definition.

We use the macros from the different icon sets n the following examples:

@startuml

' Include common to use icon macros.
!include <devicons/common>
' Include icon from Devicons.
!include <devicons/github>
' Include icon from Font Awesome icons.
!include <font-awesome/gitlab>

' Use macros from common library and icon file.
' First argument is alias, second label.
DEV_GITHUB(github, 'Github')
FA_GITLAB(gitlab, 'Gitlab')

' Use ~ to escape #
github -> gitlab : ~#movingtogitlab

@enduml

Let's render the diagram for the PlantUML definition:

In the next example we use the extra arguments to style the element. Also we use the stereotype set by the macro to change the foreground and background colors of the element:

@startuml

!include <devicons/common>
!include <devicons/github>
!include <font-awesome/gitlab>

' Change styling via stereotypes, set by
' macro from devicons/github library.
skinparam cloud<<DEV GITHUB>> {
    BackgroundColor #66ffcc
    ForegroundColor #ccff66
}

' Third argument is element type.
DEV_GITHUB(github, 'Github', cloud)
' Fourth argument is foreground color.
' After macro definition we can set the background color.
FA_GITLAB(gitlab, 'Gitlab', cloud, #ff9e27) #ccff66

github -> gitlab : ~#movingtogitlab

@enduml

We get the following diagram:

Now we use the AWS icons:

@startuml

' Include common to use icon macros.
!include <aws/common>
' Include three icons.
!include <aws/Compute/AmazonECR/AmazonECR>
!include <aws/Compute/AmazonECS/AmazonECS>
!include <aws/Compute/AmazonECS/ECScontainer/ECScontainer>

' Macro signature is the same as for font-awesome and devicons.
AMAZONECR(ecr)
AMAZONECS(ecs) {
    ECSCONTAINER(containers, 'Containers', collections)
} 

ecr .> containers

@enduml

This results in the following diagram:

And with the Google Material icon set we must keep in mind that the arguments for the macros are different:

@startuml

' Include common to use material icon macros.
!include <material/common>
' Include console icon.
!include <material/console>
' Include clipboard_text icon.
!include <material/clipboard_text>

' Do not show stereotype in diagram.
hide stereotype

' Use icon macro where first argument is
' the foreground color, the second is the
' scale of the icon, third argument is alias.
MA_CONSOLE(#ff9e27, 1, console)
' Fourth argument is the type
MA_CONSOLE(#ff9e27, 2, consoleLarge, rectangle)
' And the fifth argument is a label.
MA_CONSOLE(#ff9e27, 4, consoleBig, file, 'A big console')

file clipboard [
    ' Instead of using the macro we can reference
    ' the icon by name directory. We must use the ma_
    ' prefix before the icon name.
    <$ma_clipboard_text>
]

@enduml

The definition gives the following diagram:

Written with PlantUML 1.2018.6.

December 16, 2016

PlantUML Pleasantness: Get PlantUML Definition From PNG

When we generate a PNG version of our PlantUML definition the original definition is stored in the PNG image. We can extract the definition using the command line option -metadata. We need to provide the PNG file and in the output we see the original PlantUML definition.

The following PNG image (activity.png) is created with PlantUML:

Next we run PlantUML from the command line using the option -metadata:

$ java -jar plantuml.jar -metadata activity.png
------------------------
activity.png

@startuml

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

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

' Only change the color
"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

PlantUML version 8051(Thu Dec 01 18:52:05 CET 2016)
(GPL source distribution)
Java Runtime: Java(TM) SE Runtime Environment
JVM: Java HotSpot(TM) 64-Bit Server VM
Java Version: 1.8.0_112-b16
Operating System: Mac OS X
OS Version: 10.12.1
Default Encoding: UTF-8
Language: en
Country: US

------------------------
$

At the top we see the section @startuml..@enduml with the PlantUML syntax that was used to generate the PNG image.

Written with PlantUML 8051.

December 14, 2016

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.

December 12, 2016

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.

December 9, 2016

PlantUML Pleasantness: Check If PlantUML Is Up To Date

With the command line option -checkversion we can see if we have the latest PlantUML version. The command prints to the console our current PlantUML version and latest version that is available. Inside a PlantUML definition we can use the command checkversion and generate for example a PNG image with information about our PlantUML version and the latest version that can be downloaded.

First we use the command line option -checkversion for an out-of-date version:

$ plantuml -checkversion
PlantUML version 8048 (Thu Sep 29 19:04:02 CEST 2016)

Last available version for download : 8051

A newer version is available for download.
$

We update our PlantUML and run the command again:

$ plantuml -checkversion
PlantUML version 8051 (Thu Dec 01 18:52:05 CET 2016)

Last available version for download : 8051

Your version is up to date.
$

Now we use a PlantUML definition so we can generate a graphical representation of the information.

@startuml
checkversion
@enduml

First we use the older version of PlantUML to generate a PNG image:

Next we use the latest version that is available:

Written with PlantUML 8051.

PlantUML Pleasantness: Generate Graphical Version Information

If we want to know which version of PlantUML we are using we can use the command line option -version. PlantUML will print the version and also some extra information like the machine name, memory and more. But we can also create a PlantUML definition with the command version and we can transform it to a graphical presentation like a PNG image. This can be handy if we use PlantUML in an environment like Asciidoctor with diagram support and we want to know which version of PlantUML is used.

In our first example we run PlantUML from the command line and use the -version option:

$ plantuml -version
PlantUML version 8051 (Thu Dec 01 18:52:05 CET 2016)
(GPL source distribution)
Java Runtime: Java(TM) SE Runtime Environment
JVM: Java HotSpot(TM) 64-Bit Server VM
Java Version: 1.8.0_112-b16
Operating System: Mac OS X
OS Version: 10.12.1
Default Encoding: UTF-8
Language: en
Country: US
Machine: mrhaki-laptop-2015.fritz.box
PLANTUML_LIMIT_SIZE: 4096
Processors: 8
Max Memory: 3,817,865,216
Total Memory: 257,425,408
Free Memory: 249,050,832
Used Memory: 8,374,576
Thread Active Count: 2

The environment variable GRAPHVIZ_DOT has been set to /usr/local/bin/dot
Dot executable is /usr/local/bin/dot
Dot version: dot - graphviz version 2.38.0 (20140413.2041)
Installation seems OK. File generation OK
$

In the second example we create a file with the following PlantUML definition:

@startuml
version
@enduml

When we generate a PNG from this definition we get the following result:

Written with PlantUML 8051.

December 6, 2016

PlantUML Pleasantness: Create A Sudoku :)

PlantUML has a fun command to create a Sudoku puzzle. We must use sudoku in our PlantUML definition and a random puzzle is generated. We can even give a seed value for a given Sudoku so it is generated again.

In the following example PlantUML definition we use the sudoku command:

@startuml
sudoku
@enduml

We create a PNG file with PlantUML and we get the following result:

To regenerate the same Sudoku we must use the seed value cinnld556e0o:

@startuml
sudoku cinnld556e0o
@enduml

Written with PlantUML 8048.

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.

December 5, 2016

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.