diff --git a/.gitignore b/.gitignore index d9a5e8094..b56f5dddf 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ npm-debug.log # temporary files .*.sw[op] .commits.tmp +gen/ diff --git a/README.md b/README.md index 3b965d4dc..36875ebcc 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,16 @@ Link via cdnjs: http://cdnjs.com Or download the library from the github project: [https://github.com/almende/vis.git](https://github.com/almende/vis.git). + +### Installing module `canvas` + +Module `canvas` is only required if you need to run `vis.js` on `node.js` and require actual output. It is not required for regular usage in a browser. + +Currently, the unit tests use a mock object for canvas which has limited but adequate functionality. If `canvas` is installed, that will be used silently in place of the mock object. + +The issue with `canvas` is that it has an external dependency to `cairo`. This needs to be installed outside of the regular install as done by `npm`. Please consult [`node-canvas` github page](https://github.com/Automattic/node-canvas/wiki#desktop) for the correct installation procecure your platform + + ## Load To use a component, include the javascript and css files of vis in your web page: @@ -322,6 +332,9 @@ module: { There is also an [demo-project](https://github.com/mojoaxel/vis-webpack-demo) showing the integration of vis.js using webpack. + + + ## Test To test the library, install the project dependencies once: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..d64a0332f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,231 @@ +# Command line usage example + +``` +jsdoc -c jsdoc.json -r -t docs -d gen/docs lib +``` + +- `-c`: use this config file for `jsdoc` +- `-r`: Recurse into subdirectories of the specified source directories +- `-t`: Use template in path `docs` +- `-d`: Generated html files put in `gen/docs` +- Source files to parse are taken from directory `lib` + + +## Notes + +The template generation is set up so that: + + - Files ending in `.tmpl` are skipped + - All non-html files are plain copied + - html-files *can* contain `` tags, but this is not required + + +## Intention + +The `docs` directory is treated as a `jsdoc` template, in which the html-files are the template files. This allows for a gradual adaptation of the html-files to templates; unchanged html-files will pass through `jsdoc` unchanged. + +The added value of using `jsdoc` for documentation generation, is that the complete documentation information, as collected by `jsdoc` from the source, is available for usage. This way, it's possible to insert technical notes from the source code into the documentation. + +---- + +# Usage of and Notes on Source Code + +This section contains notes on the usage of `jsdoc` functionality, to aid with the handling of its generated data. + + +## Parameters of `publish()` + +### Parameter `taffyData` + + A table containing *all* data collected from the source code, related to jsdoc generation. See below for more info and example outputs. + +### Parameter `opt` + +Example of `opt` variable: + +```js +{ + "_":["../github/vis/lib/network/"], + "configure":"jsdoc.json", + "recurse":true, + "template":"/home/wim/projects/jsdoc/default", + "destination":"./out/", + "encoding":"utf8" +} +``` + +### Parameter `tutorial` + +This does not appear to be of use for the generation of `vis.js` documentation. + +Example of `tutorial` variable: + +```js +{ + "longname":"", + "name":"", + "title":"", + "content":"", + "parent":null, + "children":[], + "_tutorials":{} +} +``` + +## Global variable `env` + +This contains addition info for the current execution of `jsdoc`. Example of `env` variable: + +```js +{ + "run":{"start":"2017-09-16T05:06:45.621Z","finish":null}, + "args":["-c","jsdoc.json","-r","-t","default","../github/vis/lib/network/"], + "conf":{ + "plugins":["/usr/lib/node_modules/jsdoc/plugins/markdown.js"], + "recurseDepth":10, + "source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":""}, + "sourceType":"module", + "tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]}, + "templates":{"monospaceLinks":false,"cleverLinks":false} + }, + "dirname":"/usr/lib/node_modules/jsdoc", + "pwd":"/home/wim/projects/jsdoc", + "opts":{ <> }, + "sourceFiles":[ <> ], + "version":{"number":"3.5.4","revision":"Fri, 04 Aug 2017 22:05:27 GMT"} +} +``` + + +## taffyData + +This is a parameter to `publish()`. It's a table containing *all* data collected from the source code, related to jsdoc generation. + +I can't find any way to return a list of fields for the data items in the taffyDB docs, therefore below there are examples of items, for better understanding of usage. + +Example usage: + +```js + var data = taffyData; + var tmp = data().filter({name:'Label'}).get(); +``` + +Returns an array with all items with `name === 'Label'`. Example output of one of these items, for a class: + +*In these examples, block comment endings are redacted to ' * /'* + +```js +{ + "comment":"/**\n * A Label to be used for Nodes or Edges.\n * /", + "meta":{ + "range":[3770,41303], + "filename":"Label.js", + "lineno":167, + "columnno":0, + "path":"/home/wim/projects/github/vis/lib/network/modules/components/shared", + "code":{ + "id":"astnode100065034", + "name":"Label", + "type":"ClassDeclaration", + "paramnames":["body","options","edgelabel"] + } + }, + "classdesc":" +A Label to be used for Nodes or Edges. + +", + "name":"Label", + "longname":"Label", + "kind":"class", + "scope":"global", + "params":[ + {"type":{"names":["Object"]},"name":"body"}, + {"type":{"names":["Object"]},"name":"options"}, + {"type":{"names":["boolean"]},"optional":true,"defaultvalue":false,"name":"edgelabel"} + ], + "___id":"T000002R005289", + "___s":true +} +``` + +Example of item for an instance method: + +```js + var tmp = data().filter({name:'_drawText'}).get(); +``` + +Full output returned: + +```js +[{ + "comment":"/**\n *\n * @param {CanvasRenderingContext2D} ctx\n * @param {boolean} selected\n * @param {boolean} hover\n * @param {number} x\n * @param {number} y\n * @param {string} [baseline='middle']\n * @private\n * /", + "meta":{ + "range":[20060,22269], + "filename":"Label.js", + "lineno":652, + "columnno":2, + "path":"/home/wim/projects/github/vis/lib/network/modules/components/shared", + "code":{ + "id":"astnode100066427", + "name":"Label#_drawText", + "type":"MethodDefinition", + "paramnames":["ctx","selected","hover","x","y","baseline"] + }, + "vars":{"":null} + }, + "params":[ + {"type":{"names":["CanvasRenderingContext2D"]},"name":"ctx"}, + {"type":{"names":["boolean"]},"name":"selected"}, + {"type":{"names":["boolean"]},"name":"hover"}, + {"type":{"names":["number"]},"name":"x"}, + {"type":{"names":["number"]},"name":"y"}, + {"type":{"names":["string"]},"optional":true,"defaultvalue":"'middle'","name":"baseline"} + ], + "access":"private", + "name":"_drawText", + "longname":"Label#_drawText", + "kind":"function", + "memberof":"Label", + "scope":"instance", + "___id":"T000002R005388", + "___s":true +}] +``` + +## `jsdoc` template rendering + +See `function createRenderer(fromDir, data)` in code for usage. + +There are two calls for rendering templates: + + - `var html = renderer.render(inFile, docData);` + - `var html = renderer.partial(inFile, docData);` + +The difference is that `render()` will use a default layout template, if present, which will encapsulate all html. This can be set by: + +```js + renderer.layout = 'path/to/default/layout.tmpl'; +``` + +Parameter `docData` is a hash which is used to pass parameters into a template. The standard way of using this appear to be: + +``` + +``` + +But it also appear to be possible to use the elements of docData directly: + +```js +var docData = { + myTitle: 'Hello, pussycat!' +}; +``` + +Within the template: + +``` + +``` diff --git a/docs/data/dataset.html b/docs/data/dataset.html index 4c8a958cb..a47d204f0 100644 --- a/docs/data/dataset.html +++ b/docs/data/dataset.html @@ -1,86 +1,11 @@ - - - - - - - - - DataSet - vis.js - A dynamic, browser based visualization library. - - - - - - - - - - - - - - - - - - - - - + + - -
-
- -
-
- - +

