README.md
1JS Sequence Diagrams [](https://libraries.io/bower/js-sequence-diagrams) [](https://travis-ci.org/bramp/js-sequence-diagrams) 
2=============================================
3**Generates UML sequence diagrams from simple text**
4<https://bramp.github.io/js-sequence-diagrams/>
5
6by [Andrew Brampton](https://bramp.net) 2012-2017
7
8
9Example
10-------
11We turn
12
13 Alice->Bob: Hello Bob, how are you?
14 Note right of Bob: Bob thinks
15 Bob-->Alice: I am good thanks!
16
17into
18
19
20
21Requirements
22------------
23You will need [Snap.svg](http://snapsvg.io/), [Web Font Loader](https://github.com/typekit/webfontloader) (if you wish to use custom fonts), [underscore.js](http://underscorejs.org/) (or [lodash](https://lodash.com/)), and optionally [jQuery](https://jquery.com/).
24
25
26Installation
27----------------------
28
29### bower
30
31Run `bower install bramp/js-sequence-diagrams` and include the scripts below:
32
33```html
34<script src="{{ bower directory }}/bower-webfontloader/webfont.js" />
35<script src="{{ bower directory }}/snap.svg/dist/snap.svg-min.js" />
36<script src="{{ bower directory }}/underscore/underscore-min.js" />
37<script src="{{ bower directory }}/js-sequence-diagrams/dist/sequence-diagram-min.js" />
38```
39
40also import the CSS if you plan to use the hand drawn theme:
41
42```html
43<link href="{{ bower directory }}/js-sequence-diagrams/dist/sequence-diagram-min.css" rel="stylesheet" />
44```
45
46Not using bower? No problem. Just download the dependencies, and include them yourself.
47
48Usage
49-----
50
51You can use the Diagram class like:
52
53```html
54<div id="diagram">Diagram will be placed here</div>
55<script>
56 var d = Diagram.parse("A->B: Does something");
57 var options = {theme: 'simple'};
58 d.drawSVG('diagram', options);
59</script>
60```
61
62or use jQuery to do all the work:
63```html
64<script src="{{ bower directory }}/jquery/dist/jquery.min.js" />
65<div class="diagram">A->B: Message</div>
66<script>
67 var options = {theme: 'hand'};
68 $(".diagram").sequenceDiagram(options);
69</script>
70```
71
72For full examples check out [the demo site](https://bramp.github.io/js-sequence-diagrams/).
73
74Options
75-------
76
77```javascript
78var options = {
79 // Change the styling of the diagram, typically one of 'simple', 'hand'. New themes can be registered with registerTheme(...).
80 theme: string,
81
82 // CSS style to apply to the diagram's svg tag. (Only supported if using snap.svg)
83 css_class: string,
84};
85```
86
87Styling
88-------
89
90The following CSS classes are applied to the SVG diagram when using snap.svg:
91
92* `sequence`: Applies to main SVG tag.
93* `title`: Applied to the title of the diagram.
94* `actor`: Applied to the actors.
95* `signal`: Applied to the signals.
96* `note`: Applied to all notes.
97
98The diagram can then be customised, for example:
99
100```css
101.signal text {
102 fill: #000000;
103}
104.signal text:hover {
105 fill: #aaaaaa
106}
107.note rect, .note path {
108 fill: #ffff00;
109}
110.title rect, .title path,
111.actor rect, .actor path {
112 fill: #ffffff
113}
114```
115
116Raphaël Deprecation
117-------------------
118
119Version 1.x of this library used [Raphaël](http://raphaeljs.com/) for drawing the diagrams, however, Raphaël had some limitations, and since disappeared from the Internet. We've decided to move to [Snap.svg](http://snapsvg.io/), which is a pure SVG implementation, instead of Raphaël which in addition to SVG, also supported VML (on Internet Explorer). This support of VML made it impossible to use some newer SVG capabilities. Native SVG allows us to use CSS styling, better font support, animations and more.
120
121To aid in the transition Version 2.x will support both Raphaël and Snap.svg (preferring Snap.svg). If you include Raphaël instead of snap.svg, it will default to using Raphaël as the rendering library. For example
122
123```html
124<script src="{{ bower directory }}/raphael/raphael-min.js"></script>
125```
126
127There are also four transitional themes, 'snapSimple', 'snapHand', 'raphaelSimple', 'raphaelHand', which force the use of either Snap.svg, or Raphaël.
128
129The plan is to drop support for Raphaël in a future release, simplifying the library, and reducing the file size.
130
131### Adding a Font
132
133Raphael requires Cufon style fonts. Find the font you want in ttf or otf format, visit [Cufon's site](http://cufon.shoqolate.com/generate/) and process it into a javascript file. Then ensure the font is included via the HTML, or recompile after altering main.js. So far only the hand drawn font, Daniel Bold, has been included.
134
135
136Build requirements
137------------------
138The build is managed by a Makefile, and uses various tools available from npm. Thus both `make` and [npm](https://github.com/npm/npm) are required, and can easily be installed on any Linux or Mac machine.
139
140```bash
141make
142```
143
144The Makefile will use npm to install all the dev dependencies, build, and test.
145
146Testing
147-------
148
149We use [qunit](https://qunitjs.com/) for testing. It can be ran from the command line, or via a browser. The command line actually tests multiple permutations of [lodash](https://lodash.com/), [Underscore](http://underscorejs.org/), and with and without minification.
150
151```bash
152make test
153...
154Global summary:
155┌───────┬───────┬────────────┬────────┬────────┬─────────┐
156│ Files │ Tests │ Assertions │ Failed │ Passed │ Runtime │
157├───────┼───────┼────────────┼────────┼────────┼─────────┤
158│ 1 │ 13 │ 231 │ 0 │ 231 │ 250 │
159└───────┴───────┴────────────┴────────┴────────┴─────────┘
160```
161
162or `make` and then open test/qunit.html in a browser. Finally a simple playground is available at test/test.html.
163
164How to release
165--------------
166* Make sure all changes checked in
167* Bump version in src/main.js and bower.json
168* ``make clean``
169* ``make``
170* ``git add -f src/main.js bower.json dist/*``
171* ``git commit -m "Released version 2.x.x"``
172* ``git push origin master``
173* ``git tag -a v2.x.x -m v2.x.x``
174* ``git push origin v2.x.x``
175
176
177TODO
178----
179* Other themes
180* Automate the release process
181* Testing that checks the generated SVG is correct
182* Improve the hand drawn theme
183* Dozens of other issues on https://github.com/bramp/js-sequence-diagrams/issues
184
185Contributors
186------------
187
188via [GitHub](https://github.com/bramp/js-sequence-diagrams/graphs/contributors)
189
190Thanks
191------
192This project makes use of [Jison](https://zaach.github.io/jison/), snap.svg, underscore.js, and the awersome [Daniel font](http://www.dafont.com/daniel.font) (which is free to use for any purpose).
193
194Many thanks to [Web Sequence Diagrams](http://www.websequencediagrams.com/) which greatly inspired this project, and forms the basis for the syntax.
195
196Related
197-------
198
199* [Web Sequence Diagrams](http://www.websequencediagrams.com/) Server side version with a commercial offering
200* [flowchart.js](https://adrai.github.io/flowchart.js/) A similar project that draws flow charts in the browser
201
202
203Licence (Simplified BSD License)
204-------
205
206Copyright (c) 2012-2017, Andrew Brampton
207All rights reserved.
208
209Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
210
211- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
212- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
213
214THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
215
){kind=link}
){kind=link}
){kind=link}
){kind=link}
