1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
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.
|
