JupyterLab Extension

Main JupyterLab extension plugin that integrates Visual Python into the JupyterLab interface, providing panel management, command registration, and global environment setup.

Capabilities

Extension Activation

Main activation function that initializes the Visual Python extension within JupyterLab.

/**
 * Activates the Visual Python extension in JupyterLab
 * @param app - JupyterLab application instance
 * @param palette - Command palette for adding commands
 */
function activate(app: JupyterLab, palette: ICommandPalette): void;

Description: Initializes the Visual Python extension by setting up global variables, creating the VpPanel, registering commands, and integrating with JupyterLab's UI system.

Parameters:

• app: JupyterLab application instance providing access to shell, commands, and services
• palette: Command palette interface for registering Visual Python commands

Behavior:

1. Configures global environment variables for Visual Python
2. Determines extension type (lab/lite) and sets global references
3. Creates and adds VpPanel to JupyterLab's right sidebar
4. Registers toggle command for panel visibility
5. Adds command to the command palette

Usage: Called automatically by JupyterLab during extension loading.

Global Environment Setup

The extension establishes global variables accessible throughout the Visual Python system.

// Global variables set during activation
global.vpBase: string;        // Base path to Visual Python library
global.vpExtType: string;     // Extension type identifier (lab/lite)
global.vpLab: JupyterLab;     // JupyterLab application reference
global.$: jQuery;             // jQuery library for DOM manipulation

Global Variables:

global.vpBase

• Type: string
• Description: Base path to Visual Python library assets and resources
• Usage: Used by Visual Python components to locate assets

global.vpExtType

• Type: string
• Description: Extension type identifier, typically "lab" or "lite"
• Usage: Determines Visual Python behavior based on JupyterLab environment

global.vpLab

• Type: JupyterLab
• Description: Reference to main JupyterLab application instance
• Usage: Provides access to JupyterLab services and shell from Visual Python components

global.$

• Type: jQuery
• Description: jQuery library reference for DOM manipulation
• Usage: Used by Visual Python UI components for dynamic content management

Asset Loaders

Webpack-based loaders for Visual Python assets and resources.

/**
 * Loads CSS files for Visual Python styling
 * @param path - Path to CSS file
 * @returns Loaded CSS content as string
 */
function __VP_CSS_LOADER__(path: string): string;

/**
 * Loads text files for Visual Python templates and content
 * @param path - Path to text file
 * @returns Loaded text content as string
 */
function __VP_TEXT_LOADER__(path: string): string;

/**
 * Loads raw files and binary resources for Visual Python
 * @param path - Path to resource file
 * @returns Raw file content of any type
 */
function __VP_RAW_LOADER__(path: string): any;

__VP_CSS_LOADER__

• Type: Function
• Parameters: path - Path to CSS file relative to Visual Python assets
• Returns: string - Loaded CSS content ready for injection
• Description: Webpack loader that processes and loads CSS files for Visual Python styling. Used internally by the extension to load theme and component styles.

__VP_TEXT_LOADER__

• Type: Function
• Parameters: path - Path to text file relative to Visual Python assets
• Returns: string - Loaded text content
• Description: Webpack loader for loading text files such as HTML templates, configuration files, and other textual resources used by Visual Python components.

__VP_RAW_LOADER__

• Type: Function
• Parameters: path - Path to resource file relative to Visual Python assets
• Returns: any - Raw file content (can be binary data, JSON, etc.)
• Description: Webpack loader for loading raw files and binary resources including images, data files, and other non-text assets required by Visual Python.

Usage Context: These loaders are used internally by the Visual Python extension during the webpack build process to bundle static assets. They are exposed as part of the public API for potential extension by other developers or for debugging purposes.

Extension Configuration

Plugin Metadata

// Extension plugin configuration
const extension = {
  id: 'jupyterlab-visualpython:plugin',
  autoStart: true,
  requires: [ICommandPalette],
  activate: activate
};

Extension Properties:

• id: Unique identifier for the extension plugin
• autoStart: Enables automatic activation when JupyterLab starts
• requires: Dependencies required for activation (ICommandPalette)
• activate: Main activation function

Command Registration

The extension registers commands for Visual Python interaction:

// Command registration during activation
app.commands.addCommand('jupyterlab-visualpython:toggle', {
  label: 'Toggle Visual Python',
  execute: () => {
    if (vpPanel.isVisible) {
      vpPanel.hide();
    } else {
      app.shell.add(vpPanel, 'right');
      vpPanel.show();
    }
  }
});

Integration Points

JupyterLab Shell Integration

The extension integrates with JupyterLab's shell system:

• Right Sidebar: VpPanel added to right sidebar area
• Panel Management: Automatic panel show/hide functionality
• UI Updates: Panel visibility synchronized with JupyterLab state

Command Palette Integration

Commands are added to JupyterLab's command palette:

palette.addItem({
  command: 'jupyterlab-visualpython:toggle',
  category: 'Visual Python'
});

Environment Detection

The extension detects the JupyterLab environment type:

// Environment type detection
const extType = app.version.includes('lite') ? 'lite' : 'lab';
global.vpExtType = extType;

Error Handling

The extension includes error handling for:

• Missing dependencies during activation
• Asset loading failures
• Panel creation and management errors
• Command registration conflicts