Jupyter Vue Widgets Base

Common errors

• Error displaying widget: model not found

  cause The `jupyter-vue` JavaScript frontend extension is not properly installed or enabled in the Jupyter environment, preventing the Python backend model from finding its corresponding frontend rendering logic. The browser console might show 'Failed to load model class 'XModel' from module 'jupyter-vue''.
  fix After `pip install ipyvue` (which handles the frontend installation), run `jupyter nbextension enable --py --sys-prefix ipyvue` for Jupyter Notebook. For JupyterLab (version 3+ typically handles this automatically), if issues persist, `jupyter labextension install @jupyter-widgets/jupyterlab-manager` might be needed. Always restart your Jupyter kernel and browser page after enabling extensions.

• ModuleNotFoundError: No module named 'ipyvue'

  cause The 'ipyvue' Python package is not installed in the active Python environment or the environment where Jupyter is running.
  fix Install the Python package using pip: `pip install ipyvue`. Ensure your Jupyter environment is using the Python kernel where `ipyvue` is installed.

• Unexpected token < in JSON at position X (or similar parsing errors related to templates)

  cause Vue template parsing error, often due to a malformed template string or missing `<template>` tags in the Python `template` traitlet.
  fix Ensure the `template` string provided to `ipyvue.VueTemplate` is valid HTML with correct Vue.js syntax, including wrapping the main component content within a single `<template>` tag.

• Unknown dependency jupyter-vue (in Google Colab or similar environments)

  cause This issue typically arises in environments like Google Colab where the Jupyter widget manager struggles to correctly load or resolve the `jupyter-vue` JavaScript module.
  fix For Google Colab, enable the custom widget manager and ensure `ipyvue` is installed within the Colab environment: `from google.colab import output; output.enable_custom_widget_manager(); !pip install ipyvue`.

Warnings

• gotcha Scoped CSS support within VueTemplate templates is disabled by default for backwards compatibility. CSS rules defined in `<style scoped>` tags will apply globally unless explicitly enabled.
  Fix: Enable globally via environment variable `IPYVUE_SCOPED_CSS_SUPPORT=1` before starting Jupyter, or per widget instance using `scoped_css_support=True` in the Python `VueTemplate` class definition or constructor.
• gotcha In-place mutations of Python list or dictionary traitlets (e.g., `my_list.append(item)`) are not automatically detected by `ipywidgets` for synchronization with the frontend. A new list or dictionary object must be assigned to the traitlet for changes to propagate.
  Fix: Always assign a new object to mutable traitlets to trigger synchronization: e.g., `self.my_list = self.my_list + [new_item]` or `self.my_dict = {**self.my_dict, 'key': 'value'}`.
• gotcha Ensure proper version compatibility between `jupyter-vue`, Vue.js, and your JupyterLab/Notebook environment, especially when developing custom JupyterLab extensions. Mismatches in `@jupyterlab/*` or `@lumino/*` dependencies can lead to build or runtime errors.
  Fix: Consult `ipyvue` and `jupyterlab` documentation for recommended dependency versions. Use `jlpm` (JupyterLab's pinned `yarn` version) for frontend builds and ensure consistent dependency versions across your project and JupyterLab's installed extensions.
• breaking The behavior of sending event data with events like key presses and mouse clicks was significantly enhanced in v1.10.0 to send all serializable event data. While primarily a feature, this could implicitly change behavior for applications relying on older, limited event data structures.
  Fix: Review any custom event handlers that process `data` from frontend events to ensure they correctly handle the expanded set of serializable event properties now being sent.

Install

• npm install jupyter-vue npm
• yarn add jupyter-vue yarn
• pnpm add jupyter-vue pnpm

Imports

• Vue

  import Vue from 'vue'

  While `jupyter-vue` provides the bridging mechanism, custom widget frontend logic or complex component definitions often directly import Vue itself.
• VueTemplateModel
  wrong:

  const VueTemplateModel = require('jupyter-vue').VueTemplateModel

  correct:

  import { VueTemplateModel } from 'jupyter-vue'

  For developers extending `jupyter-vue` to create custom widget models on the JavaScript frontend, inheriting from the base Vue widget model.
• VueTemplateView
  wrong:

  const VueTemplateView = require('jupyter-vue').VueTemplateView

  correct:

  import { VueTemplateView } from 'jupyter-vue'

  For developers extending `jupyter-vue` to create custom widget views on the JavaScript frontend, inheriting from the base Vue widget view.

Quickstart

Demonstrates creating and displaying a reactive Vue component widget using the `ipyvue` Python library, which relies on `jupyter-vue` for frontend rendering. This example includes a counter with increment/decrement buttons and a text input field, showcasing two-way data binding and method calling between Python and Vue.

from ipyvue import VueTemplate
from IPython.display import display

class InteractiveCounter(VueTemplate):
    template = """
    <template>
        <div style="border: 1px solid #ccc; padding: 10px; border-radius: 5px; background-color: #f9f9f9;">
            <h3 style="color: #333;">Vue Counter Widget</h3>
            <p>Current Count: <strong style="color: #007bff;">{{ count }}</strong></p>
            <button @click="increment" style="margin-right: 5px; padding: 8px 15px; border: none; border-radius: 4px; background-color: #28a745; color: white; cursor: pointer;">Increment</button>
            <button @click="decrement" style="padding: 8px 15px; border: none; border-radius: 4px; background-color: #dc3545; color: white; cursor: pointer;">Decrement</button>
            <p style="margin-top: 15px;">User Input: <em style="color: #6c757d;">{{ inputText }}</em></p>
            <input v-model="inputText" placeholder="Type something here..." style="width: 100%; padding: 8px; border: 1px solid #ddd; border-radius: 4px; box-sizing: border-box;">
        </div>
    </template>
    """
    data = {
        'count': 0,
        'inputText': 'Hello ipyvue!'
    }

    def increment(self):
        self.count += 1

    def decrement(self):
        self.count -= 1

widget = InteractiveCounter()
display(widget)
# In a Jupyter Notebook/Lab cell, 'widget' on the last line
# would implicitly display it without an explicit 'display()' call.