Revision 659677 of Extension Etiquette

<p>This article describes best practices when making extensions, including&nbsp;<span style="line-height: 1.5;">how to be kind to your users.</span><span style="line-height: 1.5;">&nbsp;It assumes that you are already familiar with </span><a href="/en/Building_an_Extension" style="line-height: 1.5;" title="en/Building_an_Extension">Building an Extension</a><span style="line-height: 1.5;">.</span></p>
<h2 id="Tools_menu_items">Tools menu items</h2>
<p>Using the Tool menu option gives the author the maximum amount of choices. Whether the extensions should go at the top, bottom, or somewhere in between the&nbsp;<span style="line-height: 1.5;">Tools menu,&nbsp;</span><span style="line-height: 1.5;">the author always has a choice. Ideally, the location would be below the Add-ons item, grouped with the other extension-related commands (</span><code style="font-style: normal; line-height: 1.5;"><a href="/en/XUL/menuitem" title="en/XUL/menuitem">menuitem</a>:<a href="/en/XUL/Attribute/insertafter" title="en/XUL/Attribute/insertafter">insertafter</a>="javascriptConsole,devToolsSeparator"</code><span style="line-height: 1.5;">). Sub-menus should be used for single extensions needing multiple menu items, and a Tools menu item should not be created for options and preferences (for options and preferences, see the add-on manager.) If possible, create a menu item in the menu where it is most applicable; for instance, a bookmark sharing extension should be called from the Bookmarks menu. To maintain the default theme, avoid the use of an icon next to the menu items.</span></p>
<h2 id="Other_UI_elements">Other UI elements</h2>
<p>In general, toolbar items are very useful to end users because they can be removed or added to various toolbars as necessary. Status bar items should only be added for extensions that need constant monitoring, such as ad blocking, page ranking, or cookie management. Likewise, use context menu items sparingly — only for tasks that are done frequently or on specific elements of a web page.</p>
<h3 id="Focus"><strong>Focus</strong></h3>
<p>Don't steal focus. It's not your extension's job to take focus from the web content. &nbsp;If the user loads a website and they ask for focus, they should get it. Overriding their request isn't very nice.</p>
<h2 id="About_dialogs">About dialogs</h2>
<p>There is a default popup About dialog that is created from <a href="/en/Install_Manifests" title="en/Install_Manifests">install.rdf</a> data; creating a new XUL About box is usually unnecessary. You can decrease download size by omitting a customized About box. Make one only if you have a special feature that needs to be included. For example: a custom updater.</p>
<h2 id="Theming">Theming</h2>
<p>If you have XUL buttons in your extension that do functions similar to ones that already exist in a browser. For example, a feed reader that reloads and stop. Use icons from the browser's theme. The icons makes the extension lighter, while providing more consistency; especially for users using different themes.</p>
<h2 id="Extension_icons">Extension icons</h2>
<p>Unique icons are usually worth their download weight. They allow for easy identification among other extensions in the Extensions manager.</p>
<h2 id="Naming">Naming</h2>
<p>Be creative! Don't be redundant and include "extension," "Mozilla/Firefox/Thunderbird," or the version number in the name. Be original!</p>
<h2 id="Descriptions">Descriptions</h2>
<p>Use something that is descriptive, but that would fit in the default add-on manager width. The Mozilla extensions (Inspector/Reporter/Talkback) believe starting with a verb is the best way. For example, "Does an action in the browser."</p>
<h2 id="IDs">IDs</h2>
<p>Firefox/Thunderbird 1.5 or later are much more strict about the IDs of extensions than their 1.0 counterparts. Make sure they're <a href="/en/Install_Manifests#id" title="en/Install_Manifests#id">valid</a>.</p>
<h2 id="Version_numbering">Version numbering</h2>
<p>Please follow the Mozilla pattern: major version dot current incarnation dot security/bugfix release (like 1.0.7).</p>
<h2 id="Locales">Locales</h2>
<p>Always use locale <a href="/en/XUL_Tutorial/Localization" title="en/XUL_Tutorial/Localization">DTDs</a> and <a href="/en/XUL_Tutorial/Property_Files" title="en/XUL_Tutorial/Property_Files">property files</a>, even if providing your extension in one language. It will make translation of your extension to another language easier. It occurs more often than you would think.</p>
<h2 id="Options">Options</h2>
<p><span class="comment">Firefox users like options. Lots of options. Try to include everything a user could ever want to customize in your extension, remembering more can be added later. For a large number of options for your extension, break the options window into multiple pages (tabs) that are well labeled. Don't hesitate to give long descriptions for each preference, as long as they are easy to understand, even for non-computer-savvy users. However, please make sure the default set of preferences is adequate — don't require people to tweak options in order to get your extension's core functionality.</span></p>
<h2 id="Preferences'_internal_names">Preferences' internal names</h2>
<p>Internal Firefox preference names&nbsp;<span style="line-height: 1.5;">for extensions&nbsp;</span><span style="line-height: 1.5;">or to be clear, the name of the preference as it appears in the about:config, should start with "</span><code style="font-style: normal; line-height: 1.5;">extensions.,"</code><span style="line-height: 1.5;">&nbsp;then the name of the extension, with a dot, then the name of the preference. For instance, a boolean for the Reporter extension's option for hiding the privacy statement is, "</span><code style="font-style: normal; line-height: 1.5;">extensions.reporter.hidePrivacyStatement".</code></p>
<h2 id="Dependencies">Dependencies</h2>
<p>Requiring a user to download another extension in order to use yours isn't nice. Avoid the dependency on other extensions, especially extensions that you didn't develop.</p>
<h2 id="Documentation">Documentation</h2>
<p>Assume that the vast majority of your users don't have the inner working knowledge of Mozilla.<span style="line-height: 1.5;">&nbsp;Make sure your extension's homepage states the "obvious," including the purpose of your extension. Users also appreciate when your extension is shipped with a simple how-to document.</span></p>
<p>{{ languages( { "ja": "ja/Extension_Etiquette" } ) }}</p>