diff --git a/README.md b/README.md index ab8fddb..25ea9df 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ A tool for creating sequence diagrams from a Domain-Specific Language. -[See it in action!](https://davidje13.github.io/SequenceDiagram/editor.htm) +[See it in action!](https://davidje13.github.io/SequenceDiagram/) This project includes a web page for editing the diagrams, but the core logic is available as a component which can be -[included in other projects](https://davidje13.github.io/SequenceDiagram/). +[included in other projects](https://davidje13.github.io/SequenceDiagram/library.htm). ## Examples diff --git a/editor.htm b/editor.htm deleted file mode 100644 index 3bf8ddc..0000000 --- a/editor.htm +++ /dev/null @@ -1,77 +0,0 @@ - - - - - -Sequence Diagram - - - - - - - - - - - - - - - - - - - - - - - -
-

Sequence Diagram Online Editor

-

Loading…

-
- - - diff --git a/index.html b/index.html index de5c68c..e915672 100644 --- a/index.html +++ b/index.html @@ -4,548 +4,74 @@ -Sequence Diagram Library +Sequence Diagram - - + + + + + + - + - + - + - - - - - + -
- -
-

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>
-
- -

Or if you are using requirejs:

- -
-requirejs(['lib/sequence-diagram.min'], (SequenceDiagram) => {
-  SequenceDiagram.convertAll();
-});
-
- -

-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: -

- - -

.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 receives an object containing:

- - -

.getPNG

- -
-diagram.getPNG(options).then(({url, latest}) => { ... });
-
- -

-Generates a PNG image and returns a blob URL. -

-

The options can include:

- -

The callback receives an object containing:

- - -

.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
-
- +
+

Sequence Diagram Online Editor

+

Loading…

+
+ diff --git a/library.htm b/library.htm new file mode 100644 index 0000000..333edc9 --- /dev/null +++ b/library.htm @@ -0,0 +1,551 @@ + + + + + +Sequence Diagram Library + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+

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>
+
+ +

Or if you are using requirejs:

+ +
+requirejs(['lib/sequence-diagram.min'], (SequenceDiagram) => {
+  SequenceDiagram.convertAll();
+});
+
+ +

+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: +

+ + +

.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 receives an object containing:

+ + +

.getPNG

+ +
+diagram.getPNG(options).then(({url, latest}) => { ... });
+
+ +

+Generates a PNG image and returns a blob URL. +

+

The options can include:

+ +

The callback receives an object containing:

+ + +

.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
+
+ + + +
+ + + diff --git a/styles/home.css b/styles/library.css similarity index 100% rename from styles/home.css rename to styles/library.css