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.