paulopes / panel-components

HTML components for Panel templates

panel-components

Panel is a powerful 💪 framework for creating awesome analytics apps in Python 🐍 using the tools you know 🧠 and love ❤️.

The purpose of the panel-components package is to enable users of Panel to create data applications with a modern look and feel by making it easy to integrate with

• modern front end frameworks like Vue.js and React.
• Component libraries like Bootstrap Vue, Material UI, Shoelace and Fast.
• Any awesome .js library for data visualization and exploration.

The panel-components package does this by providing

• A general framework for creating html components for Panel. See component.py.
  • This includes html components based on Vue or React.
• The basic HTML5 components. See tags.py.
• A Vue.js component. See vue.py.

License

Licensed under the Apache License, Version 2.0

Getting Started

Installation

You can install via pip.

• pip install panel-components.

Installing via

• pip install -e git+https://github.com/paulopes/panel-components.git or
• conda install

is currently not supported.

Examples

Hello World

Let's try a Hello World example.

File: hello_world.py

from panel_components.tags import h1

layout = h1("Hello World")

layout.servable()

panel-bootstrap-vue

The panel-bootstrap-vue package wraps the Bootstrap Vue component library and enables integration with Panel.

Contributing

Developer Instructions

In order to install this repo for development you should

• Fork it
• Git clone your Fork
• Create a virtual environment in the root of the project folder

python -m venv .venv

• Activate it via source .venv/Scripts/activate for git bash on windows and similar commands in other environments.
• pip install panel.
• Set your PYTHONPATH to the project root.

There are currently no tests with which you can verify everything is working.

panel-components's Issues

Add tests

Having tests would

• enable contributors to safely refactor and improve the code.
• enable contributors and advanced users how to use the code.
• Provide an indicator of quality when potential new users evaluate whether or not to use the package.

Add Docstrings

Having docstrings would help a new user or contributor a lot. :-)

Fix Bokeh/ Panel version problems

I'm running Panel 0.9.7 and Bokeh 2.2.1 and panel-components 0.1.1 and it does not work together.

I get a Error rendering Bokeh items: either 'docid' or 'sessionid' was expected... See #5 (comment).

The problem is that the sessionid is something from an old version of Bokeh.

Solution

• Update local versions and CDN versions of Bokeh and Panel to latest version.
  • Add the version number to the name.
• State in the README, setup.py and pyproject.toml which versions of Panel and Bokeh are supported.

Alternatively automatically use the version of Bokeh and Panel assets compatible with the installed version of Panel and Bokeh.

Alternative context

Currently the pyproject.toml states

which as I understand it is incorrect.

Add .show() method to Component

I often use the .show() method because

• .servable() does not provide a good debugging experience. My terminal just freezes when reaching a breakpoint().
• .show() works great with breakpoint() and the integrated debugging in VS Code.

I can see the .show() method is not a method on the Component.

Solution

Add .show() to Component to support

from panel_components.tags import h1

layout = h1("Hello World")
layout.show(port=5007)

Workaround

For now layout.servable().show() in the above example can be used as a workaround.

Please implement in a way that provides context information in an Editor.

I've been sitting here trying to wrap my head around how to use this. I simply do not understand how to get started.

Solution

• Please provide some examples (or example links) and screenshots in the README.
• Please refactor the implementation so that static analysis can be done and help context help provided in editors

But unfortunately this means that I get no context help/ intellisense when working in an editor like VS Code.

One way to enable static analysis would be to auto generate code strings with docstrings from the list of tags.

Cannot pip install -e . the repository

Hi Paulopes

I would like to git clone the repository and work a little bit with it but I get the error.

$ pip install -e .
ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: C:\repos\private\panel-components
(A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.)

Solution

Provide setup.py file or describe how you would install this for development.

Add bidirectional communication

This is used for discussing how to add bidirectional communication.

I have something working. I think the principle will work fine.

import panel as pn
import param

from awesome_panel_extensions.data_models import ParameterizedModel
from awesome_panel_extensions.frameworks.fast import FastTemplate

HTML = """
<fast-text-field id="text-1" placeholder="name"></fast-text-field></br>
<fast-checkbox id="checkbox-1">Checkbox</fast-checkbox></br>
<fast-slider style="width:200px" min="0" max="100" step="1" value="10"></fast-slider></br>
<fast-slider id="slider-2" style="width:200px" min="0" max="1" step="0.01"></fast-slider></br>
<fast-tree-view></fast-tree-view>
<fast-button id="button-1">Click Me</fast-button>
"""

INNER_HTML = """
<fast-tree-item>Tree item 1<fast-tree-item slot="item">Tree item 1 - 1</fast-tree-item>
</fast-tree-item>
<fast-tree-item>Tree item 2</fast-tree-item>
"""


def test_app():
    class ExampleClass(ParameterizedModel, param.Parameterized):
        _models = {
            "string_value": {"element": "fast-text-field", "property": "value", "event": "input"},
            "boolean_value": {"element": "checkbox-1", "property": "checked", "event": "change"},
            "integer_value": {"element": "fast-slider", "attribute": "aria-valuenow"}, # Does not work fully. See https://github.com/microsoft/fast/issues/4021
            "number_value": {"element": "slider-2", "property": "value", "event": "change"}, # Does not work fully. See https://github.com/microsoft/fast/issues/4019
            "inner_html": {"element": "fast-tree-view", "property": "innerHTML"},
            "clicks": {"element": "button-1", "event": "click"},
        }
        string_value = param.String()
        boolean_value = param.Boolean()
        integer_value = param.Integer(default=10, bounds=(0, 100), step=1)
        number_value = param.Number(default=0.76, bounds=(0, 1), step=0.01)
        inner_html = param.String(default=INNER_HTML)
        clicks = param.Integer()

    example = ExampleClass(string_value="hello world")

    html_panel = pn.pane.HTML(HTML, height=400, sizing_mode="stretch_width")
    example_panel = pn.Param(
        example,
        parameters=["string_value", "boolean_value", "integer_value", "number_value", "clicks"],
        width=400,
    )

    return FastTemplate(main=[pn.Row(html_panel, example_panel), example.model])


