Use the web interface to import custom visualizations. Custom visualizations are installed via npm, you simply need to know the name of the module that you want to import. To search for available modules use this link to find npm modules tagged with "lightning-visualization"

Plotting a custom visualization from the API client

Creating a visualization with this new custom type is similar to creating any other type of plot.

from lightning import Lightning
from numpy import random
lgn = Lightning()

data = random.random(100)

# typical plot
lgn.line(data)

# custom plot
lgn.plot(data, type='my-custom-lightning-viz')

In addition to Lightning’s core visualization types, users can easily develop their own plots, either by modifying the existing ones, or designing visualizations from scratch. This section serves as a walkthrough to create a custom visualization. At their core custom visualizations are simply npm modules conforming to a certain specifications.

To facilitate the development of these modules, we provide a yeoman generator. The generator can be found on github here. To install the generator run the following commands (must have node installed):

$ [sudo] npm install -g yo # install yeoman
$ [sudo] npm install -g generator-lightning-viz

After installing the generator you can use it to scaffold out a custom visualization:

$ mkdir my-custom-lightning-viz
$ cd my-custom-lightning-viz
$ yo lightning-viz

The yo lightning-viz command tells yeoman to build out the skeleton of a lightning visualization in the current directory. You should now have a folder with the following structure:

You'll notice the following components:

• README- contains info about your visualization
• data/- a special folder for including sample datasets and a thumbnail image of the visualization
• index.js- the javascript entry point, you shouldn't need to touch this file
• package.json- the npm specification for your package. If the visualization has any external dependencies, e.g. d3.js they should be listed here.
• src/- the folder with the source code. View the index.js file here to start editing the visualization.

src/index.js

This is the main file for your visualization. (note: because this is simply an npm module you are free to structure the files however you like, just make sure that the module exports a LightningVisualization object):

var LightningVisualization = require('lightning-visualization');
var _ = require('lodash');

/* 
 * Uncomment this code to require an optional stylesheet
 */
// var fs = require('fs');
// var styles = fs.readFileSync(__dirname + '/styles/style.css');

/*
 * Extend the base visualization object
 */
var Visualization = LightningVisualization.extend({
    getDefaultOptions: function() {
        /*
         * If the visualization takes options provide sensible
         * defaults here.
         */
        return {
        };
    },
    
    init: function() {
        /*
         * FILL IN Add any logic for initializing the visualization
         *
         * the following are available:
         *
         * this.width - visualization container width
         * this.height - visualization container height
         * this.el - visualization container dom node
         * this.data - visualization data (that has been passed through the formatData function)
         * this.options - options that have been passed to the visualization
         */
         
        this.render();
    },
    
    /*
     * optionally pass a string of CSS styles 
     */
    // styles: styles,
    
    render: function() {
        /*
         * FILL IN Render the visualization
         */
         
        /*
         * FILL IN Get data / selector from this.data and this.selector
         */
    },
    
    formatData: function(data) {
        /*
         * Format your data from a raw JSON blob
         */
        return data;
    },
    
    updateData: function(formattedData) {
        this.data = formattedData;
        /*
         * FILL IN Re-render your visualization
         */
    },
    
    appendData: function(formattedData) {    
        /*
         * FILL IN Update this.data to include the newly formatted data
         */
         
        /*
         * FILL IN Re-render the visualization
         */    
    }
    
});


module.exports = Visualization;

Adding external dependencies

To include a dependency on a third party library (e.g. d3.js, react, etc.) you can install them via npm. Note that the visualizations are compiled via browserify, so any 3rd party library must be browserify compatible.

To install and save a dependency simultaneously, use the following command inside the top level of your custom viz folder:

$ npm install --save 

This library can now be required in your javascript code. To learn more about browserify visit http://browserify.org/

Developing and testing locally

To test a custom visualization locally, you must first notify npm that it is available on your filesystem. To do this run:

$ npm link .

from inside the root of your custom viz folder:

The visualization can imported or previewed in lightning. Use the "preview" option while developing to see changes:

Once you are happy with the visualization import it into lightning. You can then start plotting data with this visualization type.

Sharing your code with others

To allow others to use your visualization, publish it to npm. First make sure that you are logged in to your npm account (the same command can also be used to create an account):

$ npm adduser

Then create a tag with a new version number. NPM has a tool to do this automatically:

$ npm version patch # options are major, minor, or patch

The major|minor|patch options correspond to X.Y.Z in the semantic versioning system. Your package starts at 0.0.0 so e.g. a major version bump would be 1.0.0 but a patch version bump would be 0.0.1. This version number is stored in the package.json file.

Then push the change to git and publish to npm

$ git push origin master --tags # only do this if you are using git for version control 
$ npm publish .

That's it!