remove outdated docs, docs now are in docs.git
This commit is contained in:
Florian Dold
parent
36a4a6218c
commit
cec90dc294
@ -1,212 +0,0 @@
|
|||||||
..
|
|
||||||
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.
|
|
||||||
Loading…
Reference in New Issue
Block a user