DataSet

@@ -1008,18 +933,4 @@

Data Types

- - - - - - - - - - - - - - + diff --git a/docs/data/dataview.html b/docs/data/dataview.html index 9a98f7f2e..67bc09203 100644 --- a/docs/data/dataview.html +++ b/docs/data/dataview.html @@ -1,3 +1,6 @@ + @@ -35,52 +38,7 @@ - -
-
- -
-
- - +

DataView

@@ -396,18 +354,4 @@

Subscriptions

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/data/index.html b/docs/data/index.html index 12523f9d1..eb99f7285 100644 --- a/docs/data/index.html +++ b/docs/data/index.html @@ -1,3 +1,6 @@ + @@ -35,52 +38,7 @@ - -
-
- -
-
- - +

Data

@@ -121,18 +79,4 @@

DataView

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/graph2d/index.html b/docs/graph2d/index.html index dd8baaddf..ebe15083f 100644 --- a/docs/graph2d/index.html +++ b/docs/graph2d/index.html @@ -1,3 +1,6 @@ + @@ -78,57 +81,7 @@ - -
-
- -
-
- - - +

Graph2d

@@ -1500,18 +1453,4 @@

Styles

- - - - - - - - - - - - - - + diff --git a/docs/graph3d/index.html b/docs/graph3d/index.html index 19e63b9bd..7a4d6e3a2 100644 --- a/docs/graph3d/index.html +++ b/docs/graph3d/index.html @@ -1,3 +1,6 @@ + @@ -35,52 +38,7 @@ - -
-
- -
-
- - +

