Adding a widget to ipyreact

This section aims at helping developers to create new widgets within ipyreact. Here you will find how to create both the frontend and backend sides of a notebook extension.

Creating the frontend part

Notebook extensions source code lives in in nbextensions_srcs/. If you check it out, you will see that all the configuration files and necessary scripts. This source code is then transpiled to production code which is stored in nbextensions_dists/.

Directory structure

You will need to create a some mandatory files in order to create your widget

cd nbextensions_srcs/nbextensions
mkdir hello
cd hello
touch index.js hello.js

Minimal code example

Type the following lines in index.js:

import React from 'react'
import {CommWrapper} from '../../utils/commwrapper/commWrapper'
import HelloWidget from './hello'

export const load_ipython_extension = () => {
  CommWrapper("hello", HelloWidget)
}

This is your entry point, a piece of code that will make your React component available to Jupyter. Let’s look at the React component which will live in hello.js:

import React from 'react'
import Widget from '../../utils/widget/widget'

class HelloWidget extends Widget {
  render() {
    return <h1>Hello, World!</h1>
  }
}

export default HelloWidget

This is the minimum amount of code necessary to create a widget. You may then customize this component as you would do with any other React component.

Building your extension

In nbextensions_srcs, edit webpack.config.js and add your widget as a new entry:

var path = require('path')

module.exports = {
  entry: {
    breadcrumbs: './nbextensions/breadcrumbs/index.js',
    dialog: './nbextensions/dialog/index.js',
    // ...
    hello: './nbextensions/hello/index.js',
  },
  // ...
}

Then run yarn build for a production build or yarn dev for a development build.

Creating the backend part

Now that you have a minimal frontend that compiles to JavaScript, you want to invoke it in your notebook. To do so, you need Python code that will trigger rendering of the frontend part.

Directory structure

Enter the ipyreact Python package directory, then create a Python module named hello.py.

cd ipyreact
touch hello.py

develop

Copy paste the following into hello.py:

from ipyreact import Widget


class HelloWidget(Widget):

    def __init__(self):
        super().__init__("hello")

This is the minimum amount of code necessary to create the Python side of a widget. The argument passed to init should be the same as the first argument you passed to CommWrapper in your JavaScript code.

To make it easier to import your widget, edit ipyreact/__init__.py and append the following line:

from .hello import HelloWidget

To install it, from ipyreact root folder, run:

pip install .

Testing it in a notebook

Create a notebook, import your widget from ipyreact and instantiate it in a cell:

from ipyreact import HelloWidget
your_widget_instance = HelloWidget()
your_widget_instance

In this section you have seen the minimal amount of code to add a widget to ipyreact.