mscgen_js embedding

turns text into sequence charts

Embedding MscGen in your html is easy:

  1. Reference the mscgen-inpage script1 in your page head:
    <script src="https://sverweij.github.io/mscgen_js/mscgen-inpage.js" defer>
    </script>
    
  2. Put your MscGen script in the page, surrounded by a a tag with mscgen_js as one of its class attributes.
    <pre class="mscgen_js">
    msc {
        a [label="consumer"], b [label="shopfront"], c;
    
        a =>> b [label="buy (commestible)"];
        b =>> c [label="lookup_price(commestible)"];
        c >> b [label="price"];
        b =>> a [label=""];
        a =>> b [label="money"];
        ...;
    }
    </pre>
    

    We've used a pre element here, but mscgen_js works with any element type.

  3. You're done. The script replaces all elements in the page with the class mscgen_js by a rendered sequence chart. Result for the above MscGen:
    msc {
        a [label="consumer"], b [label="shopfront"], c;
    
        a =>> b [label="buy (commestible)"];
        b =>> c [label="lookup_price(commestible)"];
        c >> b [label="price"];
        b =>> a [label=""];
        a =>> b [label="money"];
        ...;
    }

1) = You can find the script in three places: on github.io, github.com and on mscgen.js.org. mscgen.js.org is an alias for sverweij.github.io/mscgen_js, so when you access the script on github.io, github.io will redirect you to mscgen.js.org.

A list of alternative locations:

Embedding MscGen in Atlassian Confluence:

Add an HTML macro to the page with the script tag in there. Sample snippet:

<script src="https://mscgen.js.org/mscgen-inpage.js" defer></script>

<code class="mscgen_js">
msc {
    a [label="Entity A"], b [label="Entity B"];

    a <<=>> b [label="testing (confluence)"];
    b note b [label="MscGen embedded in a confluence page!"];
}
</code>

Pre-condition for this to work is that your Confluence admin has enabled the HTML macro functionality.

Wikimedia style tags

From version 0.9.37 mscgen_js supports wikimedia style mscgen tags, so something like this will work too:

<mscgen>
msc {
   Co, Mo, Dolores;
   Co =>> Mo
       [label="Hello"];
   Dolores =>> Co
       [label="Is it me you're looking for?"];
   Mo =>> Dolores
       [label="I see it in your eyes"];
}
</mscgen>
msc { Co, Mo, Dolores; Co =>> Mo [label="Hello"]; Dolores =>> Co [label="Is it me you're looking for?"]; Mo =>> Dolores [label="I see it in your eyes"]; }

Script tags

For those who think it is more semantically correct to use <script> tags for embedding MscGen scripts:

<script type="text/x-mscgen">
msc {
  hscale=1.2, wordwraparcs=on;

  alice [label="Alice"], bob [label="Bob"];

  alice =>> bob [label="you can embed MscGen"];
  bob >> alice [label="That is FANTASTIC!"];
}
</script>

Recognized MIME-types: text/x-mscgen, text/x-msgenny and text/x-xu.

Error handling

If your MscGen code contains an error, instead of a sequence chart, you will see your MscGen code with the offending line highlighted, thusly:

msc {
  a, b;
  a -> b[nonexistingattribute="something"];
  b >> a[label="done dee done"];
}

As you can see in the tutorial it is possible to open embedded charts in the mscgen_js interpreter by clicking on them. By default this behavior is switched off.

Loading charts from separate files

If you want to maintain your sequence chart sources separate from your html, you can. By default this is off.

Mirror entities on the bottom

In some situations you might want to duplicate the row of entities on the bottom of the chart - e.g. when your chart is very big. Or just because you fancy it. Anyway, the data-mirror-entities attribute enables this.

<script data-mirror-entities='true' type="text/x-mscgen">
msc {
    wordwraparcs=on;

    a,b,c;

    a =>> b [label="We're mirrorred on the bottom"];
    b =>> c [label="Did ya hear that?"],
    b >> a  [label="Really?"];
}
</script>
        

Named styles

