dtd-diagram

v0.2.1

Published

2 years ago

Animated tree diagrams for XML DTDs

Downloads

0High
0Medium
0Low

klortho

d3 dtd xml

Interactive, animated DTD schema diagrams

See the demo.

This is a D3 implementation of the old XML Near & Far diagrams. See this Key to the Near & Far Diagrams and the following pages, for examples of what Near & Far diagrams look like.

This page

Implementation

Current status and to-do list

Getting started

To run from your own machine, you can use Bower, and add this as a dependency:

bower install dtd-diagram --save

Or, you download it and its dependencies manually:

To integrate it with your own DTD, you'll want to clone it and initialize a development environment, which includes DtdAnalyzer, used to convert DTDs into the JSON files that this tool consumes.

Make sure you have Node.js and npm installed, and then install gulp globally (if you haven't already). This makes the gulp command available on the command line:

npm install -g gulp

Then clone the repo, and build it:

git clone https://github.com/Klortho/dtd-diagram.git
cd dtd-diagram
npm install
gulp

Check that it worked, by bringing up the project folder in a web browser.

To generate JSON versions of DTDs, you'll need to set your PATH to include the vendor/dtd-analyzer directory, and then, for example, for the test DTD:

dtdanalyzer --roots doc --xslt daz2json.xsl test/test2.dtd > test2.json

To work with one of the JATS DTDs, you could do this:

dtdanalyzer --roots article --xslt daz2json.xsl \
  http://jats.nlm.nih.gov/publishing/1.1d3/JATS-journalpublishing1.dtd \
  > JATS-journalpublishing1.json

Then, in the HTML file that invokes the diagram, set options to load the correct DTD JSON file, and to cause documentation hyperlinks to go to the right place. (see the index.html page for an example):

<div id='dtd-diagram'
     data-options='{
         "dtd_json_file": "JATS-journalpublishing1.json",
         "tag_doc_base": "http://jatspan.org/niso/publishing-1.1d3/#p="
     }'></div>

To work on the JavaScript modules, and have gulp watch for changes, and automatically build the combined, minified files, start a watcher in a terminal with:

gulp watch

API

The simplest way to use this is to load the code in a page that has a pre-existing <div> element with id value "dtd-diagram". For example:

<head>
  ...
  <link rel="stylesheet" type="text/css" href="dtd-diagram.css">
  <script src='es6-promise.js'></script>
  <script src="d3.min.js"></script>
  <script src="d3-flextree.js"></script>
  <script src="dtd-diagram.js"></script>
  ...
</head>
<body>
  ...
  <div id='dtd-diagram'></div>
  ...
</body>

By default, if you include the JavaScript in your HTML page, then a DtdDiagram will be instantiated at document ready, using all the default options. If you want to prevent this behavior, then set auto_start to false, before document ready. This will let you control when a diagram is created, based on (for example) user events. For example:

<head>
  ...
  <script type="text/javascript" src="dtd-diagram.js"></script>
  ...
</head>
<body>
  ...
  <div id='dtd-diagram'></div>
  <input id='button' type='button' />
  ...
  <script type="text/javascript">
    DtdDiagram.auto_start = false;
    ...
    $('#button').on("click", function() {
      new DtdDiagram();
    };
  </script>
</body>

If you create your own diagram object before document ready, that will also suppress the auto-creation. This allows you to easily override default options. For example,

<script type="text/javascript" src="dtd-diagram.js"></script>
<script type="text/javascript">
  new DtdDiagram({
    duration: 5000,
  });
</script>

You can also set options on the <div> element, in the data-options attribute, in valid JSON format.

<div id='dtd-diagram'
     data-options='{"root_element": "back"}'>
</div>

You can get a list of all of the diagrams on a page from DtdDiagram.diagrams.

Options

FIXME: need to update this list.

There are various ways to set the options; in order of higher-to-lower precedence:

Pass them as an object to the DtdDiagram constructor function.
Set them on the @data-options attribute of the <div> element. Make sure they are in strictly valid JSON format.
Use the defaults

dtd_json_file

The DTD JSON file; default is "dtd.json".

root_element

The root element, by default, is read from the DTD file, but can be overridden. Default is null.

tag_doc_base

Used as the base URL for links from the element and attribute nodes to documentation. Default is "doc/#p=".

tag_doc_url

By default, this is not used. You can set this to a function that takes a Node object as an argument, and returns a string with the URL of the documentation page.

min_canvas_width, min_canvas_height

Initial value for the diagram's size.

group_separation

Ratio of the separation between groups to the separation between sibling nodes. By default, this is 1.4.

duration

Duration of the animation, in milliseconds. Default is 500.

rebase_handler

You can set this to a callback function that will be invoked whenever the user rebases the diagram.

Implementation

See Implementation.md

Credits / references

Liam Quinn, W3C. See his paper, Diagramming XML: Exploring Concepts, Constraints and Affordances, 2015.
D3, see this example.

License

See LICENSE.txt.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme