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.