Firefox OS/Stingray/Hybrid Widget Approach
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.
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()
Prerequisite
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: window.open(url, "remote");
wallpaper bugs
meta: bug 994858 Replaceable Homescreen
- bug 900551 Settings API -- for getting wallpaper image
- no bug Let Homescreen App draw the wallpaper (ref. bug 917416, bug 960325)
other gecko bugs
- bug 879475 nested OOP iframe
- bug 989198 hardware key button events
- bug 449165 expose "nearest element" api
- bug 1008862 enable spatial navigation
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: https://github.com/huchengtw-moz/gaia/commit/372650355b841d9fc4896c2a1741d993884e6f96
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:
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
- 2048 widget: it already existed in 2-layered approach: 2048 widget
Multiple Homescreen
meta: bug 1013050
Others
Event Emitter
If an object needs to fire events, we should use evt.js to dispatch custom event: https://github.com/luke-chang/gaia/blob/TV_arch1/test_apps/homescreen-tv-arch1/js/vendor/evt.js
"evt.js" is a library already used at camera app.
performance test of event emitter can be found here: http://jsperf.com/eventemitter-vs-camera-evt-js/2
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; }(window));