Software /
code /
prosody-modules
Annotate
mod_conversejs/README.markdown @ 3523:68beaf7fd7d6
luacheckrc: Copy line length setting from prosody
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Sun, 31 Mar 2019 18:31:10 +0200 |
parent | 3495:5567098a7f91 |
child | 3598:1921ae4449b8 |
rev | line source |
---|---|
2878 | 1 --- |
2 depends: | |
3 - 'mod\_bosh' | |
4 - 'mod\_websocket' | |
5 provides: | |
6 - http | |
7 title: 'mod\_conversejs' | |
8 --- | |
9 | |
10 Introduction | |
11 ============ | |
12 | |
13 This module serves a small snippet of HTML that loads | |
14 [Converse.js](https://conversejs.org/), configured to work with the | |
15 VirtualHost that it is loaded onto. | |
16 | |
17 Configuration | |
18 ============= | |
19 | |
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
20 The module uses general Prosody options for basic configuration. It |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
21 should just work after loading it. |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
22 |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
23 ``` {.lua} |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
24 modules_enabled = { |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
25 -- other modules... |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
26 "conversejs"; |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
27 } |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
28 ``` |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
29 |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
30 Authentication |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
31 -------------- |
2878 | 32 |
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
33 [Authentication settings][doc:authentication] are used determine |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
34 whether to configure Converse.js to use `login` or `anonymous` mode. |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
35 |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
36 Connection methods |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
37 ------------------ |
2878 | 38 |
3362
af085e8b9d48
mod_conversejs: Link to BOSH and WebSockets setup instructions instead of module pages
Kim Alvefur <zash@zash.se>
parents:
3334
diff
changeset
|
39 It also determines the [BOSH][doc:setting_up_bosh] and |
af085e8b9d48
mod_conversejs: Link to BOSH and WebSockets setup instructions instead of module pages
Kim Alvefur <zash@zash.se>
parents:
3334
diff
changeset
|
40 [WebSocket][doc:websocket] URL automatically, see their respective |
af085e8b9d48
mod_conversejs: Link to BOSH and WebSockets setup instructions instead of module pages
Kim Alvefur <zash@zash.se>
parents:
3334
diff
changeset
|
41 documentation for how to configure them. Both connection methods are |
af085e8b9d48
mod_conversejs: Link to BOSH and WebSockets setup instructions instead of module pages
Kim Alvefur <zash@zash.se>
parents:
3334
diff
changeset
|
42 loaded automatically. |
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
43 |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
44 HTTP |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
45 ---- |
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
46 |
3304 | 47 The module is served on Prosody's default HTTP ports at the path |
48 `/conversejs`. More details on configuring HTTP modules in Prosody can | |
49 be found in our [HTTP documentation](http://prosody.im/doc/http). | |
2878 | 50 |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
51 Other |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
52 ----- |
2878 | 53 |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
54 To pass [other Converse.js |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
55 options](https://conversejs.org/docs/html/configuration.html), or |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
56 override the derived settings, one can set `conversejs_options` like |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
57 this: |
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
58 |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
59 ``` {.lua} |
3304 | 60 conversejs_options = { |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
61 debug = true; |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
62 view_mode = "fullscreen"; |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
63 } |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
64 ``` |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
65 |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
66 Note that the following options are automatically provided, and |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
67 **overriding them may cause problems**: |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
68 |
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
69 - `authentication` *based on Prosody's authentication settings* |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
70 - `jid` *the current `VirtualHost`* |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
71 - `bosh_service_url` |
3495
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
72 - `websocket_url` |
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
73 |
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
74 `mod_bosh` and/or `mod_websocket` are automatically enabled if available |
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
75 and the respective endpoint is included in the generated options. |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
76 |
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
77 Loading resources |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
78 ----------------- |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
79 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
80 By default the module will load the main script and CSS from cdn.conversejs.org. For privacy or performance |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
81 reasons you may want to load the scripts from somewhere else, simply use the conversejs_cdn option: |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
82 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
83 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
84 conversejs_cdn = "https://cdn.example.com" |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
85 ``` |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
86 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
87 To select a specific version of Converse.js, you may override the version: |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
88 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
89 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
90 conversejs_version = "4.0.1" |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
91 ``` |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
92 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
93 Note that versions other than the default may not have been tested with this module, and may include incompatible changes. |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
94 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
95 Finally, if you can override all of the above and just specify links directly to the CSS and JS files: |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
96 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
97 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
98 conversejs_script = "https://example.com/my-converse.js" |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
99 conversejs_css = "https://example.com/my-converse.css" |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
100 ``` |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
101 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
102 Additional tags |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
103 --------------- |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
104 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
105 To add additional tags to the module, such as custom CSS or scripts, you may use the conversejs_tags option: |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
106 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
107 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
108 conversejs_tags = { |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
109 -- Load custom CSS |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
110 [[<link rel="stylesheet" href="https://example.org/css/custom.css">]]; |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
111 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
112 -- Load libsignal-protocol.js for OMEMO support (GPLv3; be aware of licence implications) |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
113 [[<script src="https://cdn.conversejs.org/3rdparty/libsignal-protocol.min.js"></script>]]; |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
114 } |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
115 ``` |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
116 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
117 The example above uses the `[[` and `]]` syntax simply because it will not conflict with any embedded quotes. |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
118 |
2920
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
119 Compatibility |
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
120 ============= |
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
121 |
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
122 Should work with Prosody 0.9 and later. Websocket support requires 0.10. |