src/chrome/common/extensions/docs/templates/intros/notifications.html

   1 <p class="note">
   2 <b>Note: </b>
   3 This API is currently available on ChromeOS, Windows, and Mac.
   4 </p>
   5
   6 <h2 id="usage">Usage</h2>
   7
   8 <p>
   9 To use this API,
  10 call the $ref:notifications.create method,
  11 passing in the notification details
  12 via the <code>options</code> parameter:
  13 </p>
  14
  15 <pre>
  16 chrome.notifications.create(id, options, creationCallback);
  17 </pre>
  18
  19 <p>
  20 The $ref:notifications.NotificationOptions must include a
  21 $ref:notifications.TemplateType,
  22 which defines available notification details
  23 and how those details are displayed.
  24 </p>
  25
  26 <p>
  27 All template types
  28 (<code>basic</code>, <code>image</code>, and <code>list</code>)
  29 must include a notification <code>title</code> and <code>message</code>,
  30 as well as an <code>iconUrl</code>, which is a link to a small icon that
  31 is displayed to the left of the notification message. The <code>image</code>
  32 template type also includes an <code>imageUrl</code>, which is a link to
  33 an image that is previewed within the notification.
  34 Due to a strict <a href="contentSecurityPolicy.html">Content Security Policy</a>
  35 in Chrome Apps, these URLs must point to a local resource or use a
  36 <a href="app_external.html">data URL</a>.
  37 </p>
  38
  39 <p>
  40 Here's an example of a <code>basic</code> template:
  41 </p>
  42
  43 <pre>
  44 var opt = {
  45   type: "basic",
  46   title: "Primary Title",
  47   message: "Primary message to display",
  48   iconUrl: "url_to_small_icon"
  49 }
  50 </pre>
  51
  52 <p>
  53 The <code>list</code> template displays <code>items</code>
  54 in a list format:
  55 </p>
  56
  57 <pre>
  58 var opt = {
  59   type: "list",
  60   title: "Primary Title",
  61   message: "Primary message to display",
  62   iconUrl: "url_to_small_icon",
  63   items: [{ title: "Item1", message: "This is item 1."},
  64           { title: "Item2", message: "This is item 2."},
  65           { title: "Item3", message: "This is item 3."}]
  66 }
  67 </pre>
  68
  69 <p>
  70 Let us know if you have ideas for new templates with varying layouts
  71 by filing a <a href="http://crbug.com/new">crbug</a>!
  72 </p>
  73
  74 <h2 id="events">Listening for and responding to events</h2>
  75
  76 <p>
  77 All notifications can include event listeners and event handlers
  78 that respond to user actions.
  79 For example,
  80 you can write an event handler to respond to an
  81 $ref:notifications.onButtonClicked event.
  82 </p>
  83
  84 <p>Consider including event listeners and handlers within the
  85   <a href="app_lifecycle.html#create_event_page">event page</a>,
  86 so that notifications can pop-up even when the app or extension isn't running.
  87 </p>