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

   1 <p>
   2 In the following figure,
   3 the multicolored square
   4 to the right of the address bar
   5 is the icon for a browser action.
   6 A popup is below the icon.
   7 </p>
   8
   9 <img src="{{static}}/images/browser-action.png"
  10   width="363" height="226" />
  11
  12 <p>
  13 If you want to create an icon that isn't always visible,
  14 use a <a href="pageAction">page action</a>
  15 instead of a browser action.
  16 </p>
  17
  18 <h2 id="manifest">Manifest</h2>
  19
  20 <p>
  21 Register your browser action in the
  22 <a href="manifest">extension manifest</a>
  23 like this:
  24 </p>
  25
  26 <pre data-filename="manifest.json">
  27 {
  28   "name": "My extension",
  29   ...
  30   <b>"browser_action": {
  31     "default_icon": {                    <em>// optional</em>
  32       "19": "images/icon19.png",           <em>// optional</em>
  33       "38": "images/icon38.png"            <em>// optional</em>
  34     },
  35     "default_title": "Google Mail",      <em>// optional; shown in tooltip</em>
  36     "default_popup": "popup.html"        <em>// optional</em>
  37   }</b>,
  38   ...
  39 }
  40 </pre>
  41
  42 <p>
  43 If you only provide one of the 19px or 38px icon size, the extension system will
  44 scale the icon you provide to the pixel density of the user's display, which
  45 can lose detail or make it look fuzzy. The old syntax for registering the
  46 default icon is still supported:
  47 </p>
  48
  49 <pre data-filename="manifest.json">
  50 {
  51   "name": "My extension",
  52   ...
  53   <b>"browser_action": {
  54     ...
  55     "default_icon": "images/icon38.png"  <em>// optional</em>
  56     <em>// equivalent to "default_icon": { "38": "images/icon38.png" }</em>
  57   }</b>,
  58   ...
  59 }
  60 </pre>
  61
  62 <h2 id="ui">Parts of the UI</h2>
  63
  64 <p>
  65 A browser action can have an <a href="#icon">icon</a>,
  66 a <a href="#tooltip">tooltip</a>,
  67 a <a href="#badge">badge</a>,
  68 and a <a href="#popups">popup</a>.
  69 </p>
  70
  71 <h3 id="icon">Icon</h3>
  72
  73 <p>Browser action icons can be up to 19 dips (device-independent pixels)
  74   wide and high. Larger icons are resized to fit, but for best results,
  75   use a 19-dip square icon.</p>
  76
  77 <p>You can set the icon in two ways:
  78   using a static image or using the
  79   HTML5 <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html">canvas element</a>.
  80   Using static images is easier for simple applications,
  81   but you can create more dynamic UIs &mdash;
  82   such as smooth animation &mdash;
  83   using the canvas element.
  84   </p>
  85
  86 <p>Static images can be in any format WebKit can display,
  87   including BMP, GIF, ICO, JPEG, or PNG.
  88   For unpacked extensions, images must be in the PNG format.
  89   </p>
  90
  91 <p>To set the icon,
  92   use the <b>default_icon</b> field of <b>browser_action</b>
  93   in the <a href="#manifest">manifest</a>,
  94   or call the $(ref:browserAction.setIcon) method.
  95   </p>
  96
  97 <p>To properly display icon when screen pixel density (ratio
  98   <code>size_in_pixel / size_in_dip</code>) is different than 1,
  99   the icon can be defined as set of images with different sizes.
 100   The actual image to display will be selected from the set to
 101   best fit the pixel size of 19 dip icon.
 102   At the moment, the icon set can contain images with pixel sizes 19 and 38.
 103   </p>
 104
 105 <h3 id="tooltip">Tooltip</h3>
 106
 107 <p>
 108 To set the tooltip,
 109 use the <b>default_title</b> field of <b>browser_action</b>
 110 in the <a href="#manifest">manifest</a>,
 111 or call the $(ref:browserAction.setTitle) method.
 112 You can specify locale-specific strings for the <b>default_title</b> field;
 113 see <a href="i18n">Internationalization</a> for details.
 114 </p>
 115
 116 <h3 id="badge">Badge</h3>
 117
 118 <p>Browser actions can optionally display a <em>badge</em> &mdash;
 119   a bit of text that is layered over the icon.
 120   Badges make it easy to update the browser action
 121   to display a small amount of information
 122   about the state of the extension.</p>
 123
 124 <p>Because the badge has limited space,
 125    it should have 4 characters or less.
 126   </p>
 127
 128 <p>
 129 Set the text and color of the badge using
 130 $(ref:browserAction.setBadgeText) and
 131 $(ref:browserAction.setBadgeBackgroundColor),
 132 respectively.
 133
 134 </p>
 135
 136
 137 <h3 id="popups">Popup</h3>
 138
 139 <p>If a browser action has a popup,
 140   the popup appears when the user clicks the icon.
 141   The popup can contain any HTML contents that you like,
 142   and it's automatically sized to fit its contents.
 143   </p>
 144
 145 <p>
 146 To add a popup to your browser action,
 147 create an HTML file with the popup's contents.
 148 Specify the HTML file in the <b>default_popup</b> field of <b>browser_action</b>
 149 in the <a href="#manifest">manifest</a>, or call the
 150 $(ref:browserAction.setPopup) method.
 151 </p>
 152
 153 <h2 id="tips">Tips</h2>
 154
 155 <p>For the best visual impact,
 156   follow these guidelines:</p>
 157
 158 <ul>
 159   <li><b>Do</b> use browser actions for features
 160     that make sense on most pages.
 161   <li><b>Don't</b> use browser actions for features
 162     that make sense for only a few pages.
 163     Use <a href="pageAction">page actions</a> instead.
 164   <li><b>Do</b> use big, colorful icons that make the most of
 165     the 38x38-pixel space.
 166     Browser action icons should seem a little bigger
 167     and heavier than page action icons.
 168   <li><b>Don't</b> attempt to mimic
 169     Google Chrome's monochrome menu icon.
 170     That doesn't work well with themes, and anyway,
 171     extensions should stand out a little.
 172   <li><b>Do</b> use alpha transparency
 173     to add soft edges to your icon.
 174     Because many people use themes,
 175     your icon should look nice
 176     on a variety of background colors.
 177   <li><b>Don't</b> constantly animate your icon.
 178     That's just annoying.
 179 </ul>
 180
 181 <h2 id="examples"> Examples </h2>
 182
 183 <p>
 184 You can find simple examples of using browser actions in the
 185 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/">examples/api/browserAction</a>
 186 directory.
 187 For other examples and for help in viewing the source code, see
 188 <a href="samples">Samples</a>.
 189 </p>