Software / code / prosody-modules
Annotate
mod_conversejs/README.markdown @ 3964:15355caf4553
mod_muc_limits: Add [luacheck] annotation to silence unused loop variable warning
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Fri, 03 Apr 2020 12:24:54 +0100 |
| parent | 3958:cacd753848b2 |
| child | 4147:3a06dea21ea1 |
| 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 | |
|
3958
cacd753848b2
mod_conversejs/README: Add an example of the URL to open
Kim Alvefur <zash@zash.se>
parents:
3711
diff
changeset
|
17 It becomes available on an URL like `https://example.com:5281/conversejs` |
|
cacd753848b2
mod_conversejs/README: Add an example of the URL to open
Kim Alvefur <zash@zash.se>
parents:
3711
diff
changeset
|
18 |
| 2878 | 19 Configuration |
| 20 ============= | |
| 21 | |
|
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
22 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
|
23 should just work after loading it. |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
24 |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
25 ``` {.lua} |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
26 modules_enabled = { |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
27 -- other modules... |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
28 "conversejs"; |
|
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 ``` |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
31 |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
32 Authentication |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
33 -------------- |
| 2878 | 34 |
|
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
35 [Authentication settings][doc:authentication] are used determine |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
36 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
|
37 |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
38 Connection methods |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
39 ------------------ |
| 2878 | 40 |
|
3362
af085e8b9d48
mod_conversejs: Link to BOSH and WebSockets setup instructions instead of module pages
Kim Alvefur <zash@zash.se>
parents:
3334
diff
changeset
|
41 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
|
42 [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
|
43 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
|
44 loaded automatically. |
|
2918
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 HTTP |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
47 ---- |
|
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
48 |
| 3304 | 49 The module is served on Prosody's default HTTP ports at the path |
| 50 `/conversejs`. More details on configuring HTTP modules in Prosody can | |
| 51 be found in our [HTTP documentation](http://prosody.im/doc/http). | |
| 2878 | 52 |
|
3598
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
53 ## Templates |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
54 |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
55 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
|
56 `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
|
57 |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
58 ```lua |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
59 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
|
60 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
|
61 ``` |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
62 |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
63 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
|
64 [`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
|
65 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
|
66 injected. |
|
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
67 |
|
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
68 Other |
|
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
69 ----- |
| 2878 | 70 |
|
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
71 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
|
72 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
|
73 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
|
74 this: |
|
2918
d2d0715f30d9
mod_conversejs/README: Expand config section
Kim Alvefur <zash@zash.se>
parents:
2878
diff
changeset
|
75 |
|
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
76 ``` {.lua} |
| 3304 | 77 conversejs_options = { |
|
2919
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
78 debug = true; |
|
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
79 view_mode = "fullscreen"; |
|
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 ``` |
|
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
82 |
|
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
83 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
|
84 **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
|
85 |
|
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
86 - `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
|
87 - `jid` *the current `VirtualHost`* |
|
0ea93da47db9
mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents:
2918
diff
changeset
|
88 - `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
|
89 - `websocket_url` |
|
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
90 |
|
5567098a7f91
mod_conversejs/README: Update text about mod_bosh and mod_websocket
Kim Alvefur <zash@zash.se>
parents:
3362
diff
changeset
|
91 `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
|
92 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
|
93 |
|
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
94 Loading resources |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
95 ----------------- |
|
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 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
|
98 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
|
99 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
100 ``` {.lua} |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
101 conversejs_cdn = "https://cdn.example.com" |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
102 ``` |
|
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 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
|
105 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
106 ``` {.lua} |
|
3643
740870196b97
mod_http_stats_stream: Make global to simplify
Kim Alvefur <zash@zash.se>
parents:
3598
diff
changeset
|
107 conversejs_version = "5.0.0" |
|
3334
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
108 ``` |
|
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 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
|
111 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
112 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
|
113 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
114 ``` {.lua} |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
115 conversejs_script = "https://example.com/my-converse.js" |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
116 conversejs_css = "https://example.com/my-converse.css" |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
117 ``` |
|
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 Additional tags |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
120 --------------- |
|
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 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
|
123 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
124 ``` {.lua} |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
125 conversejs_tags = { |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
126 -- Load custom CSS |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
127 [[<link rel="stylesheet" href="https://example.org/css/custom.css">]]; |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
128 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
129 -- 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
|
130 [[<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
|
131 } |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
132 ``` |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
133 |
|
04e5e34893e1
mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents:
3311
diff
changeset
|
134 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
|
135 |
|
2920
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
136 Compatibility |
|
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
137 ============= |
|
4d03ac2737ab
mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2919
diff
changeset
|
138 |
|
3598
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
139 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
|
140 ----------------- --------------- |
|
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.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
|
142 0.10 Should work |
|
3711
309fa523c424
mod_conversejs: Update compatibility section, pretty sure it works with 0.11
Kim Alvefur <zash@zash.se>
parents:
3643
diff
changeset
|
143 0.11 Works |
|
3598
1921ae4449b8
mod_conversejs: Separate out templates into separate configurable files (breaks 0.9 compat)
Kim Alvefur <zash@zash.se>
parents:
3495
diff
changeset
|
144 trunk Works |