author | Matthew Wild <mwild1@gmail.com> |
Tue, 18 Jan 2022 17:01:18 +0000 | |
changeset 4880 | 0f5f2d4475b9 |
parent 4187 | ad9ce6750880 |
permissions | -rw-r--r-- |
4114
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
1 |
--- |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
2 |
labels: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
3 |
- 'Stage-Beta' |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
4 |
summary: 'Manage list of compatible client apps' |
4187
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4117
diff
changeset
|
5 |
rockspec: |
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4117
diff
changeset
|
6 |
build: |
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4117
diff
changeset
|
7 |
copy_directories: |
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4117
diff
changeset
|
8 |
- assets |
4114
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
9 |
... |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
10 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
11 |
Introduction |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
12 |
============ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
13 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
14 |
This module provides a way to configure a list of XMPP client apps recommended |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
15 |
by the current server. This list is used by other modules such as mod_invites_page |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
16 |
and mod_invites_register_web. |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
17 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
18 |
It also contains the logos of a number of popular XMPP clients, and serves |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
19 |
them over HTTP for other modules to reference when serving web pages. |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
20 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
21 |
# Configuration |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
22 |
|
4117
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
23 |
| Field | Description | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
24 |
|----------------------|--------------------------------------------------------------------------| |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
25 |
| site_apps | A list of apps and their metadata | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
26 |
| site_apps_show | A list of app ids to only show | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
27 |
| site_apps_hide | A list of app ids to never show | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
28 |
|
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
29 |
An "app id" is the lower case app name, with any spaces replaced by `-`. E.g. "My Chat" would be `"my-chat"`. |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
30 |
|
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
31 |
The module comes with a preconfigured `site_apps` containing popular clients. Patches are welcome to |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
32 |
add/update this list as needed! |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
33 |
|
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
34 |
If you want to limit to just displaying a subset of the apps on your server, use the `site_apps_show` |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
35 |
option, e.g. `site_apps_show = { "conversations", "siskin-im" }`. To never show specific apps, you |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
36 |
can use `site_apps_hide`, e.g. `site_apps_hide = { "pidgin" }`. |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
37 |
|
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
38 |
# App metadata format |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
39 |
|
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4114
diff
changeset
|
40 |
The configuration option `site_apps` contains the list |
4114
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
41 |
of apps and their metadata. |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
42 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
43 |
``` {.lua} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
44 |
-- Example site_apps config with two clients |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
45 |
site_apps = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
46 |
{ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
47 |
name = "Conversations"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
48 |
text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]]; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
49 |
image = "assets/logos/conversations.svg"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
50 |
link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
51 |
platforms = { "Android" }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
52 |
supports_preauth_uri = true; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
53 |
magic_link_format = "{app.link!}&referrer={invite.uri}"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
54 |
download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
55 |
buttons = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
56 |
{ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
57 |
image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
58 |
url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
59 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
60 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
61 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
62 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
63 |
{ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
64 |
name = "Gajim"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
65 |
text = [[A fully-featured desktop chat client for Windows and Linux.]]; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
66 |
image = "assets/logos/gajim.svg"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
67 |
link = "https://gajim.org/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
68 |
platforms = { "Windows", "Linux" }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
69 |
download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
70 |
buttons = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
71 |
{ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
72 |
text = "Download Gajim"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
73 |
url = "https://gajim.org/download/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
74 |
target = "_blank"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
75 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
76 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
77 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
78 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
79 |
} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
80 |
``` |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
81 |
The fields of each client entry are as follows: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
82 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
83 |
| Field | Description | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
84 |
|----------------------|--------------------------------------------------------------------------| |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
85 |
| name | The name of the client | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
86 |
| text | Description of the client | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
87 |
| image | URL to a logo for the client, may also be a path in the assets/ directory| |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
88 |
| link | URL to the app | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
89 |
| platforms | A list of platforms the app can be installed on | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
90 |
| supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
91 |
| magic_link_format | A template to generate a magic installation link from an invite | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
92 |
| download | Download instructions and buttons, described below | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
93 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
94 |
## Download metadata |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
95 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
96 |
The `download` field supports an optional text prompt and one or more buttons. |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
97 |
Each button must contain either a `text` or `image` field and must contain |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
98 |
a `url` field. It is recommended to set `target = "_blank"` if the link |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
99 |
opens a new page, so that the user doesn't lose the invite page. |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
100 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
101 |
Example download field with instructions and two buttons: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
102 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
103 |
``` {.lua} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
104 |
download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
105 |
text = "Some optional instructions about downloading the client..."; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
106 |
buttons = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
107 |
{ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
108 |
text = "Button 1: some text"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
109 |
url = "https://example.com/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
110 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
111 |
{ |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
112 |
image = "https://example.com/button2.png"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
113 |
url = "https://example.com/download/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
114 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
115 |
}; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
116 |
} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
117 |
|
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
118 |
``` |