0
# Widget Manager
1

2
The widget manager interface provides the central system for managing widget lifecycles, creation, registration, and communication within Jupyter environments.
3

4
## Capabilities
5

6
### IWidgetManager Interface
7

8
Core interface that all widget managers must implement for managing models, views, and communication.
9

10
```typescript { .api }
11
/**
12
 * Interface for widget managers that handle model and view lifecycle
13
 */
14
interface IWidgetManager {
15
  /**
16
   * Get a model by its unique identifier
17
   * @param model_id - Unique model identifier
18
   * @returns Promise that resolves to the widget model, or undefined if not found
19
   */
20
  get_model(model_id: string): Promise<WidgetModel>;
21

22
  /**
23
   * Check if a model is registered with the manager
24
   * @param model_id - Model identifier to check
25
   * @returns True if model exists, false otherwise
26
   */
27
  has_model(model_id: string): boolean;
28

29
  /**
30
   * Register a model instance with the manager
31
   * @param model_id - Unique identifier for the model
32
   * @param modelPromise - Promise that resolves to the model instance
33
   */
34
  register_model(model_id: string, modelPromise: Promise<WidgetModel>): void;
35

36
  /**
37
   * Create a new widget with communication channel
38
   * @param options - Widget creation options (includes view information)
39
   * @param serialized_state - Optional initial state for the widget
40
   * @returns Promise that resolves to the created widget model
41
   */
42
  new_widget(options: IWidgetOptions, serialized_state?: JSONObject): Promise<WidgetModel>;
43

44
  /**
45
   * Create a new model instance
46
   * @param options - Model creation options
47
   * @param serialized_state - Optional initial state for the model
48
   * @returns Promise that resolves to the created model
49
   */
50
  new_model(options: IModelOptions, serialized_state?: JSONObject): Promise<WidgetModel>;
51

52
  /**
53
   * Create a view for a given model
54
   * @param model - Widget model to create view for
55
   * @param options - View creation options
56
   * @returns Promise that resolves to the created view
57
   */
58
  create_view<VT extends DOMWidgetView = DOMWidgetView>(
59
    model: DOMWidgetModel,
60
    options?: unknown
61
  ): Promise<VT>;
62
  create_view<VT extends WidgetView = WidgetView>(
63
    model: WidgetModel,
64
    options?: unknown
65
  ): Promise<VT>;
66

67
  /**
68
   * Get callback handlers for a specific view
69
   * @param view - View to get callbacks for (optional)
70
   * @returns Callback configuration object
71
   */
72
  callbacks(view?: WidgetView): ICallbacks;
73

74
  /**
75
   * Resolve a URL relative to the current notebook location
76
   * @param url - URL to resolve
77
   * @returns Promise that resolves to the absolute URL
78
   */
79
  resolveUrl(url: string): Promise<string>;
80

81
  /**
82
   * Sanitize HTML content for inline display
83
   * @param s - HTML string to sanitize
84
   * @returns Sanitized HTML string
85
   */
86
  inline_sanitize(s: string): string;
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
// Get existing model
94
const model = await widgetManager.get_model('widget-123');
95

96
// Check if model exists
97
if (widgetManager.has_model('widget-123')) {
98
  // Model is available
99
}
100

101
// Create new widget with comm
102
const widget = await widgetManager.new_widget({
103
  model_name: 'IntSlider',
104
  model_module: '@jupyter-widgets/controls',
105
  model_module_version: '1.0.0',
106
  view_name: 'IntSliderView',
107
  view_module: '@jupyter-widgets/controls',
108
  view_module_version: '1.0.0'
109
}, { value: 50, min: 0, max: 100 });
110

111
// Create view for model
112
const view = await widgetManager.create_view(model);
113
```
114

115
### Model Creation Options
116

117
Configuration options for creating widget models and establishing their metadata.
118

119
```typescript { .api }
120
/**
121
 * Options for creating widget models
122
 */
123
interface IModelOptions {
124
  /**
125
   * Target name of the widget model class to create
126
   */
127
  model_name: string;
128

129
  /**
130
   * Module name containing the widget model class
131
   */
132
  model_module: string;
133

134
  /**
135
   * Semver version requirement for the model module
136
   */
137
  model_module_version: string;
138

139
  /**
140
   * Target name of the widget view class (optional for model-only creation)
141
   */
142
  view_name?: string | null;
143

144
  /**
145
   * Module name containing the widget view class
146
   */
147
  view_module?: string | null;
148

149
  /**
150
   * Semver version requirement for the view module
151
   */
152
  view_module_version?: string;
153

154
  /**
155
   * Communication object for kernel interaction
156
   */
157
  comm?: any;
158

159
  /**
160
   * Unique identifier for the model (auto-generated if not provided)
161
   */
162
  model_id?: string;
163
}
164
```
165

166
### Widget Creation Options
167

168
Extended options for creating complete widgets with both model and view components.
169

