0
# Extension System
1

2
Interfaces for packaging and registering MIME renderer extensions within the JupyterLab extension system.
3

4
## Capabilities
5

6
### IExtension Interface
7

8
Defines a complete MIME renderer extension that can be registered with JupyterLab's RenderMime system.
9

10
```typescript { .api }
11
/**
12
 * An interface for using a RenderMime.IRenderer for output and read-only documents
13
 */
14
interface IExtension {
15
  /**
16
   * The ID of the extension.
17
   * The convention for extension IDs in JupyterLab is the full NPM package
18
   * name followed by a colon and a unique string token, e.g.
19
   * '@jupyterlab/apputils-extension:settings' or 'foo-extension:bar'.
20
   */
21
  readonly id: string;
22
  /**
23
   * Extension description.
24
   * This can be used to provide user documentation on the feature
25
   * brought by the extension.
26
   */
27
  readonly description?: string;
28
  /** A renderer factory to be registered to render the MIME type */
29
  readonly rendererFactory: IRendererFactory;
30
  /**
31
   * The rank passed to `RenderMime.addFactory`. If not given,
32
   * defaults to the `defaultRank` of the factory.
33
   */
34
  readonly rank?: number;
35
  /** The timeout after user activity to re-render the data */
36
  readonly renderTimeout?: number;
37
  /** Preferred data type from the model. Defaults to `string`. */
38
  readonly dataType?: 'string' | 'json';
39
  /** The options used to open a document with the renderer factory */
40
  readonly documentWidgetFactoryOptions?: IDocumentWidgetFactoryOptions | ReadonlyArray<IDocumentWidgetFactoryOptions>;
41
  /** The optional file type associated with the extension */
42
  readonly fileTypes?: ReadonlyArray<IFileType>;
43
}
44
```
45

46
**Usage Example:**
47

48
```typescript
49
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
50

51
// Complete extension definition
52
const customExtension: IRenderMime.IExtension = {
53
  id: '@my-org/custom-renderer:main',
54
  description: 'Custom renderer for specialized data formats',
55
  
56
  rendererFactory: new CustomRendererFactory(),
57
  rank: 50,
58
  renderTimeout: 1000,
59
  dataType: 'json',
60
  
61
  // Enable document rendering
62
  documentWidgetFactoryOptions: {
63
    name: 'Custom Format Viewer',
64
    label: 'Custom Viewer',
65
    primaryFileType: 'custom-format',
66
    fileTypes: ['custom-format', 'custom-alt'],
67
    defaultFor: ['custom-format']
68
  },
69
  
70
  // Associate file types
71
  fileTypes: [
72
    {
73
      name: 'custom-format',
74
      mimeTypes: ['application/my-custom-type'],
75
      extensions: ['.cust', '.custom'],
76
      displayName: 'Custom Format File',
77
      icon: 'custom-icon'
78
    }
79
  ]
80
};
81

82
// Register extension
83
renderMime.addFactory(
84
  customExtension.rendererFactory,
85
  customExtension.rank || customExtension.rendererFactory.defaultRank || 100
86
);
87
```
88

89
### IExtensionModule Interface
90

91
Defines the structure for modules that export MIME renderer extensions, supporting both single and multiple extensions.
92

93
```typescript { .api }
94
/**
95
 * The interface for a module that exports an extension or extensions as
96
 * the default value
97
 */
98
interface IExtensionModule {
99
  /** The default export - can be a single extension or array of extensions */
100
  readonly default: IExtension | ReadonlyArray<IExtension>;
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
108

109
// Single extension module
110
const singleExtensionModule: IRenderMime.IExtensionModule = {
111
  default: {
112
    id: '@my-org/single-renderer:main',
113
    rendererFactory: new MyRendererFactory(),
114
    // ... other extension properties
115
  }
116
};
117

118
// Multiple extensions module
119
const multipleExtensionsModule: IRenderMime.IExtensionModule = {
120
  default: [
121
    {
122
      id: '@my-org/multi-renderer:text',
123
      rendererFactory: new TextRendererFactory(),
124
      rank: 100
125
    },
126
    {
127
      id: '@my-org/multi-renderer:image',
128
      rendererFactory: new ImageRendererFactory(),
129
      rank: 90
130
    }
131
  ]
132
};
133

134
// Loading extensions from module
135
function loadExtensions(module: IRenderMime.IExtensionModule): void {
136
  const extensions = Array.isArray(module.default) ? module.default : [module.default];
137
  
138
  extensions.forEach(extension => {
139
    renderMime.addFactory(
140
      extension.rendererFactory,
141
      extension.rank || extension.rendererFactory.defaultRank || 100
142
    );
143
  });
144
}
145
```
146

147
## Extension Registration Patterns
148

149
### Basic Extension Registration
150

151
```typescript
152
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
153

154
// Simple extension for output rendering only
155
const outputExtension: IRenderMime.IExtension = {
156
  id: 'my-package:output-renderer',
157
  rendererFactory: new MyOutputRendererFactory(),
158
  rank: 100,
159
  dataType: 'string'
160
};
161
```
162

163
### Document Extension Registration
164

165
```typescript
166
// Extension with document rendering capabilities
167
const documentExtension: IRenderMime.IExtension = {
168
  id: 'my-package:document-renderer',
169
  description: 'Renders custom documents in JupyterLab',
170
  rendererFactory: new MyDocumentRendererFactory(),
171
  
172
  documentWidgetFactoryOptions: {
173
    name: 'My Document Viewer',
174
    primaryFileType: 'my-doc-type',
175
    fileTypes: ['my-doc-type'],
176
    defaultFor: ['my-doc-type'],
177
    
178
    // Custom toolbar
179
    toolbarFactory: (widget) => [
180
      {
181
        name: 'refresh',
182
        widget: createRefreshButton()
183
      }
184
    ]
185
  },
186
  
187
  fileTypes: [
188
    {
189
      name: 'my-doc-type',
190
      mimeTypes: ['application/my-document'],
191
      extensions: ['.mydoc'],
192
      displayName: 'My Document',
193
      fileFormat: 'text'
194
    }
195
  ]
196
};
197
```
198

199
## Types
200

201
This capability depends on interfaces from other parts of the package:
202

203
```typescript { .api }
204
interface IRendererFactory {
205
  readonly safe: boolean;
206
  readonly mimeTypes: ReadonlyArray<string>;
207
  readonly defaultRank?: number;
208
  createRenderer(options: IRendererOptions): IRenderer;
209
}
210

211
interface IDocumentWidgetFactoryOptions {
212
  readonly name: string;
213
  readonly label?: string;
214
  readonly modelName?: string;
215
  readonly primaryFileType: string;
216
  readonly fileTypes: ReadonlyArray<string>;
217
  readonly defaultFor?: ReadonlyArray<string>;
218
  readonly defaultRendered?: ReadonlyArray<string>;
219
  readonly translator?: ITranslator;
220
  readonly toolbarFactory?: (widget?: Widget) => IToolbarItem[];
221
}
222

223
interface IFileType {
224
  readonly name: string;
225
  readonly mimeTypes: ReadonlyArray<string>;
226
  readonly extensions: ReadonlyArray<string>;
227
  readonly displayName?: string;
228
  readonly pattern?: string;
229
  readonly icon?: LabIcon.IResolvable;
230
  readonly iconClass?: string;
231
  readonly iconLabel?: string;
232
  readonly fileFormat?: string | null;
233
}
234
```