jupyter_contrib_nbextensions/docs/source/internals.rst

.. module:: jupyter_contrib_nbextensions.nbconvert_support

Notebook extension structure
============================

The nbextensions are stored each as a separate subdirectory of
`src/jupyter_contrib_nbextensions/nbextensions`

Each notebook extension typically has its own directory containing:

* `thisextension/main.js`: javascript implementing the nbextension
* `thisextension/main.css`: optional CSS
* `thisextension/readme.md`: readme file describing the nbextension in markdown format
* `thisextension/config.yaml`: file describing the nbextension to the `jupyter_nbextensions_configurator` server extension

The file names do not need to have the shown names, they can be choosen freely.
This is an example for the `main.js` file:

.. code-block:: javascript

    define([
        'jquery',
        'base/js/namespace',
        'base/js/utils',
        'services/config'
    ], function (
        $,
        IPython,
        utils,
        configmod,
    ) {
        "use strict";

        // define default values for config parameters
        var params = {
            my_config_value : 100
        };

        // create config object to load parameters
        var base_url = utils.get_body_data("baseUrl");
        var config = new configmod.ConfigSection('notebook', {base_url: base_url});

        // update params with any specified in the server's config file
        var update_params = function() {
            for (var key in params) {
                if (config.data.hasOwnProperty(key))
                    params[key] = config.data[key];
            }
        };

        // will be called when the config parameters have been loaded
        config.loaded.then( function() {
            update_params();

        });

        function config_loaded_callback () {
            $.extend(true, params, config.data.thisextension);
        };

        // will be called when the nbextension is loaded
        var load_ipython_extension = function () {
            config.load(); // trigger loading config parameters

        };

        // return public methods
        return {
            load_jupyter_extension : load_jupyter_extension
        };
    });

And for the `config.yaml` file:

.. code-block:: yaml

    Type: Jupyter Notebook Extension
    Compatibility: 4.x
    Name: thisextension
    Main: main.js
    Icon: icon.png
    Link: README.md
    Description: My super duper extension
    Parameters:
    - name: my_config_value
      description: A configuration parameter
      input_type: number
      min: -1
      step: 1
      default: 100

When supplying a `readme.md` file, please supply a main heading with the
nbextension's title, as this will be linked in the generated documentation at
`jupyter-contrib-nbextensions.readthedocs.io <http://jupyter-contrib-nbextensions.readthedocs.io/en/latest>`__.
This is a simple example for `readme.md`::

    This extension
    ==============

    How to use
    ----------
    Some description here.

    ![Screenshot image](screenshot.png)

    Internals
    ---------
    How this extension works.