d3plus-project-template

A starter environment for D3plus modules.

Installing

If you use NPM, npm install d3plus-project-template. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom bundle using Rollup or your preferred bundler. You can also load directly from d3plus.org:

<script src="https://d3plus.org/js/d3plus-project-template.v0.3.full.min.js"></script>

Getting Started

This is the place to be if you want to create your own D3plus module. Here are the steps to get your module up and running:

1. Copy the contents of this repo into your new repository.
2. Install the Node Package Manager (NPM).

_{If on a Mac, we suggest using Homebrew to install packages on your machine. Once that's installed, you can install node (which includes npm) by running: brew install node}

3. Install all current dependencies:

npm i

And that's it! Now your environment should be all set up and ready to go.

Writing Code

With the introduction of modules in D3plus 2.0, all code is transpiled using buble, which allows usage of most of good bits from ES6. If you are unfamiliar with ES6, then normal vanilla javascript works fine as well. All source code lives in the /src/ director.

Running the Development Server

To test your code live in a browser, with auto-compiling and hot reloading, type this into your shell:

npm run dev

You can then go to http://localhost:4000/test/ in your preferred browser to test your code live.

Code Documentation

All of the Documentation you see in the README file is generated automagically based on the JSDoc formatted comments within each source file. This removes the nuscence of having to write documentation after the fact, and enforces strict code commenting. To regenerate the documentation, simply run:

npm run docs

Tests

Any time you write a new feature in your module, you should also be writing tests. D3plus modules come bundled with a test suite that let's you write tape tests using full ES6, which are then run directly in a headless Electron browser.

All tests need to be placed in the /test/ directory, and the filenames should match up to the components in /src/. To run all tests, run:

npm test

Examples

All D3plus 2.0 examples seen on d3plus.org are created from within their respective repositories. The examples are parsed from any markdown files placed in the /example/ directory, with the following rules:

Title

Example titles are extracted from the first H1 present in the file. Generally, the first line of the file will be the title:

## My Cool Example

Slug

The slug used in the URL on d3plus.org is taken directly from the filename. A file with the following path:

/example/my-cool-example.md

Would end up at the following URL:

https://d3plus.org/examples/d3plus-project-template/my-cool-example/

HTML

Any css, html, or js code block present in an example will be extracted and rendered into a static HTML file. This is what gets used on d3plus.org, and also let's us take screenshots!

Screenshots

A screenshot of each example is generated from the rendered HTML. By default, each screenshot is 990x400 in size, but specific dimensions can be given using markdown relative links:

[width]: 100
[height]: 100

For the purposes of this example, let's make a red square that will be rendered in HTML.

.square {
  background-color: red;
  height: 100px;
  width: 100px;
}

<div class="square"></div>

Click here to view this example live on the web.

API Reference

Sample

Kind: global class

• Sample
  • new Sample([data])
  • .constant([value])
  • .id([value])

new Sample([data])

A sample chainable function.

Param	Type	Default
[data]	Array	[]

Sample.constant([value])

If value is specified, sets the constant to the specified function or value and returns this generator. If value is not specified, returns the current constant.

Kind: static method of Sample

Param	Type	Default
[value]	function | Number | String	"sample"

Sample.id([value])

If value is specified, sets the id accessor to the specified function and returns this generator. If value is not specified, returns the current id accessor.

Kind: static method of Sample

Param	Type
[value]	function

Example

function(d) {
  return d.id;
}

_{Documentation generated on Fri, 07 Apr 2017 17:42:48 GMT}