Skip to content

jupyterlab/extension-examples

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

JupyterLab Extensions by Examples

Github Actions Status Binder

  1. Goal
  2. Develop by Examples
    1. Commands
    2. Command Palette
    3. Main Widget Content Header
    4. Context Menu
    5. Custom Log Console
    6. Datagrid
    7. Hello World
    8. Kernel Messaging
    9. Kernel Output
    10. Launcher
    11. Log Messages
    12. Main Menu
    13. React Widget
    14. Server Hello World
    15. Settings
    16. Signals
    17. State
    18. Toolbar Item
    19. Widgets
  3. Prerequisites
  4. Develop and Use the Examples
  5. Test the Examples
  6. Install a Published Extension
  7. About JupyterLab
  8. Credits
  9. Community Guidelines and Code of Conduct

TL;DR

The goal of this repository is to show how to develop extensions for JupyterLab, presented as short tutorial series.

To get started:

# clone the repository
git clone https://github.com/jupyterlab/extension-examples.git jupyterlab-extension-examples

# go to the extension examples folder
cd jupyterlab-extension-examples

# create a new environment
conda env create

# activate the environment
conda activate jupyterlab-extension-examples

# go to the hello world example
cd hello-world

# install the extension in editable mode
python -m pip install -e .

# install your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# build the TypeScript source after making changes
jlpm run build

# start JupyterLab
jupyter lab

The examples currently target JupyterLab 3.1 or later.

If you would like to use the examples with JupyterLab 2.x, check out the 2.x branch.

If you would like to use the examples with JupyterLab 1.x, check out the 1.x branch.

Note that the 1.x and 2.x branches are not updated anymore.

Develop by Examples

You may find it easier to learn how to create extensions by examples, instead of going through the documentation.

Start with the Hello World and then jump to the topic you are interested in.

You can expect from each example:

  • An explanation of its functionality.
  • An image or screencast showing its usage.
  • The list of used JupyterLab API and Extension Points.
  • Explanations of the internal working, illustrated with code snippets.

We have structured the examples based on the extension points. Browse the previews below or skip them and jump directly to the sections for developers.

You are welcome to open any issue or pull request.

Commands

Extend the main app with a Command.

Commmand example

Command Palette

Register commands in the Command Palette.

Commmand Palette

Completer

Customize tab autocomplete data sources.

Completer

Main Widget Content Header

Put widgets at the top of a main JupyterLab area widget.

contentHeader

Context Menu

Add a new button to an existent context menu.

Context Menu

Custom Log Console

Create a new log console.

Custom Log Console

Datagrid

Display a Datagrid as a Lumino Widget.

Datagrid

Documents

Create new documents and make them collaborative.

Documents

Hello World

Set up the development environment and print to the console.

Hello World

Kernel Messaging

Interact with a kernel from an extension.

Kernel Messages

Kernel Output

Render kernel messages in an OuputArea.

OutputArea class

Launcher

Start your extension from the Launcher.

Launcher

Log Messages

Send a log message to the log console.

Log Messages

Main Menu

Add a Menu to the main app.

Main Menu

React Widget

Create a React.js Widget in JupyterLab.

react-widget

Server Hello World

Create a minimal extension with backend (i.e. server) and frontend parts.

Server Hello World

Settings

Create and use new Settings for your extension.

Settings

Signals

Use Signals to allow Widgets communicate with each others.

Button with Signal

State

Use State persistence in an extension.

State

Toolbar Item

Add a new button to the notebook toolbar.

Toolbar button

Widgets

Add a new Widget element to the main window.

Custom Tab

Prerequisites

Writing an extension requires basic knowledge of JavaScript, Typescript and potentially Python.

Don't be scared of Typescript, even if you never coded in TypeScript before you touch JupyterLab you may find it easier to understand than pure JavaScript if you have a basic understanding of object oriented programming and types.

These examples are developed and tested on top of JupyterLab. You can create a conda environment to get started after cloning this repository.

conda env create && \
  conda activate jupyterlab-extension-examples

The previous command will use the environment.yaml file as requirements for the environment.

Develop and Use the Examples

Build and Install all Examples at once

jlpm
jlpm build-ext
jlpm install-py
jlpm install-ext
jupyter lab

To rebuild all the extensions:

jlpm build-ext

To clean the lib folders:

jlpm clean-ext

Build and Install one Example

Go to the example directory you want to install, e.g. cd ./hello-world, and run the following commands:

pip install -e .
jupyter labextension develop . --overwrite

Rebuild the extension:

jlpm run build

You can now start JupyterLab and check if your extension is working fine:

jupyter lab

Change the Sources

If you want to develop and iterate on the code, you will need to open 2 terminals.

In terminal 1, go to the extension folder and run the following:

jlpm watch

Then in terminal 2, start JupyterLab with the watch flag:

jupyter lab --watch

From there, you can change your extension source code, it will be recompiled, and you can refresh your browser to see your changes.

We are using embedme to embed code snippets into the markdown READMEs. If you make changes to the source code, ensure you update the README and run jlpm embedme from the root of the repository to regenerate the READMEs.

Test the Examples

The examples are automatically tested for:

  • Homogeneous configuration:
    Configuration files are compared to the reference ones of the hello-world example
  • TypeScript code lint
  • Installation in JupyterLab:
    The installation is checked by listing the installed extension and running JupyterLab with the helper python -m jupyterlab.browser_check
  • Integration test:
    Those tests are emulating user action in JupyterLab to check the extension is behaving as expected.
    The tests are defined in the ui-tests subfolder within each example. This is possible thanks to a tool called playwright.

Install a Published Extension

Once your extension is published on pypi.org (outside of this scope), you can install it with the following command:

pip install <published_extension>

About JupyterLab

JupyterLab can be used as a platform to combine existing data-science components into a new powerful application that can be deployed remotely to many users. Some of the higher level components that can be used are text editors, terminals, notebooks, interactive widgets, filebrowser, renderers for different file formats that provide access to an enormous ecosystem of libraries from different languages.

Complementary to these examples, you can rely on the official JupyterLab documentation.

Credits

We would like to thank MMesch for initiating this work, as well as everyone else who contributed!

Community Guidelines and Code of Conduct

This examples repository is a Jupyter project and follows the Jupyter Community Guides and Code of Conduct.