if __name__.startswith("bokeh"):
    test_app().servable()

The implementation is in the data_model branch. The code can be found here https://github.com/MarcSkovMadsen/awesome-panel-extensions/blob/data_models/tests/data_models/test_manual.py, https://github.com/MarcSkovMadsen/awesome-panel-extensions/tree/data_models/awesome_panel_extensions/data_models and https://github.com/MarcSkovMadsen/awesome-panel-extensions/tree/data_models/awesome_panel_extensions/bokeh_extensions/data_models.

Simplify Component by moving Vue functionality to child VueComponent

The Component class contains functionality which is only relevant for users of Vue. That can be overwhelming, confusing and/ or hard to maintain. It also makes it difficult to split documentation and examples into something that gradually builds into an understanding (I claim 😄 ).

I would suggest to simplify things by implementing a VueComponent child class that can be used by Vue users.

I believe that would include moving the data_prefix, data_postfix, component_data and related functionality from the Component into a VueComponent.

Why is it so important to be able to copy and serve local assets?

I can see the Component code contains a lot of functionality for making the local assets available by copying them from a www folder to a static folder.

With the TemporaryResources context manager it is no longer nescessary to hard code and potentially serve Bokeh/ Panel assets. All that can be done in the normal Bokeh/ Panel way and the user can specify him/ her self whether to use CDN or inline resources as documented in those frameworks.

So left are assets from other packages panel-bootstrap-vue and from the project of the user him self.

I believe the panel-bootstrap-vue could/ should use a CDN to serve the assets?

I believe the local assets of the project should just be put in the static folder if nescessary. No need to support a copy from a www folder or similar.

Solution

Simplify Component and user experience by removing functionality.

Alternatively document functionality. Why it is needed. How to use it.

Additional Context

I'm not sure I understand all the use cases here. Alternatively I would really like to learn why this functionality is important.

Describe why and how to serve static assets from a src_folder

I can see that there is a lot of functionality to copy and serve assets from a source folder (defaults to www).

I would like to know why and how to best use this.

Solution

Add description with examples to README.

Explain how to get bidirectional communication with a component.

The one remaining thing for me to understand is how to get bidirectional communication between a Component and the backend such that I can use it as any other Panel Widget, pane or Layout.

For example I want to react to clicks on a button here #5 (comment)

I can though see how my WebComponent could be used or even changed to work on a Panel-Components component via it’s id.

solution

Describe a minimum example here and I will add it to the ReadMe.md and create a real world example in a new examples folder

Remove helper functions from public api of Component

When doing tab completion on the Component I get a lot of public functions back. For example I would see the function add_attributes. To me add_attributes is a helper function and a part of the private api.

The consequence of making a lot of functions public are

1. The user of a custom Component is overwhelmed by functions to choose from.
2. The user of a custom Component might use them and start depending on them. Making it harder to change the implementation later.

I would like to make it super easy for a user of the FastButton below to see what he can do with it.

Example

import param
from panel_components.component import Component

class FastButton(Component, param.Parameterized):
    clicks = param.Number()

    def __init__(self, *children, **attributes):
        self._children = children
        self._attributes = attributes
        super().__init__(
            *children,
            tag_name="fast-button",
            opening="<",
            closing="/>",
            main=None,
            css_classes=None,
            **attributes
        )

def test_fast_button():
    fast_button = FastButton("Click Me", appearance="stealth")

    assert fast_button.clicks == 0
    assert callable(fast_button.servable)

I would like the user to not see a lot more than the clicks attribute.

Solution

Hide a lot of functions from the public api by putting an underscore _ in front of the function name.

Enable adding module scripts

If I wan't to use Fast with panel-components I need to import a module in the head. As far as I can see this is not possible.

<script type="module" src="https://unpkg.com/@microsoft/fast-components"></script>

A lot of .js libraries that I integrate with or would like to integrate with requires module imports.

Document why panel-componts is needed and what problem it solves.

I believe panel-components provides important functionality that is missing from Bokeh/ Panel today. Something that will make it easier to create awesome-analytics-apps in Panel.

But I am still trying to understand what panel-components is and what I can do with it and how.

But you should always start with the why.

So I think it's very important to describe why panel-components is needed and what problem it tries to solve.

The why should answer for example the following question

Why not just use a combination of Panel Jinja based templates and Bokeh Extensions instead of panel-components?

Why does panel-components not just extend some existing HTML generator?

I have been thing a bit about the api of panel-components and the optimal api.

I have a few considerations

• The api of panel-components is using a lot of lists and dictionaries to hold different kinds of .js and .css for the header and body bottom.
• Every time you miss something non .js or .css in the header (like language, favicon, ...) you would need to add yet another parameter to store it.

There are a lot of existing python HTML generators out there. I am thinking that maybe the right thing to do is to lean on them by either using them or getting inspiration from them.

If possible please explain if this is not a good idea and why? Why is a new python html generator for panel needed?

Consider whether the tags should be functions or classes?

I have a feeling it would be better to make the tags in the tags.py file child classes of Component child. Right now they are tag_function functions.

• It would enable inheritance.
• It would enable a better distinction between instances of tags as they are instances of different classes instead of just instances of Component.

Maybe it does not matter. Right now it is just a feeling.

The implication would be that the tags should be PascalCase and that the make_a_tag_function should return a Class instead of a function.