Access custom components#

What does this guide solve?

This guide will show you how to access local files that build custom components.

Overview#

While Lumen ships with a wide range of components, users may also define custom components in files which live alongside the YAML file. There are two approaches to reference these local custom components.

The first approach is to save your custom components to files with specific names that Lumen will automatically import. With this approach, you can just refer to your components in the YAML specification using their simple string name (for example, texteditor).

The second approach is to save your custom components to your own folder and filenames. With this approach, you can refer to your components using their module path (for example, my_library.my_module.TextEditor).

In the custom component examples below, we will add a transform for stable sorting, and a view for a rich text editor.

Approach 1: Using imported files#

Lumen will automatically import filters.py, sources.py, transforms.py, and views.py if these files exist alongside the YAML dashboard specification.

For example, if you created a custom transform and a custom view, all you have to do is save the custom transform to transforms.py and the custom view to views.py, and then place them in the same directory as your YAML specification. Now you can reference these local components within your specification using their simple string name, and they will be applied when you launch your dashboard.

Here are our example custom component files:

transforms.py

import param
from lumen import Transform

class StableSort(Transform):
    """
    Uses a stable sorting algorithm on one or more columns.

    See `pandas.DataFrame.sort_values` with kind='stable'

    df.sort_values(<by>, ascending=<ascending>, kind='stable')
    """

    by = param.ListSelector(default=[], doc="""
       Columns or indexes to sort by.""")

    ascending = param.ClassSelector(default=True, class_=(bool, list), doc="""
       Sort ascending vs. descending. Specify list for multiple sort
       orders. If this is a list of bools, must match the length of
       the by.""")

    transform_type = 'stablesort'

    _field_params = ['by']

    def apply(self, table):
        return table.sort_values(self.by, ascending=self.ascending, kind='stable')

views.py

from lumen import View
import panel as pn

class TextEditor(View):
    """
    Provides a rich text editor.

    See https://panel.holoviz.org/reference/widgets/TextEditor.html#widgets-gallery-texteditor
    """

    view_type = 'texteditor'

    _extension = 'texteditor'

    def get_panel(self):
        return pn.widgets.TextEditor(**self._get_params())

    def _get_params(self):
        return dict(**self.kwargs, sizing_mode='stretch_width', placeholder='Enter some text')

And here is our example YAML specification (dashboard.yaml) that references these local custom component files:

config:
  title: Palmer Penguins

sources:
  penguin_source:
    type: file
    tables:
      penguin_table: https://datasets.holoviz.org/penguins/v1/penguins.csv

pipelines:
  penguin_pipeline:
    source: penguin_source
    table: penguin_table
    filters:
      - type: widget
        field: sex
      - type: widget
        field: island
    transforms:
      - type: columns
        columns: ['species', 'island', 'sex', 'year', 'bill_length_mm', 'bill_depth_mm']
      - type: my_module.StableSor
        by: island

layouts:
  - title: Penguins
    pipeline: penguin_pipeline
    layout: [[0, 1], [2, 3]]
    sizing_mode: stretch_width
    height: 800
    views:
      - type: hvplot
        x: bill_length_mm
        y: bill_depth_mm
        kind: scatter
        color: species
        responsive: true
        height: 400
      - type: hvplot
        kind: hist
        y: bill_length_mm
        responsive: true
        height: 300
      - type: table
        show_index: false
        height: 300
      - type: texteditor
        height: 250

Now launch the dashboard with:

lumen serve dashboard.yaml --show

Approach 2: Using module paths#

Lumen will import custom components from your own modules (folders and files) if referenced in the YAML specification using dot notation (for example, my_library.my_module.TextEditor). If using this approach, the root of the module path (for example, my_library) needs to be in the same folder as the YAML specification.

Here is our example custom component file. In this case, we combined the components into one file, but they could have been in different module paths:

my_library/my_module.py

import param
from lumen import Transform, View
import panel as pn

class StableSort(Transform):
    """
    Uses a stable sorting algorithm on one or more columns.

    See `pandas.DataFrame.sort_values` with kind='stable'

    df.sort_values(<by>, ascending=<ascending>, kind='stable')
    """

    by = param.ListSelector(default=[], doc="""
       Columns or indexes to sort by.""")

    ascending = param.ClassSelector(default=True, class_=(bool, list), doc="""
       Sort ascending vs. descending. Specify list for multiple sort
       orders. If this is a list of bools, must match the length of
       the by.""")

    transform_type = 'stablesort'

    _field_params = ['by']

    def apply(self, table):
        return table.sort_values(self.by, ascending=self.ascending, kind='stable')


class TextEditor(View):
    """
    Provides a rich text editor.

    See https://panel.holoviz.org/reference/widgets/TextEditor.html#widgets-gallery-texteditor
    """

    view_type = 'texteditor'

    _extension = 'texteditor'

    def get_panel(self):
        return pn.widgets.TextEditor(**self._get_params())

    def _get_params(self):
        return dict(**self.kwargs, sizing_mode='stretch_width', placeholder='Enter some text')

And here is our example YAML specification (dashboard.yaml) that references these local custom components:

config:
  title: Palmer Penguins

sources:
  penguin_source:
    type: file
    tables:
      penguin_table: https://datasets.holoviz.org/penguins/v1/penguins.csv

pipelines:
  penguin_pipeline:
    source: penguin_source
    table: penguin_table
    filters:
      - type: widget
        field: sex
      - type: widget
        field: island
    transforms:
      - type: columns
        columns: ['species', 'island', 'sex', 'year', 'bill_length_mm', 'bill_depth_mm']
      - type: my_library.my_module.StableSort
        by: island

layouts:
  - title: Penguins
    pipeline: penguin_pipeline
    layout: [[0, 1], [2, 3]]
    sizing_mode: stretch_width
    height: 800
    views:
      - type: hvplot
        x: bill_length_mm
        y: bill_depth_mm
        kind: scatter
        color: species
        responsive: true
        height: 400
      - type: hvplot
        kind: hist
        y: bill_length_mm
        responsive: true
        height: 300
      - type: table
        show_index: false
        height: 300
      - type: my_library.my_module.TextEditor
        height: 250