idom-jupyter

A client for IDOM implemented using Jupyter widgets

Try It Now!

Check out some live examples by clicking the badge below:

Getting Started

To install use pip:

pip install idom_jupyter

Then, before anything else, do one of the following:

1. At the top of your notebook run

   import idom_jupyter

2. Register idom_jupyter as a permanant IPython extension in your config file:

   c.InteractiveShellApp.extensions = [
       'idom_jupyter'
   ]

Usage

Once you're done getting started, you can author and display IDOM layouts natively in your Jupyter Notebook:

import idom

@idom.component
def ClickCount():
    count, set_count = idom.hooks.use_state(0)
    return idom.html.button(
        {"onClick": lambda event: set_count(count + 1)},
        [f"Click count: {count}"],
    )

ClickCount()

You can also turn an idom element constructor into one that returns an ipywidget with the idom_juptyer.widgetize function. This is useful if you wish to use IDOM in combination with other Jupyter Widgets as in the following example:

ClickCountWidget = idom_jupyter.widgetize(ClickCount)
ipywidgets.Box(
    [
        ClickCountWidget(),
        ClickCountWidget(),
    ]
)

Alternatively just wrap an idom element instance in an idom_jupyter.LayoutWidget:

ipywidgets.Box(
    [
        idom_jupyter.LayoutWidget(ClickCount()),
        idom_jupyter.LayoutWidget(ClickCount()),
    ]
)

For a more detailed introduction check out this live demo here:

Development Installation

For a development installation (requires Node.js and Yarn version 1),

$ git clone https://github.com/idom-team/idom-jupyter.git
$ cd idom-jupyter
$ pip install -e .
$ jupyter nbextension install --py --symlink --overwrite --sys-prefix idom_jupyter
$ jupyter nbextension enable --py --sys-prefix idom_jupyter

When actively developing your extension for JupyterLab, run the command:

$ jupyter labextension develop --overwrite idom_jupyter

Then you need to rebuild the JS when you make a code change:

$ cd js
$ yarn run build

You then need to refresh the JupyterLab page when your javascript changes.