toolkit/components/payments/docs/index.rst
author Phil Ringnalda <philringnalda@gmail.com>
Fri, 03 Nov 2017 20:13:58 -0700
changeset 443421 ab983c341420850665acbad872d398cb3b8c9066
parent 443412 34fa5b4d4d596ae654b3571700afa42c290d7cc7
child 443432 77f59f25cec788999d24f6a085d6acc34baa992d
permissions -rw-r--r--
Backed out 5 changesets (bug 1383300) for leaks CLOSED TREE Backed out changeset 3879080f60c2 (bug 1383300) Backed out changeset bc8f24ca5bb3 (bug 1383300) Backed out changeset 908e2e2a759b (bug 1383300) Backed out changeset 71b84c813705 (bug 1383300) Backed out changeset 34fa5b4d4d59 (bug 1383300) MozReview-Commit-ID: BVz3KG0Qixi

==============
WebPayments UI
==============

User Interface for the WebPayments `Payment Request API <https://w3c.github.io/browser-payment-api/>`_ and `Payment Handler API <https://w3c.github.io/payment-handler/>`_.

JSDoc style comments are used within the JS files of the component. This document will focus on higher-level and shared concepts.

.. toctree::
   :maxdepth: 5

Debugging
=========

Set the pref ``dom.payments.loglevel`` to "Debug".


Communication with the DOM
==========================

Communication from the DOM to the UI happens via the `paymentUIService.js` (implementing ``nsIPaymentUIService``).
The UI talks to the DOM code via the ``nsIPaymentRequestService`` interface.


Dialog Architecture
===================

Privileged wrapper XHTML document (paymentDialog.xhtml) containing a remote ``<iframe mozbrowser="true" remote="true">`` containing unprivileged XHTML (paymentRequest.xhtml).
Keeping the dialog contents unprivileged is useful since the dialog will render payment line items and shipping options that are provided by web developers and should therefore be considered untrusted.
In order to communicate across the process boundary a privileged frame script (`paymentDialogFrameScript.js`) is loaded into the iframe to relay messages.
This is because the unprivileged document cannot access message managers.
Instead, all communication across the privileged/unprivileged boundary is done via custom DOM events:

* A ``paymentContentToChrome`` event is dispatched when the dialog contents want to communicate with the privileged dialog wrapper.
* A ``paymentChromeToContent`` event is dispatched on the ``document`` with the ``detail`` property populated when the privileged dialog wrapper communicates with the unprivileged dialog.

These events are converted to/from message manager messages of the same name to communicate to the other process.
The purpose of `paymentDialogFrameScript.js` is to simply convert unprivileged DOM events to/from messages from the other process.