0
# Renderer System
1

2
Core rendering interfaces for creating MIME renderers and factories that integrate with JupyterLab's rendering pipeline.
3

4
## Capabilities
5

6
### IRenderer Interface
7

8
A widget that displays the contents of a MIME model. Must extend the Lumino Widget class and implement the renderModel method.
9

10
```typescript { .api }
11
/**
12
 * A widget which displays the contents of a mime model
13
 */
14
interface IRenderer extends Widget {
15
  /**
16
   * Render a mime model.
17
   * This method may be called multiple times during the lifetime
18
   * of the widget to update it if and when new data is available.
19
   * @param model - The mime model to render
20
   * @returns A promise which resolves when rendering is complete
21
   */
22
  renderModel(model: IMimeModel): Promise<void>;
23
}
24
```
25

26
**Usage Example:**
27

28
```typescript
29
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
30
import { Widget } from "@lumino/widgets";
31

32
class CustomRenderer extends Widget implements IRenderMime.IRenderer {
33
  async renderModel(model: IRenderMime.IMimeModel): Promise<void> {
34
    // Clear previous content
35
    this.node.innerHTML = '';
36
    
37
    // Extract data from the model
38
    const data = model.data['application/my-custom-type'] as string;
39
    
40
    // Create and append content
41
    const content = document.createElement('div');
42
    content.className = 'custom-content';
43
    content.textContent = data;
44
    
45
    // Apply trust-based styling
46
    if (!model.trusted) {
47
      content.style.border = '2px solid orange';
48
      content.title = 'Untrusted content';
49
    }
50
    
51
    this.node.appendChild(content);
52
  }
53
}
54
```
55

56
### IRendererFactory Interface
57

58
Factory for creating renderer instances. Defines which MIME types can be handled and creates renderers with the appropriate options.
59

60
```typescript { .api }
61
/**
62
 * The interface for a renderer factory
63
 */
64
interface IRendererFactory {
65
  /**
66
   * Whether the factory is a "safe" factory.
67
   * A "safe" factory produces renderer widgets which can render
68
   * untrusted model data in a usable way. All renderers must
69
   * handle untrusted data safely, but some may simply failover
70
   * with a "Run cell to view output" message. A "safe" renderer
71
   * is an indication that its sanitized output will be useful.
72
   */
73
  readonly safe: boolean;
74
  /** The mime types handled by this factory */
75
  readonly mimeTypes: ReadonlyArray<string>;
76
  /** The default rank of the factory. If not given, defaults to 100. */
77
  readonly defaultRank?: number;
78
  /**
79
   * Create a renderer which displays the mime data
80
   * @param options - The options used to render the data
81
   */
82
  createRenderer(options: IRendererOptions): IRenderer;
83
}
84
```
85

86
**Usage Example:**
87

88
```typescript
89
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
90

91
class CustomRendererFactory implements IRenderMime.IRendererFactory {
92
  readonly safe = true;
93
  readonly mimeTypes = ['application/my-custom-type', 'text/my-format'];
94
  readonly defaultRank = 50;
95

96
  createRenderer(options: IRenderMime.IRendererOptions): IRenderMime.IRenderer {
97
    return new CustomRenderer(options);
98
  }
99
}
100

101
// Register with RenderMime
102
const factory = new CustomRendererFactory();
103
renderMime.addFactory(factory, factory.defaultRank);
104
```
105

106
### IRendererOptions Interface
107

108
Options passed to renderer factories when creating new renderer instances. Contains all the services needed for rendering.
109

110
```typescript { .api }
111
/**
112
 * The options used to create a renderer
113
 */
114
interface IRendererOptions {
115
  /** The preferred mimeType to render */
116
  mimeType: string;
117
  /** The html sanitizer */
118
  sanitizer: ISanitizer;
119
  /** An optional url resolver */
120
  resolver: IResolver | null;
121
  /** An optional link handler */
122
  linkHandler: ILinkHandler | null;
123
  /** The LaTeX typesetter */
124
  latexTypesetter: ILatexTypesetter | null;
125
  /** The Markdown parser */
126
  markdownParser?: IMarkdownParser | null;
127
  /** The application language translator */
128
  translator?: ITranslator;
129
}
130
```
131

132
**Usage Example:**
133

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

138
class AdvancedRenderer extends Widget implements IRenderMime.IRenderer {
139
  constructor(private options: IRenderMime.IRendererOptions) {
140
    super();
141
    this.addClass('advanced-renderer');
142
  }
143

144
  async renderModel(model: IRenderMime.IMimeModel): Promise<void> {
145
    const data = model.data[this.options.mimeType] as string;
146
    
147
    // Use sanitizer for HTML content
148
    if (this.options.mimeType === 'text/html') {
149
      const sanitized = this.options.sanitizer.sanitize(data);
150
      this.node.innerHTML = sanitized;
151
    }
152
    
153
    // Use markdown parser if available
154
    if (this.options.markdownParser && this.options.mimeType === 'text/markdown') {
155
      const html = await this.options.markdownParser.render(data);
156
      const sanitized = this.options.sanitizer.sanitize(html);
157
      this.node.innerHTML = sanitized;
158
    }
159
    
160
    // Use LaTeX typesetter for math content
161
    if (this.options.latexTypesetter) {
162
      this.options.latexTypesetter.typeset(this.node);
163
    }
164
    
165
    // Handle links if link handler is available
166
    if (this.options.linkHandler) {
167
      const links = this.node.querySelectorAll('a');
168
      links.forEach(link => {
169
        const href = link.getAttribute('href');
170
        if (href) {
171
          this.options.linkHandler!.handleLink(link as HTMLElement, href);
172
        }
173
      });
174
    }
175
    
176
    // Use translator for internationalization
177
    if (this.options.translator) {
178
      const bundle = this.options.translator.load('my-renderer');
179
      const title = bundle.__('Rendered Content');
180
      this.node.title = title;
181
    }
182
  }
183
}
184
```
185

186
## Types
187

188
All interfaces in this capability depend on several external types and interfaces:
189

190
```typescript { .api }
191
// From @lumino/widgets
192
class Widget {
193
  // Widget implementation from Lumino
194
}
195

196
// From other capabilities in this package
197
interface IMimeModel {
198
  readonly trusted: boolean;
199
  readonly data: ReadonlyPartialJSONObject;
200
  readonly metadata: ReadonlyPartialJSONObject;
201
  setData(options: IMimeModel.ISetDataOptions): void;
202
}
203

204
interface ISanitizer {
205
  sanitize(dirty: string, options?: ISanitizerOptions): string;
206
  getAutolink?(): boolean;
207
  readonly allowNamedProperties?: boolean;
208
}
209

210
interface IResolver {
211
  resolveUrl(url: string): Promise<string>;
212
  getDownloadUrl(url: string): Promise<string>;
213
  isLocal?(url: string, allowRoot?: boolean): boolean;
214
  resolvePath?(path: string): Promise<IResolvedLocation | null>;
215
}
216

217
interface ILinkHandler {
218
  handleLink(node: HTMLElement, path: string, id?: string): void;
219
  handlePath?(node: HTMLElement, path: string, scope: 'kernel' | 'server', id?: string): void;
220
}
221

222
interface ILatexTypesetter {
223
  typeset(element: HTMLElement): void;
224
}
225

226
interface IMarkdownParser {
227
  render(source: string): Promise<string>;
228
}
229

230
interface ITranslator {
231
  readonly languageCode: string;
232
  load(domain: string): TranslationBundle;
233
}
234
```