Graph3d

@@ -961,18 +919,4 @@

Data Policy

- - - - - - - - - - - - - - + diff --git a/docs/network/configure.html b/docs/network/configure.html index 98be9e16a..7a7690fe9 100644 --- a/docs/network/configure.html +++ b/docs/network/configure.html @@ -1,3 +1,6 @@ + @@ -41,57 +44,7 @@ - -
-
- -
-
- - - +

Network - configure

@@ -176,18 +129,4 @@

Options

- - - - - - - - - - - - - - + diff --git a/docs/network/edges.html b/docs/network/edges.html index 7d4ae05ab..8efddbc5e 100644 --- a/docs/network/edges.html +++ b/docs/network/edges.html @@ -1,3 +1,6 @@ + @@ -41,57 +44,7 @@ - -
-
- -
-
- - - +

Network - edges

@@ -299,6 +252,44 @@

Options

true When false, the edge stops at the arrow. This can be useful if you have thick lines and you want the arrow to end in a point. Middle arrows are not affected by this. + + background + Object or Boolean + Object + When true, a background will be under the edge using the default settings. This can be further defined by supplying + an object. + + + + background.enabled + Boolean + false + Toggle the display of backgrounds. If this option is not defined, it is set to true if any of the properties + in this object are defined. + + + + background.color + String + 'rgba(111,111,111,0.5)' + The color size of the background as a string. Supported formats are 'rgb(255,255,255)', 'rgba(255,255,255,1)' and '#FFFFFF'. + + + background.size + Number + 10 + The blur size of the background. + + + background.dashes + Array or Boolean + false + When true, the background will be drawn as a dashed line. You can customize the dashes by supplying an Array. + Array formart: Array of numbers, gap length, dash length, gap length, dash length, ... etc. The array is + repeated until the distance is filled. + When using dashed lines in IE versions older than 11, the line will be drawn straight, not smooth. + + chosen Object or Boolean @@ -999,18 +990,4 @@

Options

- - - - - - - - - - - - - - + diff --git a/docs/network/groups.html b/docs/network/groups.html index caa8d1781..7bf6bd10c 100644 --- a/docs/network/groups.html +++ b/docs/network/groups.html @@ -1,3 +1,6 @@ + @@ -39,57 +42,7 @@ - -
-
- -
-
- - - +

Network - groups

@@ -160,18 +113,4 @@

Options

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/network/index.html b/docs/network/index.html index 2ade87953..f60ca719a 100644 --- a/docs/network/index.html +++ b/docs/network/index.html @@ -1,3 +1,6 @@ + @@ -70,57 +73,7 @@ - -
-
- -
-
- - - +

Network

@@ -609,6 +562,21 @@

Methods

The options object is explained in full below. + + + + + This comes from the source! + + + Returns: + + + + + findNode( String/Number nodeId) @@ -1487,7 +1455,7 @@

Events

stabilized Object - Fired when the network has stabilized or when the stopSimulation() has been called. The amount of iterations it took could be used to tweak the maximum amount of iterations needed to stabilize the network. Passes an object with properties structured as: + Fired when the network has stabilized, when the amount of iterations defined in the options has been reached, or when the stopSimulation() has been called. The amount of iterations it took could be used to tweak the maximum amount of iterations needed to stabilize the network. Passes an object with properties structured as: 
{
   iterations: Number // iterations it took
 }
