diff options
Diffstat (limited to 'docs/dev-wallet-wx.rst')
| -rw-r--r-- | docs/dev-wallet-wx.rst | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/docs/dev-wallet-wx.rst b/docs/dev-wallet-wx.rst new file mode 100644 index 00000000..8ba29975 --- /dev/null +++ b/docs/dev-wallet-wx.rst @@ -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. |