Sequence Diagram
+ ++ define Complex System as sys + define User as usr + define Sequence Diagram as diagram + define Other Users as usr2 + begin sys, usr, usr2 + sys ~> usr + note over usr: "Take time to\nunderstand System" + usr -> *diagram: Create + usr -> usr2: Inform + usr2 <-> diagram: Learn & understand + usr2 -> sys: Use + terminators box ++
Introduction
+ ++Want to draw a Sequence Diagram? +Go to the online editor. +
++This library renders sequence diagrams from code. It is +open-source +(LGPL-3.0), and including it in a website is as simple as adding the script:
+ ++<script src="lib/sequence-diagram.min.js"></script> ++ +
+Any element with the class sequence-diagram will automatically be
+converted when the page loads:
+
+ A -> B: foo + B -> A: bar ++
+<pre class="sequence-diagram"> + A -> B: foo + B -> A: bar +</pre> ++ +
Language
+ +Connection Types
++title Connection Types + +begin Foo, Bar, Baz + +Foo -> Bar: Simple arrow +Bar --> Baz: Dashed arrow +Foo <- Bar: Reversed arrow +Bar <-- Baz: Reversed & dashed +Foo <-> Bar: Double arrow +Bar <--> Baz: Double dashed arrow + +# An arrow with no label: +Foo -> Bar + +Bar ->> Baz: Different arrow +Foo <<--> Bar: Mix of arrows + +Bar -> Bar: Bar talks to itself + +Foo -> +Bar: Foo asks Bar +-Bar --> Foo: and Bar replies + +# Arrows leaving on the left and right of the diagram +[ -> Foo: From the left +[ <- Foo: To the left +Foo -> ]: To the right +Foo <- ]: From the right +[ ~> ]: Wavy left to right! +# (etc.) ++ +
Notes & State
++title Note Placements + +note over Foo: Foo says something +note left of Foo: Stuff +note right of Bar: More stuff +note over Foo, Bar: "Foo and Bar +on multiple lines" +note between Foo, Bar: Link + +text right: 'Comments\nOver here!' + +state over Foo: Foo is ponderous ++ +
Logic
++title At the Bank + +begin Person, ATM, Bank +Person -> ATM: Request money +ATM -> Bank: Check funds +if fraud detected + Bank -> Police: "Get 'em!" + Police -> Person: "You're nicked" + end Police +else if sufficient funds + ATM -> Bank: Withdraw funds + repeat until "all requested money + has been handed over" + ATM -> Person: Dispense note + end +else + ATM -> Person: Error +end ++ +
Label Templates
++autolabel "[<inc>] <label>" + +begin "Underpants\nGnomes" as A +A <- ]: Collect underpants +A <-> ]: ??? +A <- ]: Profit! ++ +
Multiline Text
++title 'My Multiline +Title' + +note over Foo: 'Also possible\nwith escapes' + +Foo -> Bar: 'Lines of text\non this arrow' + +if 'Even multiline\ninside conditions like this' + Foo -> 'Multiline\nagent' +end + +state over Foo: 'Newlines here, +too!' ++ +
Short-Lived Agents
++title "Baz doesn't live long" + +note over Foo, Bar: Using begin / end + +begin Baz +Bar -> Baz +Baz -> Foo +end Baz + +note over Foo, Bar: Using * / ! + +# * and ! cause agents to be created and destroyed inline +Bar -> *Baz: make Baz +Foo <- !Baz: end Baz + +# Foo and Bar end with black bars +terminators bar +# (options are: box, bar, cross, fade, none) ++ +
Agent Aliases
++define My complicated agent name as A +define "Another agent name, +and this one's multi-line!" as B + +A -> B: this is much easier +A <- B: than writing the whole name ++ +
Alternative Agent Ordering
++define Baz, Foo + +Foo -> Bar +Bar -> Baz ++ +
More
+ ++More features are supported. See the +online editor's library and +autocomplete features to discover them. +
+ +Browser Support
+ ++This has been tested in the latest versions of Google Chrome, Mozilla Firefox, +and Apple Safari. Versions of Microsoft Internet Explorer / Edge have not been +tested and probably won't work. Any bugs found in a supported browser should be +reported in the +Issue Tracker. +
+ +API
+ ++For more advanced usage, an API is available: +
+ + + +
+var diagram = new SequenceDiagram();
+diagram.set('A -> B\nB -> A');
+document.body.appendChild(diagram.dom());
+diagram.setHighlight(1); // Highlight elements created in line 1 (0-based)
+
+
+Constructor
+ ++diagram = new SequenceDiagram(code, options); +diagram = new SequenceDiagram(code); +diagram = new SequenceDiagram(options); +diagram = new SequenceDiagram(); ++ +
+Creates a new SequenceDiagram object. Options is an object which can contain: +
+-
+
code: Alternative way of specifying code, instead of using a separate argument.
+container: DOM node to append the diagram to (defaults to null).
+themes: List of themes to make available to the diagram (defaults to globally registered themes).
+namespace: Each diagram on a page must have a unique namespace. By default a unique namespace is generated, but if you want something specific, enter it here.
+
.clone
+ ++newDiagram = diagram.clone(options); +newDiagram = diagram.clone(); ++ +
+Creates a copy of the diagram. If options are given, they will override the +current diagram's state (options is passed to the constructor of the new object, +so all the same options are available). +
+ +.set
+ ++diagram.set(code); ++ +
+Changes the code for the diagram and causes a re-render. +
+ +.process
+ ++processed = diagram.process(code); ++ +
+Processes the given code but does not render it. Causes no change to the
+diagram object. This is mostly useful for debounced rendering with immediate
+error notifications. The resulting object can be passed to
+render at a later point.
+
.render
+ ++diagram.render(); +diagram.render(processed); ++ +
+Forces a re-render of the diagram. Typically this happens automatically.
+Optionally, the result of an earlier call to
+process can be provided.
+
.setHighlight
+ ++diagram.setHighlight(line); +diagram.setHighlight(); ++ +
+Marks elements generated by the specified line with a "focus" CSS class, which
+can be used to style them. Only one line can be highlighted at a time. Calling
+with no parameter (or null) will remove the highlighting.
+
.addTheme
+ ++diagram.addTheme(theme); ++ +
+Make a new theme available to the diagram. Any unrecognised themes are replaced +with the default theme. +
++The theme API has not been finalised yet, so this method is not typically +useful. +
+ +.getThemeNames
+ ++names = diagram.getThemeNames(); ++ +
+Returns a list of names of themes which are available to this diagram. These
+can be specified in a theme <name> line in the code.
+
.getThemes
+ ++themes = diagram.getThemes(); ++ +
+Returns a list of themes which are available to this diagram. +
+ +.getSVGSynchronous
+ ++svgURL = diagram.getSVGSynchronous(); ++ +
+Returns a blob URL which contains the SVG code for the current diagram. +
+ +.getSVG
+ +
+diagram.getSVG().then(({url, latest}) => { ... });
+
+
+
+Asynchronous version of
+getSVGSynchronous. This is
+provided for compatibility with getPNG,
+which has no synchronous equivalent.
+
The callback recieves an object containing:
+-
+
url: The URL of the generated blob.
+latest: True if the URL given is still valid; subsequent calls to this method will invalidate previous URLs.
+
.getPNG
+ +
+diagram.getPNG(options).then(({url, latest}) => { ... });
+
+
++Generates a PNG image and returns a blob URL. +
+The options can include:
+-
+
resolution: Desired pixels-per-unit.
+size: Optional width and/or height to render the image at (defaults to the unit size of the diagram). The final output will have sizewidth * resolution×height * resolution.
+
The callback recieves an object containing:
+-
+
url: The URL of the generated blob.
+latest: True if the URL given is still valid; subsequent calls to this method will invalidate previous URLs.
+
.getSize
+ ++size = diagram.getSize(); ++ +
+Returns an object containing width and height
+properties, corresponding to the size of the diagram in units.
+
.setContainer
+ ++diagram.setContainer(node); ++ +
+Same as calling node.appendChild(diagram.dom()).
+
.dom
+ ++node = diagram.dom(); ++ +
+Returns the base SVG element which the diagram has been rendered into. +
+ +Thanks
+ ++Thanks to +websequencediagrams.com +and +js-sequence-diagrams +for inspiring the syntax of this project. +
+ ++ begin User, SequenceDiagram as SD, Parser, Generator, Renderer + + User -> +SD: code + + SD -> +Parser: code + -Parser --> SD: parsed + + SD -> +Generator: parsed + -Generator --> SD: generated + + -SD -> +Renderer: generated + -Renderer -> *DOM: SVG + User <~> DOM: interaction + + terminators box ++ + + +