Overview

In order to get the best use out of this user guide it is important to have a grasp of some core concepts and ideas.

Components

Component refers to one of the three types of objects you will ordinarily be working with a Pane, Widget or Panel layout. To get an overview of the basic operation of different components see the Components user guide.

  • Pane: A Pane object wraps a user supplied object and turns it into a renderable view. When the wrapped object changes or any other parameters changes a pane will update the view accordingly.

  • Panel: A Panel layout is a container to arrange multiple components into a visual layout, a Panel may therefore also refer not specifically to the object but the combination of multiple components into a simple app.

  • Widget: A Widget is a control component which allows users to provide input to your app or dashboard either in Python or directly in Javascript.


Display and rendering

Throughout this user guide we will cover a number of ways to display panel objects, including display in the notebook, starting a server from the commandline, saving and embedding and more. For a detailed description see the Deploy and Export user guide.

Notebook

The documentation is built using Jupyter notebooks and Panel objects display themselves in a notebook when placed on the last line of a notebook cell.

pn.extension()

The panel extension loads BokehJS, any custom models required and optionally custom JS and CSS in Jupyter notebook environments.

.app()

The .app() method present on all panel objects allows displaying an panel server inline in a notebook.

Python REPL

When working in a Python REPL which does not support rich-media output a panel can be still be launched.

.show()

The .show() method is present on all viewable panel objects and starts a server instance and opens a browser window to point to it. When working remotely a specific port to launch the app on can be supplied.

Commandline

Panel mirrors bokeh's commandline interface for launching and exporting apps and dashboards.

panel serve app.py

The panel serve command allows allows interactively displaying and deploying Panel apps from the commandline.

Export

When not working interactively a panel object can be exported to a static file.

.save()

The .save method present on all viewable panel objects allows saving panel objects to HTML or PNG files.

Embedding

Embedding refers to the ability of a Panel object to serialize the widget state space into JSON which can be embedded in the notebook or as separate files and allow simple apps to be served without running a server.


Linking and callbacks

One of the most important aspects of a general app and dashboarding framework is the ability to link different components in flexible ways and schedule callbacks in response to internal and external events. Panel provides convenient lower and higher-level APIs to achieve both for more details see the Links and the Callbacks user guide.

.param.watch

The .param.watch method allows listening to parameter changes on an object using Python callbacks. It is the lowest level API and provides the most amount of control.

.link()

The .link() method present on all viewable panel objects is a convenient API to link the parameters of two objects together, uni- or bi-directionally.

.jslink()

The .jslink() method links the properties of the underlying bokeh models making it possible to define interactivity which works without a running server.


Interfaces

Panel provides three main interfaces for building GUIs and dashboards, each of which has different benefits and drawbacks.

Component API

At the lowest level you can build interactive components entirely using Pane, Widget and Panel components. By registering callbacks on components to modify other components provides a huge amount of flexibility in building interactive features but a lot of callbacks can often be difficult to keep track of. In other words this approach affords the most amount of flexibility but can easily grow in complexity. See the Widgets user guide

Param

Panel itself is built on the param library which allows expressing parameters on classes entirely independently of any GUI code. By using param to declare the parameters along with methods that depend on those parameters complex GUIs can be encapsulated in tidy, well-organized and declarative way. Panel will automatically convert parameter definition to corresponding widgets. This API requires the use of the param library to express the inputs and encapsulate the computations to be performed but once implemented this approach can lend itself to neat, well encapsulated code. See the Param user guide for more detail.

interact

The interact API will be familiar to ipywidgets users; it provides a very simple API to define an interactive view which depends on a number of arguments. This approach works by declaring functions whose arguments will be inspected to infer a set widgets of widgets to control the display output. This approach makes it extremely easy to get started and even allows re-arranging the widgets and plots in different ways but may not be suited to more complex scenarios. See the Interact user guide for more detail.


Right click to download this notebook from GitHub.