|
| 1 | +# d3 process map |
| 2 | + |
| 3 | +This is a PHP web application that displays a directed acyclic graph in a |
| 4 | +modern web browser using [d3.js](http://d3js.org/). It is designed for |
| 5 | +illustrating the relationships between objects in a process. |
| 6 | + |
| 7 | +### Examples |
| 8 | + |
| 9 | +#### Data manipulation and reporting process: |
| 10 | + |
| 11 | +http://nylen.tv/d3-process-map/ |
| 12 | + |
| 13 | +#### Co-occurrences of Les Miserables characters: |
| 14 | + |
| 15 | +http://nylen.tv/d3-process-map/?dataset=les-mis |
| 16 | + |
| 17 | +### Features |
| 18 | + |
| 19 | +* Hover over a node to see that object's relationships. (Unrelated objects and |
| 20 | + links will be made partially transparent.) |
| 21 | +* Click on a node to show the documentation for that object. |
| 22 | +* Click the "View list" button to view the documentation for all objects (good |
| 23 | + for printing). |
| 24 | + |
| 25 | +### Data format |
| 26 | + |
| 27 | +The application can display one or more datasets located in the `data/` folder. |
| 28 | +Each dataset gets its own folder. There are two datasets bundled with the |
| 29 | +application (one for each of the examples above). Switch between datasets by |
| 30 | +appending `?dataset=folder-name` to the URL. If no dataset name is given, the |
| 31 | +dataset in the `default` folder will be displayed. |
| 32 | + |
| 33 | +Each dataset should contain the following files: |
| 34 | + |
| 35 | +* `objects.json` |
| 36 | +* `config.json` |
| 37 | +* `*.mkdn` (one per object) |
| 38 | + |
| 39 | +#### `objects.json` |
| 40 | + |
| 41 | +An array of data objects to be displayed as graph nodes, each with the |
| 42 | +following properties: |
| 43 | + |
| 44 | +* `name`: The name of this object |
| 45 | +* `type`: The type of this object (e.g. `view`, `table`, etc.) |
| 46 | +* `depends`: An array of object names that this object depends on. |
| 47 | +* `group` (optional): This could be thought of as a "subtype". |
| 48 | + |
| 49 | +#### `config.json` |
| 50 | + |
| 51 | +A JSON object which contains the following fields: |
| 52 | + |
| 53 | +* `title`: The page title. |
| 54 | +* `graph`: The parameters for the graph and the d3.js force layout. |
| 55 | + * `linkDistance`: The |
| 56 | + [link distance](https://github.com/mbostock/d3/wiki/Force-Layout#wiki-linkDistance) |
| 57 | + for the d3.js force layout. |
| 58 | + * `charge`: The |
| 59 | + [charge](https://github.com/mbostock/d3/wiki/Force-Layout#wiki-charge) |
| 60 | + for the d3.js force layout. |
| 61 | + * `height`: The height of the graph, in pixels. (The width of the graph is |
| 62 | + determined by the width of the browser window when the page is loaded.) |
| 63 | + * `numColors`: The number of colors to display (between **3** and **12**). |
| 64 | + * `labelPadding`: The padding inside the node rectangles, in pixels. |
| 65 | + * `labelMargin`: The margin outside the node rectangles, in pixels. |
| 66 | +* `types`: Descriptions of the object types displayed in this graph, each with |
| 67 | + a `long` and a `short` field that describe the object type for documentation |
| 68 | + and for the graph legend, respectively. |
| 69 | +* `constraints`: An array of objects that describe how to position the nodes. |
| 70 | + Each constraint should have a `type` field whose value should be either |
| 71 | + `'position'` or `'linkStrength'`, and a `has` field that specifies the |
| 72 | + conditions an object must meet for the constraints to be applied. |
| 73 | + * **Position constraints**: These constraints should have the properties |
| 74 | + `weight`, `x` (optional) and `y` (optional). On each iteration of the |
| 75 | + force layout, node positions will be "nudged" towards the `x` and/or `y` |
| 76 | + values given, with a force proportional to the `weight` given. |
| 77 | + * **Link strength constraints**: These constraints should have the property |
| 78 | + `strength`, which is a multiplier on the link strength of the links to and |
| 79 | + from the objects that the constraint applies to. This can be used to relax |
| 80 | + the position of certain nodes. |
| 81 | + |
| 82 | +#### `*.mkdn` |
| 83 | + |
| 84 | +Each object can have a Markdown file associated with it for additional |
| 85 | +documentation. The syntax is |
| 86 | +[standard Markdown](https://daringfireball.net/projects/markdown/syntax) with |
| 87 | +one addition: object names can be enclosed in `{{brackets}}` to insert a link |
| 88 | +to that object. |
| 89 | + |
| 90 | +If an object's name contains a slash (`/`), replace it with an underscore (`_`) |
| 91 | +in the documentation filename. |
| 92 | + |
| 93 | +### Other details |
| 94 | + |
| 95 | +The code uses a |
| 96 | +[d3.js force layout](https://github.com/mbostock/d3/wiki/Force-Layout) to |
| 97 | +compute object positions, with |
| 98 | +[collision detection](http://bl.ocks.org/mbostock/3231298) to prevent nodes |
| 99 | +from overlapping each other. |
| 100 | + |
| 101 | +Nodes are colored by the |
| 102 | +[ColorBrewer Set3 scheme](http://colorbrewer2.org/?type=qualitative&scheme=Set3&n=12), |
| 103 | +with colors assigned by the combination of the object's `type` and `group`. |
| 104 | + |
| 105 | +To ensure that the arrows on the ends of the links remain visible, the links |
| 106 | +only extend to the outer edge of the target object's node. |
| 107 | + |
| 108 | +### Browser support |
| 109 | + |
| 110 | +Works in recent versions of Chrome and Firefox. Other browsers have not been |
| 111 | +tested, but Internet Explorer doesn't stand a chance until at least version 9. |
0 commit comments