Mercurial > prosody-modules

comparison mod_server_info/README.md @ 5842:ed82916e5796

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
author Matthew Wild <mwild1@gmail.com>
date Fri, 23 Feb 2024 22:47:05 +0000
parents 174c77da03f5
children
comparison
equal deleted inserted replaced
5841:904b226fddf1 5842:ed82916e5796
12 extensions in the config file. It may be useful as a way to advertise certain 12 extensions in the config file. It may be useful as a way to advertise certain
13 information. 13 information.
14 14
15 Everything configured here is publicly visible to other XMPP entities. 15 Everything configured here is publicly visible to other XMPP entities.
16 16
17 **Note:** This module was rewritten in February 2024, the configuration is not
18 compatible with the previous version of the module.
19
17 ## Configuration 20 ## Configuration
18 21
19 The `server_info` option accepts a list of dataforms. A dataform is an array 22 The `server_info_extensions` option accepts a list of custom fields to include
20 of fields. A field has three required properties: 23 in the server info form.
24
25 A field has three required properties:
21 26
22 - `type` - usually `text-single` or `list-multi` 27 - `type` - usually `text-single` or `list-multi`
23 - `var` - the field name 28 - `var` - the field name (see below)
24 - `value` the field value 29 - `value` the field value
25 30
26 Example configuration: 31 Example configuration:
27 32
28 ``` lua 33 ``` lua
29 server_info = { 34 server_info = {
35 -- Advertise that our maximum speed is 88 mph
36 { type = "text-single", var = "speed", value = "88" };
30 37
31 -- Our custom form 38 -- Advertise that the time is 1:20 AM and zero seconds
32 { 39 { type = "text-single", var = "time", value = "01:21:00" };
33 -- Conventionally XMPP dataforms have a 'FORM_TYPE' field to
34 -- indicate what type of form it is
35 { type = "hidden", var = "FORM_TYPE", value = "urn:example:foo" };
36
37 -- Advertise that our maximum speed is 88 mph
38 { type = "text-single", var = "speed", value = "88" };
39
40 -- Advertise that the time is 1:20 AM and zero seconds
41 { type = "text-single", var = "time", value = "01:21:00" };
42 };
43
44 } 40 }
45 ``` 41 ```
46 42
43 The `var` attribute is used to uniquely identify fields. Every `var` should be
44 registered with the XSF [form registry](https://xmpp.org/registrar/formtypes.html#http:--jabber.org-network-serverinfo),
45 or prefixed with a custom namespace using Clark notation, e.g. `{https://example.com}my-field-name`. This is to prevent
46 collisions.
47
48 ## Developers
49
50 Developers of other modules can add fields to the form at runtime:
51
52 ```lua
53 module:depends("server_info");
54
55 module:add_item("server-info-fields", {
56 { type = "text-single", var = "speed", value = "88" };
57 { type = "text-single", var = "time", value = "01:21:00" };
58 });
59 ```
60
61 Prosody will ensure they are removed if your module is unloaded.
62
47 ## Compatibility 63 ## Compatibility
48 64
49 This module should be compatible with Prosody 0.12, and possibly earlier 65 This module should be compatible with Prosody 0.12 and later.
50 versions.