0
# Frontend Integration
1

2
JupyterLab user interface integration providing toolbar buttons, menu items, command palette integration, keyboard shortcuts, and format-on-save functionality.
3

4
## Capabilities
5

6
### Main Extension Class
7

8
The primary extension class that implements JupyterLab's widget extension interface and orchestrates all UI components.
9

10
```typescript { .api }
11
class JupyterLabCodeFormatter implements DocumentRegistry.IWidgetExtension<NotebookPanel, INotebookModel> {
12
  constructor(
13
    app: JupyterFrontEnd,
14
    tracker: INotebookTracker,
15
    palette: ICommandPalette,
16
    settingRegistry: ISettingRegistry,
17
    menu: IMainMenu,
18
    editorTracker: IEditorTracker
19
  );
20

21
  createNew(
22
    nb: NotebookPanel,
23
    context: DocumentRegistry.IContext<INotebookModel>
24
  ): IDisposable;
25
}
26
```
27

28
**Parameters**:
29
- `app` - JupyterLab application instance
30
- `tracker` - Notebook tracker for managing notebook widgets
31
- `palette` - Command palette for adding commands
32
- `settingRegistry` - Settings registry for configuration
33
- `menu` - Main menu for adding menu items
34
- `editorTracker` - File editor tracker for managing editor widgets
35

36
**Methods**:
37
- `createNew()` - Creates toolbar button and connects save event handlers for notebooks
38

39
### Plugin Configuration
40

41
The main plugin export that configures the JupyterLab extension.
42

43
```typescript { .api }
44
const plugin: JupyterFrontEndPlugin<void>;
45
```
46

47
**Plugin Properties**:
48
- `id` - Plugin identifier
49
- `autoStart` - Automatically start on JupyterLab load
50
- `requires` - Required JupyterLab services
51
- `activate` - Activation function that creates the main extension instance
52

53
### Extension Constants
54

55
Core constants used throughout the extension.
56

57
```typescript { .api }
58
namespace Constants {
59
  const PLUGIN_NAME: string; // "jupyterlab_code_formatter"
60
  const FORMAT_COMMAND: string; // Format selected cells command
61
  const FORMAT_ALL_COMMAND: string; // Format all cells command
62
  const ICON_FORMAT_ALL_SVG: string; // SVG icon for format button
63
  const ICON_FORMAT_ALL: string; // CSS class for format icon
64
  const SETTINGS_SECTION: string; // Settings registry section
65
  const COMMAND_SECTION_NAME: string; // Command palette category
66
  const PLUGIN_VERSION: string; // Plugin version
67
}
68
```
69

70
## Usage Examples
71

72
### Creating the Extension
73

74
```typescript
75
import { JupyterFrontEnd, JupyterFrontEndPlugin } from '@jupyterlab/application';
76
import { ICommandPalette } from '@jupyterlab/apputils';
77
import { INotebookTracker } from '@jupyterlab/notebook';
78
import { ISettingRegistry } from '@jupyterlab/settingregistry';
79
import { IMainMenu } from '@jupyterlab/mainmenu';
80
import { IEditorTracker } from '@jupyterlab/fileeditor';
81

82
const plugin: JupyterFrontEndPlugin<void> = {
83
  id: 'jupyterlab_code_formatter',
84
  autoStart: true,
85
  requires: [
86
    ICommandPalette,
87
    INotebookTracker,
88
    ISettingRegistry,
89
    IMainMenu,
90
    IEditorTracker
91
  ],
92
  activate: (
93
    app: JupyterFrontEnd,
94
    palette: ICommandPalette,
95
    tracker: INotebookTracker,
96
    settingRegistry: ISettingRegistry,
97
    menu: IMainMenu,
98
    editorTracker: IEditorTracker
99
  ) => {
100
    new JupyterLabCodeFormatter(
101
      app,
102
      tracker,
103
      palette,
104
      settingRegistry,
105
      menu,
106
      editorTracker
107
    );
108
  }
109
};
110

111
export default plugin;
112
```
113

114
### Using Constants
115

116
```typescript
117
import { Constants } from './constants';
118

119
// Register commands
120
app.commands.addCommand(Constants.FORMAT_COMMAND, {
121
  execute: async () => {
122
    // Format selected cells
123
  },
124
  label: 'Format cell'
125
});
126

127
app.commands.addCommand(Constants.FORMAT_ALL_COMMAND, {
128
  execute: async () => {
129
    // Format all cells
130
  },
131
  label: 'Format notebook'
132
});
133
```
134

135
## Integration Points
136

137
### Toolbar Integration
138

139
The extension adds a format button to notebook toolbars:
140

141
- **Button Icon**: SVG icon defined in Constants.ICON_FORMAT_ALL_SVG
142
- **Button Action**: Formats all code cells in the notebook
143
- **Button Placement**: Inserted after the cell type selector
144

145
### Menu Integration
146

147
Formatter-specific menu items are added to the Edit menu:
148

149
- **Dynamic Menu Items**: Created based on available formatters
150
- **Formatter Labels**: Use human-readable names from formatter definitions
151
- **Visibility Logic**: Menu items shown only when applicable to current context
152

153
### Command Palette Integration
154

155
Commands are registered with the command palette:
156

157
- **Category**: "Jupyterlab Code Formatter"
158
- **Format Cell**: Format selected cells
159
- **Format All**: Format all cells in notebook
160
- **Formatter-Specific**: Individual commands for each available formatter
161

162
### Context Menu Integration
163

164
Right-click context menu integration:
165

166
- **Selector**: `.jp-Notebook` (notebook cells)
167
- **Command**: Format command for selected cells
168

169
### Settings Integration
170

171
JupyterLab settings system integration:
172

173
- **Settings Section**: `jupyterlab_code_formatter:settings`
174
- **Configuration**: Formatter options, format-on-save, error handling
175
- **Live Updates**: Settings changes trigger configuration updates
176

177
### Save Event Handling
178

179
Format-on-save functionality:
180

181
- **Notebook Save**: Monitors notebook save state
182
- **Editor Save**: Monitors file editor save state  
183
- **Conditional Formatting**: Only formats when `formatOnSave` setting is enabled
184
- **Error Suppression**: Configurable error handling during auto-format