@@ -1678,18 +1646,4 @@

Import data in DOT language

- - - - - - - - - - - - - - + diff --git a/docs/network/interaction.html b/docs/network/interaction.html index 5483636bd..4be1c97b7 100644 --- a/docs/network/interaction.html +++ b/docs/network/interaction.html @@ -1,3 +1,6 @@ + @@ -34,52 +37,7 @@ - -
-
- -
-
- - +

Network - interaction

Used for all user interaction with the network. Handles mouse and touch events as well as the navigation buttons and the popups.

@@ -155,18 +113,4 @@

Options

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/network/layout.html b/docs/network/layout.html index 3b38048bd..2b11a8904 100644 --- a/docs/network/layout.html +++ b/docs/network/layout.html @@ -1,3 +1,6 @@ + @@ -35,55 +38,7 @@ - - - -
-
- -
-
- - +

Network - layout

Acts as the camera that looks on the canvas. Does the animation, zooming and focusing.

@@ -152,18 +107,4 @@

Options

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/network/manipulation.html b/docs/network/manipulation.html index 95f9fc889..d426ceb95 100644 --- a/docs/network/manipulation.html +++ b/docs/network/manipulation.html @@ -1,3 +1,6 @@ + @@ -34,52 +37,7 @@ - -
-
- -
-
- - +

Network - manipulation

Acts as the camera that looks on the canvas. Does the animation, zooming and focusing.

@@ -187,18 +145,4 @@

Options

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/network/nodes.html b/docs/network/nodes.html index ca2d93976..c0c0fff2c 100644 --- a/docs/network/nodes.html +++ b/docs/network/nodes.html @@ -1,3 +1,6 @@ + @@ -35,57 +38,7 @@ - -
-
- -
-
- - - +

Network - nodes

@@ -1091,18 +1044,4 @@

Options

- - - - - - - - - - - - - - + diff --git a/docs/network/physics.html b/docs/network/physics.html index c8fe99208..c7defd613 100644 --- a/docs/network/physics.html +++ b/docs/network/physics.html @@ -1,3 +1,6 @@ + @@ -35,52 +38,7 @@ - -
-
- -
-
- - +

Network - physics

Handles the physics simulation, moving the nodes and edges to show them clearly.

@@ -207,18 +165,4 @@

Options

- - - - - - - - - - - - - - \ No newline at end of file + diff --git a/docs/publish.js b/docs/publish.js new file mode 100644 index 000000000..f500e3662 --- /dev/null +++ b/docs/publish.js @@ -0,0 +1,118 @@ +/*============================================================================== + Demo template, showing how documentation can be generated for `vis.js`. + + ------------------------------------------------------------------------------ + ## Notes on `jsdoc` code + + // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness + // doesn't try to hand them out later + indexUrl = helper.getUniqueFilename('index'); + // don't call registerLink() on this one! 'index' is also a valid longname + + globalUrl = helper.getUniqueFilename('global'); + helper.registerLink('global', globalUrl); + + ============================================================================== */ +'use strict'; +//var taffy = require('taffydb').taffy; // not really required here, left for reference + +// Internal modules of `jsdoc` are available here. +// This is not the complete list, there may be more useful stuff in jsdoc +// For all modules scan in: '/usr/lib/node_modules/jsdoc/lib/jsdoc/' (or similar on your system) +var fs = require('jsdoc/fs'); +var path = require('jsdoc/path'); +var template = require('jsdoc/template'); + + +/** + * Set up the template rendering engine. + */ +function createRenderer(fromDir, data) { + var renderer = new template.Template(fromDir); // Param is the template source directory. + // All template files are relative to this directory! + /** + * Example helper method + * + * This can be called from within a template as follows: + * + * ``` + * + * ... + * + * ``` + * + * / + renderer.helper = function(val) { + return 'this is a helper! ' + val; + }; + */ + + /** + * Retrieves jsdoc info for the passed instance method. + */ + renderer.getComment = function(methodName) { + var tmp = data().filter({longname: methodName}).get()[0]; + //console.log(JSON.stringify(tmp)); + + // Some restructuring, to adapt it to the docs layout + // This needs some work to make it handle 0 and > 1 parameters + var param = tmp.params[0]; + var prototype = tmp.name + '(' + param.type.names.join('|') + ' ' + param.name + ')'; + var returns = tmp.returns[0].type.names; + + return { + prototype: prototype, + returns: returns, + description: tmp.description + } + }; + + return renderer; +} + + +/** + Entry point for the template. + + This is called from `jsdoc` during execution + + @param {TAFFY} taffyData See . + @param {object} opts + @param {Tutorial} tutorials + */ +exports.publish = function(taffyData, opts, tutorials) { + //console.log(JSON.stringify(opts, null, 2)); + + var fromDir = path.resolve(opts.template); + var toDir = path.join(opts.destination); + var renderer = createRenderer(fromDir, taffyData); + + var docFiles = fs.ls(fromDir, 3); + docFiles.forEach(function(fileName) { + // Template filenames need to be relative to template source dir + var relName = path.relative(fromDir, fileName); + var outFile = path.join(toDir, relName); + + if (/publish.js$/.test(fileName)) return; // Skip self + if (/README.md$/.test(fileName)) return; // Skip own README + if (/\.tmpl$/.test(fileName)) return; // Skip .tmpl files; these are used as partials only + + if (!/\.html$/.test(fileName)) { + // Just plain copy over non-html files + var tmpDir = fs.toDir(outFile); + fs.mkPath(tmpDir); + fs.copyFileSync(fileName, tmpDir); + return; + } + + // Render html files as templates + //console.log(relName); + var html = renderer.partial(relName, {}); + fs.mkPath(fs.toDir(outFile)); + fs.writeFileSync(outFile, html, 'utf8'); + }); + + //console.log(JSON.stringify(env, null, 2)); +}; diff --git a/docs/timeline/index.html b/docs/timeline/index.html index 0b6f46c0e..297891498 100644 --- a/docs/timeline/index.html +++ b/docs/timeline/index.html @@ -1,3 +1,6 @@ + @@ -41,39 +44,7 @@ - - -
-
- -
-
- - +