If you want to represent the chart a little different, from version 1.4.2 mscgenjs supports some 'named styles'. They'll add the most value when you use plain MsGenny or MscGen that do not contain any colors - as colors defined in scripts have precedence.

<script data-named-style='lazy'
        src="samples/sample11_basic_named_style_demo.msgenny"
        type="text/x-msgenny">
</script>

This is how the same simple chart looks without and with a style (lazy):

The complete list of named styles:

Vertical label alignment

Normally, labels for regular arcs align vertically with the arc in the middle:

To change that pass the type of alignment you want to the data-regular-arc-text-vertical-alignment attribute. Valid values are above, middle (which is the default) and below (which is not implemented yet).

<script data-regular-arc-text-vertical-alignment="above" type="text/x-msgenny">
  wordwraparcs=true, watermark="above";

  a => b: "This label will align above the arc";
</script>
        

Supported browsers: most

We have verified in page script to work in all desktop and mobile versions of Firefox, Safari, Chrome and Opera released since 2013. PhantomJS and SlimerJS work fine as well, and in Internet explorer it works from version 10.

Using mscgen-inpage.js in your own projects

You're welcome to use mscgen-inpage.js from github.io. If you are going to use it in serious volumes though or don't want to depend on github servers, you can include it in your own software. To ease that process a bit mscgen-inpage.js is available as an npm (front-end) package.

npm install mscgenjs-inpage

Until 2016-06-01 there was a bower package (mscgen_js-inpage-package) - it is discontinued in favor of the npm package.

Other sequence chart languages: MsGenny, Xù and JSON

Mscgen_js assumes the language of the presented script to be MscGen. If you use one of the other languages supported by mscgen_js, add a data-language attribute to the element with the target language: <code class="mscgen_js" data-language="msgenny">.

Three examples for msgenny, and the abstract syntax tree as produced by the parsers (json):

MsGenny

<pre id="yourownidsgetpreserved"
     class="mscgen_js"
     data-language="msgenny">
  arcgradient=10, watermark="msgenny";

  Harry =>> Sally: "marry(Sally, Harry)?";
  Sally >> Harry: YES,
  Sally -> mother: he's asked me to marry him!;
  mother -> *: "Stop that. Silly Sally.";
</pre>
hscale=0.9, arcgradient=10, watermark="msgenny";

Harry =>> Sally: "marry(Sally, Harry)?";
Sally >> Harry: YES,
Sally -> mother: he's asked me to marry him!;
mother -> *: "Stop that. Silly Sally.";
        

<pre class="mscgen_js" data-language="xu">
msc{
    watermark="xù: 序列圖", wordwraparcs="true";
    a,b,d,e;
    a => d;
    b loop e [label="for each element with class='mscgen_js'"]{
        b =>> d [label="get textContent of the element"];
        d >> b  [label="textContent"];
        b =>> e [label="parse(textContent)"];
        b alt e [label="happy day", textbgcolor="#f7fff7"] {
            e >> b [label="abstract syntax tree"];
            b -> d [label="clear inner HTML of the element"];
            b -> d [label="render (abstract syntax tree)"];
            --- [label="error", linecolor="red"];
            e >> b [label="error object", linecolor="red"];
            b -> d [label="add error message to innerHTML of the element",
                    linecolor="red"];
        };
    };
    ...;
}
</pre>
msc{
    watermark="xù: 序列圖", wordwraparcs="true", hscale=0.9;
    a,b,d,e;
    a => d;
    b loop e [label="for each element with class='mscgen_js'"]{
        b =>> d [label="get textContent of the element"];
        d >> b  [label="textContent"];
        b =>> e [label="parse(textContent)"];
        b alt e [label="happy day", textbgcolor="#f7fff7"] {
            e >> b [label="abstract syntax tree"];
            b -> d [label="clear inner HTML of the element"];
            b -> d [label="render (abstract syntax tree)"];
            --- [label="error", linecolor="red"];
            e >> b [label="error object", linecolor="red"];
            b -> d [label="add error message to innerHTML of the element",
                    linecolor="red"];
        };
    };
    ...;
}
        

JSON

