0
# Document System
1

2
Interfaces for document widget factories and file type associations that enable full document rendering capabilities.
3

4
## Capabilities
5

6
### IDocumentWidgetFactoryOptions Interface
7

8
Configuration options for creating document widget factories that integrate MIME renderers with JupyterLab's document system.
9

10
```typescript { .api }
11
/**
12
 * The options used to initialize a document widget factory.
13
 * This interface is intended to be used by mime renderer extensions
14
 * to define a document opener that uses its renderer factory.
15
 */
16
interface IDocumentWidgetFactoryOptions {
17
  /** The name of the widget to display in dialogs */
18
  readonly name: string;
19
  /** The label of the widget to display in dialogs. If not given, name is used instead. */
20
  readonly label?: string;
21
  /** The name of the document model type */
22
  readonly modelName?: string;
23
  /** The primary file type of the widget */
24
  readonly primaryFileType: string;
25
  /** The file types the widget can view */
26
  readonly fileTypes: ReadonlyArray<string>;
27
  /** The file types for which the factory should be the default */
28
  readonly defaultFor?: ReadonlyArray<string>;
29
  /**
30
   * The file types for which the factory should be the default for rendering,
31
   * if that is different than the default factory (which may be for editing)
32
   * If undefined, then it will fall back on the default file type.
33
   */
34
  readonly defaultRendered?: ReadonlyArray<string>;
35
  /** The application language translator */
36
  readonly translator?: ITranslator;
37
  /** A function returning a list of toolbar items to add to the toolbar */
38
  readonly toolbarFactory?: (widget?: Widget) => IToolbarItem[];
39
}
40
```
41

42
**Usage Example:**
43

44
```typescript
45
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
46
import { Widget } from "@lumino/widgets";
47

48
// Custom toolbar creation
49
function createCustomToolbar(widget?: Widget): IRenderMime.IToolbarItem[] {
50
  const refreshButton = new Widget();
51
  refreshButton.node.innerHTML = '<button class="jp-Button">Refresh</button>';
52
  refreshButton.node.onclick = () => {
53
    // Refresh logic
54
    console.log('Refreshing document...');
55
  };
56

57
  const exportButton = new Widget();
58
  exportButton.node.innerHTML = '<button class="jp-Button">Export</button>';
59
  
60
  return [
61
    {
62
      name: 'refresh',
63
      widget: refreshButton
64
    },
65
    {
66
      name: 'export', 
67
      widget: exportButton
68
    }
69
  ];
70
}
71

72
// Document widget factory options
73
const documentOptions: IRenderMime.IDocumentWidgetFactoryOptions = {
74
  name: 'Data Visualization Viewer',
75
  label: 'Data Viz',
76
  modelName: 'data-viz-model',
77
  
78
  // File type configuration
79
  primaryFileType: 'data-viz',
80
  fileTypes: ['data-viz', 'data-viz-alt'],
81
  defaultFor: ['data-viz'],
82
  defaultRendered: ['data-viz', 'data-viz-alt'],
83
  
84
  // Custom toolbar
85
  toolbarFactory: createCustomToolbar,
86
  
87
  // Internationalization
88
  translator: myTranslator
89
};
90

91
// Use in extension
92
const extension: IRenderMime.IExtension = {
93
  id: 'my-org:data-viz-renderer',
94
  rendererFactory: new DataVizRendererFactory(),
95
  documentWidgetFactoryOptions: documentOptions
96
};
97
```
98

99
### IFileType Interface
100

101
Defines file type associations including MIME types, file extensions, and display properties.
102

103
```typescript { .api }
104
/**
105
 * A file type to associate with the renderer
106
 */
107
interface IFileType {
108
  /** The name of the file type */
109
  readonly name: string;
110
  /** The mime types associated the file type */
111
  readonly mimeTypes: ReadonlyArray<string>;
112
  /** The extensions of the file type (e.g. ".txt"). Can be a compound extension (e.g. ".table.json"). */
113
  readonly extensions: ReadonlyArray<string>;
114
  /** An optional display name for the file type */
115
  readonly displayName?: string;
116
  /** An optional pattern for a file name (e.g. "^Dockerfile$") */
117
  readonly pattern?: string;
118
  /**
119
   * The icon for the file type. Can either be a string containing the name
120
   * of an existing icon, or an object with {name, svgstr} fields, where
121
   * svgstr is a string containing the raw contents of an svg file.
122
   */
123
  readonly icon?: LabIcon.IResolvable;
124
  /** The icon class name for the file type */
125
  readonly iconClass?: string;
126
  /** The icon label for the file type */
127
  readonly iconLabel?: string;
128
  /** The file format for the file type ('text', 'base64', or 'json') */
129
  readonly fileFormat?: string | null;
130
}
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
137

138
// Simple text-based file type
139
const csvFileType: IRenderMime.IFileType = {
140
  name: 'csv-custom',
141
  mimeTypes: ['text/csv', 'application/csv'],
142
  extensions: ['.csv'],
143
  displayName: 'CSV Data File',
144
  fileFormat: 'text',
145
  icon: 'table',
146
  iconLabel: 'CSV'
147
};
148

149
// Complex binary file type with custom icon
150
const customBinaryType: IRenderMime.IFileType = {
151
  name: 'custom-binary',
152
  mimeTypes: ['application/x-custom-binary'],
153
  extensions: ['.cbin', '.custom'],
154
  displayName: 'Custom Binary Format',
155
  fileFormat: 'base64',
156
  
157
  // Custom SVG icon
158
  icon: {
159
    name: 'custom-binary:icon',
160
    svgstr: `<svg width="16" height="16" viewBox="0 0 16 16">
