Mercurial > prosody-modules

annotate mod_conversejs/README.markdown @ 3492:f59334da6df9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_conversejs: Show fallback text if converse.js fails to load (thanks MattJ) This can happen if javascript is enabled but 3rd party resources are blocked, or some other error happened.
author Kim Alvefur <zash@zash.se>
date Tue, 19 Mar 2019 19:43:13 +0100
parents af085e8b9d48
children 5567098a7f91
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2878
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 depends:
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 - 'mod\_bosh'
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 - 'mod\_websocket'
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 provides:
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 - http
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 title: 'mod\_conversejs'
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 ---
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 Introduction
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 ============
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 This module serves a small snippet of HTML that loads
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 [Converse.js](https://conversejs.org/), configured to work with the
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 VirtualHost that it is loaded onto.
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 Configuration
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18 =============
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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
27db90321e7b Fix README of mod_conversejs
t2d <td@tem.li>
parents: 2920
diff changeset
47 The module is served on Prosody's default HTTP ports at the path
27db90321e7b Fix README of mod_conversejs
t2d <td@tem.li>
parents: 2920
diff changeset
48 `/conversejs`. More details on configuring HTTP modules in Prosody can
27db90321e7b Fix README of mod_conversejs
t2d <td@tem.li>
parents: 2920
diff changeset
49 be found in our [HTTP documentation](http://prosody.im/doc/http).
2878
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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
ed5ad4fd5bdd mod_conversejs: Add a readme
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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
27db90321e7b Fix README of mod_conversejs
t2d <td@tem.li>
parents: 2920
diff changeset
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`
0ea93da47db9 mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents: 2918
diff changeset
72 - `websocket_url` *if `mod_websocket` is available*
0ea93da47db9 mod_conversejs: Allow passing arbitrary options trough to Converse.js
Kim Alvefur <zash@zash.se>
parents: 2918
diff changeset
73
3334
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
74 Loading resources
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
75 -----------------
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
76
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
77 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
78 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
79
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
80 ``` {.lua}
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
81 conversejs_cdn = "https://cdn.example.com"
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
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
84 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
85
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
86 ``` {.lua}
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
87 conversejs_version = "4.0.1"
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
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
90 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
91
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
92 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
93
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
94 ``` {.lua}
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
95 conversejs_script = "https://example.com/my-converse.js"
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
96 conversejs_css = "https://example.com/my-converse.css"
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
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
99 Additional tags
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 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
103
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
104 ``` {.lua}
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
105 conversejs_tags = {
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
106 -- Load custom CSS
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
107 [[<link rel="stylesheet" href="https://example.org/css/custom.css">]];
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 -- 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
110 [[<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
111 }
04e5e34893e1 mod_conversejs: Update README
Matthew Wild <mwild1@gmail.com>
parents: 3311
diff changeset
112 ```
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 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
115
2920
4d03ac2737ab mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2919
diff changeset
116 Compatibility
4d03ac2737ab mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2919
diff changeset
117 =============
4d03ac2737ab mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2919
diff changeset
118
4d03ac2737ab mod_conversejs/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2919
diff changeset
119 Should work with Prosody 0.9 and later. Websocket support requires 0.10.