<pre class="mscgen_js" data-language="json">
{
    "meta": {
    "extendedOptions": false,
    "extendedArcTypes": false,
    "extendedFeatures": false
    },
    "options":{
    "watermark" : "JSON/ AST"
    },
    "entities": [
    {
    "name": "Alice",
    "linecolor": "#008800",
    "textbgcolor": "#CCFFCC",
    "textcolor": "black",
    "arctextcolor": "#008800",
    "arclinecolor": "#008800"
    },
    {
    "name": "Bob",
    "linecolor": "#FF0000",
    "textbgcolor": "#FFCCCC",
    "textcolor": "black",
    "arctextcolor": "#FF0000",
    "arclinecolor": "#FF0000"
    },
    {
    "name": "pocket",
    "linecolor": "#0000FF",
    "textbgcolor": "#CCCCFF",
    "textcolor": "black",
    "arctextcolor": "#0000FF",
    "arclinecolor": "#0000FF"
    }
    ],
    "arcs":[[{
        "kind" : "=>",
        "from" : "Alice",
        "to" : "Bob",
        "label" : "do something funny"
    }], [{
        "kind" : "=>",
        "from" : "Bob",
        "to" : "pocket",
        "label" : "fetch (nose flute)"
    }], [{
        "kind" : ">>",
        "from" : "Bob",
        "to" : "Alice",
        "label" : "PHEEE!"
    }], [{
        "kind" : "=>",
        "from" : "Alice",
        "to" : "Alice",
        "label" : "hihihi"
    }]]
}
</pre>
{
    "meta": {
    "extendedOptions": false,
    "extendedArcTypes": false,
    "extendedFeatures": false
    },
    "options":{
    "watermark" : "JSON/ AST"
    },
    "entities": [
    {
    "name": "Alice",
    "linecolor": "#008800",
    "textbgcolor": "#CCFFCC",
    "textcolor": "black",
    "arctextcolor": "#008800",
    "arclinecolor": "#008800"
    },
    {
    "name": "Bob",
    "linecolor": "#FF0000",
    "textbgcolor": "#FFCCCC",
    "textcolor": "black",
    "arctextcolor": "#FF0000",
    "arclinecolor": "#FF0000"
    },
    {
    "name": "pocket",
    "linecolor": "#0000FF",
    "textbgcolor": "#CCCCFF",
    "textcolor": "black",
    "arctextcolor": "#0000FF",
    "arclinecolor": "#0000FF"
    }
    ],
    "arcs":[[{
        "kind" : "=>",
        "from" : "Alice",
        "to" : "Bob",
        "label" : "do something funny"
    }], [{
        "kind" : "=>",
        "from" : "Bob",
        "to" : "pocket",
        "label" : "fetch (nose flute)"
    }], [{
        "kind" : ">>",
        "from" : "Bob",
        "to" : "Alice",
        "label" : "PHEEE!"
    }], [{
        "kind" : "=>",
        "from" : "Alice",
        "to" : "Alice",
        "label" : "hihihi"
    }]]
}

Licensing: GPL-3.0 with a relaxation

As you can read on the mscgen_js github page mscgen_js is licensed under the GNU General Public License version 3 ("the GPL").

For the use of the minified version of the embedding code (mscgen-inpage.js) as described on this page a special exception to the GPL is made. This is so you can use it to render sequence charts in documentation which has a different license from the GPL without that documention (let alone the software it documents, if any) having to be licensed under the GPL:

As a special exception to the GPL, any HTML file which merely makes function calls to mscgen-inpage.js, and for that purpose includes it by reference shall be deemed a separate work for copyright law purposes. In addition, the copyright holders of this code give you permission to combine this code with free software libraries that are released under the GNU LGPL. You may copy and distribute such a system following the terms of the GNU GPL for this code and the LGPL for the libraries. If you modify this code, you may extend this exception to your version of the code, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

About

v1.12.0

Apart from making embedding sequence charts easy as drinking apple juice, the mscgen_js library serves as the engine for a cool on line interpreter.

photograph of the author

Author

Sander Verweij

Twitter LinkedIn Google+

GPL-3.0

License

open source (GPL-3.0), with a relaxation.

Source Licenses