Pro UML Diagram Widget
GitPitch Paid Plans activate powerful Pro syntax shortcuts supported by PITCHME.md markdown that can be used to generate rich visual components - aka. widgets - on any slide. This guide introduces the @uml widget.
- @uml - UML Widget for Diagrams
- Learn By Example - Sequence Diagrams
- Learn By Example - Activity Diagrams
- Learn By Example - State Diagrams
- Learn By Example - Timing Diagrams
- Learn By Example - Use Case Diagrams
- Learn By Example - Deployment Diagrams
- Learn By Example - Object Diagrams
- Learn By Example - LaTeX Math Diagrams
- Learn By Example - Ascii Math Diagrams
- UML Diagrams Layout Controls
- UML Diagrams Caching Policy
- Advanced Graphviz/DOT Language Support
UML Widget for DiagramsPolicy
The @uml widget supports the creation of pixel-perfect UML diagrams generated as SVG images from simple text-based descriptions. GitPitch UML diagram support is powered by PlantUML.
The following conventions for GitPitch UML diagrams are in use:
- PlantUML diagram descriptions must be defined in a file within your local repository.
- These PlantUML diagram description files must have a .puml extension.
If you follow these conventions you can then use the following @uml syntax to render a UML diagram on any slide:
@uml[style...](path/to/diagram.puml)
The CSS style… list can make use of the built-in span styles giving you control over the rendering width and height of your UML diagrams.
Click on the above screenshot to experience UML Disgrams live in a sample GitPitch slide deck.
If you are developing your slide decks using GitPitch Desktop then you should take note of the current caching policy for your UML diagrams.
Learn By Example - Sequence Diagrams
This PlantUML sequence diagram syntax:
@startuml
actor Alice #yellow
participant Bob
Alice->Bob: Auth Request
Bob->Alice: Auth Response
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@snap[west span-60]
@code[uml rawcode zoom-15](src/uml/sequence.puml)
@snapend
@snap[east span-40]
@uml[span-100 bg-white](src/uml/sequence.puml)
@snapend
@snap[south-west span-100]
@[1,6](Start with opening and closing PlantUML delimiters.)
@[2,3](Declare participants, actors, boundaries, etc.)
@[4,5](Then define the messages between participants.).
@snapend
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about Sequence Diagrams syntax see the following PlantUML Guide.
Learn By Example - Activity Diagrams
This PlantUML activity diagram syntax:
@startuml
start
if (Graphviz installed?) then (yes)
:Process all\ndiagrams;
else (no)
:Process only
__sequence__ and __activity__ diagrams;
endif
stop
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@snap[west span-50]
@code[uml rawcode zoom-09](src/uml/activity.puml)
@snapend
@snap[east span-50]
@uml[span-100 bg-white](src/uml/activity.puml)
@snapend
@snap[south-west span-100]
@[1,14](Start with opening and closing PlantUML delimiters.)
@[3,12](Declare activity diagram start and stop states.)
@[5,7,10](Use *if*, *then*, and *else* keywords to define logical branches.)
@[6,8-9](Then define a process for each branch path in the activity diagram.)
@snapend
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about Activity Diagrams syntax see the following PlantUML Guide.
Learn By Example - State Diagrams
This PlantUML state diagram syntax:
@startuml
hide empty description
[*] --> State1
State1 --> [*]
State1 : this is a string
State1 : this is another string
State1 -> State2
State2 --> [*]
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@uml[span-45 bg-white](src/uml/state.puml)
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about State Diagrams syntax see the following PlantUML Guide.
Learn By Example - Timing Diagrams
This PlantUML timing diagram syntax:
@startuml
robust "Web Browser" as WB
concise "Web User" as WU
@0
WU is Idle
WB is Idle
@100
WU is Waiting
WB is Processing
@300
WB is Waiting
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@snap[west span-45]
@code[uml rawcode zoom-11](src/uml/timing.puml)
@snapend
@snap[east span-55]
@uml[span-100 bg-white](src/uml/timing.puml)
@snapend
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about Timing Diagrams syntax see the following PlantUML Guide.
Learn By Example - Use Case Diagrams
This PlantUML use-case diagram syntax:
@startuml
:Main Admin: as Admin
(Use the application) as (Use)
User -> (Start)
User --> (Use)
Admin ---> (Use)
note right of Admin : This is an example.
note right of (Use)
A note can also
be on several lines
end note
note "Note connected\nto several objects." as N2
(Start) .. N2
N2 .. (Use)
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@uml[span-75 bg-white](src/uml/usecase.puml)
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about Use Case Diagrams syntax see the following PlantUML Guide.
Learn By Example - Deployment Diagrams
This PlantUML deployment diagram syntax:
@startuml
actor actor
agent agent
artifact artifact
boundary boundary
card card
cloud cloud
component component
control control
database database
entity entity
file file
folder folder
frame frame
interface interface
node node
package package
queue queue
stack stack
rectangle rectangle
storage storage
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@uml[span-55 bg-white](src/uml/deployment.puml)
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about Deployment Diagrams syntax see the following PlantUML Guide.
Learn By Example - Object Diagrams
This PlantUML object diagram syntax:
@startuml
object Object01
object Object02
object Object03
object Object04
object Object05
object Object06
object Object07
object Object08
Object01 <|-- Object02
Object03 *-- Object04
Object05 o-- "4" Object06
Object07 .. Object08 : some labels
@enduml
Used within the following PITCHME.md markdown snippet:
---?color=#E58537;
@uml[span-90 bg-white](src/uml/object.puml)
Results in the rendering of the following slide:
Click on the above image to view this slide within a live GitPitch presentation.
For further details about Object Diagrams syntax see the following PlantUML Guide.
UML Diagrams Layout Controls
By default, PlantUML diagram entities are rendered in a top-to-bottom layout. For any diagram with more than a couple of entities this typically results in tall-and-thin UML diagrams. For example:
Given the aspect ratio of GitPitch slides are wide-and-short there may be times when you need to activate a left-to-right layout for your UML diagrams. Doing so will let you to take better advantage of the full width of your slides. You can activate a left-to-right layout for any UML diagram by adding a direction instruction directly following the opening @startuml tag, as follows:
@startuml
left to right direction
.
.
.
@enduml
When activated, this same sample UML diagram is rendered as follows:
UML Diagrams Caching Policy
Test-based UML diagram descriptions maintained within local repository files are converted to SVG images at runtime. This means whether you are developing or sharing a slide deck there can be a small rendering overhead due to the time taken to convert the text-based description to an image.
To ensure this processing overhead does not unduly interfere with smooth development workflows, in particular within GitPitch Desktop, each generated SVG image is cached for up to 60 seconds.
This means if you make changes to any UML description file you may not see those changes reflected on your slides for up to 60 seconds.
Advanced Graphviz/DOT Language Support
PlantUML uses Graphviz/DOT under the hood. Leveraging this support directly, GitPitch presentation authors can generate sophisticated graphs. Thanks to a kind contribution from a member of the GitPitch community we have the following sample diagrams to share that demonstrate some of these advanced features.
Sample Diagram
This sample diagram was generated using the following PUML/Dot syntax:
@startdot
digraph foo {
node [style=rounded, width=1, margin="0,0"];
Supervisory [shape=house, width=1];
Workstation [label="Engineering/\nTechnician\nWorkstation", style=dotted, color=red, fontcolor=red];
Controller [fillcolor=yellow, style="rounded,filled", shape=diamond, height=1];
Actuators [shape=box];
cl [label="Control\nLoop", shape=none, fontcolor=forestgreen, style=bold, fontsize=18];
Sensors [shape=box];
Process [shape=doublecircle, width=1];
{rank=same; Supervisory; Workstation};
Supervisory:s -> Controller:n [dir=both, weight=9];
Controller -> cl -> Process [weight=9, style=invis];
Controller -> Actuators:n [taillabel="output", labeldistance=3];
{rank=same; Actuators; cl; Sensors};
Actuators:s -> Process [headlabel="changes", labeldistance=3, labelangle=35];
Process -> Sensors:s [weight=5, taillabel="measures", labeldistance=3.2, labelangle=-35];
Sensors:n -> Controller [weight=5, headlabel="input", labeldistance=3, labelangle=25];
Supervisory -> Workstation [dir=back, style=dotted, minlen=5, color=red];
Controller -> Workstation [dir=back, style=dotted, color=red];
Actuators:nw -> Workstation [weight=0, dir=back, style=dotted, color=red];
cl -> Workstation [weight=2, style=invis];
Sensors:ne -> Workstation [weight=3, dir=back, style=dotted, color=red];
}
@enddot
Sample Diagram
This sample diagram was generated using the following PUML/Dot syntax:
@startuml
digraph G {
node [shape=record, fillcolor=lightgrey, style="filled,rounded"]
capture [label="Traffic Capture"]
capture -> analyze
subgraph cluster0 {
label = "Same as\nNetwork Capture Assessment"
labeljust = left
style = "filled,rounded"
color = deepskyblue
analyze [label="Endpoint and Flow Analysis"]
analyze:0 -> known:n
analyze:1 -> unknown:n
known [label="Known Protocol Analysis"]
unknown [label="Unknown Protocol Decode"]
}
known:s -> enum:0
unknown:s -> enum:1
enum [label="Protocol Enumeration"]
enum -> fuzz
fuzz [label="Protocol Fuzzing"]
fuzz -> exploit
exploit [label="Protocol Exploitation"]
}
@enduml
Sample Diagram
This sample diagram was generated using the following PUML/Dot syntax:
@startuml
digraph structs {
node [shape=record];
write [label="\> | <0>0xA0 | <1>0x00 | <2>0xBE | <3>0xEF | <4>...", fillcolor=lightgrey, style=filled];
write:0 -> command:4;
command [label="<0>1|<1>0|<2>1|<3>0|<4>0|<5>0|<6>0|<7>0", fillcolor=whitesmoke, style=filled];
command:0 -> chip:0;
command:1 -> chip:1;
command:2 -> chip:2;
command:3 -> chip:3;
chip [label="Chip\nAddress"];
command:4 -> memblock:0;
command:5 -> memblock:1;
command:6 -> memblock:2;
memblock [label="{Memory Blocks | 000 = Block 0\n001 = Block 1\n010 = Block 2\n011 = Block 3\n100 = Block 4\n101 = Block 5\n110 = Block 6\n111 = Block 7}"];
command:7 -> rw;
rw [label="Write = 0\nRead = 1"];
write:1 -> address;
address [label="Memory\nLocation"];
write:2 -> data:0;
write:3 -> data:1;
write:4 -> data:2;
data [label="Bytes to Write\n(max of write buffer)\n(none to move pointer)"];
}
@enduml
Sample Diagram
This sample diagram was generated using the following PUML/Dot syntax:
@startuml
skinparam monochrome true
skinparam shadowing false
skinparam sequenceArrowThickness 2
skinparam roundcorner 10
skinparam sequenceReferenceAlign center
participant "ModbusTCP Client" as TcpClient
participant "ModbusTCP Server" as TcpServer
participant "vs"
participant "ModbusTCP Client" as UdpClient
participant "ModbusTCP Server" as UdpServer
group ModbusTCP Connection Establishment
TcpClient o-> TcpServer: TCP SYN (Synchronize)
TcpServer -> TcpClient: TCP SYN ACK (Acknowledge)
TcpClient -> TcpServer: TCP ACK
end
group ModbusTCP vs ModbusUDP Payload
TcpClient -> TcpServer : ModbusTCP Request
TcpClient <- TcpServer : TCP ACK
UdpClient -> UdpServer : ModbusUDP Request
TcpServer -> TcpClient : ModbusTCP Response
TcpServer <- TcpClient : TCP ACK
UdpClient <- UdpServer : ModubsUDP Response
end
group ModbusTCP Connection Teardown
TcpClient -> TcpServer: TCP FIN (Finalize)
TcpClient <- TcpServer: TCP FIN or FIN ACK
TcpClient <-- TcpServer: TCP ACK
TcpClient ->x TcpServer: TCP ACK
End
@enduml