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.
Component refers to one of the three types of objects you will ordinarily be working with a
Panel layout. To get an overview of the basic operation of different components see the Components user guide.
Paneobject wraps a user supplied object and turns it into a renderable view. When the wrapped
objectchanges or any other parameters changes a pane will update the view accordingly.
Panellayout 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.
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.
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.
The panel extension loads BokehJS, any custom models required and optionally custom JS and CSS in Jupyter notebook environments.
.app()method present on all panel objects allows displaying an panel server inline in a notebook.
When working in a Python REPL which does not support rich-media output a panel can be still be launched.
.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.
Panel mirrors bokeh's commandline interface for launching and exporting apps and dashboards.
panel serve app.py¶
panel servecommand allows allows interactively displaying and deploying Panel apps from the commandline.
When not working interactively a panel object can be exported to a static file.
.savemethod present on all viewable panel objects allows saving panel objects to HTML or PNG files.
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.watchmethod 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()method present on all viewable panel objects is a convenient API to link the parameters of two objects together, uni- or bi-directionally.
.jslink()method links the properties of the underlying bokeh models making it possible to define interactivity which works without a running server.
Panel provides three main interfaces for building GUIs and dashboards, each of which has different benefits and drawbacks.
At the lowest level you can build interactive components entirely using
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
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 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.