8000 updated documentation · JavaScriptExpert/weh@fefa3af · GitHub
[go: up one dir, main page]
Skip to content

Commit fefa3af

Browse files
mi-gmi-g
committed
updated documentation
1 parent 074785a commit fefa3af

File tree

1 file changed

+292
-1
lines changed

1 file changed

+292
-1
lines changed

‎README.md

Lines changed: 292 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,294 @@
11
# weh
22

3-
Sorry, documentation for Weh 2 is not yet available
3+
**weh** stands for *WebExtensions Helper*.
4+
5+
This toolkit speeds up browser add-ons development by providing a number of facilities for WebExtensions-based (Firefox, Chrome, Opera and Edge) extensions.
6+
7+
This is not a framework in the sense that the developer does not have to embrace all the provided utilities and there is not many architectural constraints to follow in order to take benefit of the tool.
8+
9+
The build system generates automatically a directory you can directly install into your browser, compiling
10+
automatically CoffeeScript, TypeScript and JSX to Javascript, Sass, Less and Stylus to CSS.
11+
12+
**weh** also provides some libraries that goes into your addon to ease a number of common tasks like managing preferences and two-way communications between the extension background and its user interface content pages,
13+
providing a way for the end-user to customize any string in the add-on user interface. Developing the user interface using ReactJS is also simplified but you may choose
14+
not to use this library.
15+
16+
In addition, an inspector application (under the form of a **weh**-based extension) is provided to monitor other **weh** extensions in real-time.
17+
18+
**weh**-generated extensions are compatible with Firefox, Chrome, Opera and Edge. You should of course maintain this compatibility in the code you add to your project.
19+
20+
## install from npm
21+
22+
```
23+
npm install -g weh gulp
24+
```
25+
26+
### testing installation
27+
28+
```
29+
weh init --prjdir myextension
30+
```
31+
32+
You can now install your skeleton extension from the `myextension/build` directory as described
33+
[here](#install-local).
34+
35+
## install from github
36+
37+
```
38+
npm install -g gulp
39+
git clone https://github.com/mi-g/weh.git
40+
cd weh
41+
npm install
42+
npm link
43+
```
44+
45+
You can now move away from the *weh* directory.
46+
47+
## using weh
48+
49+
To create a new extension project:
50+
51+
```
52+
weh init --prjdir myextension
53+
```
54+
55+
You now have a `myextension` folder. The ` D7AE myextension/src` sub-directory is the place where your add-on specific
56+
code goes. After running `weh init`, the directory contains a simple skeleton code that demonstrates preferences edition. This code is to be modified
57+
to do what your extension is supposed to do.
58+
The `myextension/build` contain an add-on ready to be installed into your browser.
59+
60+
To build and maintain the add-on:
61+
62+
```
63+
cd myextension
64+
weh
65+
```
66+
67+
You will notice that the last `weh` command does not return. It is in watch mode, meaning whenever you make a change into the `myextension/src`
68+
directory, those changes are rebuild into `myextension/build`. If you do not want this behavior and prefer running the build command manually,
69+
add `--no-watch` to the command line.
70+
71+
Run `weh help` to see more command line options.
72+
73+
## <a name="install-local"></a>installing a local add-on into the browser
74+
75+
- on ***Firefox***: visit `about:debugging`, click *Load Temporary Addon*, select the `myextension/build/manifest.json` file
76+
- on ***Chrome***: visit `chrome://extension`, check *Developer mode*, click *Load unpacked extension*, select the `myextension/build` directory
77+
- on ***Opera***: visit `about:extension`, click *Developer mode*, *Load unpacked extension*, select `myextension/build` directory
78+
- on ***Edge***: (tested with insider *Edge version 39.14959*) click the 3 dots icon at the top right, select *Extensions*, click *Load extension*, select `myextension/build` directory
79+
80+
## extension directory structure
81+
82+
**weh** expects all project-specific code to be put into the `src` sub-directory:
83+
84+
- `src/manifest.json`: your add-on's manifest
85+
- `src/**/*`: those files are processed, so resources like js and css (and other supported languages) are learned and processed to the build directory.
86+
- `src-modules/**/*`: files here are used to resolve dependencies
87+
- `locales`: files are copied to `build/_locales`
88+
89+
Also note that you can change the `src` directory by specifying a directory path with the `--srcdir` option.
90+
91+
## accessing weh services
92+
93+
Declaring `weh` from a background script: `const weh = require('weh-background');`
94+
From a content script: `const weh = require('weh-content');`
95+
From a web worker: `const weh =
96+
97+
You can then access a number of services from the `weh` variable:
98+
99+
- `weh.rpc`: making function calls (both ways) through various components completely transparent: beetwen background and content, background and workers, background and native apps, background and injected-content
100+
- `weh.prefs`: preferences system
101+
- `weh.i18n`: translation system
102+
- `weh.ui`: content management from background utilities
103+
104+
## multi-language support
105+
106+
*Weh* obviously supports Javascript (`.js` file extension) for scripts and Cascading Style Sheets (`.css` extension), but you can also use other languages:
107+
108+
- scripts: *JSX* (`.jsx`), *Typescript* (`.ts`), *Coffee* (`.coffee`)
109+
- styling: *Sass* (`.scss`), *Less* (`.less`), *Stylus* (`.styl`)
110+
111+
## pre-processing files
112+
113+
All files with a `.ejs` are processed first by an *EJS* processor. For instance, a file named `myscript.js.ejs` will
114+
be transformed to `myscript.js` before being processed. You can specify one or several JSON files to provide data
115+
for the EJS resolution using the `--ejsdata` option.
116+
117+
The EJS pre-processing occurs in a first place, so a file named `myscript.ts.ejs` will first be EJS-processed, then
118+
compiled using Typescript, and will endup in the build directory as `myscript.js`.
119+
120+
Any text file in the `src` directory can be processed with EJS, not only js and css-like.
121+
122+
Pre-processing is useful if you want to generate different builds from the same source code.
123+
124+
## using weh libraries
125+
126+
### weh preferences
127+
128+
Preferences are to be formally defined in order to be used in your add-on. An example of preferences description could be:
129+
```
130+
weh.prefs.declare([{
131+
name: "myparam_string",
132+
type: "string",
133+
defaultValue: "Default value",
134+
maxLength: 15,
135+
regexp: "^[a-zA-Z ]+$"
136+
},{
137+
name: "myparam_integer",
138+
type: "integer",
139+
defaultValue: 42,
140+
minimum: -10,
141+
maximum: 100
142+
},{
143+
name: "myparam_float",
144+
type: "float",
145+
defaultValue: 3.14159,
146+
minimum: 1.5,
147+
maximum: 10.8
148+
},{
149+
name: "myparam_boolean",
150+
type: "boolean",
151+
defaultValue: true
152+
},{
153+
name: "myparam_choice",
154+
type: "choice",
155+
defaultValue: "second",
156+
choices: [{
157+
name: "First choice",
158+
value: "first"
159+
},{
160+
name: "Second choice",
161+
value: "second"
162+
},{
163+
name: "Third choice",
164+
value: "third"
165+
}]
166+
}]);
167+
```
168+
For each parameter, you must provide at least `name`, `type` and `defaultValue`. `type` must be one of `string`, `integer`, `float`, `boolean` or
169+
`choice`. A specific preference parameter can then be accessed, as read or write, through `weh.prefs["parameter name"]`.
170+
171+
You can install preferences listeners using `weh.prefs.on(whatToWatch,callback)` and uninstall listeners using `weh.prefs.off` with the same parameters. `whatToWatch` uses a dotted notation. For instance, listening to `""`, `"a"`, `"a.b"` or `"a.b.c"` will trigger the callback whenever
172+
parameter `a.b.c` is modified. Note that the preferences listeners are available from both background and local content.
173+
174+
You should also define a couple of human viewable strings associated to each parameter in `locales/<locale>/messages.json`:
175+
- `weh_prefs_label_<parameter name>` defines a label for the parameter
176+
- `weh_prefs_description_<parameter name>` defines an optional longer description for this parameter
177+
178+
Example (`locales/en_US/messages.json`):
179+
```
180+
"weh_prefs_label_myparam_string": {
181+
"message": "String parameter"
182+
},
183+
"weh_prefs_description_myparam_string": {
184+
"message": "Only letters and spaces, 20 characters max"
185+
},
186+
```
187+
188+
You can define a number of constraints to your preferences. This is useful with the settings user interface provided by *weh*.
189+
- `maxLength`: (type `string`, `integer` and `float`) the number of characters in the input
190+
- `regexp`: (type `string`) a regular expression the string must match
191+
- `minimum`: (type `integer` and `float`) the minimum acceptable value
192+
- `maximum`: (type `integer` and `float`) the maximum acceptable value
193+
- `choices`: (type `choice`) the set of possible choices to appear in a select input. This is array of either:
194+
- object containing fields `value` (the actual preference value) and `name` (what is to be displayed to the user)
195+
- string representing the actual preference value. The label to be displayed for this choice is searched in `locales/<locale>/messages.json` as `weh_prefs_label_<parameter name>_option_<parameter value>`
196+
197+
Note that the preferences definition can be declared or updated at any time. This is useful if, for instance, you don't the list of choices in advance.
198+
199+
*weh* takes care of adding/removing the listener when the component is mounted/unmounted and delivering the message to the `onWehMessage` method.
200+
201+
## debugging tools
202+
203+
The *weh* toolkit includes an extension called *weh-inspector* which allows to:
204+
- monitor messages between the background and UI
205+
- read/write addon preferences
206+
- read add-on storage
207+
208+
The *weh-inspector* is available as a template in the *weh* toolkit. As such, you can install it with `weh init --template inspector --prjdir inspector` and then load the generated extension into the browser like any regular weh addon.
209+
210+
## i18n
211+
212+
*weh* provides some utilities for dealing with locales.
213+
214+
Instead of `browser.i18n.getMessage()`, you should use `weh._()`, with the same parameters:
215+
- it's shorter
216+
- it automatically turns character `'-'` into `'_'` in string tags while leaving a warning in the console
217+
- more important: it allows overwriting some or all locale strings. Whenever a call is made to `weh._()`, the library first searches for a storage-based translation for this tag. If not found, it uses the default string defined in `_locales/<locale>/messages.json`. By default, *weh* provides a user interface page for the user to edit locale strings. It is up to the add-on developer to write the code to centralize the user-generated translations on a server, so that it can be shared amongst all users.
218+
219+
## rpc
220+
221+
*weh* provides an easy way to call functions across components that do not run within the same threads.
222+
223+
All the functions return promises. If a declared function returns something other than a Promise object, *weh* takes of promisifying the returned value.
224+
225+
Functions are declared on the called side using `weh.rpc.listen()` and are called with `weh.rpc.call()`.
226+
227+
For instance, the background can define a function like this:
228+
```
229+
weh.rpc.listen({
230+
my_function: (a,b) => {
231+
return a + b;
232+
}
233+
})
234+
```
235+
236+
and a content script can call the function this way:
237+
```
238+
weh.call("my_function",39,3)
239+
.then((result)=>{
240+
console.info("=",result);
241+
});
242+
```
243+
244+
`weh.rpc.listen()` can declare several functions at once, and can be called several times: only function with the same name are overwritten.
245+
246+
When using the `weh.ui` module to create a content, for instance creating a tab, a name is given to this content, for instance `settings`. When the background wants to call a function declared within this content, it must use the content name as the first parameter: `weh.rpc.call("settings","my_function",39,3);
247+
248+
If the called function does not exists, throw an exception or return explicitly a failed promise the returned promise is rejected.
249+
250+
## native messaging
251+
252+
*weh* is also very useful when dealing with native messaging.
253+
254+
```
255+
var nativeApp = require('weh-natmsg')("com.example.myapp");
256+
257+
nativeApp.call("my_function",...params)
258+
.then((result)=>{
259+
// do something
260+
})
261+
.catch((err)=>{
262+
// handle error
263+
})
264+
```
265+
266+
You can catch all errors due to the native app not being installed (or at least not being callable):
267+
```
268+
nativeApp.onAppNotFound.addListener((err)=>{
269+
// for instance, open a tab to a site where to download the app
270+
})
271+
```
272+
273+
You can just check whether the app is present, without triggering the `onAppNotFound()` if it is not:
274+
```
275+
nativeApp.callCatchAppNotFound((err)=>{
276+
// this is called if the app could not be launched
277+
},"my_function",...params);
278+
```
279+
280+
On the native app side, assuming it is developed on node.js, you can use the exact same rpc mechanism, using `rpc.listen()` and `rpc.call()` to communicate both ways with the add-on.
281+
282+
For now, the only implementation of such a native is available on the [`vdhcoapp` project](https://github.com/mi-g/vdhcoapp) under GPL-2.0 license. It is planned to release a version using a less restrictive license.
283+
284+
## UI utilities
285+
286+
`weh.ui` provides the ability to open a tab or a panel, so that the created content can directly be callable from the background using `weh.rpc`.
287+
288+
```
289+
weh.ui.open("some_name",{
290+
url: "content/content.html",
291+
type: "tab"
292+
});
293+
weh.rpc.call("some_name","my_content_function",...params);
294+
```

0 commit comments

Comments
 (0)
0