Timeline

@@ -773,6 +744,13 @@

Configuration Options

If true, range of all items in the Timeline is draggable without being selected. If false, range is only draggable for the selected item(s). Only applicable when option itemsAlwaysDraggable.item is set true. + + loadingScreenTemplate + function + none + A template function used to generate the timeline initial loading screen. See section Templates for a detailed explanation. + + locale String @@ -2159,18 +2137,4 @@

Performance Tips

- - - - - - - - - - - - - - + diff --git a/docs/tmpl/html-foot.tmpl b/docs/tmpl/html-foot.tmpl new file mode 100644 index 000000000..fd3a494a0 --- /dev/null +++ b/docs/tmpl/html-foot.tmpl @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/tmpl/html-head.tmpl b/docs/tmpl/html-head.tmpl new file mode 100644 index 000000000..7fd3adb8a --- /dev/null +++ b/docs/tmpl/html-head.tmpl @@ -0,0 +1,40 @@ + + + + + + + + + + <?js= title ?> + + + + + + + + + + + + + + + + + + + + + +' purposely missing here, so that more stuff can be added to header */ ?> \ No newline at end of file diff --git a/docs/tmpl/navbar.tmpl b/docs/tmpl/navbar.tmpl new file mode 100644 index 000000000..884f7aa3a --- /dev/null +++ b/docs/tmpl/navbar.tmpl @@ -0,0 +1,48 @@ + +
+
+ +
+
+ + diff --git a/examples/network/edgeStyles/background.html b/examples/network/edgeStyles/background.html new file mode 100644 index 000000000..88ba71ed5 --- /dev/null +++ b/examples/network/edgeStyles/background.html @@ -0,0 +1,67 @@ + + + + Network | Edge background + + + + + + + + +

+ Edge background. +

+ +
+ + + + + + diff --git a/examples/network/nodeStyles/customGroups.html b/examples/network/nodeStyles/customGroups.html index e14a2acdd..b83999e54 100644 --- a/examples/network/nodeStyles/customGroups.html +++ b/examples/network/nodeStyles/customGroups.html @@ -20,7 +20,7 @@ - + diff --git a/examples/network/nodeStyles/icons.html b/examples/network/nodeStyles/icons.html index c44e5becc..8bbd2755d 100644 --- a/examples/network/nodeStyles/icons.html +++ b/examples/network/nodeStyles/icons.html @@ -1,4 +1,4 @@ - + @@ -8,7 +8,7 @@ - +