Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(830)

Side by Side Diff: chrome/common/extensions/docs/templates/articles/app_codelab8_webresources.html

Issue 645693006: Updated Chrome Apps codelab (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Created 6 years, 2 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
(Empty)
1 <h1 id="lab_8_web_resources">Access Web Resources</h1>
2
3 <p>Chrome Apps have a strict
4 <a href="contentSecurityPolicy">Content Security Policy</a>
5 which will not let the user execute code or load resources that are hosted remot ely.</p>
6
7 <p>Many applications, however, need to be able to load and display content from a remote location. A News Reader, for example, needs to display remote content i nline or load and show images from a remote URL.</p>
8
9 <h2 id="loading_external_web_content_into_an_element">Load external web content< /h2>
10
11 <p>Sites on the internet are inherently a security risk and rendering arbitrary web pages directly into your application with elevated privileges would be a pot ential source of exploits.</p>
12
13 <p>Chrome Apps offer developers the ability
14 to securely render third-party content in the <code>&lt;webview&gt;</code> tag.
15 A <a href="webview_tag">webview</a>
16 is like an iframe that you can control with greater flexibility and added securi ty.
17 It runs in a separate sandboxed process and can&#39;t communicate directly with the application.</p>
18
19 <p>The <code>webview</code> has a very simple API.
20 From your app you can:</p>
21
22 <ul>
23 <li> Change the URL of the <code>webview</code>.</li>
24 <li> Navigate forwards and backward, stop loading and reload.</li>
25 <li> Check if the <code>webview</code> has finished loading and if it is possibl e, go back and forward in the history stack.</li>
26 </ul>
27
28 <p>We will change our code to render the content of URLs dropped
29 in the drag-and-drop operations in a <code>webview</code> when the user clicks o n a link.</p>
30
31 <h3 id="manifest">Update manifest</h3>
32
33 <p>Request a new permission, &quot;webview&quot;, in the manifest.
34 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/1_webview/manifest.json">Angular JS manifest.json</a> and
35 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/1_webview/manifest.json">JavaScript manifest.json</a> are t he same:
36 </p>
37
38 <pre data-filename="manifest.json">
39 &quot;permissions&quot;: [&quot;storage&quot;, &quot;webview&quot;]
40 </pre>
41
42 <h3 id="view">Update view</h3>
43
44 <p>Add a <code>&lt;webview&gt;</code> tag and a link to the view:
45 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/1_webview/index.html">AngularJS index.html</a> or
46 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/1_webview/index.html">JavaScript index.html</a>:
47 </p>
48
49 <tabs data-group="source">
50
51 <header tabindex="0" data-value="angular">Angular</header>
52 <header tabindex="0" data-value="js">JavaScript</header>
53
54 <content>
55 <pre data-filename="index.html">
56 &lt;!-- in TODO item: --&gt;
57 &lt;a ng-show=&quot;todo.uri&quot; href=&quot;&quot; ng-click=&quot;showUri(todo .uri)&quot;&gt;(view url)&lt;/a&gt;
58 &lt;!-- at the bottom, below the end of body: --&gt;
59 &lt;webview&gt;&lt;/webview&gt;
60 </pre>
61 </content>
62 <content>
63 <pre data-filename="index.html">
64 &lt;!-- right after the &quot;dropText&quot; div: --&gt;
65 &lt;webview&gt;&lt;/webview&gt;
66 &lt;!-- in the TODO template, right before the end of the li: --&gt;
67 &lt;a style=&quot;display: none;&quot; href=&quot;&quot;&gt;(view url)&lt;/a&gt;
68 </pre>
69 </content>
70
71 </tabs>
72
73 <h3 id="css">Update stylesheet</h3>
74
75 <p>Set an appropriate width and height to the <code>&lt;webview&gt;</code> tag i n
76 the style sheet.
77 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/1_webview/todo.css">AngularJS todo.css</a> and
78 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/1_webview/todo.css">JavaScript todo.css</a> are the same:
79 </p>
80
81 <pre data-filename="todo.css">
82 webview {
83 width: 100%;
84 height: 200px;
85 }
86 </pre>
87
88 <h3 id="controller">Update controller</h3>
89
90 <p>We now only need to add a method,
91 <code>showUri</code>, to the
92 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/1_webview/controller.js">AngularJS controller.js</a>
93 or an event handler, <code>showUrl</code>, to the
94 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/1_webview/controller.js">JavaScript controller.js</a>.
95 </p>
96
97 <tabs data-group="source">
98
99 <header tabindex="0" data-value="angular">Angular</header>
100 <header tabindex="0" data-value="js">JavaScript</header>
101
102 <content>
103 <pre data-filename="controller.js">
104 $scope.showUri = function(uri) {
105 var webview=document.querySelector(&quot;webview&quot;);
106 webview.src=uri;
107 };
108 </pre>
109 </content>
110 <content>
111 <pre data-filename="controller.js">
112 if(/^http:\/\/|https:\/\//.test(todoObj.text)) {
113 var showUrl = el.querySelector('a');
114 showUrl.addEventListener('click', function(e) {
115 e.preventDefault();
116 var webview=document.querySelector("webview");
117 webview.src=todoObj.text;
118 });
119 showUrl.style.display = 'inline';
120 }
121 </pre>
122 </content>
123
124 </tabs>
125
126 <h3 id="results">Check the results</h3>
127
128 <p>To test, open the app, right-click, and select Reload App.
129 You should be able to click on the &quot;view url&quot; link
130 on any dropped URL Todo item,
131 and the corresponding web page will show in the <code>webview</code>.
132 If it&#39;s not showing,
133 inspect the page and check if you set the <code>webview</code> size appropriatel y.</p>
134
135 <p>If you get stuck and want to see the app in action,
136 go to <code>chrome://extensions</code>,
137 load the unpacked
138 <a href="https://github.com/GoogleChrome/chrome-app-codelab/tree/master/lab8_web resources/angularjs/1_webview">AngularJS 1_webview</a> or
139 <a href="https://github.com/GoogleChrome/chrome-app-codelab/tree/master/lab8_web resources/javascript/1_webview">JavaScript 1_webview</a>,
140 and launch the app from a new tab.</p>
141
142 <h2 id="loading_external_images">Load external images</h2>
143
144 <p>If you try to add an <code>&lt;img&gt;</code> tag to your <code>index.html</c ode>, and point its <code>src</code> attribute to any site on the web, the follo wing exception is thrown in the console and the image isn&#39;t loaded:</p>
145
146 <p class="note"><b></b> Refused to load the image &#39;http://angularjs.org/img/ AngularJS-large.png&#39; because it violates the following Content Security Poli cy directive: &quot;img-src &#39;self&#39; data: chrome-extension-resource:&quot ;.</p>
147
148 <p>Chrome Apps cannot load any external resource directly in the DOM, because of the <a href="contentSecurityPolicy">CSP restrictions</a>.</p>
149
150 <p>To avoid this restriction, you can use XHR requests, grab the blob correspond ing to the remote file and use it appropriately.
151 For example, <code>&lt;img&gt;</code> tags can use a blob URL.
152 Let&#39;s change our application to show a small icon in the Todo list if the dr opped URL represents an image.</p>
153
154 <h3 id="manifest2">Update manifest</h3>
155
156 <p>Before you start firing XHR requests, you must request permissions.
157 Since we want to allow users to drag and drop images from any server,
158 we need to request permission to XHR to any URL.
159 Change
160 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/2_loading_resources/manifest.json">AngularJS manifest.json</ a> or
161 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/2_loading_resources/manifest.json">JavaScript manifest.json </a>:
162 </p>
163
164 <pre data-filename="manifest.json">
165 &quot;permissions&quot;: [&quot;storage&quot;, &quot;webview&quot;, &quot;&lt;al l_urls&gt;&quot;]
166 </pre>
167
168 <h3 id="image">Add image</h3>
169
170 <p>Add to your project a placeholder image
171 <img src="https://github.com/GoogleChrome/chrome-app-codelab/raw/master/lab8_web resources/angularjs/2_loading_resources/loading.gif" alt="loading.gif">
172 that will be shown while we are loading the proper image.</p>
173
174 <p>Then add the <code>&lt;img&gt;</code> tag to the Todo item on the view:
175 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/2_loading_resources/index.html">AngularJS index.html</a> or
176 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/2_loading_resources/index.html">JavaScript index_html</a>:
177 </p>
178
179 <tabs data-group="source">
180
181 <header tabindex="0" data-value="angular">Angular</header>
182 <header tabindex="0" data-value="js">JavaScript</header>
183
184 <content>
185 <pre data-filename="loader.js">
186 &lt;img style=&quot;max-height: 48px; max-width: 120px;&quot; ng-show=&quot;todo .validImage&quot;
187 ng-src=&quot;&#123;&#123;todo.imageUrl&#125;&#125;&quot;&gt;&lt;/img&gt;
188 </pre>
189 </content>
190 <content>
191 <pre data-filename="loader.js">
192 &lt;img style=&quot;max-height: 48px; max-width: 120px;&quot;&gt;&lt;/img&gt;
193 </pre>
194 </content>
195
196 </tabs>
197
198 <p>
199 In the
200 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/2_loading_resources/controller.js">JavaScript controller.js </a>,
201 add a constant for the placeholder image:
202 </p>
203
204 <pre data-filename="controller.js">
205 const PLACEHOLDER_IMAGE = "loading.gif";
206 </pre>
207
208 <p>
209 As you will see soon,
210 this element is only shown when the <code>validImage</code> attribute of the Tod o item is true.
211 </p>
212
213 <h3 id="controller2">Update controller</h3>
214
215 <p>Add the method <code>loadImage</code> to a new script file
216 that will start a XHR request and execute a callback with a Blob URL.
217 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/2_loading_resources/loader.js">AngularJS loader.js</a> and
218 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/2_loading_resources/loader.js">JavaScript loader.js</a> are the same:
219 </p>
220
221 <pre data-filename="loader.js">
222 var loadImage = function(uri, callback) {
223 var xhr = new XMLHttpRequest();
224 xhr.responseType = &#39;blob&#39;;
225 xhr.onload = function() {
226 callback(window.URL.createObjectURL(xhr.response), uri);
227 }
228 xhr.open(&#39;GET&#39;, uri, true);
229 xhr.send();
230 }
231 </pre>
232
233 <p>In the
234 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/2_loading_resources/controller.js">AngularJS controller.js</ a> or
235 <a href="">JavaScript controller.js</a>,
236 add a new method that will search the Todo list looking for images that are not loaded yet:
237 </p>
238
239 <tabs data-group="source">
240
241 <header tabindex="0" data-value="angular">Angular</header>
242 <header tabindex="0" data-value="js">JavaScript</header>
243
244 <content>
245 <pre data-filename="controller.js">
246 // for each image with no imageUrl, start a new loader
247 $scope.loadImages = function() {
248 for (var i=0; i&lt;$scope.todos.length; i++) {
249 var todo=$scope.todos[i];
250 if (todo.validImage &amp;&amp; todo.imageUrl===PLACEHOLDER_IMAGE) {
251 loadImage(todo.uri, function(blob_uri, requested_uri) {
252 $scope.$apply(function(scope) {
253 for (var k=0; k&lt;scope.todos.length; k++) {
254 if (scope.todos[k].uri==requested_uri) {
255 scope.todos[k].imageUrl = blob_uri;
256 }
257 }
258 });
259 });
260 }
261 }
262 };
263 </pre>
264 </content>
265 <content>
266 <pre data-filename="controller.js">
267 var maybeStartImageLoader = function(el, todo) {
268 var img = el.querySelector('img');
269 if (todo['extras'] && todo.extras.validImage && todo.extras.imageUrl) {
270 if (todo.extras.imageUrl===PLACEHOLDER_IMAGE) {
271 img.src = PLACEHOLDER_IMAGE;
272 img.style.display = 'inline';
273 window.loadImage(todo.extras.uri, function(blob_uri, requested_uri) {
274 todo.extras.imageUrl = blob_uri;
275 img.src = blob_uri;
276 });
277 } else {
278 img.src = todo.extras.imageUrl;
279 img.style.display = 'inline';
280 }
281 } else {
282 img.style.display = 'none';
283 }
284 };
285 </pre>
286 </content>
287
288 </tabs>
289
290 <p>
291 If writing your app in JavaScript,
292 you will need to call the <code>maybeStartImageLoader</code> function
293 in the
294 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/2_loading_resources/controller.js">JavaScript controller.js </a>
295 to update the Todo list from the model:
296 </p>
297
298 <pre data-filename="controller.js">
299 var updateTodo = function(model) {
300 var todoElement = list.querySelector('li[data-id="'+model.id+'"]');
301 if (todoElement) {
302 var checkbox = todoElement.querySelector('input[type="checkbox"]');
303 var desc = todoElement.querySelector('span');
304 checkbox.checked = model.isDone;
305 desc.innerText = model.text;
306 desc.className = "done-"+model.isDone;
307
308 // load image, if this ToDo has image data
309 maybeStartImageLoader(todoElement, model);
310 }
311 }
312 </pre>
313
314 <p>Then in the
315 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/angularjs/2_loading_resources/controller.js">AngularJS controller.js</ a> or
316 <a href="https://github.com/GoogleChrome/chrome-app-codelab/blob/master/lab8_web resources/javascript/2_loading_resources/controller.js">JavaScript.controller.js </a>,
317 <code>drop()</code> method,
318 change the handling of URIs to appropriately detect a valid image.
319 For simplicity sake, we only tested for png and jpg extensions.
320 Feel free to have a better coverage in your code.
321 </p>
322
323 <tabs data-group="source">
324
325 <header tabindex="0" data-value="angular">Angular</header>
326 <header tabindex="0" data-value="js">JavaScript</header>
327
328 <content>
329 <pre data-filename="controller.js">
330 var uri=e.dataTransfer.getData(&quot;text/uri-list&quot;);
331 var todo = {text:uri, done:false, uri: uri};
332 if (/.png$/.test(uri) || /.jpg$/.test(uri)) {
333 hasImage = true;
334 todo.validImage = true;
335 todo.imageUrl = PLACEHOLDER_IMAGE;
336 }
337 newTodos.push(todo);
338
339 // [...] inside the $apply method, before save(), call the loadImages method:
340 $scope.loadImages();
341 </pre>
342 </content>
343 <content>
344 <pre data-filename="controller.js">
345 var uri = e.dataTransfer.getData("text/uri-list");
346 var extras = { uri: uri };
347 if (/\.png$/.test(uri) || /\.jpg$/.test(uri)) {
348 hasImage = true;
349 extras.validImage = true;
350 extras.imageUrl = PLACEHOLDER_IMAGE;
351 }
352 model.addTodo(uri, false, extras);
353 </pre>
354 </content>
355
356 </tabs>
357
358 <p>And, finally, we will change the load method to reset the Blob URLs,
359 since Blob URLs don&#39;t span through sessions.
360 Setting Todo&#39;s imageUrls to the PLACEHOLDER_IMAGE
361 will force the loadImages method to request them again:
362 </p>
363
364 <tabs data-group="source">
365
366 <header tabindex="0" data-value="angular">Angular</header>
367 <header tabindex="0" data-value="js">JavaScript</header>
368
369 <content>
370 <pre data-filename="controller.js">
371 // If there is saved data in storage, use it. Otherwise, bootstrap with sample t odos
372 $scope.load = function(value) {
373 if (value &amp;&amp; value.todolist) {
374 // ObjectURLs are revoked when the document is removed from memory,
375 // so we need to reload all images.
376 for (var i=0; i&lt;value.todolist.length; i++) {
377 value.todolist[i].imageUrl = PLACEHOLDER_IMAGE;
378 }
379 $scope.todos = value.todolist;
380 $scope.loadImages();
381 } else {
382 $scope.todos = [
383 {text:&#39;learn angular&#39;, done:true},
384 {text:&#39;build an angular app&#39;, done:false}];
385 }
386 }
387 </pre>
388 </content>
389 <content>
390 <pre data-filename="controller.js">
391 /**
392 * Listen to changes in the model and trigger the appropriate changes in the vie w
393 **/
394 model.addListener(function(model, changeType, param) {
395 if ( changeType === 'reset' ) {
396 // let's invalidate all Blob URLs, since their lifetime is tied to the docum ent's lifetime
397 for (var id in model.todos) {
398 if (model.todos[id].extras && model.todos[id].extras.validImage) {
399 model.todos[id].extras.imageUrl = PLACEHOLDER_IMAGE;
400 }
401 }
402 }
403
404 if ( changeType === 'removed' || changeType === 'archived' || changeType === ' reset') {
405 redrawUI(model);
406 } else if ( changeType === 'added' ) {
407 drawTodo(model.todos[param], list);
408 } else if ( changeType === 'stateChanged') {
409 updateTodo(model.todos[param]);
410 }
411 storageSave();
412 updateCounters(model);
413 });
414 </pre>
415 </content>
416
417 </tabs>
418
419 <h3 id="results2">Check the results</h3>
420
421 <p>To test, open the app, right-click, and select Reload App.
422 Go to
423 <a href="https://www.google.com/imghp?hl=en&amp;tab=wi&amp;authuser=0">Google im ages</a>,
424 search for and select an image,
425 then drag and drop the image into the Todo list app.
426 Assuming no mistakes were made,
427 you should now have a thumbnail of every image URL dropped into the Todo list ap p.</p>
428
429 <p>
430 Notice we are not handling local images dropped from the file manager in this ch ange.
431 We leave this as a challenge for you.
432 </p>
433
434 <p>If you get stuck and want to see the app in action,
435 go to <code>chrome://extensions</code>, load the unpacked
436 <a href="https://github.com/GoogleChrome/chrome-app-codelab/tree/master/lab8_web resources/angularjs/2_loading_resources">AngularJS 2_loading_resources</a> or,
437 <a href="https://github.com/GoogleChrome/chrome-app-codelab/tree/master/lab8_web resources/javascript/2_loading_resources">JavaScript 2_loading_resources</a>
438 and launch the app from a new tab.</p>
439
440 <p>The <code>loadImage()</code> method above is not the best solution for this p roblem, because it doesn&#39;t handle errors correctly and it could cache images in a local filesystem.
441 We've created the
442 <a href="https://github.com/GoogleChrome/apps-resource-loader">apps-resource-loa der library</a>
443 that's much more robust.</p>
444
445 <h2 id="takeaways_">Takeaways</h2>
446
447 <ul>
448 <li><p>The <code>&lt;webview&gt;</code> tag allows you to have a controlled brow ser inside your app.
449 You can use it if you have part of your application that is not CSP compatible a nd you don&#39;t have resources to migrate it immediately, for example.
450 One feature we didn&#39;t mention here is that webviews can communicate with you r app and vice-versa using asynchronous <a href="app_external#postMessage">postM essages</a>.</p></li>
451 <li><p>Loading resources like images from the web is not straightforward compare d to a standard web page.
452 But it&#39;s not too different from traditional native platforms, where you need to handle the resource download and, only when it is correctly downloaded, you can render it in the UI. We have also developed <a href="https://github.com/Goog leChrome/apps-resource-loader">a sample library</a> to asynchronously handle res ource loading from XHR calls. Feel free to use it in your projects.</p></li>
453 </ul>
454
455 <h2 id="you_should_also_read">You should also read</h2>
456
457 <ul>
458 <li><a href="webview_tag">Webview Tag API</a> reference</li>
459 <li><a href="app_external">Embed Content</a> tutorial</li>
460 </ul>
461
462 <h2 id="what_39_s_next_">What's next?</h2>
463
464 <p>In <a href="app_codelab_10_publishing">8 - Publish App</a>,
465 we finish off with instructions on how to publish your app in the Chrome Web Sto re.</p>
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698