Mobile/Fennec/Extensions/BestPractices

Fennec is designed to run on mobile devices with small screens, touch interfaces, small batteries and low-power CPUs. When building extensions for Fennec, you need to keep in mind that actions or designs which have no consequence in desktop Firefox might be very bad in Fennec. This page describes practices or conventions that can help you make a Fennec extension that doesn't degrade the user experience.

Delay Everything

It's very common for extensions to listener for the window load event and execute some initialization code. The problem with this is it can negatively affect startup time.

• Try to do a few things as possible in the window load event handler
• Delay any time-consuming code as much as possible.
  • Wait until the user activates the extension's UI
  • Wait for an explicit notification or event
• Use JavaScript Code Modules (.jsm files) to delay loading of your code.

Examples: Most of the Browser Tool panels: Add-ons Manager, Downloads Manager and Error Console. These panels do not fully initialize until the user explicitly presses the button to view them.

Screen Space is Valuable

Fennec is designed to maximize the available screen space. This is especially so for the content area. Remember that devices have landscape and portrait modes. Adding simple buttons to the URLbar or the sidebars could cause some primary buttons to get pushed offscreen. We also want to minimize clutter in the primary UI.

• Do not add buttons to the URLBar
• Minimize your extension's UI to the point of making it almost invisible
• If your extension needs space to display content, consider using a Browser Tool panel. Even better, consider making a new tab and displaying the content in the main content area.

Use Fewer Dialogs and Popups

Consider not using any dialogs. They are slow to load and can grow larger than the screen. Switching between portrait and landscape also makes it hard to find the right size.

• Don't use dialogs. Try to make good assumptions about situations and don't bother users. This is especially true for mobile user experience.
• If you really need user input - keep it extremely simple. Do not make elaborate dialogs.
  • If your dialog uses <tabbox>, you lose.
  • If your dialog has more than one label, one form control and three buttons, you lose.
• Use Alerts to notify the user that some event has happened.
• nsIPromptService and nsIAlertsService are overridden in Fennec. Use them the same way you would for Firefox.
• Avoid window.open and window.openDialog for displaying dialogs. Instead, use boxes in the main browser stack to display your dialog as a panel.

See more info on dialogs and prompts.

Blend In

Whenever possible, please use the CSS styles shipped with Fennec to allow your extension to blend into the rest of the application.

• Don't play with font sizes. Fennec defaults the font-size to something suitable for the device. Best to stick with that.
• Fennec uses border-image to create nice looking buttons that can grow in either direction. We have overridden some widget styling, so you need to do nothing extra. Some widgets use special class names to achieve the desired look.
• (TODO: List of built-in styles)
• (TODO: Add sample and tutorial)

Conflicts

Since there is only one window in Fennec, all extensions that need to add content will likely overlay browser.xul. To avoid conflicts between different extensions and the main browser, extension authors must use unique names for their element's IDs and classe names. For instance, using the chrome shortcut as a prefix for IDs and class names will prevent such issues : don't use

<button id="update-button"/>

but

<button id="myext-update-button"/>.

Of course, you should also namespace all JavaScript code used in extensions.

Support Panning

Fennec does not show scrollbars. Finger touch panning is used to move and scroll through content. Many standard XUL widgets (scrollbox, autoscrollbox, listbox and richlistbox) are already supported in Fennec.

If you create a custom XBL widget which embeds one of these scrollable widgets, you'll need to expose a scrollBoxObject property from your XBL, so Fennec can access the scroll box object of the embedded widget.

<property name="scrollBoxObject" readonly="true"
          onget="return this._mylist.scrollBoxObject;"/>

Assume Nothing is Safe

When creating or porting an extension for Fennec, you really can't assume anything you have done or learned about desktop extensions is safe (or fast) in Fennec. Even simple things like checking to see if a file exists or access DOM attributes can affect performance.

So, if your extension seems to affect overall performance, don't assume parts of your code are fast just because it's simple, written in C++ or works great on the desktop.