Mercurial > prosody-modules
annotate mod_conversejs/README.markdown @ 3656:3e0f4d727825
mod_vcard_muc: Add an alternative method of signaling avatar change
When the avatar has been changed, a signal is sent that the room
configuration has changed. Clients then do a disco#info query to find
the SHA-1 of the new avatar. They can then fetch it as before, or not if
they have it cached already.
This is meant to be less disruptive than signaling via presence, which
caused problems for some clients.
If clients transition to the new method, the old one can eventually be removed.
The namespace is made up while waiting for standardization.
Otherwise it is very close to what's described in
https://xmpp.org/extensions/inbox/muc-avatars.html
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Sun, 25 Aug 2019 20:46:43 +0200 |
parents | 740870196b97 |
children | 309fa523c424 |
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 |
3598
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
51 ## Templates |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
52 |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
53 The HTML and JS can be customized either by editing the included |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
54 `template.html` and `template.js` files or configuring your own like: |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
55 |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
56 ```lua |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
57 conversejs_html_template = "/path/to/my-template.html" |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
58 conversejs_js_template = "/path/to/my-template.js" |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
59 ``` |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
60 |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
61 The HTML template uses Prosodys |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
62 [`util.interpolation`][doc:developers:util:interpolation] template |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
63 library while the JS template has `%s` where generated settings are |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
64 injected. |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
65 |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
66 Other |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
67 ----- |
2878 | 68 |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
69 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
|
70 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
|
71 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
|
72 this: |
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
73 |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
74 ``` {.lua} |
3304 | 75 conversejs_options = { |
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
76 debug = true; |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
77 view_mode = "fullscreen"; |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
78 } |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
79 ``` |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
80 |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
81 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
|
82 **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
|
83 |
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
84 - `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
|
85 - `jid` *the current `VirtualHost`* |
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
86 - `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
|
87 - `websocket_url` |
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
88 |
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
89 `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
|
90 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
|
91 |
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
92 Loading resources |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
93 ----------------- |
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 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
|
96 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
|
97 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
98 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
99 conversejs_cdn = "https://cdn.example.com" |
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 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
|
103 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
104 ``` {.lua} |
3643
740870196b97
mod_http_stats_stream: Make global to simplify
Kim Alvefur <zash@zash.se>
parents:
3598
diff
changeset
|
105 conversejs_version = "5.0.0" |
3334
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 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
108 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
|
109 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
110 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
|
111 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
112 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
113 conversejs_script = "https://example.com/my-converse.js" |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
114 conversejs_css = "https://example.com/my-converse.css" |
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 Additional tags |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
118 --------------- |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
119 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
120 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
|
121 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
122 ``` {.lua} |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
123 conversejs_tags = { |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
124 -- Load custom CSS |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
125 [[<link rel="stylesheet" href="https://example.org/css/custom.css">]]; |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
126 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
127 -- 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
|
128 [[<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
|
129 } |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
130 ``` |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
131 |
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
132 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
|
133 |
2920
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
134 Compatibility |
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
135 ============= |
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
136 |
3598
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
137 Prosody version state |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
138 ----------------- --------------- |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
139 0.9 Does not work |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
140 0.10 Should work |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
141 0.11 Should work |
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
142 trunk Works |