UNPKG

4.22 kBPlain TextView Raw
1// Copyright (c) Jupyter Development Team.
2// Distributed under the terms of the Modified BSD License.
3
4import { Widget } from '@lumino/widgets';
5
6/**
7 * A Lumino widget which wraps an IFrame.
8 */
9export class IFrame extends Widget {
10 /**
11 * Create a new IFrame widget.
12 */
13 constructor(options: IFrame.IOptions = {}) {
14 super({ node: Private.createNode() });
15 this.addClass('jp-IFrame');
16 this.sandbox = options.sandbox || [];
17 this.referrerPolicy = options.referrerPolicy || 'no-referrer';
18 }
19
20 /**
21 * Referrer policy for the iframe.
22 *
23 * #### Notes
24 * By default, `no-referrer` is chosen.
25 *
26 * For more information, see
27 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement/referrerPolicy
28 */
29 get referrerPolicy(): IFrame.ReferrerPolicy {
30 return this._referrerPolicy;
31 }
32 set referrerPolicy(value: IFrame.ReferrerPolicy) {
33 if (this._referrerPolicy === value) {
34 return;
35 }
36 this._referrerPolicy = value;
37 const iframe = this.node.querySelector('iframe')!;
38 iframe.setAttribute('referrerpolicy', value);
39 }
40
41 /**
42 * Exceptions to the sandboxing.
43 *
44 * #### Notes
45 * By default, all sandboxing security policies are enabled.
46 * This setting allows the user to selectively disable these
47 * policies. This should be done with care, as it can
48 * introduce security risks, and possibly allow malicious
49 * sites to execute code in a JupyterLab session.
50 *
51 * For more information, see
52 * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe
53 */
54 get sandbox(): IFrame.SandboxExceptions[] {
55 return this._sandbox.slice();
56 }
57 set sandbox(values: IFrame.SandboxExceptions[]) {
58 this._sandbox = values.slice();
59 const iframe = this.node.querySelector('iframe')!;
60 const exceptions = values.length ? values.join(' ') : '';
61 iframe.setAttribute('sandbox', exceptions);
62 }
63
64 /**
65 * The url of the IFrame.
66 */
67 get url(): string {
68 return this.node.querySelector('iframe')!.getAttribute('src') || '';
69 }
70 set url(url: string) {
71 this.node.querySelector('iframe')!.setAttribute('src', url);
72 }
73
74 private _sandbox: IFrame.SandboxExceptions[] = [];
75 private _referrerPolicy: IFrame.ReferrerPolicy;
76}
77
78/**
79 * A namespace for IFrame widget statics.
80 */
81export namespace IFrame {
82 /**
83 * Referrer policy for the iframe.
84 *
85 * User documentation for the policies can be found here:
86 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement/referrerPolicy
87 */
88 export type ReferrerPolicy =
89 | 'no-referrer'
90 | 'no-referrer-when-downgrade'
91 | 'origin'
92 | 'origin-when-cross-origin'
93 | 'same-origin'
94 | 'strict-origin'
95 | 'strict-origin-when-cross-origin'
96 | 'unsafe-url';
97
98 /**
99 * Exceptions to the iframe sandboxing policies.
100 * These are specified here:
101 * https://www.w3.org/TR/2011/WD-html5-20110525/the-iframe-element.html#attr-iframe-sandbox
102 *
103 * More user-friendly documentation can be found here:
104 * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox
105 */
106 export type SandboxExceptions =
107 | 'allow-downloads'
108 | 'allow-forms'
109 | 'allow-modals'
110 | 'allow-orientation-lock'
111 | 'allow-pointer-lock'
112 | 'allow-popups'
113 | 'popups-to-escape-sandbox'
114 | 'allow-presentation'
115 | 'allow-same-origin'
116 | 'allow-scripts'
117 | 'allow-storage-access-by-user-activation'
118 | 'allow-top-navigation'
119 | 'allow-top-navigation-by-user-activation';
120
121 /**
122 * Options for creating a new IFrame widget.
123 */
124 export interface IOptions {
125 /**
126 * Exceptions for the iframe sandbox.
127 */
128 sandbox?: SandboxExceptions[];
129
130 /**
131 * Referrer policy for the iframe.
132 */
133 referrerPolicy?: ReferrerPolicy;
134 }
135}
136
137/**
138 * A namespace for private data.
139 */
140namespace Private {
141 /**
142 * Create the main content node of an iframe widget.
143 */
144 export function createNode(): HTMLElement {
145 const node = document.createElement('div');
146 const iframe = document.createElement('iframe');
147 iframe.setAttribute('sandbox', '');
148 iframe.style.height = '100%';
149 iframe.style.width = '100%';
150 node.appendChild(iframe);
151 return node;
152 }
153}