View source for Firefox OS/Stingray/Hybrid Widget Model

== 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.

=== Limitations ===
* 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 '''
* {{bug|899994}} mozApp.mgmt: query installed app list, listen app install/uninstall events, use "app://" protocol, etc.
* '''no bug''' embed-apps: assign iframe mozApp attribute to grant permissions.
* {{bug|819882}} open-remote-window: window.open(url, "remote");

''' wallpaper '''
* {{bug|900551}} Settings API --  for getting wallpaper image 
* {{bug|917416}} Let Homescreen App draw the wallpaper

''' other gecko bugs '''
* {{bug|879475}} nested OOP iframe
* {{bug|989198}} hardware key button events

== Item List ==
=== Homescreen Base ===
* utilities like spatial navigation, selection border: to support keyboard only navigating function (e.g. TV remote controller).
* applications: a helper to wrap functions of mozApps.mgmt like query app list, get icon blob, etc.
* app list: render app icons to let users launch apps or choose widgets.

=== Widget Editor ===
* layout editor for customizing widget position
* widget editor for choosing widget
* persistence module for saving the editing result

=== Widget Manager ===
* widget life-cycle management

=== Build System ===
* pack and build correct homescreen
* change default homescreen

=== Sample Widgets ===
* 2048 widget: it already existed in 2-layered approach: [https://github.com/luke-chang/gaia/tree/TV_arch1/test_apps/2048widget 2048 widget]

== Others ==
=== Class Definition Style ===
All class definitions should use the following convention:

  /* global BrowserConfigHelper, WidgetWindow, Applications */
  'use strict';
  
  (function(exports) {
  
    var WidgetFactory = function() {
    };
  
    WidgetFactory.prototype = {
      createWidget: function(args) {
        var manifestURL = args.widgetOrigin + '/manifest.webapp';
        var appInfo = Applications.getByManifestURL(manifestURL);
        if (!appInfo.manifest) {
          return;
        }
        
        var appURL = args.widgetOrigin + (args.widgetEntryPoint ?
          appInfo.manifest.entry_points[args.widgetEntryPoint].launch_path :
          appInfo.manifest.launch_path);
        
        var config = new BrowserConfigHelper(appURL, manifestURL);
        
        var widgetOverlay =
          document.getElementsByClassName('widget-overlay')[0];
        var app = new WidgetWindow(config, widgetOverlay);
        // XXX: Separate styles.
        app.setStyle(args);
        this.publish('launchwidget', app.instanceID);
        
        return app;
      },
      
      publish: function wf_publish(event, detail) {
        var evt = document.createEvent('CustomEvent');
        evt.initCustomEvent(event, true, false, detail);
        window.dispatchEvent(evt);
      }
    };
    
    exports.WidgetFactory = WidgetFactory;
  }(window));