Firefox OS/Stingray/Hybrid Widget Approach

From MozillaWiki
Jump to: navigation, search

Hybrid Widget Approach

Hybrid Widget Approach means homescreen has more power and responsibilities. A homescreen app may manage and host widgets in itself no longer needing system app's support, unlike 2-layered widget approach. All apps opened by homescreen app are still managed and hosted by system app.

We will create the hybrid widget approach for TV first and support phone version if the resource is available.


Hybrid Widget Approach Architecture

Limitations of This Approach

  • Users cannot have multiple instances of the same widget with different configurations (need new API support)
  • A widget cannot open new screen, excepting using mozApps.getSelf().launch()


The homescreen app of hybrid widget approach may depends on the following bugs. We need all of permission bugs fixed to have a privileged homescreen app. We will create a certified homescreen app when they are not ready.

permission bugs

meta: bug 994858 Replaceable Homescreen

  • bug 899994 webapps-manage: query installed app list, listen app install/uninstall events, use "app://" protocol, etc.
  • bug 1005818 embed-widgets: assign iframe mozApp attribute to grant permissions.
  • bug 819882 open-remote-window:, "remote");

wallpaper bugs

meta: bug 994858 Replaceable Homescreen

other gecko bugs

How to use it

Workaround of bug 879475

Before bug 879475 fixed, we need to make homescreen-stingray app not be OOP and request the "Browser API permission". Please apply the following patch:

Build and Install

We may build and install the homescreen-stingray with GAIA_DEVICE_TYPE=tv parameter, like:

 make reset-gaia GAIA_DEVICE_TYPE=tv

This command clears all data and installs homescreen-stingray as its default homescreen. After that, we can have the homescreen looks like:

prototype of homescreen stingray

Work List

The following work items will be landed to dev_apps/homescreen-stingray/

Meta bug: bug 1002336

Homescreen Base

meta: bug 1002344 => Luke Chang

  • template bug 1002377 => Luke Chang: creating a template for the homescreen-stingray app could make further works easier.
  • applications bug 1002355 => Luke Chang: a helper to wrap functions of mozApps.mgmt like query installed apps, get app icon blob, launch an app, etc.
  • app list bug 1002358 => Luke Chang: render app icons to let users launch apps or choose widgets.

Keyboard Support

meta: bug 1013040

  • selection border bug 1006378 => John Hu: add selection border UI to support spatial navigation
  • spatial navigator bug 1002350 => Luke Chang: finding the nearest element on 2D plane.

Widget Editor

meta: bug 1002337 => John Hu

  • layout editor bug 1002339 => John Hu: We need to calculate the position of widget slots for customizing widget position. In TV, we have only fixed slots and no widgets can cross two slots. But we may have widgets crossing icon slots in phone. The crossing depends on the preferred widget size and we don't have that information, yet. So, we may have a crossing widget with fixed size, like bug 980935 and bug 980936.
  • widget editor bug 1002341 => John Hu: It is a UI for user to customize their widgets. In TV, we may have a dedicated UI for user to customize the position of widgets. In phone, we may use long press to move the widget which means widget editor handles the positing of moved widgets and icons and layout editor handles the calculation of the final result.
  • persistence module bug 1002343 => John Hu: It is for saving the editing result.
  • static elements bug 1013036 => Luke Chang: put some static elements on homescreen.

Widget Manager

  • widget life-cycle management bug 1002345 => Rex Lee: This work item is to handle the creation/deletion/update of widget window which is created with iframe.
  • widget initializer bug 1009444 => John Hu: Homescreen app should initialize widgets when it boots up and updates widgets when user change it.

Build System

meta: bug 979784 => Gary Chen

  • bug 979785 => Gary Chen - [GAIA][BUILD SYSTEM] Overwrite common-setting.json by GAIA_DEVICE_TYPE in build/settings.js
  • bug 1002360 => Gary Chen - [Stingray][Build] support customizable homescreen url

Sample Widgets

bug 1002348

  • 2048 widget: it already existed in 2-layered approach: 2048 widget

Multiple Homescreen

meta: bug 1013050


Event Emitter

If an object needs to fire events, we should use evt.js to dispatch custom event:

"evt.js" is a library already used at camera app.

performance test of event emitter can be found here:

Class Definition Style

All class definitions should use the following convention:

 /* global evt, Applications, ...etc */
 'use strict';
 (function(exports) {
   function Module() {
   Module.prototype = evt({ // (Optional) Use "evt" only if you need to emit events.
     start: function(options) {
     stop: function() {
     camelCase: function() {
     _private: function() { // Variables with underline prefix stands for private member
     }                      // which means that its API may be changed anytime so do not
                            // use it in public.
   exports.Module = Module;