| 6dd74de | | | 1 | # @mermaid-js/mermaid-zenuml |
| 6dd74de | | | 2 | |
| 6dd74de | | | 3 | MermaidJS plugin for ZenUML integration - A powerful sequence diagram rendering engine. |
| 6dd74de | | | 4 | |
| 6dd74de | | | 5 | > A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order. |
| 6dd74de | | | 6 | |
| 6dd74de | | | 7 | Mermaid can render sequence diagrams with [ZenUML](https://zenuml.com). Note that ZenUML uses a different |
| 6dd74de | | | 8 | syntax than the original Sequence Diagram in mermaid. |
| 6dd74de | | | 9 | |
| 6dd74de | | | 10 | ```mermaid |
| 6dd74de | | | 11 | zenuml |
| 6dd74de | | | 12 | BookLibService.Borrow(id) { |
| 6dd74de | | | 13 | User = Session.GetUser() |
| 6dd74de | | | 14 | if(User.isActive) { |
| 6dd74de | | | 15 | try { |
| 6dd74de | | | 16 | BookRepository.Update(id, onLoan, User) |
| 6dd74de | | | 17 | receipt = new Receipt(id, dueDate) |
| 6dd74de | | | 18 | } catch (BookNotFoundException) { |
| 6dd74de | | | 19 | ErrorService.onException(BookNotFoundException) |
| 6dd74de | | | 20 | } finally { |
| 6dd74de | | | 21 | Connection.close() |
| 6dd74de | | | 22 | } |
| 6dd74de | | | 23 | } |
| 6dd74de | | | 24 | return receipt |
| 6dd74de | | | 25 | } |
| 6dd74de | | | 26 | ``` |
| 6dd74de | | | 27 | |
| 6dd74de | | | 28 | ## Installation |
| 6dd74de | | | 29 | |
| 6dd74de | | | 30 | ### With bundlers |
| 6dd74de | | | 31 | |
| 6dd74de | | | 32 | ```sh |
| 6dd74de | | | 33 | npm install @mermaid-js/mermaid-zenuml |
| 6dd74de | | | 34 | ``` |
| 6dd74de | | | 35 | |
| 6dd74de | | | 36 | ```ts |
| 6dd74de | | | 37 | import mermaid from 'mermaid'; |
| 6dd74de | | | 38 | import zenuml from '@mermaid-js/mermaid-zenuml'; |
| 6dd74de | | | 39 | |
| 6dd74de | | | 40 | await mermaid.registerExternalDiagrams([zenuml]); |
| 6dd74de | | | 41 | ``` |
| 6dd74de | | | 42 | |
| 6dd74de | | | 43 | ### With CDN |
| 6dd74de | | | 44 | |
| 6dd74de | | | 45 | ```html |
| 6dd74de | | | 46 | <script type="module"> |
| 6dd74de | | | 47 | import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; |
| 6dd74de | | | 48 | import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/mermaid-zenuml@0.2.0/dist/mermaid-zenuml.core.mjs'; |
| 6dd74de | | | 49 | await mermaid.registerExternalDiagrams([zenuml]); |
| 6dd74de | | | 50 | </script> |
| 6dd74de | | | 51 | ``` |
| 6dd74de | | | 52 | |
| 6dd74de | | | 53 | > [!NOTE] |
| 6dd74de | | | 54 | > ZenUML uses experimental lazy loading & async rendering features which could change in the future. |
| 6dd74de | | | 55 | |
| 6dd74de | | | 56 | ## Basic Usage |
| 6dd74de | | | 57 | |
| 6dd74de | | | 58 | Once the plugin is registered, you can create ZenUML diagrams using the `zenuml` syntax: |
| 6dd74de | | | 59 | |
| 6dd74de | | | 60 | ```mermaid |
| 6dd74de | | | 61 | zenuml |
| 6dd74de | | | 62 | Controller.Get(id) { |
| 6dd74de | | | 63 | Service.Get(id) { |
| 6dd74de | | | 64 | item = Repository.Get(id) |
| 6dd74de | | | 65 | if(item) { |
| 6dd74de | | | 66 | return item |
| 6dd74de | | | 67 | } else { |
| 6dd74de | | | 68 | return null |
| 6dd74de | | | 69 | } |
| 6dd74de | | | 70 | } |
| 6dd74de | | | 71 | return result |
| 6dd74de | | | 72 | } |
| 6dd74de | | | 73 | ``` |
| 6dd74de | | | 74 | |
| 6dd74de | | | 75 | ## ZenUML Syntax Reference |
| 6dd74de | | | 76 | |
| 6dd74de | | | 77 | ### Participants |
| 6dd74de | | | 78 | |
| 6dd74de | | | 79 | The participants can be defined implicitly as in the first example on this page. The participants or actors are |
| 6dd74de | | | 80 | rendered in order of appearance in the diagram source text. Sometimes you might want to show the participants in a |
| 6dd74de | | | 81 | different order than how they appear in the first message. It is possible to specify the actor's order of |
| 6dd74de | | | 82 | appearance by doing the following: |
| 6dd74de | | | 83 | |
| 6dd74de | | | 84 | ```mermaid |
| 6dd74de | | | 85 | zenuml |
| 6dd74de | | | 86 | title Declare participant (optional) |
| 6dd74de | | | 87 | Bob |
| 6dd74de | | | 88 | Alice |
| 6dd74de | | | 89 | Alice->Bob: Hi Bob |
| 6dd74de | | | 90 | Bob->Alice: Hi Alice |
| 6dd74de | | | 91 | ``` |
| 6dd74de | | | 92 | |
| 6dd74de | | | 93 | ### Annotators |
| 6dd74de | | | 94 | |
| 6dd74de | | | 95 | If you specifically want to use symbols instead of just rectangles with text you can do so by using the annotator syntax to declare participants as per below. |
| 6dd74de | | | 96 | |
| 6dd74de | | | 97 | ```mermaid |
| 6dd74de | | | 98 | zenuml |
| 6dd74de | | | 99 | title Annotators |
| 6dd74de | | | 100 | @Actor Alice |
| 6dd74de | | | 101 | @Database Bob |
| 6dd74de | | | 102 | Alice->Bob: Hi Bob |
| 6dd74de | | | 103 | Bob->Alice: Hi Alice |
| 6dd74de | | | 104 | ``` |
| 6dd74de | | | 105 | |
| 6dd74de | | | 106 | Available annotators include: |
| 6dd74de | | | 107 | |
| 6dd74de | | | 108 | - `@Actor` - Human figure |
| 6dd74de | | | 109 | - `@Database` - Database symbol |
| 6dd74de | | | 110 | - `@Boundary` - Boundary symbol |
| 6dd74de | | | 111 | - `@Control` - Control symbol |
| 6dd74de | | | 112 | - `@Entity` - Entity symbol |
| 6dd74de | | | 113 | - `@Queue` - Queue symbol |
| 6dd74de | | | 114 | |
| 6dd74de | | | 115 | ### Aliases |
| 6dd74de | | | 116 | |
| 6dd74de | | | 117 | The participants can have a convenient identifier and a descriptive label. |
| 6dd74de | | | 118 | |
| 6dd74de | | | 119 | ```mermaid |
| 6dd74de | | | 120 | zenuml |
| 6dd74de | | | 121 | title Aliases |
| 6dd74de | | | 122 | A as Alice |
| 6dd74de | | | 123 | J as John |
| 6dd74de | | | 124 | A->J: Hello John, how are you? |
| 6dd74de | | | 125 | J->A: Great! |
| 6dd74de | | | 126 | ``` |
| 6dd74de | | | 127 | |
| 6dd74de | | | 128 | ## Messages |
| 6dd74de | | | 129 | |
| 6dd74de | | | 130 | Messages can be one of: |
| 6dd74de | | | 131 | |
| 6dd74de | | | 132 | 1. Sync message |
| 6dd74de | | | 133 | 2. Async message |
| 6dd74de | | | 134 | 3. Creation message |
| 6dd74de | | | 135 | 4. Reply message |
| 6dd74de | | | 136 | |
| 6dd74de | | | 137 | ### Sync message |
| 6dd74de | | | 138 | |
| 6dd74de | | | 139 | You can think of a sync (blocking) method in a programming language. |
| 6dd74de | | | 140 | |
| 6dd74de | | | 141 | ```mermaid |
| 6dd74de | | | 142 | zenuml |
| 6dd74de | | | 143 | title Sync message |
| 6dd74de | | | 144 | A.SyncMessage |
| 6dd74de | | | 145 | A.SyncMessage(with, parameters) { |
| 6dd74de | | | 146 | B.nestedSyncMessage() |
| 6dd74de | | | 147 | } |
| 6dd74de | | | 148 | ``` |
| 6dd74de | | | 149 | |
| 6dd74de | | | 150 | ### Async message |
| 6dd74de | | | 151 | |
| 6dd74de | | | 152 | You can think of an async (non-blocking) method in a programming language. Fire an event and forget about it. |
| 6dd74de | | | 153 | |
| 6dd74de | | | 154 | ```mermaid |
| 6dd74de | | | 155 | zenuml |
| 6dd74de | | | 156 | title Async message |
| 6dd74de | | | 157 | Alice->Bob: How are you? |
| 6dd74de | | | 158 | ``` |
| 6dd74de | | | 159 | |
| 6dd74de | | | 160 | ### Creation message |
| 6dd74de | | | 161 | |
| 6dd74de | | | 162 | We use `new` keyword to create an object. |
| 6dd74de | | | 163 | |
| 6dd74de | | | 164 | ```mermaid |
| 6dd74de | | | 165 | zenuml |
| 6dd74de | | | 166 | new A1 |
| 6dd74de | | | 167 | new A2(with, parameters) |
| 6dd74de | | | 168 | ``` |
| 6dd74de | | | 169 | |
| 6dd74de | | | 170 | ### Reply message |
| 6dd74de | | | 171 | |
| 6dd74de | | | 172 | There are three ways to express a reply message: |
| 6dd74de | | | 173 | |
| 6dd74de | | | 174 | ```mermaid |
| 6dd74de | | | 175 | zenuml |
| 6dd74de | | | 176 | // 1. assign a variable from a sync message. |
| 6dd74de | | | 177 | a = A.SyncMessage() |
| 6dd74de | | | 178 | |
| 6dd74de | | | 179 | // 1.1. optionally give the variable a type |
| 6dd74de | | | 180 | SomeType a = A.SyncMessage() |
| 6dd74de | | | 181 | |
| 6dd74de | | | 182 | // 2. use return keyword |
| 6dd74de | | | 183 | A.SyncMessage() { |
| 6dd74de | | | 184 | return result |
| 6dd74de | | | 185 | } |
| 6dd74de | | | 186 | |
| 6dd74de | | | 187 | // 3. use @return or @reply annotator on an async message |
| 6dd74de | | | 188 | @return |
| 6dd74de | | | 189 | A->B: result |
| 6dd74de | | | 190 | ``` |
| 6dd74de | | | 191 | |
| 6dd74de | | | 192 | The third way `@return` is rarely used, but it is useful when you want to return to one level up. |
| 6dd74de | | | 193 | |
| 6dd74de | | | 194 | ```mermaid |
| 6dd74de | | | 195 | zenuml |
| 6dd74de | | | 196 | title Reply message |
| 6dd74de | | | 197 | Client->A.method() { |
| 6dd74de | | | 198 | B.method() { |
| 6dd74de | | | 199 | if(condition) { |
| 6dd74de | | | 200 | return x1 |
| 6dd74de | | | 201 | // return early |
| 6dd74de | | | 202 | @return |
| 6dd74de | | | 203 | A->Client: x11 |
| 6dd74de | | | 204 | } |
| 6dd74de | | | 205 | } |
| 6dd74de | | | 206 | return x2 |
| 6dd74de | | | 207 | } |
| 6dd74de | | | 208 | ``` |
| 6dd74de | | | 209 | |
| 6dd74de | | | 210 | ## Advanced Features |
| 6dd74de | | | 211 | |
| 6dd74de | | | 212 | ### Nesting |
| 6dd74de | | | 213 | |
| 6dd74de | | | 214 | Sync messages and Creation messages are naturally nestable with `{}`. |
| 6dd74de | | | 215 | |
| 6dd74de | | | 216 | ```mermaid |
| 6dd74de | | | 217 | zenuml |
| 6dd74de | | | 218 | A.method() { |
| 6dd74de | | | 219 | B.nested_sync_method() |
| 6dd74de | | | 220 | B->C: nested async message |
| 6dd74de | | | 221 | } |
| 6dd74de | | | 222 | ``` |
| 6dd74de | | | 223 | |
| 6dd74de | | | 224 | ### Comments |
| 6dd74de | | | 225 | |
| 6dd74de | | | 226 | It is possible to add comments to a sequence diagram with `// comment` syntax. |
| 6dd74de | | | 227 | Comments will be rendered above the messages or fragments. Comments on other places |
| 6dd74de | | | 228 | are ignored. Markdown is supported. |
| 6dd74de | | | 229 | |
| 6dd74de | | | 230 | ```mermaid |
| 6dd74de | | | 231 | zenuml |
| 6dd74de | | | 232 | // a comment on a participant will not be rendered |
| 6dd74de | | | 233 | BookService |
| 6dd74de | | | 234 | // a comment on a message. |
| 6dd74de | | | 235 | // **Markdown** is supported. |
| 6dd74de | | | 236 | BookService.getBook() |
| 6dd74de | | | 237 | ``` |
| 6dd74de | | | 238 | |
| 6dd74de | | | 239 | ### Loops |
| 6dd74de | | | 240 | |
| 6dd74de | | | 241 | It is possible to express loops in a ZenUML diagram. This is done by any of the |
| 6dd74de | | | 242 | following notations: |
| 6dd74de | | | 243 | |
| 6dd74de | | | 244 | 1. while |
| 6dd74de | | | 245 | 2. for |
| 6dd74de | | | 246 | 3. forEach, foreach |
| 6dd74de | | | 247 | 4. loop |
| 6dd74de | | | 248 | |
| 6dd74de | | | 249 | ```zenuml |
| 6dd74de | | | 250 | while(condition) { |
| 6dd74de | | | 251 | ...statements... |
| 6dd74de | | | 252 | } |
| 6dd74de | | | 253 | ``` |
| 6dd74de | | | 254 | |
| 6dd74de | | | 255 | Example: |
| 6dd74de | | | 256 | |
| 6dd74de | | | 257 | ```mermaid |
| 6dd74de | | | 258 | zenuml |
| 6dd74de | | | 259 | Alice->John: Hello John, how are you? |
| 6dd74de | | | 260 | while(true) { |
| 6dd74de | | | 261 | John->Alice: Great! |
| 6dd74de | | | 262 | } |
| 6dd74de | | | 263 | ``` |
| 6dd74de | | | 264 | |
| 6dd74de | | | 265 | ### Alt (Alternative paths) |
| 6dd74de | | | 266 | |
| 6dd74de | | | 267 | It is possible to express alternative paths in a sequence diagram. This is done by the notation |
| 6dd74de | | | 268 | |
| 6dd74de | | | 269 | ```zenuml |
| 6dd74de | | | 270 | if(condition1) { |
| 6dd74de | | | 271 | ...statements... |
| 6dd74de | | | 272 | } else if(condition2) { |
| 6dd74de | | | 273 | ...statements... |
| 6dd74de | | | 274 | } else { |
| 6dd74de | | | 275 | ...statements... |
| 6dd74de | | | 276 | } |
| 6dd74de | | | 277 | ``` |
| 6dd74de | | | 278 | |
| 6dd74de | | | 279 | Example: |
| 6dd74de | | | 280 | |
| 6dd74de | | | 281 | ```mermaid |
| 6dd74de | | | 282 | zenuml |
| 6dd74de | | | 283 | Alice->Bob: Hello Bob, how are you? |
| 6dd74de | | | 284 | if(is_sick) { |
| 6dd74de | | | 285 | Bob->Alice: Not so good :( |
| 6dd74de | | | 286 | } else { |
| 6dd74de | | | 287 | Bob->Alice: Feeling fresh like a daisy |
| 6dd74de | | | 288 | } |
| 6dd74de | | | 289 | ``` |
| 6dd74de | | | 290 | |
| 6dd74de | | | 291 | ### Opt (Optional) |
| 6dd74de | | | 292 | |
| 6dd74de | | | 293 | It is possible to render an `opt` fragment. This is done by the notation |
| 6dd74de | | | 294 | |
| 6dd74de | | | 295 | ```zenuml |
| 6dd74de | | | 296 | opt { |
| 6dd74de | | | 297 | ...statements... |
| 6dd74de | | | 298 | } |
| 6dd74de | | | 299 | ``` |
| 6dd74de | | | 300 | |
| 6dd74de | | | 301 | Example: |
| 6dd74de | | | 302 | |
| 6dd74de | | | 303 | ```mermaid |
| 6dd74de | | | 304 | zenuml |
| 6dd74de | | | 305 | Alice->Bob: Hello Bob, how are you? |
| 6dd74de | | | 306 | Bob->Alice: Not so good :( |
| 6dd74de | | | 307 | opt { |
| 6dd74de | | | 308 | Bob->Alice: Thanks for asking |
| 6dd74de | | | 309 | } |
| 6dd74de | | | 310 | ``` |
| 6dd74de | | | 311 | |
| 6dd74de | | | 312 | ### Parallel |
| 6dd74de | | | 313 | |
| 6dd74de | | | 314 | It is possible to show actions that are happening in parallel. |
| 6dd74de | | | 315 | |
| 6dd74de | | | 316 | This is done by the notation |
| 6dd74de | | | 317 | |
| 6dd74de | | | 318 | ```zenuml |
| 6dd74de | | | 319 | par { |
| 6dd74de | | | 320 | statement1 |
| 6dd74de | | | 321 | statement2 |
| 6dd74de | | | 322 | statement3 |
| 6dd74de | | | 323 | } |
| 6dd74de | | | 324 | ``` |
| 6dd74de | | | 325 | |
| 6dd74de | | | 326 | Example: |
| 6dd74de | | | 327 | |
| 6dd74de | | | 328 | ```mermaid |
| 6dd74de | | | 329 | zenuml |
| 6dd74de | | | 330 | par { |
| 6dd74de | | | 331 | Alice->Bob: Hello guys! |
| 6dd74de | | | 332 | Alice->John: Hello guys! |
| 6dd74de | | | 333 | } |
| 6dd74de | | | 334 | ``` |
| 6dd74de | | | 335 | |
| 6dd74de | | | 336 | ### Try/Catch/Finally (Break) |
| 6dd74de | | | 337 | |
| 6dd74de | | | 338 | It is possible to indicate a stop of the sequence within the flow (usually used to model exceptions). |
| 6dd74de | | | 339 | |
| 6dd74de | | | 340 | This is done by the notation |
| 6dd74de | | | 341 | |
| 6dd74de | | | 342 | ``` |
| 6dd74de | | | 343 | try { |
| 6dd74de | | | 344 | ...statements... |
| 6dd74de | | | 345 | } catch { |
| 6dd74de | | | 346 | ...statements... |
| 6dd74de | | | 347 | } finally { |
| 6dd74de | | | 348 | ...statements... |
| 6dd74de | | | 349 | } |
| 6dd74de | | | 350 | ``` |
| 6dd74de | | | 351 | |
| 6dd74de | | | 352 | Example: |
| 6dd74de | | | 353 | |
| 6dd74de | | | 354 | ```mermaid |
| 6dd74de | | | 355 | zenuml |
| 6dd74de | | | 356 | try { |
| 6dd74de | | | 357 | Consumer->API: Book something |
| 6dd74de | | | 358 | API->BookingService: Start booking process |
| 6dd74de | | | 359 | } catch { |
| 6dd74de | | | 360 | API->Consumer: show failure |
| 6dd74de | | | 361 | } finally { |
| 6dd74de | | | 362 | API->BookingService: rollback status |
| 6dd74de | | | 363 | } |
| 6dd74de | | | 364 | ``` |
| 6dd74de | | | 365 | |
| 6dd74de | | | 366 | ## Contributing |
| 6dd74de | | | 367 | |
| 6dd74de | | | 368 | This package is part of the [Mermaid](https://github.com/mermaid-js/mermaid) project. See the main repository for contributing guidelines. |
| 6dd74de | | | 369 | |
| 6dd74de | | | 370 | ## Contributors |
| 6dd74de | | | 371 | |
| 6dd74de | | | 372 | - [Peng Xiao](https://github.com/MrCoder) |
| 6dd74de | | | 373 | - [Sidharth Vinod](https://sidharth.dev) |
| 6dd74de | | | 374 | - [Dong Cai](https://github.com/dontry) |
| 6dd74de | | | 375 | |
| 6dd74de | | | 376 | ## License |
| 6dd74de | | | 377 | |
| 6dd74de | | | 378 | MIT |
| 6dd74de | | | 379 | |
| 6dd74de | | | 380 | ## Links |
| 6dd74de | | | 381 | |
| 6dd74de | | | 382 | - [ZenUML Official Website](https://zenuml.com) |
| 6dd74de | | | 383 | - [Mermaid Documentation](https://mermaid.js.org) |
| 6dd74de | | | 384 | - [GitHub Repository](https://github.com/mermaid-js/mermaid) |