How to draw

Prerequisites

Graphviz

Graph drawing currently uses the dot drawing program from the graphviz graph visualisation software package. This should be available on most distributions through your graphical installer or on the command line:

  • Debian, Ubuntu, etc.
    $ sudo apt-get install graphviz
  • CentOS, Fedora, RHEL, etc.
    $ yum install graphviz

Failing that, installation instructions are available on the graphviz webpage, here.

ImageMagick (optional)

To use the command line examples below which use the display application you need the ImageMagick package. Again, this is widely available and can be installed graphically or on the command line:

  • Debian, Ubuntu, etc.
    $ sudo apt-get install imagemagick
  • CentOS, Fedora, RHEL, etc.
    $ sudo yum install ImageMagick

Using the 'ignite' helper app

We recommend that state machines are written in a modular fashion, such that the generator function (SMGF) is exported from the file containing it (this can be seen in action in any of the examples). This pattern makes it easy to use the ignite application to draw a state machine diagram (in the ignite directory):

$ ./bin/ignite -m draw -T png examples/apps/reader/rss_catalog.js

This will generate a PNG called rss_feed.png:

If you have ImageMagick (display) installed, then you can generate the diagram and draw it on a single line:
$ ./bin/ignite -m draw -T png -o - examples/apps/reader/rss_catalog.js | display

(This works by setting the output file to stdout and piping the result into the display application).

By default a fairly detailed diagram is drawn, showing details of each state along with guard functions (blue diamonds) and action functions (green diamonds). This level of detail can be reduced by setting the --level option to 1.
$ ./bin/ignite -m draw -T png --level 1 -o - examples/apps/reader/rss_catalog.js | display

Within the code

Diagrams can be easily created within the code by using a ignite.Diagram object. The constructor for which is passed either a Factory object or an SMGF.

Once a diagram object is constructed, then it can be drawn by running it through a processor. At present there are two processors, one that generates dot format files (the default) and one that generates a JSON representation of the graph.

function draw (smgf) {
    var diagram = new ignite.Diagram(jsmFactory) ;
    var dotText, jsonText ;

    // Create text:
    dotText = graph.process() ;
    jsonText = graph.process({processor: 'json'}) ;

    // Create text and write to file:
    dotText = graph.processAndWrite("diagram.dot") ;
    jsonText = graph.processAndWrite("diagram.json", {processor: 'json'}) ;

    // Change detail level:
    dotText = graph.processAndWrite("diagram.dot", {level:1}) ;
}