Goto Chapter: Top 1 2 3 Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

3 Adding new visualization tools
 3.1 Why you might want to do this
 3.2 What you will need
 3.3 The appropriate procedure

3 Adding new visualization tools

3.1 Why you might want to do this

The visualization tools made available by this package (Plotly, D3, CanvasJS, etc.) provide many visualization options. However, you may come across a situation that they do not cover. Or a new and better tool may be invented after this package is created, and you wish to add it to the package.

Currently, the only supported way to do this is to alter the package code itself. In the future, it would be nice to make it so that you can register new visualization tools with the package without modifying the package code. But until then, this is the supported method.

3.2 What you will need

Before proceeding, you will need the following information:

3.3 The appropriate procedure

Throughout these steps, I will assume that the name of the new tool you wish to install is NEWTOOL. I choose all capital letters to make it stand out, so that you can tell where you need to fill in blanks in the examples, but you should probably use lower-case letters, to match the convention used by all of the built-in tools.

  1. Clone the repository for this package.

  2. Enter the lib/js/ folder in the repository.

  3. Duplicate the file viz-tool-chartjs.js and rename it suitably for the tool you wish to import, such as viz-tool-NEWTOOL.js. It must begin with viz-tool-.

  4. Edit that file. At the top, you will notice the installation of the CDN URL mentioned in the previous section. Replace it with the URL for your toolkit, and replace the identifier chartjs with NEWTOOL.

    window.requirejs.config( {
        paths : {
            NEWTOOL : 'https://cdn.example.com/NEWTOOL.min.js'
        }
    } );
    
  5. In the middle of the same file, feel free to update the comments to reflect your toolkit rather than ChartJS.

  6. At the end of the same file, you will notice code that installs chartjs as a new function in the window.VisualizationTools object. Replace it with code that installs your tool instead. See the comments below for some guidance.

    window.VisualizationTools.NEWTOOL = function ( element, json, callback ) {
        // The variable "element" is the output cell in the notebook into
        // which you should place your visualization.  For example, perhaps
        // your new toolkit draws in SVG elements, so you need one:
        var result = document.createElement( 'SVG' );
        element.append( result );
        // The variable "json" is all the data, in JSON form, passed from
        // GAP to tell you how to create a visualization.  The data format
        // convention is up to you to explain and document with your new
        // tool.  Two attributes in particular are important here, "width"
        // and "height" -- if you ignore everything else, at least respect
        // those in whatever way makes sense for your visualization.  Here
        // is an example for an SVG:
        if ( json.width ) result.width = json.width;
        if ( json.height ) result.width = json.height;
        // Then use RequireJS to import your toolkit (which will use the CDN
        // URL you registered above) and use it to fill the element with the
        // desired visualization.  You may or may not need to modify "json"
        // before passing it to your toolkit; this is up to the conventions
        // you choose to establish.
        require( [ 'NEWTOOL' ], function ( NEWTOOL ) {
            // Use your library to set up a visualization.  Example:
            var viz = NEWTOOL.setUpVisualizationInElement( result );
            // Tell your library what to draw.  Example:
            viz.buildVisualizationFromJSON( json );
            // Call the callback when you're done.  Pass the element you were
            // given, plus the visualization you created.
            callback( element, result );
        } );
    };
    
  7. Optionally, in the lib/js/ folder, run the minify-all-scripts.sh script, which compresses your JavaScript code to save on data transfer, memory allocation, and parsing time. Rerun that script each time you change your file as well.

  8. You should now be able to use your new visualization tool in GAP. Verify that your changes worked, and debug as necessary. You may be able to notice the change only if you refresh in your browser the page containing the Jupyter notebook in question and also restart the GAP kernel in that same page. Then try code like the following in the Jupyter notebook to test what you've done.

    CreateVisualization( rec(
        tool := "NEWTOOL",
        # any other data you need goes here
    ) );
    
  9. Once your changes work, commit them to the repository and submit a pull request back to the original repository, to have your work included in the default distribution.

A complete and working (but silly) example follows. This portion would go in lib/js/viz-tool-color.js:

// No need to import any library from a CDN for this baby example.
window.VisualizationTools.color = function ( element, json, callback ) {
    // just writes json.text in json.color, that's all
    var span = document.createElement( 'span' );
    span.textContent = json.text;
    span.style.color = json.color;
    callback( element, span );
};

This is an example usage of that simple tool from GAP in a Jupyter notebook:

CreateVisualization( rec(
    tool := "color",
    text := "Happy St. Patrick's Day.",
    color := "green"
) );
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 Ind

generated by GAPDoc2HTML