Mercurial > prosody-modules

annotate mod_conversejs/README.markdown @ 3587:c24d43ababc6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_storage_xmlarchive: Try harder to limit range of time to check Fixes read of entire index in case where the time range is outside the range present in the archive.
author Kim Alvefur <zash@zash.se>
date Tue, 07 May 2019 17:10:07 +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.