Mercurial > prosody-modules

annotate mod_conversejs/README.markdown @ 3334:04e5e34893e1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_conversejs: Update README
author Matthew Wild <mwild1@gmail.com>
date Thu, 27 Sep 2018 12:19:21 +0100
parents 5b3347056f07
children af085e8b9d48
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
3311
5b3347056f07 mod_conversejs/README: Fix links to mod_bosh and mod_websocket (thanks jubalh)
Kim Alvefur <zash@zash.se>
parents: 3304
diff changeset
39 It also determines the [BOSH][doc:modules:mod_bosh] and
5b3347056f07 mod_conversejs/README: Fix links to mod_bosh and mod_websocket (thanks jubalh)
Kim Alvefur <zash@zash.se>
parents: 3304
diff changeset
40 [WebSocket][doc:modules:mod_websocket] URL automatically, see their
5b3347056f07 mod_conversejs/README: Fix links to mod_bosh and mod_websocket (thanks jubalh)
Kim Alvefur <zash@zash.se>
parents: 3304
diff changeset
41 respective documentation for how to configure them. Both connection
5b3347056f07 mod_conversejs/README: Fix links to mod_bosh and mod_websocket (thanks jubalh)
Kim Alvefur <zash@zash.se>
parents: 3304
diff changeset
42 methods are 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.