170
```typescript { .api }
171
/**
172
 * Options for creating connected widgets (requires view information)
173
 */
174
interface IWidgetOptions extends IModelOptions {
175
  /**
176
   * Target name of the widget model class to create (required)
177
   */
178
  model_name: string;
179

180
  /**
181
   * Module name containing the widget model class (required)
182
   */
183
  model_module: string;
184

185
  /**
186
   * Semver version requirement for the model module (required)
187
   */
188
  model_module_version: string;
189

190
  /**
191
   * Target name of the widget view class (required for widgets)
192
   */
193
  view_name: string | null;
194

195
  /**
196
   * Module name containing the widget view class (required for widgets)
197
   */
198
  view_module: string | null;
199

200
  /**
201
   * Semver version requirement for the view module (required)
202
   */
203
  view_module_version: string;
204

205
  /**
206
   * Communication object for kernel interaction
207
   */
208
  comm?: IClassicComm;
209

210
  /**
211
   * Unique identifier for the model
212
   */
213
  model_id?: string;
214
}
215
```
216

217
**Usage Examples:**
218

219
```typescript
220
// Create model-only (no view)
221
const modelOptions: IModelOptions = {
222
  model_name: 'DataModel',
223
  model_module: 'my-widgets',
224
  model_module_version: '1.0.0',
225
  model_id: 'unique-data-model'
226
};
227
const dataModel = await widgetManager.new_model(modelOptions);
228

229
// Create complete widget
230
const widgetOptions: IWidgetOptions = {
231
  model_name: 'SliderModel',
232
  model_module: '@jupyter-widgets/controls',
233
  model_module_version: '1.0.0',
234
  view_name: 'SliderView',
235
  view_module: '@jupyter-widgets/controls',
236
  view_module_version: '1.0.0'
237
};
238
const slider = await widgetManager.new_widget(widgetOptions, { value: 42 });
239
```
240

241
## Widget Manager Implementation Patterns
242

243
### Typical Manager Workflow
244

245
Common patterns for implementing and using widget managers:
246

247
```typescript
248
// Manager initialization
249
class MyWidgetManager implements IWidgetManager {
250
  private models: Map<string, Promise<WidgetModel>> = new Map();
251
  
252
  async get_model(model_id: string): Promise<WidgetModel> {
253
    const modelPromise = this.models.get(model_id);
254
    if (!modelPromise) {
255
      throw new Error(`Model ${model_id} not found`);
256
    }
257
    return modelPromise;
258
  }
259
  
260
  has_model(model_id: string): boolean {
261
    return this.models.has(model_id);
262
  }
263
  
264
  register_model(model_id: string, modelPromise: Promise<WidgetModel>): void {
265
    this.models.set(model_id, modelPromise);
266
  }
267
  
268
  async new_model(options: IModelOptions, state?: JSONObject): Promise<WidgetModel> {
269
    // Load model class
270
    const ModelClass = await this.loadModelClass(options.model_module, options.model_name);
271
    
272
    // Create instance
273
    const model = new ModelClass(state || {}, {
274
      model_id: options.model_id || this.generateId(),
275
      widget_manager: this,
276
      comm: options.comm
277
    });
278
    
279
    // Register and return
280
    this.register_model(model.model_id, Promise.resolve(model));
281
    return model;
282
  }
283
  
284
  // Additional implementation methods...
285
}
286
```
287

288
### View Creation Patterns
289

290
```typescript
291
// Create views with proper error handling
292
async createWidgetView(model: WidgetModel): Promise<WidgetView> {
293
  try {
294
    const view = await this.widgetManager.create_view(model, {
295
      parent: this.parentView
296
    });
297
    
298
    // Setup view lifecycle
299
    view.displayed.then(() => {
300
      console.log('View displayed');
301
    });
302
    
303
    return view;
304
  } catch (error) {
305
    console.error('Failed to create view:', error);
306
    throw error;
307
  }
308
}
309

310
// Manage view collections
311
const views = await Promise.all(
312
  models.map(model => this.widgetManager.create_view(model))
313
);
314
```
315

316
### Model Registration and Lookup
317

318
```typescript
319
// Register models with manager
320
const registerWidget = async (modelClass: typeof WidgetModel, initialState: any) => {
321
  const model = new modelClass(initialState, {
322
    model_id: generateUniqueId(),
323
    widget_manager: widgetManager
324
  });
325
  
326
  widgetManager.register_model(model.model_id, Promise.resolve(model));
327
  return model;
328
};
329

330
// Lookup and use existing models
331
const findOrCreateModel = async (modelId: string, fallbackOptions: IModelOptions) => {
332
  if (widgetManager.has_model(modelId)) {
333
    return await widgetManager.get_model(modelId);
334
  } else {
335
    return await widgetManager.new_model({
336
      ...fallbackOptions,
337
      model_id: modelId
338
    });
339
  }
340
};
341
```
342

343
### Communication Integration
344

345
```typescript
346
// Setup callbacks for widget communication
347
const setupWidgetCallbacks = (view: WidgetView): ICallbacks => {
348
  return widgetManager.callbacks(view);
349
};
350

351
// Handle model creation with communication
352
const createConnectedWidget = async (comm: IClassicComm, options: IWidgetOptions) => {
353
  const widget = await widgetManager.new_widget({
354
    ...options,
355
    comm: comm,
356
    model_id: comm.comm_id
357
  });
358
  
359
  // Widget is now connected to kernel
360
  return widget;
361
};
362
```