A Node.js module that converts JSON to DOT language and can create GraphViz graphics with viz.js (without installing GraphViz)
npm install jsonvizA Node.js module that converts JSON to DOT language and can create GraphViz
svg graphics with the viz.js (does not need to install GraphViz).
The jsonviz module is not an abstraction level that makes UML creation very easier.
It is just a JSON format that describes dot graphs. That helps to create graphs
in a more intuitive way with JavaScript objects and to update your graph in a
script before it is created.
Table of content:
1. JSONGraph class
1. JSONGraph.SVG class
1. JSONGraph.HTML class
1. JSONGraph.Raw class
1. Additional attributes
1. Extensions | JSDoc
1. Util
1. DOT language
1. Version changes
The jsonviz module exports the JSONGraph class constructor.
This class allows the creation of a GraphViz graph with the JavaScript object syntax.
`new JSONGraph(object opts);
> Arguments:
* object opts: contains the constructor arguments
* boolean opts.strict = false
* string opts.type = "digraph"
* string opts.name = ""
* object opts.graph = {}
* object opts.node = {}
* object opts.edge = {}
* Array opts.statements = []
For more information about the arguments, see the JSONGraph attributes section.
`js
// Gets the jsonviz module
var jsonviz = require("jsonviz");
// Creates the JSONGraph instance
var o = new jsonviz(
{
// Styles applies on all nodes of the graph
node: {fillcolor: "#eeeeee", style: "filled,rounded", shape: "rect"},
// A collection of styles than can be referred from their names
styles:
{
selected: {fillcolor: "#bbccff:#ddeeff"},
depends: {label: "depends", style: "dashed", arrowhead: "open"}
}
// All statements in DOT language in order
statements:
[
// The B node will use the selected style
{stmt: "B", attributes: {ref: "selected"}},
// Adds a simple statement without any attribute (the nodes use the generic attributes set above)
"B -> C",
// Adds a statement with attributes that are added to the generic ones defined above
// The edge uses the depends style and have a blue color
{stmt: "A -> B", attributes: {ref: "depends", color: "#8888cc"}}
]
});
// Generates the DOT version, then generates the svg one, saves it and returns it (JSONGraph.SVG object)
// If the second parameter is set to true, the save is asynchronous, else a callback function that
// takes an error string can be passed
var svg = o.save("./UML.svg" /, true/);
// Prints the svg as a text (implicitely call the toString method of JSONGraph.SVG)
console.log("SVG:\n" + svg);
// You can also recover the dot version (cached in the instance)
console.log(o.dot());
`
#### boolean strict
The graph use the strict mode. As explained on the GraphViz web site,
this forbids the creation of multi-edges, i.e., there can be at most one
edge with a given tail node and head node in the directed case.
#### string type
The graph use the strict mode. As explained on the GraphViz web site,
this forbids the creation of multi-edges, i.e., there can be at most one
edge with a given tail node and head node in the directed case.
#### string name
Provides a name the graph.
#### object|string|string[] graph
A key-value pair of
DOT attributes
that define the appearence of the graph. It can also be one or several
references to a style in styles. Note that if graph is a string,
it can contain several styles separated with comas.
#### object|string|string[] node
A key-value pair of
DOT attributes
that define the generic appearence of all nodes. It can also be one or several
references to a style in styles. Note that if node is a string,
it can contain several styles separated with comas.
#### object|string|string[] edge
A key-value pair of
DOT attributes
that define the generic appearence of all edges. It can also be one or several
references to a style in styles. Note that if edge is a string,
it can contain several styles separated with comas.
#### object styles
A key-value pair of styles that are themselves a key-value pair of
DOT attributes.
A style can be used inside the attributes on any statement with
the (string|string[]) ref attribute. It can also be used instead
of the attribute list in a statement or for inside the global styles
(graph, node, edge).
Some css to put inside the svg itself. It can be usefull to have local svg, but
it is essentially used if a global style does not affect the svg itself (for example,
changin the cursor on the anchor elements).
For more information on the format of a css array, see util.css
#### (string|JSONGraph|object)[] statements
An array that contains all statements of the graph:
* It can be a simple string that contains the statement such like A -> B
or even A -> B[label="depends", style="dashed"].
* Or another JSONGraph that must have the subgraph type.
* Or a key-value pair object that contains the statement and attributes.
** string statement or stmt: the statement without the attributes such like RGB or RGB -> Color
** object|string|string[] attributes or attrs: the key-value pair of
DOT attributes that define
the appearence of the node, if the statement is just a node identifier,
or the edge(s) in other cases. It can also be one or several
references to a style in styles. Note that if attributes is a string,
it can contain several styles separated with comas.
static JSONGraph import(string pathOrJSON)
Imports a JSONGraph object by parsing a JSON string that defines its properties.
> Arguments:
* string pathOrJSON: the JSON content is identified if the string begins with
optional white spaces and an opening curly bracket. In this case, the JSON string is
parsed and the result is passed as the options of theJSONGraph constructor. In the other case, the file is read from the
given path, and then the content parsed as a JSON string to be passed to the
constructor.
> Returns: JSONGraph - the JSONGraph created from the JSON options.
#### JSONGraph.generate
static boolean generate(object|string opts[, object dotOpts[, string path[, function cb(string error)]]]) static boolean generate(object opts[, object dotOpts[, string path[, boolean ansyc]]]) static boolean generate(object opts[, string path[, function cb(string error)]]) static boolean generate(object opts[, string path[, boolean async]])
Generates the svg text from the JSONGraph options, and save it if path is defined.
> Arguments:
* object|string opts: the JSONGraph constructor options. It can use the JSON string or a path to a file that contains the JSON option.
See the doc of the pathOrJSON argument of the JSONGraph.import method above for details about the opts parsing if it is a string.
* object dotOpts={}: the viz.js graph creation options
* string path="": the path where to save the final svg file. If it is not set, the result is not saved.
* function cb(string error)=null: the callback used after the result is saved in the given path.
* boolean async=false: instead of using a callback, set async to true to save the result asynchromously.
> Returns: JSONGraph.SVG - the generated SVG.
static function extends(moduleName)
Extends the JSONGraph class with a JSONGraph extension. This function allows to load only a light version of jsonviz and
then to extends it with useful features.
> Arguments:
* string moduleName: the module name or an absolute path to a module
> Returns: function- the JSONGraphconstructor
> See: Extensions
#### JSONGraph#reset
JSONGraph reset()
Resets the dot code generated. Uses that function if the arguments where changed after
a call to the dot, generate or save method.
> Returns: JSONGraph - this instance to chain actions.
#### JSONGraph#dot
JSONGraph dot()
Generates the dot code according to the attributes values, and returns it.
The generated code is internaly stored. The reset method can be used to remove it.
> Returns: string - the dot code used by GraphViz to generate the final graph.
#### JSONGraph#generate
JSONGraph generate([object dotOpts])
Generates the final svg graph text according to the attributes values.
> Arguments:
* object dotOpts={}: the viz.js graph creation options
> Returns: JSONGraph.SVG - the generated svg.
#### JSONGraph#svg
JSONGraph svg([object dotOpts])
An alias of the generate method.
> Arguments:
* object dotOpts={}: the viz.js graph creation options
> Returns: JSONGraph.SVG - the generated svg.
#### JSONGraph#save
JSONGraph save(string path[, object dotOpts[, function cb(string error)]]) JSONGraph save(string path[, object dotOpts[, boolean sync]]) JSONGraph save(string path[, function cb(string error)]]) JSONGraph save(string path[, boolean sync]])
Generates the dot code according to the attributes values, save it to the
given path and then returns it.
> Arguments:
* string path: the path where to save the final svg file.
* object dotOpts={}: the viz.js graph creation options
* optional function cb(string error) || sync: the callback used after the result is saved in the given path.
If nothing is provided, uses the snyc argument that is true by default.
* boolean sync=true: instead of using a callback, set sync to true (default) to save the result synchromously.
Set this argument to false to proceed to an asynchronous save withotu any callback
> Returns: JSONGraph.SVG - the generated svg.
#### JSONGraph#clone
JSONGraph clone([name])
Clones the JSONGraph instance by deeply copying all the attributes.
> Arguments:
* string name=null: a new optional name for the cloned graph
> Returns: JSONGraph - the cloned instance.
#### JSONGraph#toJSON
string toJSON([function|(string|number)[] replacer[, string|number space]])
Converts the JSONGraph object to a JSON string.
> Arguments:
* function replacer(string error)|(string|number)[]=null
* string|number space=null
The optional arguments are the ones used in theJSON.stringify
function. For more information about this arguments, see the
MDN documentation.
> Returns: string - the stringified JSONGraph object.
number addRaw(string raw)
Adds a new node to the graph with its attributes.
> Arguments:
* string raw: the raw content that will be converted to a JSONGraph.Raw instance.
> Returns: number - the statement index that corresponds to the added raw statement.
number addNode(string name[, object attrs])
Adds a new node to the graph with its attributes.
> Arguments:
* string name: the name of the node
* object attrs=null: the attributes of the node
> Returns: number - the statement index that corresponds to the added node.
number addEdge((string|number|object)[] nodes[, object attrs])
Links nodes together with edges.
> Arguments:
* (string|number)[] nodes: the names (or indices in the statement)
of the nodes that will be linked. It can also be an object with the name of a structure as the kay
and the cell name as the value.
* object attrs=null: the attributes of each link between the nodes
> Returns: number - the statement index that corresponds to the added edge.
An alias of the JSONGraph#addEdge method.
number addStruct(string name, Array nodes[, object attrs])
Adds a structure (a record-based node)
to the graph.
> Arguments:
* string name: the attributes of each link between the nodes
* Array nodes: an array if cells.
* object attrs=null: the attributes of each link between the nodes
> Returns: number - the statement index that corresponds to the added edge.
> Example:
`js
var jsonviz = require("jsonviz"),
o = new jsonviz();
o.addStruct("struct1", ["A", ["B", ["C", "D", "E"], "F"], "G"]);
o.addStruct("struct2", [[["A", "B"], ["C", "D"]]]);
o.linkNodes([{struct1:"A"}, {struct2:"C"}]);
`
number addSubgraph(JSONGraph|object graph)
Adds a subgraph.
> Arguments:
* JSONGraph|object graph: the graph or the graph options. The type is automatically set to "subgraph"
> Returns: number - the statement index that corresponds to the added subgraph.
This class is created by the JSONGraph#generate and JSONGraph#save methods.
It contains the generated svg text and allows it to be saved.
new JSONGraph.SVG(string text);
> Arguments:
string text, the svg text.
#### string text
The svg text.
#### JSONGraph#toString
string toString()
Returns the svg text. So a JSONGraph.SVG instance will return its text
when it is used as a string.
> Returns: string - the svg text.
$3
#### JSONGraph.SVG#save
string save(string path[, function cb(string error)]) string save(string path[, boolean asnyc])
Saves the svg text to the given destination path.
> Arguments:
* string path: the path where to save the svg text.
* function cb(string error)=null: the callback used after the svg text is saved in the given path.
* boolean async=false: instead of using a callback, set async to true to save the svg text asynchromously.
> Returns: JSONGraph.SVG - this isntance to chain actions.
JSONGraph.HTML class
This class is used to insert HTML content inside label
DOT attributes
(label, headlabel, taillabel, xlabel).
new JSONGraph.HTML(string content);
> Arguments:
* string content: the HTML content. It must escape the html special characters with html entities.
JSONGraph.HTML can also be used as a function:
`js
// The following declaration...
new JSONGraph.HTML("A");
// ...is the same than the following function call
JSONGraph.HTML("A");
`
#### string content
The HTML content. It must escape the html special characters with html entities.
#### JSONGraph.HTML#toString
string toString()
Returns the html content.
> Returns: string - the html content.
This class is used to insert raw content in a statement or an attribute.
* When used for a statement, the string is used as raw string (html special chars and quotes are not escaped).
* When used for an attribute, the html sepcial characters are not escaped, but the quotes are escaped to put the
string between double quotes without errors.
new JSONGraph.Raw(string content);
> Arguments:
* string content: the raw content. The html special characters will not be
automatically escaped while the DOT code is generated, so
if some of them must be escaped, it must done manually.
JSONGraph.HTML can also be used as a function:
`js
// The following declaration...
new JSONGraph.Raw("struct [label=\" A | B\"]");
// ...is the same than the following function call
JSONGraph.Raw("struct [label=\" A | B\"]");
`
#### string content
The raw content. The html special characters will not be
automatically escaped while the DOT code is generated, so
if some of them must be escaped, it must done manually.
#### JSONGraph.Raw#toString
string toString()
Returns the raw content.
> Returns: string - the raw content.
Additional attributes
In addition of the DOT language attributes,
jsonviz provides its own attributes :
* string|string[] ref: the name(s) of a(several) style(s) stored inside the JSONGraph#styles
attribute. The attribute of the style(s) will be copied in order before the attribute
list that contains the reference. If ref is a string, several styles can be used by
using a coma separators, so the style names cannot contain any coma.
* string|string[] textstyle: the name(s) of a(several) text style(s). It will replace
the label attribute so it cannot be used at the same type than a label attribute.
If textstyle is a string, several styles can be used by using a coma separators. The accepted
styles are the following ones:
* bold or b
* italic or i
* underline or u
* stroke or s
For now, jsonviz only have one extension. You can easilly add your own extension by
creating a .js file and then exporting a function that takes the JSONGraph
constructor to add members.
/path/extension.js:
`js
var util = require("jsonviz/util.js");
exports = module.exports = function(JSONGraph)
{
// Adds a static attribute
JSONGraph.helloSentence = "Hello !";
// Adds an instance method
JSONGraph.prototype.sayHello = function()
{
console.log(JSONGraph.helloSentence);
};
// Adds an instance method to JSONGraph.SVG
JSONGraph.SVG.prototype.addSimpleMetaData = function(meta)
{
var str = "", n;
for(n in meta)
{
meta[n];
}
this.text.replace(/<\/svg>/, "
This extension allows to read the classes as generated with JSDoc and then generate
a class diagram (without members).
#### Example:
`js
var jsonviz = require("jsonviz"), i = 0, c,
// Creates the grtaph that will be used to create all classes
graph = new jsonviz({
// Defines a generic node style with a nice gradient
node:
{
fillcolor: "#dddddd:#ffffff",
gradientangle: 90,
fontsize: 8,
fontname: "arial"
},
// Adds the gree ngradient for the main node of the graph
styles:
{
node_selected: {fillcolor: "#bbccff:#ddeeff"}
}
});
// Loops on each class providen in jsdoc
for(; i < classes.length; i++)
{
// Gets the class
c = classes[i];
// Creates graph for the given class
// - By default, the statements are removed before, so the graph will not cumulate the previous classes
// - The graph will create the links to each class documentation
graph .fromJSDoc(members.classes, {className: c.longname, links: function(c){return "#" + c.longname;} / or just true to get the lng name + ".html" /})
// Saves the graph
.save(c.longname + ".svg", true);
}
`
#### JSONGraph.JSDoc.getClassesByName
static object JSONGraph.JSDoc.getClassesByName(object[] classes)
Returns an associative array (i.e. an object) of JSDoc classes from which the key is the long name
of each class.
The associative array will also be added in a byNames property of the passed argument.
If this property is already defined, it will be returned without any new computation.
> Note: this method calls JSONGraph.JSDoc.getClassesByName method,
and the JSONGraph.JSDoc.addSubClasses if opts.children is true.
> Arguments:
* object[] classes: the classes as it is returned in the JSDoc's helper.getMembers()
from jsdoc/util/templateHelper (see in the publish.js file of the JSDoc default template) or by usingtaffyData({kind: 'class'}).get().
> Returns: object - an associative array (i.e. an object) of JSDoc classes from which the key is the long name
of each class.
#### JSONGraph.JSDoc.addSubClasses
static object JSONGraph.JSDoc.addSubClasses(object[] classes)
Adds the sub-classes in a string[] subClasses property (stores the long name as the augments property),
of each class in the argument array.
It requires to call the JSONGraph.JSDoc.getClassesByName method.
> Note: this method calls the JSONGraph.JSDoc.getClassesByName method,
and the JSONGraph.JSDoc.addSubClasses if opts.children is true.
> Arguments:
* object[] classes: the classes as it is returned in the JSDoc's helper.getMembers()
from jsdoc/util/templateHelper (see in the publish.js file of the JSDoc default template) or by usingtaffyData({kind: 'class'}).get().
> Returns: object - an associative array (i.e. an object) of JSDoc classes from which the key is the long name
of each class.
JSONGraph JSONGraph.fromJSDoc(object[] classes, object opts)
Adds all the statements to the JSONGraph instance to create the proper class
diagram from JSDoc.
> Note: this method calls JSONGraph.JSDoc.getClassesByName method,
and the JSONGraph.JSDoc.addSubClasses if opts.children is true.
> Arguments:
* object[] classes: the classes as it is returned in the JSDoc's helper.getMembers()
from jsdoc/util/templateHelper (see in the publish.js file of the JSDoc default template) or by usingtaffyData({kind: 'class'}).get().
* object opts: the creation options
* string className: the class from which to create the diagram (it must be the long name of the class).
This is the only required option.
* boolean opts.changeName=true: if true, the diagrm name is changed for "class "
* boolean opts.reset=true: if true, the previous satements are deleted before the new one are created
* boolean opts.parents=true: if true, the diagram includes all the parents
* boolean opts.children=true: if true, the diagram includes all the children
* boolean opts.select=true: if true, the given class will use the node_selected style and it will appear in bold.
* boolean|function opts.links=false: if true, the class rects are clickables. A function can be used instead
of a boolean to format the link. This function takes the doclet as argument.
> Returns: JSONGraph - this isntance to chain actions.
> Styles: the following styles can be added to the JSONGraph instance frmo which this method is called :
* node_selected: applied on the node from which the graph is drawn
extends: an additional style for the extends and implements* arrows (alos use an internal edge_extends style with arrowhead=empty)
implements: an additional style for the implements* arrows (alos use an internal edge_implements style with style=dashed).
* node_class: redefines the class style. By default: shape="rect" and style="rounded,filled"
class: an additional style for the class* nodes
JSONGraph JSONGraph.fromJSDoc(object[] classes, object opts)
Adds all the statements to the JSONGraph instance to create the proper class
diagram from JSDoc.
> Note: this method calls JSONGraph.JSDoc.getClassesByName method,
and the JSONGraph.JSDoc.addSubClasses if opts.children is true.
> Arguments:
* object[] classes: the classes as it is returned in the JSDoc's helper.getMembers()
from jsdoc/util/templateHelper (see in the publish.js file of the JSDoc default template) or by usingtaffyData({kind: 'class'}).get().
* object opts: the creation options
* string className: the class from which to create the diagram (it must be the long name of the class).
This is the only required option.
* boolean opts.changeName=true: if true, the diagrm name is changed for "class "
* boolean opts.reset=true: if true, the previous satements are deleted before the new one are created
* boolean opts.parents=true: if true, the diagram includes all the parents
* boolean opts.children=true: if true, the diagram includes all the children
* boolean opts.select=true: if true, the given class will use the node_selected style and it will appear in bold.
* boolean opts.links=false: if true, the class rects are clickables
> Returns: JSONGraph - this isntance to chain actions.
> Styles: the following styles can be added to the JSONGraph instance frmo which this method is called :
* node_selected: applied on the node from which the graph is drawn
extends: an additional style for the extends and implements* arrows (alos use an internal edge_extends style with arrowhead=empty)
implements: an additional style for the implements* arrows (alos use an internal edge_implements style with style=dashed).
* node_class: redefines the class style. By default: shape="rect" and style="rounded,filled"
class: an additional style for the class* nodes
The jsonviz library includes a util module that is used internally.
It could be usefull to share its content.
`js`
var util = require("jsonviz/util");
`string util.escapeString(string src[, boolean single])`
Escapes a string by adding an anti-slash before simple or double quotes.
> Arguments:
* string src: the source
* boolean single=false: if true, escape the string to put it between single quotes, else escapes it for double quotes.
> Returns: string - the escaped string (without surrounding quotes)
`string util.escapeHTML(string src)`
Escapes a string to be inserted in an HTML content as a pure string
by replacing HTML specials characters with HTML entities.
For example: -> becomes -> .
> Arguments:
* string src: the source
> Returns: string - the string escaped for html
`object|Array util.clone(object|Array original)`
Deeply clones an object or an array by cloniing each object/array inside it.
Limitationms:
* The non-enumerable properties
of an object are not copied in the cloned one.
* If an array also contain additional attributes, there are not copied. In other words,
for arrays, only indexed data are copied.
> Arguments:
* object|Array original: the object to clone
> Returns: object|Array - the cloned object
`string util.css(object[] css)`
Converts a JavaScript object css desacription to a formatted css string.
Example:
`js`
util.css([
{
select: "a",
style: {cursor: "pointer"}
},
{
select: [".myClass", ".myOtherClass div"],
style: {backgroundColor: "#eee"} // Or {"background-color": "#eee"}
}
]);
Returns the css string:
`css`
a
{
cursor: pointer;
}
.myClass, .myOtherClass div
{
background-color: #eee;
}
> Arguments:
* object[] css: the description of the css. A css description array is a collection of key-style pairs:string|string[] select
* : one or more css selectorsobject style
on which to apply the style.
* : the style as a property-value object (like {cursor: pointer}).
CSS properties that use a dash can be put between double quotes or removes the dash
and set the case to the following character to upper case.
> Returns: string - the css formatted style
The jsonviz module produces DOT language and then svg graphics with the
viz.js module. For more information,
here are some documentations on the GraphViz web site:
* Syntax guide
* Attribute reference
* Shape reference
Creates the JSONGraph, JSONGraph.SVG and JSONGraph.HTML classes.
* Can instanciate a JSONGraph without any arguments
* The JSONGraph#save cb argument is not passed, jsonviz will use
the default sync value (true) and then uses a synchronous saving.
* Adds JSON import / export:
* Adds the JSONGraph.import method
* Adds the JSONGraph#toJSON method
* Adds the JSONGraph.Raw class
* Adds the build methods:
* Adds the JSONGraph#addRaw method
* Adds the JSONGraph#addNode method
* Adds the JSONGraph#addEdge/JSONGraph#linkNodes methods
* Adds the JSONGraph#addStruct method
* Adds the JSONGraph#addSubgraph method
* Adds the extension management:
* Adds the JSONGraph#extends method
* Adds the JSDoc extension:
* Adds the JSONGraph.JSDoc.getClassesByName method
* Adds the JSONGraph.JSDoc.addSubClasses method
* Adds the JSONGraph#fromJSDoc method
* JSDoc: recognizes the final flag.
* Documents the util library
* Adds the util.css method
* Adds the JSONGraph#css` attribute