Important: The descriptions on this page and its subpages are old descriptions written around the first few versions of Firefox OS (1.0.1–1.3), so are out of date. You'll only find these useful if you are writing an app specifically aimed at an old version of Firefox OS, or fixing a bug on an old branch of Gaia. If you want to find more up to date building block information, go to our main Firefox OS building blocks landing page.

This page provides links to the Firefox OS 1.x building blocks.

Action menu


 Details
Coding guide

An action menu presents a list of actions, related to the app's content, from which the user may make a selection. See the Coding guide for details on how to implement an action menu in your app.

 

Characteristics

  • Opened from buttons within app content; these buttons are often inside toolbars (for example, the Browser app's "Share" button).
  • Action menus contain one or more items.
  • These menus expand in height to accomodate their items, to a maximum of the screen's height. Once that maximum height is reached, the content becomes scrollable vertically. Generally, the best practice is to try to include no more than five items plus a menu title.
  • The title string is optional.
  • The menu is closed by one of:
    • Selecting one of the actions.
    • Tapping the "Cancel" button.

 

Button

Details
Coding guide

Performs an action when tapped by the user. These are highly flexible user interface objects that have a wide variety of styles. See the Coding guide for information on how to implement buttons that look like those described here.

 

Characteristics

  • Buttons have two components: a visual target and a hit target. The hit target is always larger, in order to reduce targeting errors by making the button easier to tap.
  • Buttons have two states: normal and pressed.
  • Buttons can also be disabled, which means they can't be activated by the user, and are displayed dimmed to indicate that they're disabled.

There are several types of buttons:

Action buttons
Used when there are only a few actions and a list isn't needed. The main action button uses a special highlight color to indicate that it's the primary option.
List buttons
Used when displaying a list of actions, or to trigger the display of a value selector.
Input field buttons
Used to perform actions with input fields.
Special/custom buttons
These are used to provide specific actions including recording, dialing, and the like.

 

Confirmation

Details
Coding guide
 

A confirmation prompt asks the user to take or confirm an action, such as responding to a system event such as asking the user to restart the device after swapping SIM cards, or to ask the user to grant or deny permission to perform a task. See the Coding guide for information about how to implement these prompts in your app.

 

Characteristics

  • Confirmation prompts are modal; they occupy the entire screen, and require user input to close them.
  • Confirmation prompts consist of:
    • Title (optional)
    • Body
    • Icon (optional)
    • A Confirmation input button, whose label can be customized
    • An optional Cancel input button, whose label can be customized

 

Filter

Details

Filters can be used for two purposes: data filtering, in which the user can view a single set of data in different ways (for example, the Calendar app uses filters to select the time scale to use when viewing data (that is, by day, week, or month); and secondary navigation (presenting a second set of tabs when tabs are already present in your user interface).

 

Characteristics

  • Filters are presented as a horizontal sequence of buttons.
  • Only one button is focused at a time.
  • The best practice is to place filters within toolbars, so that they don't flow with content.
  • Left, middle, and right buttons can be styled uniquely. This lets you make, for example, the left and right ends of your bar take on a "sheen," or to make the bar rounded on the ends.
  • Filter buttons' widths vary depending on the number of filters in a single set.
  • You must have at least two and no more than five filters in a set.
  • A given set of filters may be labeled with either text or icons, but not both. Because filters' heights are relatively small compared to tabs, text is typically the best practice.

 

Details
Coding guide

A header labels the active view. In addition, it can contain top-level navigation and inputs for the active view. See the Coding guide for information on implementing headers in your apps.

 

Characteristics

  • A header is a horizontal bar the full width of the screen, which appears at the top of the screen in most apps.
  • Headers float above content, with the option of flowing with content in special instances, such as in the Browser app.
  • The heading's text provides the name of the current view.
  • The heading may optionally include additional text; for example, in an email app, the number of unread messages may be displayed.
  • Headers may include inputs for navigating and manipulating the current view.
  • Most apps (full-screen games being an obvious exception) have a header.

 

Input area

Details

An input area is a data entry field. There are many variations on what an input area can look like; they can be as simple as a text entry field, and as complex as a multi-part entry field with text entry, value selectors, and buttons.

Details coming soon.

List

Details

Lists are used to display a set of consecutive items, such as a list of contacts or a list of messages.

 

Characteristics

  • List items may vary in height (from one to three rows in a single item).
  • List items may be as simple as just a text string, to including images, text, and buttons.
  • Lists are comprised of rows, with optional section headers.

There are several types of list rows:

Action row
An action row is one in which a tap anywhere in the row triggers the row.
Status indicator row
Need details.
Button row
Need details.
Link row
Need details.

 

Object menu

Details

 

An object menu is a menu that lets the user directly manipulate objects without having to open them and navigate deeper into a view hierarchy.

  • Deleting a photo by selecting its thumbnail, instead of by opening the full image first.
  • Flagging an email by selecting its preview instead of by first opening the email.
  • Calling a contact by selecting their name, instead of by opening their detailed contact information then pressing a "Call" button.

Object menus are currently implemented as a special case of action menu; this will evolve over time. For now, see the action menu coding guide for information on how to implement an object menu.

 

Characteristics

  • Object menus are accessed using a "press-and-hold" gesture on a selectable object, such as a list row, phone number, URL, or the like.
  • An object menu contains one or more items.
  • Object menus expand in height to accomodate their contents, to a maximum of the height of the screen; at that point, the contents of the menu scroll. As a rule of thumb, you should try to avoid having more than five items in the menu.
  • Unlike action menus, object menus do not have titles.
  • You implement object menus using the same code and style as for action menus.

 

 

Progress and activity indicator

Details

Progress and activity indicators are used to provide visual feedback that a process is active.

 

Characteristics

  • May include an animated visual element, a text label, or both.
  • Progress and activity indicators may be used in modal windows, or inline either with content or adjacent to content.
  • An activity indicator is used to show that an activity is ongoing without indicating how long the task is expected to take; these can be "barberpole" style indicators, or spinners.
  • A progress indicator is used to show how much out of 100% of an activity has been completed.

 

Scrolling

Details

Scrolling areas are used to let the user move text and/or images across the device's display.

 

Characteristics

There are two types of scrolling areas: scrollbars and index scrolling.

 

Seek bar

Details

Seek bars have a draggable thumb the user can touch and drag back and forth to scroll through content (such as to set playback position in a media file) or to set a new value for a given control, such as sound volume or display brightness.

 

Characteristics

  • A seek bar consists of a track with a knob that indicates the current playback position.
  • The knob has both normal and "pressed" states.
  • The values for the ends of the seek bar can be specified as either text or images.
  • Seek bars may be oriented either horizontally or vertically.

 

Status


Details
Coding guide

Relays information to the user in a transitory fashion, typically to confirm a user action or to alert the user to a system event. See the Coding guide for details on how to implement a status bar. Sometimes status bars are referred to as "banners."

 

Characteristics

  • Examples include deleting multiple photos in Gallery, or deleting or moving multiple emails.
  • Positioned at the bottom of the screen, covering underlying content.
  • Closing: Status bars automatically disappear, typically after a few seconds for short messages. This can be longer, though, depending on the message and context.
  • Can include an input, such as an "Undo" option; this is optional.
  • Can optionally include an image.
  • Can either be part of an app (such as a "Photos deleted" banner in the Gallery app) or in the System (such as a "Low battery" alert).
  • Avoid displaying more than one status bar at the same time. If two status bars appear at the same time, the newer status bar replaces the older one.

 

Switch

Details
Coding guide

A switch is any control which presents two mutually exclusive options or states. Switches are also used to select items within lists. See the Coding guide for details on implementing switches in your apps.

 

Characteristics

  • A switch presents two mutually exclusive choices or states.
  • There are three types of switch:
    • On/Off toggle switches
    • Checkboxes
    • Radio buttons

 

Tabs

Details
Coding guide

Tabs are used as a navigational widget that let the user switch among sets of views. This way, a window may contain multiple views. See the Coding guide for details on how to implement tabs in your apps.

 

Characteristics

  • Tab bars always fill the full horizontal width of the screen.
  • You may have up to (but no more than) five tabs in a tab bar.
  • Tab bars should be positioned at the very bottom of the screen, unless doing so would result in excessive clutter due to multiple bars of controls at the bottom of the screen.
  • Tabs can contain a variety of elements, such as buttons, filters, indicators, and the like.
  • Tabs' labels may be text, text with an icon, or just an icon.

 

Toolbar

Details
Coding guide

Toolbars contain actions, indicators, and navigation elements associated with the current view. These may include things such as buttons to delete the currently selected items, a filter to enter edit mode, or a filter to show only "favorite" contacts. See the Coding guide for details on how to implement toolbars in your apps.

 

Characteristics

  • Toolbars are always the full width of the screen, and are always the same height.
  • Toolbars never scroll with content; instead, they float above content.
  • Toolbars should always be positioned at the very bottom edge of the screen unless tabs are also present, in which case the toolbar is positioned at the top of the screen instead.
  • Toolbars may contain a wide variety of elements, including buttons, filters, progress/activity indicators, and so forth.

 

Value selector

Details
Coding Guide

Value selectors let the user choose one of a number of possible values, and are typically used from a form interface. For example, value selectors could be used to choose the month or day for a calendar event. These are presented automatically for the values of the <input> element's type attribute.

 

Characteristics

  • Value selectors may have an optional title.
  • The following types of value selectors are provided:
    • Date
    • Time
    • SIngle-select list
    • Multiple-select list

 

 

Document Tags and Contributors

Contributors to this page: fscholz, chrisdavidmills, fflorez478, Logi0, Sheppy
Last updated by: fscholz,