forked from mirrors/gecko-dev
7ee74f6891
MozReview-Commit-ID: LaXHOm15mxi --HG-- extra : rebase_source : f641fcd8e20383b89fd62abe1b567133dba3db82
71 lines
3.3 KiB
ReStructuredText
71 lines
3.3 KiB
ReStructuredText
==============
|
|
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/Development
|
|
=====================
|
|
|
|
Must Have Electrolysis
|
|
-------
|
|
|
|
Web Payments `does not work without e10s <https://bugzilla.mozilla.org/show_bug.cgi?id=1365964>`_!
|
|
|
|
Logging
|
|
-------
|
|
|
|
Set the pref ``dom.payments.loglevel`` to "Debug" to increase the verbosity of console messages.
|
|
|
|
Unprivileged UI Development
|
|
---------------------------
|
|
During development of the unprivileged custom elements, you can load the dialog over a file: URI or
|
|
local server without even requiring a build. Simply load
|
|
`toolkit/components/payments/res/paymentRequest.xhtml` in the browser. Use the debugging console to
|
|
load sample data.
|
|
|
|
Debugging Console
|
|
-----------------
|
|
|
|
To open the debugging console in the dialog, use the keyboard shortcut
|
|
**Ctrl-Alt-d (Ctrl-Option-d on macOS)**. While loading `paymentRequest.xhtml` directly in the
|
|
browser, add `?debug=1` to have the debugging console open by default.
|
|
|
|
Debugging the unprivileged frame with the developer tools
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To open a debugger in the context of the remote payment frame, click the "Debug frame" button in the
|
|
debugging console.
|
|
|
|
Use the `tabs` variable in the Browser Content Toolbox's console to access the frame contents.
|
|
There can be multiple frames loaded in the same process so you will need to find the correct tab
|
|
in the array by checking the file name is `paymentRequest.xhtml` (e.g. `tabs[0].content.location`).
|
|
|
|
|
|
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 (paymentDialogWrapper.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 ``window`` 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.
|