Mercurial > prosody-modules

annotate mod_conversejs/README.markdown @ 3524:a7a751e57f32

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
luacheckrc: Update API method list from prosody
author Kim Alvefur <zash@zash.se>
date Sun, 31 Mar 2019 18:31:38 +0200
parents 5567098a7f91
children 1921ae4449b8
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`
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.