mozilla-b2g/gaia — pull request #11499 by jrburke (2013-08-12 23:24:50+00:00)
Title: Bug 892519 - [email] Notifications - Email App Not Foreground

Preliminary Gaia pull request. While this code works and has had some end-to-end testing on a phone, there is a high likelihood it will need some changes before it is merge-worthy. Most importantly, it is lacking tests. Doing a pull request now though to work through any higher level design issues first.

Terms:

* BE: back end: usually means GELAM itself, including the main-frame-setup.js and code under that, the worker code.
* FE: front end: the code in gaia for showing the email UI and front end logic.

### General notes

Existing accounts are treated to be "manual" sync (syncInterval of 0) and not notified of new mail. Any new account created with this branch of the code will be set to "notify of new mail", but sync is set to "manual" by default.

There are some UI controls in the settings for an account to turn on syncing. However, this UI is **just temporary**, with the real UI coming in [Bug 892518](https://bugzilla.mozilla.org/show_bug.cgi?id=892518). The temporary hacky UI also has to "DEV" settings at the bottom, for 20 secs and 60 secs to make testing some things easier. **Be sure to set it back to manual** if you use one of those settings, to save the forests and perhaps bad consequences from your email provider from hammering them with too many syncs.

Right now notifications are only text based, and do not allow any formatting. If the sync results in 1 or 2 emails, then a notification for each email is generated showing the subject and the author. If more than two, then there is just one notification that tells the number of new messages, and then a comma separated list of unique authors.

That layout seemed to work well: there was not much room for much else.

There is no revoking or removing of notifications as that is not available in the platform at the moment.

Clicking on the notifications should go somewhere useful: if multi-email notification, to the message list for that email account. If a single email notification, then jumping to that message.

If the email app is visible when the new message comes in:

* If in the account for the message, no notification.
* If for an account that is not the current one being shown in the app, a system notification is sent.

All alarm and notification work goes through the index.html file. This is partly because right now alarms can only be fired [for the same page that sets them]( https://bugzilla.mozilla.org/show_bug.cgi?id=800431). Once that alarm bug is fixed and SharedWorkers are available, a more efficient approach may be possible.

Still to do:

* Add tests.
* There are new l10n string work to wire up.
* See if sync time can be reduced. It takes about 10 seconds right now from start to finish on a wifi network for an account that is already synced.

Related GELAM changeset pull request:
https://github.com/mozilla-b2g/gaia-email-libs-and-more/pull/232

Notes on the implementation:

### app_messages

It now listens for 'notification' messages, and converts the data passed via the iconURL into a data structure that is then passed to app code.

### app_self

module for wrapping the mozApps.getSelf() call, as it is needed to get an iconURL for the notification. It uses the evt so that other code can use the "latest" callback structure to get the mozApps value.

### account_picker, folder_picker

They no longer look for related cards and prod them to update to new account/folder values, but instead, the other cards now just listen to the `model` module for changes.

### message_list

Listens to model now for changes instead of waiting for a direct call from folder_picker.

### settings_account.js/.html

Has the hacky UI for the syncInterval and notifyOnNew setting. That UI was stolen from the hidden portions that were in settings_main.html.

### cards/setup_progress.js

Sets some defaults for the new account values.

### evt.js

Had a bug around "once" notifications. New unit test confirms the fix.

### html_cache_restore.js

Checks for alarm and notification pending messages as it did before for activities, but now sets an object specifying what was detected. This is done since calling mozHasPendingMessage only seems to work once per type.

### mail_app.js

Loads the new modules that handle the sync events and wake locks, then registers for 'notification' messages to know how to start up the UI.

### model.js

Refactored a bit to allow setting account and folder more granularly. Used mostly for the notification listening in mail_app.js to switch to the correct account/folder to use for the UI.

### query_string.js

Handle converting an object to a querystring value to add to iconURL, and then to hydrate that querystring back into an object.

### sync.js

Handles the "cron start" and "cron stop" messages from the back end. Determines how to notify the user, and then emits a "cronSyncStop" that is used by the wake_locks module to know when to release the wake locks. sync.js also will shut down the app if it has not been made visible during the time it was started.

### wake_locks.js

Handles the 'conrSyncWakeLocks' event that is broadacast from the BE, and then listens for 'cronSyncStop' from sync.js to know when to release the locks. Also sets up a timer for 45 seconds as a max time for the locks, to prevent a bug from keeping the wake locks operational forever. This means syncs neeed to finish within 45 seconds or risk going into sleep state.