moving content for wallet devs into doc/
This commit is contained in:
Marcello Stanisci
parent
87f981d91c
commit
f286ed2355
212
doc/dev-wallet-wx.rst
Normal file
212
doc/dev-wallet-wx.rst
Normal file
@ -0,0 +1,212 @@
|
||||
..
|
||||
This file is part of GNU TALER.
|
||||
Copyright (C) 2014, 2015, 2016 INRIA
|
||||
TALER is free software; you can redistribute it and/or modify it under the
|
||||
terms of the GNU General Public License as published by the Free Software
|
||||
Foundation; either version 2.1, or (at your option) any later version.
|
||||
TALER is distributed in the hope that it will be useful, but WITHOUT ANY
|
||||
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
|
||||
A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
|
||||
You should have received a copy of the GNU Lesser General Public License along with
|
||||
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
|
||||
|
||||
@author Florian Dold
|
||||
|
||||
=====================
|
||||
WebExtensions Wallet
|
||||
=====================
|
||||
|
||||
------------
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The WebExtensions Wallet (*wxwallet*) can be used to pay with GNU Taler on web
|
||||
sites from within modern web browsers. The `WebExtensions
|
||||
<https://wiki.mozilla.org/WebExtensions>`_ API enables the development of
|
||||
cross-browser extensions. Google Chrome / Chromium, Mozilla Firefox, Opera and
|
||||
Microsoft Edge will all offer support for WebExtensions and thus be able to support Taler.
|
||||
|
||||
Currently Chrome hast the best support for WebExtensions (since the API is a
|
||||
superset of Chrome's extension API).
|
||||
|
||||
-----------------------
|
||||
Development Environment
|
||||
-----------------------
|
||||
|
||||
The *wxwallet* mainly written in the `TypeScript
|
||||
<http://www.typescriptlang.org/>`_ language, which is a statically typed
|
||||
superset of JavaScript.
|
||||
|
||||
While the *wxwallet* is mainly intended to be run from inside a browser, the
|
||||
logic is implemented in browser-independent modules that can also be called
|
||||
from other environments such as `nodejs <https://nodejs.org>`_. This is
|
||||
especially useful for automatically running unit tests.
|
||||
|
||||
|
||||
-----------------
|
||||
Project Structure
|
||||
-----------------
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
**manifest.json** extension configuration
|
||||
**package.json** node.js package configuration
|
||||
**tsconfig.json** TypeScript compiler configuration
|
||||
**gulpfile.js** Build tasks script
|
||||
**lib/**
|
||||
**vendor/** 3rd party libraries
|
||||
**wallet/** actual application logic
|
||||
**emscripten/** emscripten object file and glue
|
||||
**test/**
|
||||
**run_tests.js** nodejs entry point for tests
|
||||
**tests/** test cases
|
||||
**content_scripts/notify.ts** wallet<->website signaling
|
||||
**backgrond/main.ts** backend entry point
|
||||
**img/** static image resources
|
||||
**style/** CSS stylesheets
|
||||
**pages/** pages shown in browser tabs
|
||||
**popup/** pages shown the extension popup
|
||||
|
||||
|
||||
-------------------
|
||||
Building the Wallet
|
||||
-------------------
|
||||
|
||||
To build the extension for use during development, simply run the TypeScript compiler
|
||||
from the extension directory:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ cd wallet.git/wallet_webextension/extension/
|
||||
$ tsc
|
||||
|
||||
This will use the ``tsconfig.json`` with development options such as `source map`_ support.
|
||||
|
||||
.. _`source map`: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit
|
||||
|
||||
When TypeScript source files are added or deleted to the project, make sure that the
|
||||
globs in ``gulpfile.js`` match them so that they will be compiled. The ``tsconfig.json``
|
||||
is generated by running:
|
||||
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ gulp tsconfig
|
||||
|
||||
.. caution::
|
||||
|
||||
Do not edit the ``tsconfig.json`` manually. The source files should be defined in
|
||||
one place, and that is ``gulpfile.js``.
|
||||
|
||||
To pack the extension in a format that can be uploaded to the Google Webstore, run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ gulp package
|
||||
|
||||
This will build the wallet without source maps, copy resource files (which also need to be
|
||||
specified in ``gulpfile.js``) and create an archive.
|
||||
|
||||
|
||||
----------
|
||||
Emscripten
|
||||
----------
|
||||
|
||||
`Emscripten <https://kripken.github.io/emscripten-site/index.html>`_ is C/C++
|
||||
to JavaScript compiler. Emscripten is used in the *wxwallet* to access
|
||||
low-level cryptography from *libgcrypt*, and miscellaneous functionality from
|
||||
*libgnunetutil* and *libtalerwallet*.
|
||||
|
||||
TODO: say things about wrappers
|
||||
|
||||
|
||||
--------------------------------------
|
||||
Target Environments and Modularization
|
||||
--------------------------------------
|
||||
|
||||
Modules in the wallet are declared in TypeScript with
|
||||
the ES6 module syntax. These modules are then compiled
|
||||
to `SystemJS <https://github.com/systemjs/systemjs>`_ `register` modules.
|
||||
|
||||
SystemJS modules can be loaded from the browser as well as from nodejs.
|
||||
However they require special entry points that configure the module system,
|
||||
load modules and execute code. Examples are `backgrond/main.ts` for the
|
||||
browser and `test/run_tests.js` for nodejs.
|
||||
|
||||
Note that special care has to be taken when loading the Emscript code,
|
||||
as it is not compatible with the SystemJS module, even in the `globals`
|
||||
compatibility mode.
|
||||
|
||||
The TypeScript sources in the *wxwallet* are compiled down to ES5, both to
|
||||
enable running in node.js without transpilers and to avoid a `bug
|
||||
<https://github.com/Microsoft/TypeScript/issues/6426>`_ in the TypeScript
|
||||
compiler.
|
||||
|
||||
----------------------------
|
||||
IndexedDB Query Abstractions
|
||||
----------------------------
|
||||
|
||||
The *wxwallet* uses a fluent-style API for queries on IndexedDB.
|
||||
|
||||
TODO: say more about this
|
||||
|
||||
|
||||
-------
|
||||
Testing
|
||||
-------
|
||||
|
||||
Test cases for the wallet are written in TypeScript and
|
||||
run with `mochajs <http://mochajs.org/>`_ and the `better-assert <https://github.com/tj/better-assert>`_ assertion
|
||||
library.
|
||||
|
||||
Run the default test suite with ``npm run test``, which will
|
||||
call `mocha` with the right parameters.
|
||||
|
||||
|
||||
--------------------
|
||||
Internationalisation
|
||||
--------------------
|
||||
|
||||
Strings in the JavaScript code are internationalised using the following functions:
|
||||
|
||||
- *i18n*: translate string with arbitrary arguments, the result is returned as string.
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
i18n`You have ${n} coins.`
|
||||
|
||||
- *i18n.parts*: Interpolate i18nized values with arbitrary objects.
|
||||
Useful for example to include HTML elements.
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
i18n.parts`Visit ${link} to get more coins.`
|
||||
|
||||
- *i18n.pluralize*: translate with plural form.
|
||||
The i18n.number() function returns a ``PluralNumber`` object
|
||||
that specifies the argument that determines the plural form,
|
||||
if not present the first numeric argument is used.
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
i18n.pluralize(
|
||||
i18n`${i}: you have ${i18n.number(n)} coin.`,
|
||||
`${i}: you have ${i18n.number(n)} coins.`);
|
||||
|
||||
These functions are defined in ``lib/i18n.ts``.
|
||||
Include ``lib/vendor/jed.js``, ``lib/i18n.js``, ``lib/i18n-strings.js`` to use them.
|
||||
|
||||
To extract strings from sources and update the .po files, run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ make i18n
|
||||
|
||||
In static HTML files the ``lang`` attribute is used for language-specific strings:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<p lang="en">Hello World!</p>
|
||||
<p lang="de">Hallo Welt!</p>
|
||||
|
||||
``lib/i18n.js`` and ``style/lang.css`` needs to be included for this to work.
|
||||
@ -1 +1 @@
|
||||
Subproject commit a8bff2e27b89feb3696cf0e3a49fc00155d92de5
|
||||
Subproject commit fd80260fce96df674111f9100fa2d91c83a9a3bc
|
||||
Loading…
Reference in New Issue
Block a user