Chromium Code Reviews| OLD | NEW |
|---|---|
| 1 <h1>External Content</h1> | 1 <h1>External Content</h1> |
| 2 | 2 |
| 3 | 3 |
| 4 <p> | 4 <p> |
| 5 The <a href="app_architecture.html#security">Chrome Apps security model</a> disa llows | 5 The <a href="app_architecture#security">Chrome Apps security model</a> disallows |
| 6 external content in iframes and | 6 external content in iframes and |
| 7 the use of inline scripting and <code>eval()</code>. | 7 the use of inline scripting and <code>eval()</code>. |
| 8 You can override these restrictions, | 8 You can override these restrictions, |
| 9 but your external content must be isolated from the app. | 9 but your external content must be isolated from the app. |
| 10 </p> | 10 </p> |
| 11 | 11 |
| 12 <p> | 12 <p> |
| 13 Isolated content cannot directly | 13 Isolated content cannot directly |
| 14 access the app's data or any of the APIs. | 14 access the app's data or any of the APIs. |
| 15 Use cross-origin XMLHttpRequests | 15 Use cross-origin XMLHttpRequests |
| 16 and post-messaging to communicate between the event page and sandboxed content | 16 and post-messaging to communicate between the event page and sandboxed content |
| 17 and indirectly access the APIs. | 17 and indirectly access the APIs. |
| 18 </p> | 18 </p> |
| 19 | 19 |
| 20 <p class="note"> | 20 <p class="note"> |
| 21 <b>API Sample: </b> | 21 <b>API Sample: </b> |
| 22 Want to play with the code? | 22 Want to play with the code? |
| 23 Check out the | 23 Check out the |
| 24 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/sandbox" >sandbox</a> sample. | 24 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/sandbox" >sandbox</a> sample. |
| 25 </p> | 25 </p> |
| 26 | 26 |
| 27 <h2 id="external">Referencing external resources</h2> | 27 <h2 id="external">Referencing external resources</h2> |
| 28 | 28 |
| 29 <p> | 29 <p> |
| 30 The <a href="contentSecurityPolicy.html">Content Security Policy</a> used by app s disallows | 30 The <a href="contentSecurityPolicy">Content Security Policy</a> used by apps dis allows |
| 31 the use of many kinds of remote URLs, so you can't directly reference external | 31 the use of many kinds of remote URLs, so you can't directly reference external |
| 32 images, stylesheets, or fonts from an app page. Instead, you can use use | 32 images, stylesheets, or fonts from an app page. Instead, you can use use |
| 33 cross-origin XMLHttpRequests to fetch these resources, | 33 cross-origin XMLHttpRequests to fetch these resources, |
| 34 and then serve them via <code>blob:</code> URLs. | 34 and then serve them via <code>blob:</code> URLs. |
| 35 </p> | 35 </p> |
| 36 | 36 |
| 37 <h3 id="manifest">Manifest requirement</h3> | 37 <h3 id="manifest">Manifest requirement</h3> |
| 38 | 38 |
| 39 <p> | 39 <p> |
| 40 To be able to do cross-origin XMLHttpRequests, you'll need to add a permission | 40 To be able to do cross-origin XMLHttpRequests, you'll need to add a permission |
| (...skipping 20 matching lines...) Expand all Loading... | |
| 61 xhr.responseType = 'blob'; | 61 xhr.responseType = 'blob'; |
| 62 xhr.onload = function(e) { | 62 xhr.onload = function(e) { |
| 63 var img = document.createElement('img'); | 63 var img = document.createElement('img'); |
| 64 img.src = window.URL.createObjectURL(this.response); | 64 img.src = window.URL.createObjectURL(this.response); |
| 65 document.body.appendChild(img); | 65 document.body.appendChild(img); |
| 66 }; | 66 }; |
| 67 | 67 |
| 68 xhr.send(); | 68 xhr.send(); |
| 69 </pre> | 69 </pre> |
| 70 | 70 |
| 71 <p>You may want to <a href="offline_apps.html#saving-locally">save</a> | 71 <p>You may want to <a href="offline_apps#saving-locally">save</a> |
| 72 these resources locally, so that they are available offline.</p> | 72 these resources locally, so that they are available offline.</p> |
| 73 | 73 |
| 74 <h2 id="webview">Embed external web pages</h2> | 74 <h2 id="webview">Embed external web pages</h2> |
| 75 | 75 |
| 76 <p class="note"> | 76 <p class="note"> |
| 77 <b>API Sample: </b> | 77 <b>API Sample: </b> |
| 78 Want to play with the code? Check out the | 78 Want to play with the code? Check out the |
| 79 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/browser" >browser</a> | 79 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/browser" >browser</a> |
| 80 sample. | 80 sample. |
| 81 </p> | 81 </p> |
| 82 | 82 |
| 83 <p> | 83 <p> |
| 84 The <code>webview</code> tag allows you to embed external web content in your | 84 The <code>webview</code> tag allows you to embed external web content in your |
| 85 app, for example, a web page. It replaces iframes that point to remote URLs, | 85 app, for example, a web page. It replaces iframes that point to remote URLs, |
| 86 which are disabled inside Chrome Apps. Unlike iframes, the | 86 which are disabled inside Chrome Apps. Unlike iframes, the |
| 87 <code>webview</code> tag runs in a separate process. This means that an exploit | 87 <code>webview</code> tag runs in a separate process. This means that an exploit |
| 88 inside of it will still be isolated and won't be able to gain elevated | 88 inside of it will still be isolated and won't be able to gain elevated |
| 89 privileges. Further, since its storage (cookies, etc.) is isolated from the app, | 89 privileges. Further, since its storage (cookies, etc.) is isolated from the app, |
| 90 there is no way for the web content to access any of the app's data. | 90 there is no way for the web content to access any of the app's data. |
| 91 </p> | 91 </p> |
| 92 | 92 |
| 93 <h3 id="webview_element">Add webview element</h3> | 93 <h3 id="webview_element">Add webview element</h3> |
| 94 | 94 |
| 95 <p> | 95 <p> |
| 96 Your <code>webview</code> element must include the URL to the source content | 96 Your <code>webview</code> element must include the URL to the source content |
| 97 and specify its dimensions. | 97 and specify its dimensions. |
| 98 </p> | 98 </p> |
| 99 | 99 |
| 100 <pre data-filename="browser.html"> | 100 <pre data-filename="browser"> |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 101 <webview src="http://news.google.com/" width="640" height="480"></webview> | 101 <webview src="http://news.google.com/" width="640" height="480"></webview> |
| 102 </pre> | 102 </pre> |
| 103 | 103 |
| 104 <h3 id="properties">Update properties</h3> | 104 <h3 id="properties">Update properties</h3> |
| 105 | 105 |
| 106 <p> | 106 <p> |
| 107 To dynamically change the <code>src</code>, <code>width</code> and | 107 To dynamically change the <code>src</code>, <code>width</code> and |
| 108 <code>height</code> properties of a <code>webview</code> tag, you can either | 108 <code>height</code> properties of a <code>webview</code> tag, you can either |
| 109 set those properties directly on the JavaScript object, or use the | 109 set those properties directly on the JavaScript object, or use the |
| 110 <code>setAttribute</code> DOM function. | 110 <code>setAttribute</code> DOM function. |
| 111 </p> | 111 </p> |
| 112 | 112 |
| 113 <pre data-filename="browser.js"> | 113 <pre data-filename="browser.js"> |
| 114 document.querySelector('#mywebview').src = | 114 document.querySelector('#mywebview').src = |
| 115 'http://blog.chromium.org/'; | 115 'http://blog.chromium.org/'; |
| 116 // or | 116 // or |
| 117 document.querySelector('#mywebview').setAttribute( | 117 document.querySelector('#mywebview').setAttribute( |
| 118 'src', 'http://blog.chromium.org/'); | 118 'src', 'http://blog.chromium.org/'); |
| 119 </pre> | 119 </pre> |
| 120 | 120 |
| 121 <h2 id="sandboxing">Sandbox local content</h2> | 121 <h2 id="sandboxing">Sandbox local content</h2> |
| 122 | 122 |
| 123 <p> | 123 <p> |
| 124 Sandboxing allows specified pages | 124 Sandboxing allows specified pages |
| 125 to be served in a sandboxed, unique origin. | 125 to be served in a sandboxed, unique origin. |
| 126 These pages are then exempt from their Content Security Policy. | 126 These pages are then exempt from their Content Security Policy. |
| 127 Sandboxed pages can use iframes, inline scripting, | 127 Sandboxed pages can use iframes, inline scripting, |
| 128 and <code>eval()</code>. | 128 and <code>eval()</code>. |
| 129 Check out the manifest field description for | 129 Check out the manifest field description for |
| 130 <a href="manifest/sandbox.html">sandbox</a>. | 130 <a href="manifest/sandbox">sandbox</a>. |
| 131 </p> | 131 </p> |
| 132 | 132 |
| 133 <p> | 133 <p> |
| 134 It's a trade-off though: | 134 It's a trade-off though: |
| 135 sandboxed pages can't use the chrome.* APIs. | 135 sandboxed pages can't use the chrome.* APIs. |
| 136 If you need to do things like <code>eval()</code>, | 136 If you need to do things like <code>eval()</code>, |
| 137 go this route to be exempt from CSP, | 137 go this route to be exempt from CSP, |
| 138 but you won't be able to use the cool new stuff. | 138 but you won't be able to use the cool new stuff. |
| 139 </p> | 139 </p> |
| 140 | 140 |
| 141 <h3 id="inline_scripts">Use inline scripts in sandbox</h3> | 141 <h3 id="inline_scripts">Use inline scripts in sandbox</h3> |
| 142 | 142 |
| 143 <p> | 143 <p> |
| 144 Here's a sample sandboxed page | 144 Here's a sample sandboxed page |
| 145 which uses an inline script and <code>eval()</code>: | 145 which uses an inline script and <code>eval()</code>: |
| 146 </p> | 146 </p> |
| 147 | 147 |
| 148 <pre data-filename="sandboxed.html"> | 148 <pre data-filename="sandboxed"> |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 149 <html> | 149 <html> |
| 150 <body> | 150 <body> |
| 151 <h1>Woot</h1> | 151 <h1>Woot</h1> |
| 152 <script> | 152 <script> |
| 153 document.write('I am an inline script.<br>'); | 153 document.write('I am an inline script.<br>'); |
| 154 eval('document.write(\'I am an eval-ed inline script.\');'); | 154 eval('document.write(\'I am an eval-ed inline script.\');'); |
| 155 </script> | 155 </script> |
| 156 </body> | 156 </body> |
| 157 </html> | 157 </html> |
| 158 </pre> | 158 </pre> |
| 159 | 159 |
| 160 <h3 id="include_sandbox">Include sandbox in manifest</h3> | 160 <h3 id="include_sandbox">Include sandbox in manifest</h3> |
| 161 | 161 |
| 162 <p> | 162 <p> |
| 163 You need to include the <code>sandbox</code> field in the manifest | 163 You need to include the <code>sandbox</code> field in the manifest |
| 164 and list the app pages to be served in a sandbox: | 164 and list the app pages to be served in a sandbox: |
| 165 </p> | 165 </p> |
| 166 | 166 |
| 167 <pre data-filename="manifest.json"> | 167 <pre data-filename="manifest.json"> |
| 168 "sandbox": { | 168 "sandbox": { |
| 169 "pages": ["sandboxed.html"] | 169 "pages": ["sandboxed"] |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 170 } | 170 } |
| 171 </pre> | 171 </pre> |
| 172 | 172 |
| 173 <h3 id="opening_sandbox">Opening a sandboxed page in a window</h3> | 173 <h3 id="opening_sandbox">Opening a sandboxed page in a window</h3> |
| 174 | 174 |
| 175 <p> | 175 <p> |
| 176 Just like any other app pages, | 176 Just like any other app pages, |
| 177 you can create a window that the sandboxed page opens in. | 177 you can create a window that the sandboxed page opens in. |
| 178 Here's a sample that creates two windows, | 178 Here's a sample that creates two windows, |
| 179 one for the main app window that isn't sandboxed, | 179 one for the main app window that isn't sandboxed, |
| 180 and one for the sandboxed page: | 180 and one for the sandboxed page: |
| 181 </p> | 181 </p> |
| 182 | 182 |
| 183 <p class="warning"> | 183 <p class="warning"> |
| 184 NOTE: | 184 NOTE: |
| 185 <a href="https://code.google.com/p/chromium/issues/detail?id=154662">issue 15466 2</a> | 185 <a href="https://code.google.com/p/chromium/issues/detail?id=154662">issue 15466 2</a> |
| 186 is a bug when using sandbox pages to create windows. | 186 is a bug when using sandbox pages to create windows. |
| 187 The effect is that an error "Uncaught TypeError: Cannot call method | 187 The effect is that an error "Uncaught TypeError: Cannot call method |
| 188 'initializeAppWindow' of undefined" is output to the developer console | 188 'initializeAppWindow' of undefined" is output to the developer console |
| 189 and that the app.window.create call does not call the callback function | 189 and that the app.window.create call does not call the callback function |
| 190 with a window object. However, the sandbox page is created as a new window. | 190 with a window object. However, the sandbox page is created as a new window. |
| 191 </p> | 191 </p> |
| 192 | 192 |
| 193 <pre data-filename="background.js"> | 193 <pre data-filename="background.js"> |
| 194 chrome.app.runtime.onLaunched.addListener(function() { | 194 chrome.app.runtime.onLaunched.addListener(function() { |
| 195 chrome.app.window.create('window.html', { | 195 chrome.app.window.create('window', { |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 196 'bounds': { | 196 'bounds': { |
| 197 'width': 400, | 197 'width': 400, |
| 198 'height': 400, | 198 'height': 400, |
| 199 'left': 0, | 199 'left': 0, |
| 200 'top': 0 | 200 'top': 0 |
| 201 } | 201 } |
| 202 }); | 202 }); |
| 203 | 203 |
| 204 chrome.app.window.create('sandboxed.html', { | 204 chrome.app.window.create('sandboxed', { |
| 205 'bounds': { | 205 'bounds': { |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 206 'width': 400, | 206 'width': 400, |
| 207 'height': 400, | 207 'height': 400, |
| 208 'left': 400, | 208 'left': 400, |
| 209 'top': 0 | 209 'top': 0 |
| 210 } | 210 } |
| 211 }); | 211 }); |
| 212 }); | 212 }); |
| 213 </pre> | 213 </pre> |
| 214 | 214 |
| 215 <h3 id="embedding_sandbox">Embedding a sandboxed page in an app page</h3> | 215 <h3 id="embedding_sandbox">Embedding a sandboxed page in an app page</h3> |
| 216 | 216 |
| 217 <p>Sandboxed pages can also be embedded within another app page | 217 <p>Sandboxed pages can also be embedded within another app page |
| 218 using an <code>iframe</code>:</p> | 218 using an <code>iframe</code>:</p> |
| 219 | 219 |
| 220 <pre data-filename="window.html"> | 220 <pre data-filename="window"> |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 221 <!DOCTYPE html> | 221 <!DOCTYPE html> |
| 222 <html> | 222 <html> |
| 223 <head> | 223 <head> |
| 224 </head> | 224 </head> |
| 225 <body> | 225 <body> |
| 226 <p>I am normal app window.</p> | 226 <p>I am normal app window.</p> |
| 227 | 227 |
| 228 <iframe src="sandboxed.html" width="300" height="200"></iframe> | 228 <iframe src="sandboxed" width="300" height="200"></iframe> |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 229 </body> | 229 </body> |
| 230 </html> | 230 </html> |
| 231 </pre> | 231 </pre> |
| 232 | 232 |
| 233 | 233 |
| 234 <h2 id="postMessage">Sending messages to sandboxed pages</h2> | 234 <h2 id="postMessage">Sending messages to sandboxed pages</h2> |
| 235 | 235 |
| 236 <p> | 236 <p> |
| 237 There are two parts to sending a message: | 237 There are two parts to sending a message: |
| 238 you need to post a message from the sender page/window, | 238 you need to post a message from the sender page/window, |
| 239 and listen for messages on the receiving page/window. | 239 and listen for messages on the receiving page/window. |
| 240 </p> | 240 </p> |
| 241 | 241 |
| 242 <h3 id="post_message">Post message</h3> | 242 <h3 id="post_message">Post message</h3> |
| 243 | 243 |
| 244 <p> | 244 <p> |
| 245 You can use <code>postMessage</code> to communicate | 245 You can use <code>postMessage</code> to communicate |
| 246 between your app and sandboxed content. | 246 between your app and sandboxed content. |
| 247 Here's a sample background script | 247 Here's a sample background script |
| 248 that posts a message to the sandboxed page it | 248 that posts a message to the sandboxed page it |
| 249 opens: | 249 opens: |
| 250 </p> | 250 </p> |
| 251 | 251 |
| 252 <pre data-filename="background.js"> | 252 <pre data-filename="background.js"> |
| 253 var myWin = null; | 253 var myWin = null; |
| 254 | 254 |
| 255 chrome.app.runtime.onLaunched.addListener(function() { | 255 chrome.app.runtime.onLaunched.addListener(function() { |
| 256 chrome.app.window.create('sandboxed.html', { | 256 chrome.app.window.create('sandboxed', { |
| 257 'bounds': { | 257 'bounds': { |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 258 'width': 400, | 258 'width': 400, |
| 259 'height': 400 | 259 'height': 400 |
| 260 } | 260 } |
| 261 }, function(win) { | 261 }, function(win) { |
| 262 myWin = win; | 262 myWin = win; |
| 263 myWin.contentWindow.postMessage('Just wanted to say hey.', '*'); | 263 myWin.contentWindow.postMessage('Just wanted to say hey.', '*'); |
| 264 }); | 264 }); |
| 265 }); | 265 }); |
| 266 </pre> | 266 </pre> |
| 267 | 267 |
| (...skipping 12 matching lines...) Expand all Loading... | |
| 280 To find out more, | 280 To find out more, |
| 281 see <a href="https://developer.mozilla.org/en/DOM/window.postMessage">window.pos tMessage</a>. | 281 see <a href="https://developer.mozilla.org/en/DOM/window.postMessage">window.pos tMessage</a>. |
| 282 </p> | 282 </p> |
| 283 | 283 |
| 284 <h3 id="listen_message">Listen for message</h3> | 284 <h3 id="listen_message">Listen for message</h3> |
| 285 | 285 |
| 286 <p> | 286 <p> |
| 287 Here's a sample message receiver | 287 Here's a sample message receiver |
| 288 that gets added to your sandboxed page: | 288 that gets added to your sandboxed page: |
| 289 </p> | 289 </p> |
| 290 | 290 |
|
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
| 291 <pre data-filename="sandboxed.html"> | 291 <pre data-filename="sandboxed"> |
| 292 var messageHandler = function(e) { | 292 var messageHandler = function(e) { |
| 293 console.log('Background script says hello.', e.data); | 293 console.log('Background script says hello.', e.data); |
| 294 }; | 294 }; |
| 295 | 295 |
| 296 window.addEventListener('message', messageHandler); | 296 window.addEventListener('message', messageHandler); |
| 297 </pre> | 297 </pre> |
| 298 | 298 |
| 299 <p class="backtotop"><a href="#top">Back to top</a></p> | 299 <p class="backtotop"><a href="#top">Back to top</a></p> |
| OLD | NEW |