Skip to content

Commit

Permalink
plantUml: Explain how to use SD reference frames
Browse files Browse the repository at this point in the history
Based on #62

author: @mfjkri
  • Loading branch information
damithc committed Sep 8, 2024
1 parent 6dcbb98 commit d6721a9
Show file tree
Hide file tree
Showing 4 changed files with 150 additions and 0 deletions.
24 changes: 24 additions & 0 deletions tutorials/images/plantuml/OriginalSequenceDiagram.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
@startuml

hide footbox
skinparam sequenceReferenceBackgroundColor #f7807c

actor Player

participant ":TextUi" as TextUi #EE82EE
participant ":MSLogic" as MSLogic #90EE90

Player -> TextUi : mark x y
TextUi -> MSLogic : markCellAt(x, y)
return

'This sequence can be abstracted into a reference frame for simplicity
TextUi -> MSLogic : getAppearanceOfCellAt(x, y)
MSLogic -> TextUi : getConfig()
TextUi --> MSLogic : config
MSLogic --> TextUi : cellAppearance
'---

TextUi --> Player : Show updated minefield

@enduml
21 changes: 21 additions & 0 deletions tutorials/images/plantuml/ParentReferenceFrameDiagram.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
@startuml

hide footbox
skinparam sequenceReferenceBackgroundColor #f7807c

actor Player

participant ":TextUi" as TextUi #EE82EE
participant ":MSLogic" as MSLogic #90EE90

Player -> TextUi : mark x y
TextUi -> MSLogic : markCellAt(x, y)
return

ref over TextUi, MSLogic
get minefield appearance
end ref

TextUi --> Player : Show updated minefield

@enduml
16 changes: 16 additions & 0 deletions tutorials/images/plantuml/ReferenceFrameDiagram.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
@startuml

hide footbox

participant ":TextUi" as TextUi #EE82EE
participant ":MSLogic" as MSLogic #90EE90

group sd get minefield appearance
'Contents of reference frame
TextUi -> MSLogic : getAppearanceOfCellAt(x, y)
MSLogic -> TextUi : getConfig()
TextUi --> MSLogic : config
MSLogic --> TextUi : cellAppearance
end

@enduml
89 changes: 89 additions & 0 deletions tutorials/plantUml.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,3 +278,92 @@ package "Rule Of Thumb";{

Explicitly define all symbols to avoid any potential layout mishaps.
</box>

### Using reference frames

Reference frames in PlantUML sequence diagrams allow you to **group and reuse sequences** of interactions, which helps improve readability and reduce repetition in complex scenarios. By encapsulating sequences into reference frames, you can also **reduce complexity**, making it easier to manage and understand the overall flow of interactions within your diagrams.

Refer to the following example:
```
@startuml
hide footbox
skinparam sequenceReferenceBackgroundColor #f7807c
actor Player
participant ":TextUi" as TextUi #EE82EE
participant ":MSLogic" as MSLogic #90EE90
Player -> TextUi : mark x y
TextUi -> MSLogic : markCellAt(x, y)
return
TextUi -> MSLogic : getAppearanceOfCellAt(x, y)
MSLogic -> TextUi : getConfig()
TextUi --> MSLogic : config
MSLogic --> TextUi : cellAppearance
TextUi --> Player : Show updated minefield
@enduml
```
<puml src="images/plantuml/OriginalSequenceDiagram.puml" width=500 />

The sequence diagram illustrates two main actions: marking a cell and retrieving its appearance. We can simplify the diagram by moving the latter into a new reference frame.

First we update the original diagram as follows:

```{highlight-lines="15-17"}
@startuml
hide footbox
skinparam sequenceReferenceBackgroundColor #f7807c
actor Player
participant ":TextUi" as TextUi #EE82EE
participant ":MSLogic" as MSLogic #90EE90
Player -> TextUi : mark x y
TextUi -> MSLogic : markCellAt(x, y)
return
ref over TextUi, MSLogic
get minefield appearance
end ref
TextUi --> Player : Show updated minefield
@enduml
```

<puml src="images/plantuml/ParentReferenceFrameDiagram.puml" width=300 />

Then, we create a new diagram for the reference frame.

```
@startuml
hide footbox
participant ":TextUi" as TextUi #EE82EE
participant ":MSLogic" as MSLogic #90EE90
group sd get minefield appearance
TextUi -> MSLogic : getAppearanceOfCellAt(x, y)
MSLogic -> TextUi : getConfig()
TextUi --> MSLogic : config
MSLogic --> TextUi : cellAppearance
end
@enduml
```
<puml src="images/plantuml/ReferenceFrameDiagram.puml" width=300 />


--------------------------------------------------------------------------------
**Authors:**
* Initial Version: Jeffry Lum
* Contributors:
* MUHAMMAD FIKRI BIN ABDUL KALAM (@mfjkri): added the part on SD reference frames

0 comments on commit d6721a9

Please sign in to comment.