src/chrome/common/extensions/docs/templates/articles/desktop_notifications.html

   1 <h1>Rich Notifications</h1>
   2
   3 <p class="warning"><b>Warning:</b>
   4 <code>webKitNotifications.createHTMLNotification()</code> in the
   5 <a href="http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification">web notifications API</a> has been deprecated.
   6 The new <a href="http://www.w3.org/TR/notifications/">web notifications API</a> only allows text.
   7 <a href="notifications.html">Chrome notifications API</a>
   8 will be promoted to stable soon and
   9 web notifications will be updated
  10 to use the new rich notifications format.
  11 </p>
  12
  13 <p>
  14 Use rich desktop notifications to notify users that something
  15 important has happened.
  16 Notifications appear outside the browser window.
  17 As the following snapshots show,
  18 the details of how notifications look
  19 and where they're shown depend on the platform.
  20 </p>
  21
  22 <img src="{{static}}/images/notification-windows.png"
  23   width="28%" style="margin:2em 0.5em 1em; border:1px solid black;"
  24   alt="Notifications on Microsoft Windows"/>
  25 <img src="{{static}}/images/notification-mac.png"
  26   width="28%" style="margin:2em 0.5em 1em; border:1px solid black;"
  27   alt="Notifications on Mac OS X"/>
  28 <img src="{{static}}/images/notification-linux.png"
  29   width="28%" style="margin:2em 0.5em 1em; border:1px solid black;"
  30   alt="Notifications on Ubuntu Linux"/>
  31
  32 <p>
  33 You create the notification window
  34 using a bit of JavaScript and, optionally,
  35 an HTML page packaged inside your extension.
  36 </p>
  37
  38
  39 <h2 id="example">Example</h2>
  40
  41 <p>First, declare the <code>notifications</code> permission in your manifest:</p>
  42 <pre data-filename="manifest.json">
  43 {
  44   "name": "My extension",
  45   "manifest_version": 2,
  46   ...
  47 <b>  "permissions": [
  48     "notifications"
  49   ]</b>,
  50   ...
  51   // <strong>Note:</strong> Because of <a href="http://code.google.com/p/chromium/issues/detail?id=134315">bug 134315</a>, you must declare any images you
  52   // want to use with createNotification() as a web accessible resource.
  53 <b>  "web_accessible_resources": [
  54     "48.png"
  55   ]</b>,
  56 }
  57 </pre>
  58
  59 <p>Then, use <code>webkitNotifications</code> object to create notifications:</p>
  60
  61 <pre>
  62 // <strong>Note:</strong> There's no need to call webkitNotifications.checkPermission().
  63 // Extensions that declare the <em>notifications</em> permission are always
  64 // allowed create notifications.
  65
  66 // Create a simple text notification:
  67 var notification = webkitNotifications.createNotification(
  68   '48.png',  // icon url - can be relative
  69   'Hello!',  // notification title
  70   'Lorem ipsum...'  // notification body text
  71 );
  72
  73 // Or create an HTML notification:
  74 var notification = webkitNotifications.createHTMLNotification(
  75   'notification.html'  // html url - can be relative
  76 );
  77
  78 // Then show the notification.
  79 notification.show();
  80 </pre>
  81
  82 <h2 id="reference">API Reference</h2>
  83
  84 <p>See the <a href="http://dev.chromium.org/developers/design-documents/desktop-notifications/api-specification">Desktop Notifications Draft Specification</a>.</p>
  85
  86
  87 <h2 id="communication">Communicating with Other Views</h2>
  88
  89 <p>
  90 You can communicate between a notification
  91 and other views in your extension using
  92 $ref:extension.getBackgroundPage and
  93 $ref:extension.getViews. For example:
  94 </p>
  95
  96 <pre data-filename="notification.js">
  97 chrome.extension.getBackgroundPage().doThing();
  98 </pre>
  99 <pre data-filename="background.js">
 100 chrome.extension.getViews({type:"notification"}).forEach(function(win) {
 101   win.doOtherThing();
 102 });
 103 </pre>
 104
 105
 106 <h2 id="examples">More Examples</h2>
 107
 108 <p>
 109 You can find a simple example
 110 of using notifications in the
 111 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/notifications/">examples/api/notifications</a>
 112 directory.
 113 For other examples
 114 and for help in viewing the source code,
 115 see <a href="samples.html">Samples</a>.
 116 </p>
 117
 118 <p>
 119 Also see html5rocks.com's
 120 <a href="http://www.html5rocks.com/tutorials/notifications/quick/">notifications tutorial</a>.
 121 Ignore the permission-related code;
 122 it's unnecessary if you declare the "notifications" permission.
 123 </p>