System App convention

[Tim Guan-tin Chien]

Dear all,

I am sorry that I have not made this clear, but we do have a System app
convention that needs to be maintained.

1) Functionality should be isolated in their own script file in
system/js ("modules"). Each script expose an object, with public
accessible API methods. It can be an static object or a module pattern
function or a prototype function instance, whatever you see fit.

2) Each module should be kept as independent as possible. Try not to put
unrelated code in a module. Try not to call other modules directly
(since that create dependency) if the same thing can be done with (3) or
(4).

3) Modules announce a inter-system-app notification or signal via custom
DOM Events. DOM Events may dispatched from it's own DOM element so we
will have a capturing phase and a bubbling phase, or it may not.

4) Alternatively, a state can be kept as a class name of <div
id="screen">. Other modules may check the class or the property of the
module to probe the state (e.g. |LockScreen.locked|,
|screenElement.classList.contains('attention-screen')|)

5) DOM event can be canceled by other modules via
stopImmdiatePropagation() or stopPropagation() so it will not be
captured by other modules (e.g. hardware key events "home" are
dispatched by hardware_buttons.js and captured by window_manager.js, but
before that, lockscreen.js will cancel it if the lockscreen is currently
locked). *

* Note on (5): Unfortunately some of the events are dispatched at the
topmost |window| object; we will not have capturing phase nor bubbling
phase on such event (just the "at-target" phase), so |stopPropagation()|
is useless for us. For such event, if you wish to cancel the event, make
sure your event listener registered before others and use
|stopImmdiatePropagation()|.

As we are not using any libraries to enfore the code isolated and
cleanness, it is important that all devs touching System app remember
these convention and tried not to break them. Modularization will help
us down the road for future projects on many front:

- improve code portability; some of the code can be upgraded to
independent library in the long run
- lazily loading them. I don't expect this to happen on v1 but we should
do so for the long term.
- allow venders to plug/unplug functions easily so we can make more than
just phone (but tablet, game console, etc.)

I expect all code reviewer to impose these rules. As Gaia module peers
we are all responsible of keeping the code manageable, not just finish
the task at hand. If you have any question on these rules that applied
to System app, talk to me, Vivien, or djf.


Happy Friday night.

--
Tim Guan-tin Chien, Front-end Dev, Mozilla Corp. (Taipei)

[Dietrich Ayala]

This is great information Tim. Can you add it to the wiki somewhere?
Or at least link to this message on Google Groups from the
/Gaia/Hacking page?

> _______________________________________________
> dev-gaia mailing list
> dev-...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-gaia