cm-jupyter-widget 0.3.5

CleverMaps Marimo Widget - A widget for embedding CleverMaps visualizations in Marimo notebooks.

CleverMaps Jupyter Widget

A Jupyter widget for embedding and interacting with CleverMaps visualizations in Jupyter notebooks.

Installation

You can install the package using pip:

pip install clevermaps-jupyter-widget

Requirements

• Python >= 3.9
• Jupyter notebook or JupyterLab
• anywidget

Usage

Basic Usage

from cm_jupyter_widget.widget import CleverMapsWidget

# Create a widget with a view URL
widget = CleverMapsWidget(view_url="https://your-view-url")

# Display the widget
widget

Advanced Usage with Options

# Create a widget with custom options
widget = CleverMapsWidget(
    view_url="https://your-view-url",
    options='''{
        "componentSettings": {
            "infoBox": {
                "defaultExpanded": false
            },
            "tools": {
                "search": false
            }
        },
        "theme": {
            "colorPrimary": "#0055ff"
        },
        "interactivity": {
            "afterClick": false
        },
        "fullScreenButton": {
            "enabled": false
        },
        "studioLinkButton": {
            "enabled": false
        }
    }'''
)

API Reference

Widget Properties

• view_url (required): The URL of the CleverMaps view to display
• base_url (optional): The base URL for CleverMaps API (defaults to 'https://secure.clevermaps.io/')
• options (optional): A JSON string containing configuration options for the widget
• width (optional): The width of the widget (e.g. '100%', '500px', '1000px')
• height (optional): The height of the widget (e.g. '100%', '500px', '1000px')
• add_filter_callback (optional): A Python function that will be called when a filter is added. The function will be called without any arguments.

Methods

toggle_fit_all()

Fits all features in the current view.

add_filter(definition_id: str, values: Dict[str, Any], instance_id: str)

Adds a new filter to the view.

Parameters:

• definition_id: The ID of the filter definition
• values: Filter values (format depends on filter type)
• instance_id: The instance ID of the filter

Filter value formats:

• MultiSelect: {"values": ["Male", 1, null]}
• SingleSelect: {"value": "selected_value"} or {"value": null}
• Feature: {"values": ["feature1", 1]} or {"values": null}
• Histogram: {"values": [1, 10], "nullFiltered": true} or {"values": [null, null]}
• Date: {"startDate": {"value": "2023-01-01"}, "endDate": {"value": "2023-12-31"}}
• Indicator: {"values": [min, max], "granularity": "year"}

set_filter(instance_id: str, value)

Sets the value of an existing filter.

Parameters:

• instance_id: The instance ID of the filter to set
• value: The new filter value

remove_filter(instance_id: str)

Removes a filter from the view.

Parameters:

• instance_id: The instance ID of the filter to remove

reset_filter(instance_id: str)

Resets a filter to its default state.

Parameters:

• instance_id: The instance ID of the filter to reset

set_state(view_url: str)

Loads a new view URL.

Parameters:

• view_url: The URL of the view to load

open_bookmark_modal()

Opens the bookmark modal dialog.

open_export_modal()

Opens the export modal dialog.

Examples

Using Filter Callbacks

def on_filter_added():
    print("A filter was added")
    # Handle the filter addition event

widget = CleverMapsWidget(view_url="your-view-url")
widget.add_filter_callback = on_filter_added

Check out the example notebook in the repository:

• sdk-test.ipynb: Advanced usage and testing examples

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Karel Psota ([e-mail])