161
      <rect width="16" height="16" fill="#4CAF50"/>
162
      <text x="8" y="12" text-anchor="middle" fill="white" font-size="10">CB</text>
163
    </svg>`
164
  }
165
};
166

167
// Pattern-based file type (like Dockerfile)
168
const configFileType: IRenderMime.IFileType = {
169
  name: 'app-config',
170
  mimeTypes: ['application/json'],
171
  extensions: ['.json'],
172
  pattern: '^app\\.config\\.json$',
173
  displayName: 'Application Configuration',
174
  fileFormat: 'json',
175
  iconClass: 'jp-MaterialIcon jp-SettingsIcon'
176
};
177

178
// Multiple extensions with compound names
179
const dataTableType: IRenderMime.IFileType = {
180
  name: 'data-table',
181
  mimeTypes: ['application/x-data-table'],
182
  extensions: ['.table.json', '.data.json', '.tbl'],
183
  displayName: 'Data Table',
184
  fileFormat: 'json',
185
  icon: 'spreadsheet'
186
};
187

188
// Register file types with extension
189
const extension: IRenderMime.IExtension = {
190
  id: 'my-org:multi-format-renderer',
191
  rendererFactory: new MultiFormatRendererFactory(),
192
  
193
  fileTypes: [
194
    csvFileType,
195
    customBinaryType,
196
    configFileType,
197
    dataTableType
198
  ],
199
  
200
  documentWidgetFactoryOptions: [
201
    {
202
      name: 'CSV Viewer',
203
      primaryFileType: 'csv-custom',
204
      fileTypes: ['csv-custom']
205
    },
206
    {
207
      name: 'Binary Data Viewer', 
208
      primaryFileType: 'custom-binary',
209
      fileTypes: ['custom-binary'],
210
      defaultFor: ['custom-binary']
211
    },
212
    {
213
      name: 'Config Editor',
214
      primaryFileType: 'app-config', 
215
      fileTypes: ['app-config'],
216
      pattern: '^app\\.config\\.json$'
217
    }
218
  ]
219
};
220
```
221

222
## Advanced File Type Patterns
223

224
### File Format Handling
225

226
```typescript
227
// Different file format types
228
const textFileType: IRenderMime.IFileType = {
229
  name: 'custom-text',
230
  mimeTypes: ['text/x-custom'],
231
  extensions: ['.ctxt'],
232
  fileFormat: 'text' // Read as text string
233
};
234

235
const binaryFileType: IRenderMime.IFileType = {
236
  name: 'custom-binary',
237
  mimeTypes: ['application/x-custom-binary'],
238
  extensions: ['.cbin'],
239
  fileFormat: 'base64' // Read as base64-encoded string
240
};
241

242
const jsonFileType: IRenderMime.IFileType = {
243
  name: 'custom-json',
244
  mimeTypes: ['application/x-custom'],
245
  extensions: ['.cjson'],
246
  fileFormat: 'json' // Parse as JSON
247
};
248
```
249

250
### Icon Configuration Options
251

252
```typescript
253
// String icon reference
254
const stringIconType: IRenderMime.IFileType = {
255
  name: 'document-type',
256
  mimeTypes: ['application/document'],
257
  extensions: ['.doc'],
258
  icon: 'document' // Reference to existing icon
259
};
260

261
// CSS class icon
262
const cssIconType: IRenderMime.IFileType = {
263
  name: 'spreadsheet-type',
264
  mimeTypes: ['application/spreadsheet'],
265
  extensions: ['.sheet'],
266
  iconClass: 'jp-MaterialIcon jp-SpreadsheetIcon'
267
};
268

269
// Custom SVG icon
270
const customIconType: IRenderMime.IFileType = {
271
  name: 'special-type',
272
  mimeTypes: ['application/special'],
273
  extensions: ['.spec'],
274
  icon: {
275
    name: 'special:icon',
276
    svgstr: '<svg>...</svg>' // Full SVG content
277
  }
278
};
279
```
280

281
## Types
282

283
This capability depends on several interfaces:
284

285
```typescript { .api }
286
// From other capabilities
287
interface ITranslator {
288
  readonly languageCode: string;
289
  load(domain: string): TranslationBundle;
290
}
291

292
interface IToolbarItem {
293
  name: string;
294
  widget: Widget;
295
}
296

297
namespace LabIcon {
298
  interface IIcon {
299
    readonly name: string;
300
    svgstr: string;
301
  }
302
  
303
  interface IRenderer {
304
    readonly render: (container: HTMLElement, options?: any) => void;
305
    readonly unrender?: (container: HTMLElement, options?: any) => void;
306
  }
307
  
308
  type IResolvable = string | (IIcon & Partial<IRenderer>);
309
}
310

311
// From @lumino/widgets
312
class Widget {
313
  // Widget implementation from Lumino
314
}
315
```