blob: 59476da1b69a893371bde100f187f7e69eb81555 [file] [log] [blame]
<div id="pageData-name" class="pageData">Browser Actions</div>
<!-- BEGIN AUTHORED CONTENT -->
<p>Use browser actions to put icons
in the main Google Chrome toolbar,
to the right of the address bar.
In addition to its <a href="#icon">icon</a>,
a browser action can also have
a <a href="#tooltip">tooltip</a>,
a <a href="#badge">badge</a>,
and a <a href="#popup">popup</a>.
</p>
<p>
In the following figure,
the multicolored square
to the right of the address bar
is the icon for a browser action.
A popup is below the icon.
</p>
<img src="images/browser-action.png"
width="363" height="226" />
<p>
If you want to create an icon that isn't always visible,
use a <a href="pageAction.html">page action</a>
instead of a browser action.
</p>
<!-- [PENDING: We should show tooltips and badges, as well.] -->
<h2 id="manifest">Manifest</h2>
<p>
Register your browser action in the
<a href="manifest.html">extension manifest</a>
like this:
</p>
<pre>"browser_action": {
"default_icon": "images/icon19.png", <em>// <b>required</b></em>
"default_title": "Google Mail", <em>// optional; shown in tooltip</em>
"popup": "popup.html" <em>// optional</em>
}</pre>
<h2 id="ui">Parts of the UI</h2>
<p>
A browser action must have an <a href="#icon">icon</a>.
It can also have
a <a href="#tooltip">tooltip</a>,
a <a href="#badge">badge</a>,
and a <a href="#popup">popup</a>.
</p>
<h3 id="icon">Icon</h3>
<p>Browser action icons can be up to 19 pixels wide and high.
Larger icons are resized to fit, but for best results,
use a 19-pixel square icon.</p>
<p>You can set the icon in two ways:
using a static image or using the
HTML5 <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html">canvas element</a>.
Using static images is easier for simple applications,
but you can create more dynamic UIs &mdash;
such as smooth animation &mdash;
using the canvas element.
</p>
<p>Static images can be in any format WebKit can display,
including BMP, GIF, ICO, JPEG, or PNG.
</p>
<p>To set the icon,
use the <b>default_icon</b> field of <b>browser_action</b>
in the <a href="#manifest">manifest</a>,
or call the <a href="#method-setIcon">setIcon()</a> method.
<h3 id="tooltip">Tooltip</h3>
<p>
To set the tooltip,
use the <b>default_title</b> field of <b>browser_action</b>
in the <a href="#manifest">manifest</a>,
or call the <a href="#method-setTitle">setTitle()</a> method.
</p>
<h3 id="badge">Badge</h3>
<p>Browser actions can optionally display a <em>badge</em> &mdash;
a bit of text that is layered over the icon.
Badges make it easy to update the browser action
to display a small amount of information
about the state of the extension.</p>
<p>Because the badge has limited space,
it should have 4 characters or less.
</p>
<p>
Set the text and color of the badge using
<a href="#method-setBadgeText">setBadgeText()</a> and
<a href="#method-setBadgeBackgroundColor">setBadgeBackgroundColor()</a>,
respectively.
<!-- [PENDING: if you have a color but no text, will anything display?] -->
</p>
<h3 id="popups">Popup</h3>
<p>If a browser action has a popup,
the popup appears when the user clicks the icon.
The popup can contain any HTML contents that you like,
and it's automatically sized to fit its contents.
</p>
<p>
To add a popup to your browser action,
create an HTML file with the popup's contents.
Then specify the HTML file in
the <a href="#manifest">manifest</a>,
using the <b>popup</b> field of <b>browser_action</b>.
</p>
<h2>Tips</h2>
<p>For the best visual impact,
follow these guidelines:</p>
<ul>
<li><b>Do</b> use browser actions for features
that make sense on most pages.
<li><b>Don't</b> use browser actions for features
that make sense for only a few pages.
Use <a href="pageAction.html">page actions</a> instead.
<li><b>Do</b> use big, colorful icons that make the most of
the 19x19-pixel space.
Browser action icons should seem a little bigger
and heavier than page action icons.
<li><b>Don't</b> attempt to mimic
Google Chrome's monochrome "wrench" and "page" icons.
That doesn't work well with themes, and anyway,
extensions should stand out a little.
<li><b>Do</b> use alpha transparency
to add soft edges to your icon.
Because many people use themes,
your icon should look nice
on a variety of background colors.
<li><b>Don't</b> constantly animate your icon.
That's just annoying.
</ul>
<!-- END AUTHORED CONTENT -->