New Getting started example for extensions

chrome/common/extensions/docs/examples/tutorials/getstarted/popup.js

Index: chrome/common/extensions/docs/examples/tutorials/getstarted/popup.js
diff --git a/chrome/common/extensions/docs/examples/tutorials/getstarted/popup.js b/chrome/common/extensions/docs/examples/tutorials/getstarted/popup.js
index bdbe548d457cf40f2945c1af0ab8ae61a6b4e2cf..0a1a444ac58f2ab3bf4783db6a4b63c9f88b4093 100644
--- a/chrome/common/extensions/docs/examples/tutorials/getstarted/popup.js
+++ b/chrome/common/extensions/docs/examples/tutorials/getstarted/popup.js
@@ -1,83 +1,104 @@
-// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Copyright (c) 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /**
- * Global variable containing the query we'd like to pass to Flickr. In this
- * case, kittens!
+ * Get the current URL.
  *
- * @type {string}
- */
-var QUERY = 'kittens';
+ * @param {function(string)} callback - called when the URL of the current tab
+ *   is found.
+ **/
+function getCurrentTabUrl(callback) {
+  // Query filter to be passed to chrome.tabs.query - see
+  // https://developer.chrome.com/extensions/tabs#method-query
+  var queryInfo = {
+    active: true,
+    currentWindow: true
+  };
+
+  chrome.tabs.query(queryInfo, function(tabs) {
+    // chrome.tabs.query invokes the callback with a list of tabs that match the
+    // query. When the popup is opened, there is certainly a window and at least
+    // one tab, so we can safely assume that |tabs| is a non-empty array.
+    // A window can only have one active tab at a time, so the array consists of
+    // exactly one tab.
+    var tab = tabs[0];
+
+    // A tab is a plain object that provides information about the tab.
+    // See https://developer.chrome.com/extensions/tabs#type-Tab
+    var url = tab.url;
 
-var kittenGenerator = {
-  /**
-   * Flickr URL that will give us lots and lots of whatever we're looking for.
-   *
-   * See http://www.flickr.com/services/api/flickr.photos.search.html for
-   * details about the construction of this URL.
-   *
-   * @type {string}
-   * @private
-   */
-  searchOnFlickr_: 'https://secure.flickr.com/services/rest/?' +
-      'method=flickr.photos.search&' +
-      'api_key=90485e931f687a9b9c2a66bf58a3861a&' +
-      'text=' + encodeURIComponent(QUERY) + '&' +
-      'safe_search=1&' +
-      'content_type=1&' +
-      'sort=interestingness-desc&' +
-      'per_page=20',
+    // tab.url is not set when you forget to declare the "tabs" permission in
+    // manifest.json.

[not at google - send to devlin, 2014/11/17 22:02:57]

You should be able to rely on activeTab to get the URL. No need to specify the
tabs permission.

[robwu, 2014/11/17 22:26:11]

Done.

+    console.assert(typeof url == 'string', 'tab.url should be a string');
 
-  /**
-   * Sends an XHR GET request to grab photos of lots and lots of kittens. The
-   * XHR's 'onload' event is hooks up to the 'showPhotos_' method.
-   *
-   * @public
-   */
-  requestKittens: function() {
-    var req = new XMLHttpRequest();
-    req.open("GET", this.searchOnFlickr_, true);
-    req.onload = this.showPhotos_.bind(this);
-    req.send(null);
-  },
+    callback(url);
+  });
 
-  /**
-   * Handle the 'onload' event of our kitten XHR request, generated in
-   * 'requestKittens', by generating 'img' elements, and stuffing them into
-   * the document for display.
-   *
-   * @param {ProgressEvent} e The XHR ProgressEvent.
-   * @private
-   */
-  showPhotos_: function (e) {
-    var kittens = e.target.responseXML.querySelectorAll('photo');
-    for (var i = 0; i < kittens.length; i++) {
-      var img = document.createElement('img');
-      img.src = this.constructKittenURL_(kittens[i]);
-      img.setAttribute('alt', kittens[i].getAttribute('title'));
-      document.body.appendChild(img);
+  // Most methods of the Chrome extension APIs are asynchronous. This means that
+  // you CANNOT do something like this:
+  //
+  // var url;
+  // chrome.tabs.query(queryInfo, function(tabs) {
+  //   url = tabs[0].url;
+  // });
+  // alert(url); // Shows "undefined", because chrome.tabs.query is async.
+}
+
+/**
+ * @param {string} searchTerm - Search term for Google Image search.
+ * @param {function(string)} callback - Called when an image has been found.
+ *   The callback gets the URL of the image.
+ * @param {function(string)} errorCallback - Called when the image is not found.
+ *   The callback gets a string that describes the failure reason.
+ */
+function getImageUrl(searchTerm, callback, errorCallback) {
+  // Google image search - 100 searches per day.
+  var searchUrl = 'https://ajax.googleapis.com/ajax/services/search/images' +
+    '?v=1.0&q=' + encodeURIComponent(searchTerm);
+  var x = new XMLHttpRequest();
+  x.open('GET', searchUrl);
+  // The Google image search API responds with JSON, so let Chrome parse it.
+  x.responseType = 'json';
+  x.onload = function() {
+    // Parse and process the response from Google Image Search.

[not at google - send to devlin, 2014/11/17 22:02:57]

Does it reply with any sizing info? It'd be nice to put the correct size on the
img.

[robwu, 2014/11/17 22:26:11]

Yes, the size is available. I have not used it though, because the purpose of
the tutorial is to show how to develop an extension using a third-party API, not
teaching the specifics of a certain external web service. If it's worth to
mention, I can put a suggestion ("exercise for the reader") in the tutorial
page.

[not at google - send to devlin, 2014/11/17 23:14:03]

The practical effect would be to avoid unnecessary popup resizing. Do you notice
a different setting an explicit size once the image is fetched?

[robwu, 2014/11/17 23:18:54]

What did you mean by that? Whether I can observe that the page resizes after the
image is fetched? If so, yes. But that will happens regardless of whether I set
the image size now or later. If I set it upfront, then the page resizes in this
callback; if I don't set the size, the page will resize once the image is
loaded.

[not at google - send to devlin, 2014/11/17 23:24:05]

An advantage of setting it up-front is that there's less pop-in. The popup will
resize immediately (and if you wanted you could show a spinner or something) and
then load later.

I think it's good practice to avoid pop-in as much as possible, so code along
those lines + comment explaining it would be good (for a first extension).

[robwu, 2014/11/17 23:26:47]

Okay, sounds plausible. I will submit a change tomorrow.

+    var response = x.response;
+    if (!response || !response.responseData || !response.responseData.results ||
+        response.responseData.results.length === 0) {
+      errorCallback('No response from Google Image search!');
+      return;
     }
-  },
+    var firstResult = response.responseData.results[0];
+    var imageUrl = firstResult.url;
+    callback(imageUrl);
+  };
+  x.onerror = function() {
+    errorCallback('Network error.');
+  };
+  x.send();
+}
+
+function renderStatus(statusText) {
+  document.getElementById('status').textContent = statusText;
+}
+
+function main() {
+  getCurrentTabUrl(function(url) {
+    // Put the image URL in Google search.
+    renderStatus('Performing Google Image search for ' + url);
+
+    getImageUrl(url, function(imageUrl) {
+
+      renderStatus('Search term: ' + url + '\n' +
+          'Google image search result: ' + imageUrl);
+      document.getElementById('image-result').src = imageUrl;
 
-  /**
-   * Given a photo, construct a URL using the method outlined at
-   * http://www.flickr.com/services/api/misc.urlKittenl
-   *
-   * @param {DOMElement} A kitten.
-   * @return {string} The kitten's URL.
-   * @private
-   */
-  constructKittenURL_: function (photo) {
-    return "http://farm" + photo.getAttribute("farm") +
-        ".static.flickr.com/" + photo.getAttribute("server") +
-        "/" + photo.getAttribute("id") +
-        "_" + photo.getAttribute("secret") +
-        "_s.jpg";
-  }
-};
+    }, function(errorMessage) {
+      renderStatus('Cannot display image. ' + errorMessage);
+    });
+  });
+}
 
-// Run our kitten generation script as soon as the document's DOM is ready.
-document.addEventListener('DOMContentLoaded', function () {
-  kittenGenerator.requestKittens();
+document.addEventListener('DOMContentLoaded', function() {
+  main();
 });

[not at google - send to devlin, 2014/11/17 22:02:57]

You could do just

document.addEventListener('DOMContentLoaded', main);

[robwu, 2014/11/17 22:26:11]

Done.