0
# JupyterLab Extension
1

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

4
## Capabilities
5

6
### Extension Activation
7

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

10
```javascript { .api }
11
/**
12
 * Activates the Visual Python extension in JupyterLab
13
 * @param app - JupyterLab application instance
14
 * @param palette - Command palette for adding commands
15
 */
16
function activate(app: JupyterLab, palette: ICommandPalette): void;
17
```
18

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

21
**Parameters**:
22
- `app`: JupyterLab application instance providing access to shell, commands, and services
23
- `palette`: Command palette interface for registering Visual Python commands
24

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

32
**Usage**: Called automatically by JupyterLab during extension loading.
33

34
### Global Environment Setup
35

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

38
```javascript { .api }
39
// Global variables set during activation
40
global.vpBase: string;        // Base path to Visual Python library
41
global.vpExtType: string;     // Extension type identifier (lab/lite)
42
global.vpLab: JupyterLab;     // JupyterLab application reference
43
global.$: jQuery;             // jQuery library for DOM manipulation
44
```
45

46
**Global Variables**:
47

48
**`global.vpBase`**
49
- **Type**: `string`
50
- **Description**: Base path to Visual Python library assets and resources
51
- **Usage**: Used by Visual Python components to locate assets
52

53
**`global.vpExtType`**
54
- **Type**: `string`
55
- **Description**: Extension type identifier, typically "lab" or "lite"
56
- **Usage**: Determines Visual Python behavior based on JupyterLab environment
57

58
**`global.vpLab`**
59
- **Type**: `JupyterLab`
60
- **Description**: Reference to main JupyterLab application instance
61
- **Usage**: Provides access to JupyterLab services and shell from Visual Python components
62

63
**`global.$`**
64
- **Type**: `jQuery`
65
- **Description**: jQuery library reference for DOM manipulation
66
- **Usage**: Used by Visual Python UI components for dynamic content management
67

68
### Asset Loaders
69

70
Webpack-based loaders for Visual Python assets and resources.
71

72
```javascript { .api }
73
/**
74
 * Loads CSS files for Visual Python styling
75
 * @param path - Path to CSS file
76
 * @returns Loaded CSS content as string
77
 */
78
function __VP_CSS_LOADER__(path: string): string;
79

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

87
/**
88
 * Loads raw files and binary resources for Visual Python
89
 * @param path - Path to resource file
90
 * @returns Raw file content of any type
91
 */
92
function __VP_RAW_LOADER__(path: string): any;
93
```
94

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

101
**`__VP_TEXT_LOADER__`**
102
- **Type**: Function  
103
- **Parameters**: `path` - Path to text file relative to Visual Python assets
104
- **Returns**: `string` - Loaded text content
105
- **Description**: Webpack loader for loading text files such as HTML templates, configuration files, and other textual resources used by Visual Python components.
106

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

113
**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.
114

115
## Extension Configuration
116

117
### Plugin Metadata
118

119
```javascript { .api }
120
// Extension plugin configuration
121
const extension = {
122
  id: 'jupyterlab-visualpython:plugin',
123
  autoStart: true,
124
  requires: [ICommandPalette],
125
  activate: activate
126
};
127
```
128

129
**Extension Properties**:
130
- **`id`**: Unique identifier for the extension plugin
131
- **`autoStart`**: Enables automatic activation when JupyterLab starts
132
- **`requires`**: Dependencies required for activation (ICommandPalette)
133
- **`activate`**: Main activation function
134

135
### Command Registration
136

137
The extension registers commands for Visual Python interaction:
138

139
```javascript { .api }
140
// Command registration during activation
141
app.commands.addCommand('jupyterlab-visualpython:toggle', {
142
  label: 'Toggle Visual Python',
143
  execute: () => {
144
    if (vpPanel.isVisible) {
145
      vpPanel.hide();
146
    } else {
147
      app.shell.add(vpPanel, 'right');
148
      vpPanel.show();
149
    }
150
  }
151
});
152
```
153

154
## Integration Points
155

156
### JupyterLab Shell Integration
157

158
The extension integrates with JupyterLab's shell system:
159

160
- **Right Sidebar**: VpPanel added to right sidebar area
161
- **Panel Management**: Automatic panel show/hide functionality
162
- **UI Updates**: Panel visibility synchronized with JupyterLab state
163

164
### Command Palette Integration
165

166
Commands are added to JupyterLab's command palette:
167

168
```javascript
169
palette.addItem({
170
  command: 'jupyterlab-visualpython:toggle',
171
  category: 'Visual Python'
172
});
173
```
174

175
### Environment Detection
176

177
The extension detects the JupyterLab environment type:
178

179
```javascript
180
// Environment type detection
181
const extType = app.version.includes('lite') ? 'lite' : 'lab';
182
global.vpExtType = extType;
183
```
184

185
## Error Handling
186

187
The extension includes error handling for:
188
- Missing dependencies during activation
189
- Asset loading failures
190
- Panel creation and management errors
191
- Command registration conflicts